feat: acp_rule persistent model reminders (compress.rules)

[ranxianglei]

来源: ranxianglei/billion-context-pi#433（https://github.com/ranxianglei/billion-context-pi/issues/433）实现三仓 acp_rule 时，billion-context 侧适配需独立跟踪。

What

Opt-in support for the acp_rule tool from acp-kernel (acp-kernel#283): persistent principle-level reminders the model records, which survive every compression fold.

Design (owner constraints: keep it simple, no system-prompt changes)

• Config: rules?: boolean scalar on CompressSettings — three-level cascade (global → provider → model, deepest wins), off by default. Maps to kernel Config.rules = { enabled }.
• Tool injection: when enabled, injected on the anthropic / openai / responses native-tool wires next to absorb (same gate: enabled && injectTool). Plugin clients get it in the manifest unconditionally (like absorb) with a per-session execution gate via effectiveRulesConfig.
• Semantics: ordinary tool, add-by-default — pass rule to record a short reminder, omit the argument to list recorded rules. No remove/clear actions (stale-rule management = edit the session state file). Kernel validation errors are returned verbatim (no FAILED marker): empty / too long / duplicate / limit reached.
• Protection: hard protection comes free from the kernel (ALWAYS_PROTECTED_TOOLS includes acp_rule) — the call and its result survive every fold. No client-side logic needed.
• No system-prompt changes: usage guidance lives entirely in the kernel's tool description.
• Persistence: rules live in CompressionState.rules; added to the persist.ts mergeState whitelist so they survive restarts.
• Limits: kernel defaults 50 rules × 300 chars each.

Dependency

Requires acp-kernel #283 merged + published (wire schemas + state API). Until then this branch validates against a local dist overlay; the acp-kernel pin bump follows as a follow-up commit before merge.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 接手确认。状态盘点:

• 实现已在分支 2026-09-13_acp-rule-tool @ afca571,PR feat(rules): acp_rule persistent reminders (compress.rules) #750 已开。
• 内核 acp-kernel#283 仍为 open(未合并),stable 0.0.69 不含 rules API(已验证 tarball 无 acp_rule 符号)——所以本分支按 issue 约定走本地 dist overlay 验证,pin bump 等内核发布后作为 follow-up commit。

我正在用 PR #283 的 dist overlay 重新跑完整验证(typecheck / test / build)。初步 diff 审查已发现两条缺陷,修复中:

1. anthropic 线:injectTool(parsed.tools, [...]) 传了数组但 helper 签名是单个 {name} —— 非空时整个数组会被当作一个工具对象推进 tools 列表;
2. openai / responses 线:rulesActive 只声明未使用,RULE_TOOL_OPENAI / RULE_TOOL_RESPONSES 从未注入,且这两条路径缺 storeEffectiveRules(plugin 执行门控会静默失效)。

修完补 wire 级测试后同步结果。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Status: wire fixes landed on PR #750 — verification green against the kernel overlay. Remaining blocker is acp-kernel#283 itself.

While validating the existing branch work I found the previously reported "typecheck clean" claim was not true. Two real defects, both fixed in follow-up commit 2ac0a97:

Defect 1 — anthropic wire (would break the API): injectTool() accepted a single extra tool, but the call site passed an [absorb?, rule?] array — which got pushed as one nested element into the tools list (tsc error TS2345 confirmed it). Fixed by generalizing the helper to an extras array with per-name dedup (src/server.ts).

Defect 2 — openai + responses wires (silent no-op): rulesActive was computed on the openai path but never used — acp_rule was never injected, and storeEffectiveRules() was missing on both openai and responses paths, so the plugin execution gate would silently fall back to base config (rules off). Both paths now inject acp_rule next to absorb with the same gate (skip on compaction-trigger requests and text protocol, which has no native tool surface), and store the effective rules config like anthropic does.

New coverage: tests/rules-wire.test.ts — real-HTTP tests through startServer with a mock upstream capturing the forwarded body, asserting acp_rule lands flat (never nested) alongside the ACP tools on all three wires, is absent by default, and dedups against client-supplied tools (plugin case). 5/5 pass.

Verification (against a locally built acp-kernel dist from PR #283 head 2bf84ee, overlaid into node_modules — the published 0.0.69 does not contain the feature yet):

• npm run typecheck — clean
• npm test — 1461 tests, 1459 pass, 0 fail, 2 skipped (e2e gates)
• npm run build — OK (tsup bundles the overlay)

Remaining before merge (per the issue's dependency note):

1. Merge acp-kernel#283 (currently open, mergeable_state: clean) and wait for CI publish.
2. Follow-up commit here bumping the acp-kernel pin (exact version, lockfile refresh) — CI stays red until then because npm ci resolves a kernel without the rules API.

中文摘要：修复了 acp_rule 在三条原生工具链路上的注入缺陷（anthropic 把工具数组当成单个嵌套元素、openai/responses 根本没注入且缺执行门控配置），补了三条链路真实 HTTP 注入测试，typecheck/1459 项测试/build 全绿；剩 acp-kernel#283 合并发布后提 pin 升级 commit 即可合并。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Addendum — e2e status: AGENTS.md requires the codex e2e before merging request-pipeline changes, so I ran it. The zero-token preflight (E2E_CHECK=1) passes, but the full 4-phase core currently cannot complete from this environment: the suite's default local test upstream is down (ECONNREFUSED on every forwarded request, warmup exits 1 with no model output).

To make sure this wasn't caused by my diff, I ran the identical e2e on a fresh checkout of master — same failure, same signature (warmup exit=1). So: pre-existing/environmental (test upstream not running), unrelated to the acp_rule change. The injection path I touched is inert when rules/absorb are off (empty extras array = byte-identical behavior to before), and the new wire tests + full unit suite cover the changed code paths. Once the local upstream is back up, ACP_TEST_E2E=1 node --import tsx --test tests/e2e/e2e-codex.test.ts should be re-run as the final gate.

中文补充：e2e 因本地测试上游服务当前未启动而无法跑完（连接被拒）；已在 master 上复现完全相同的失败，确认与本次改动无关。上游恢复后需重跑一次作为合并前最终验证。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Addendum — validated against the published kernel artifact: to de-risk the upcoming pin-bump commit, I pulled acp-kernel@0.0.69-pr.283.149 from npm (the CI prerelease of PR #283) and diffed it against my locally built dist from PR head 2bf84ee: all JS files byte-identical except index.js, which differs only in import-statement order — same commit, same code. I then swapped the prerelease into node_modules/acp-kernel/dist and re-ran everything: typecheck clean, 1461 tests / 1459 pass / 0 fail / 2 skipped — identical to the local-build run.

So the branch is verified not just against a hand-built overlay but against the exact artifact shape CI will install once #283 goes stable. The pin-bump follow-up commit is ready to land as soon as acp-kernel#283 is merged + published (still open as of now; npm latest remains 0.0.69). PR #750 is also confirmed mergeable: true vs current master (only "behind" by the docs merge, no conflicts).

中文补充：已用 npm 上的内核预发布包（PR #283 的 CI 产物）替换本地构建并全量复验，结果与本地构建完全一致——pin 升级提交随时可上，只等内核 #283 合并发布。