Skip to content

feat(#433): wire acp_rule record tool behind opt-in rules config - #490

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-21_acp-rule-tool
Sep 25, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-21_acp-rule-tool

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #433

What

Completes the adapter side of #433 (state pipeline — deriveChildState/mergeInitialState carrying rules/nextRuleId — already landed on master via 953d56a; kernel 0.0.81 ships the full rule surface). This PR wires the remaining surface:

  • src/rule-tool.ts (new) — acp_rule, a plain record tool per the issue's final scope: one optional rule argument. Value present → records via kernel addRule, echoes Recorded ruleN: …. Argument omitted → lists recorded rules (formatRulesList) for humans. No remove/clear, no action enum.
  • Zero system-prompt involvement (issue constraint 「不要动系统提示词」): no promptSnippet/promptGuidelines on the tool definition (pi renders those into the system prompt); all usage guidance lives in the tool description only; nothing re-injected per turn.
  • Hard-protected from compression: acp_rule is in the kernel's ALWAYS_PROTECTED_TOOLS, so its call+result survive any compress covering them — the reminder stays visible as a trace in the conversation.
  • Config: new top-level rules?: boolean key (src/user-config.ts KNOWN set + AdapterConfig), default off; registered at session start after user-config reload so project-local acp.json wins.
  • Limits come from kernel defaults (50 rules × 300 chars) via resolveRuleLimits; validation errors (empty / over-length / duplicate / limit reached) are returned verbatim to the model.
  • Docs: CONFIGURATION.md + .zh-CN.md (summary row + dedicated section), both READMEs (tool table + opt-in note), AGENTS.md module map.

Tests

+8 tests (tests/rule-tool.test.ts + tests/user-config.test.ts): registration gating (default off / rules: true), explicit assertion that the tool carries NO prompt-surface fields (regression guard for the zero-system-prompt constraint), record/list round-trips, verbatim validation errors incl. the 50-rule limit, restart persistence via the .acp.json sidecar, and a compression-protection test whose fixture places the acp_rule pair between the kernel's first-user pin and the last-5 recent zone so its survival can only come from protection, not recency.

Full suite: typecheck clean, 788 pass / 82 fail / 6 skip — the 82 failures are pre-existing sandbox-only /tmp EACCES artifacts of this environment (identical set on master before this change; CI is unaffected). Build clean.

Notes (findings, not fixed here)

  • master's package-lock.json root version lags package.json (0.1.73 vs 0.1.74); npm install re-syncs it locally, so this PR deliberately leaves the lockfile untouched to keep the diff pure.
  • Kernel RULES_USAGE_PROMPT claims rules are "re-injected into the system prompt every turn" — true for the billion-context proxy path, false for pi; the pi tool description therefore does not make that claim.
  • Kernel's limit-reached error text says "remove or clear outdated rules first" although the pi surface intentionally exposes neither — cosmetic wording wart for a future kernel pass.

No version bump, no acp-kernel pin change (0.0.81 already carries everything needed).

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Extension Artifact

Branch: 2026-09-21_acp-rule-tool (fa05715)

Option A — Install from npm PR tag (recommended)

pi install npm:billion-context-pi@pr-490

Each push to this PR publishes a new version under the pr-490 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pi-pr490.tgz
pi install ./package

This comment is automatically updated on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Picking up this PR now — pulling branch 2026-09-21_acp-rule-tool, reviewing the diff against master, checking CI, and re-running the local suite before reporting back with a verdict.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Verified PR #490 (2026-09-21_acp-rule-tool @ cdac3d7, single commit on master 72d8771) by pulling the branch, cross-checking every claim in the description against the code, re-running the suite locally, and checking CI.

Code review — all claims hold:

  • src/rule-tool.ts: single optional rule param, no promptSnippet/promptGuidelines on the definition (zero-system-prompt constraint honored); validation errors returned verbatim; runtime.save only after a successful addRule; refusal path returns refusalMessage ?? UNSUPPORTED_HOST_MESSAGE.
  • Registration at src/index.ts:311-312 sits inside session_start after reloadConfig(ctx.cwd) (:255), so a project-local acp.json wins; the second reloadConfig at :363 is the per-turn context event and doesn't affect registration.
  • Config plumbing: rules added to both UserAcpConfig + KNOWN (src/user-config.ts) and AdapterConfig (src/config.ts); coreOverrides?: Partial<Config> spreads into the resolved kernel config which carries rules, so custom limits flow to resolveRuleLimits as documented.
  • Kernel surface confirmed in pinned acp-kernel 0.0.81: ALWAYS_PROTECTED_TOOLS = readonly ["compress", "acp_rule"] (protected.d.ts:9), addRule/listRules/formatRulesList/resolveRuleLimits exported — hard-protection and limits claims true.
  • Diff is clean: 11 files, +358/-2, no lockfile churn, no version bump, zh/en docs in sync (CONFIGURATION ±, READMEs ±, AGENTS module map).

Verification run on branch head:

  • npm run typecheck — clean.
  • npm test — 876 tests: 788 pass / 82 fail / 6 skip, exactly the numbers in the PR description. All 7 new rule-tool tests pass (incl. the compression-protection fixture where the acp_rule pair sits between the first-user pin and the last-5 recent zone) plus the new user-config test. The 82 failures are all pre-existing sandbox artifacts from /tmp being read-only here (EACCES on /tmp/*.acp.json, e.g. lstat '/tmp/pai-acp-cache-nofolds.session.json.acp.json') — none touch this PR's files, and CI runs on a writable filesystem.
  • npm run build — clean (dist/index.js 859 KB, acp-kernel inlined).
  • CI on cdac3d7: CI ✅ success · E2E ✅ success · PR Build Artifact ✅ success.

On the three "Notes" findings: already properly documented in the PR body (lockfile root-version lag, kernel RULES_USAGE_PROMPT wording mismatch for the pi path, limit-reached error text mentioning remove/clear). I'm not filing separate issues from this working session per platform rules — flagging here so you can decide whether any deserve its own issue before or after merge.

This is a feat (new tool surface), so per §7.4 it stays a human merge either way — nothing here blocks it.

结论:核对并复跑通过——acp_rule 工具按 #433 最终范围实现(opt-in、零系统提示词、硬保护、校验错误原样返回),代码与描述逐条相符,typecheck/构建干净、新增 8 个测试全过、CI 三条流水线全绿(本地 82 个失败均为沙箱 /tmp 只读的环境问题,与 master 一致),可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Note from #537 work: the human /acp-rule command just gained remove <id> / clear ops (#538), porting the wiring from bili ranxianglei/billion-context#1178 (issue #1177).

When this model-side acp_rule tool lands, it should mirror bili's RULE_TOOL schema for the delete/clear params: mutually exclusive action params, one operation per call (mixed ops rejected before any mutation), kernel removeRule(state, id) / clearRules(state) against the same session sidecar state, unknown-id errors surfaced verbatim. Per the #537 scope decision, that work belongs here, not in #538.

@Juna9969 Juna9969 mentioned this pull request Sep 25, 2026
@ranxianglei
ranxianglei force-pushed the 2026-09-21_acp-rule-tool branch 2 times, most recently from c8aa2ce to 50060e7 Compare September 25, 2026 14:34
Plain record tool per issue scope: single optional 'rule' argument —
value records a short reminder (echoes 'Recorded ruleN: …'), omitted
argument lists recorded rules for humans. No remove/clear, no action
enum, zero system-prompt involvement (no promptSnippet/promptGuidelines;
usage guidance lives in the tool description only). Rules persist in the
.acp.json sidecar (state pipeline already on master via deriveChildState/
mergeInitialState) and are hard-protected from compression by the kernel's
ALWAYS_PROTECTED_TOOLS. Off by default: 'rules': true in acp.json registers
it at session start, after user-config reload.

Adds 8 tests (registration gating, no-prompt-surface regression guard,
record/list round-trip, verbatim validation errors incl. 50-rule limit,
restart persistence, compression-protection fixture placed between the
kernel's first-user pin and recent zone so survival proves protection)
and documents the key in CONFIGURATION.md/.zh-CN.md, both READMEs, and
the AGENTS.md module map.
@ranxianglei
ranxianglei force-pushed the 2026-09-21_acp-rule-tool branch from 50060e7 to fa05715 Compare September 25, 2026 14:40
@ranxianglei

Copy link
Copy Markdown
Owner Author

补充关联:本 PR 也是 #539(rules 管道残缺)的修复 —— #539 报的正是 npm dist 里 acp_rule 工具注册缺失(仅剩 ALWAYS_PROTECTED_TOOLS 硬编码名),本 PR 接回完整管道:makeRuleTool + src/index.ts:336 rules: true 门控注册 + kernel addRule/listRules/resolveRuleLimits 接线 + 245 行回归测试。合并时请一并关 Closes #539。

(另:分支已 rebase 到含 #533/#534/#543 的最新 master 33fb14e+,head fa05715,970 tests / 0 fail,typecheck/build 绿)

@ranxianglei
ranxianglei merged commit f3fca31 into master Sep 25, 2026
9 checks passed
HangxiangMa pushed a commit to HangxiangMa/billion-context-pi that referenced this pull request Sep 29, 2026
Mirrors the /acp-cache human-command pattern for the acp_rule feature
(ranxianglei#490): bare /acp-rule lists all rules recorded in the current session,
/acp-rule <text> records one via the same kernel API the model path
uses (persisted in the session sidecar, injected next round). Output is
transcript-only and stripped from model context via the same custom-type
exclusion in entriesToCoreMessages; falls back to ui.notify on hosts
without sendMessage. Ported from billion-context #1259 (issue #1251).

Fixes ranxianglei#527
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

增接rule命令,专门用来记住用户对模型的提别提醒

1 participant