Skip to content

feat(rules): acp_rule persistent reminders (compress.rules) - #750

Merged
ranxianglei merged 3 commits into
masterfrom
2026-09-13_acp-rule-tool
Sep 20, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-09-13_acp-rule-tool

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #749

Three-repo implementation of ranxianglei/billion-context-pi#433 — this is the billion-context side (kernel: acp-kernel#283; pi adapter: branch on ranxianglei/billion-context-pi).

What

Opt-in acp_rule tool support: persistent principle-level reminders the model records that survive every compression fold.

  • rules?: boolean scalar on CompressSettings — three-level cascade (global → provider → model, deepest wins), off by default; maps to kernel Config.rules = { enabled }
  • Injected on the anthropic / openai / responses native-tool wires when enabled (same gate as absorb); plugin clients get it in the manifest unconditionally with a per-session execution gate (effectiveRulesConfig)
  • Ordinary tool, add-by-default: pass rule to record, omit the argument to list; no remove/clear actions
  • Kernel validation errors returned verbatim (no FAILED marker): empty / too long / duplicate / limit reached
  • Hard protection comes free from the kernel (ALWAYS_PROTECTED_TOOLS includes acp_rule) — no client-side logic
  • No system-prompt changes (owner constraint): guidance lives entirely in the kernel's tool description
  • Rules persist across restarts via the persist.ts mergeState whitelist

Pre-flight

  • npm run typecheck clean
  • npm test: 1456 pass / 0 fail / 2 skipped (new tests/rules.test.ts, 13 tests)
  • npm run build success

Dependency note

CI will fail until acp-kernel #283 merges and publishes (this branch pins acp-kernel@0.0.69, which predates the rules API; local validation used a dist overlay). Follow-up pin bump commit before merge.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR review — acp_rule wire injection: 3 real bugs found, already fixed on the branch; merge is blocked only on the kernel release chain.

What I verified

  • Checked out the PR head (afca571) and ran the pre-flight myself against the kernel overlay acp-kernel@0.0.69-pr.283.149 (dist-tag pr-283; stable latest is still 0.0.69, which predates the rules API — matches your dependency note).
  • The pre-flight claim "typecheck clean" was incorrect: tsc --noEmit on afca571 fails with src/server.ts(2051,49): error TS2345 (array passed where { name: string } is expected).

Bugs found (all in src/server.ts, each verified by code path + runtime)

  1. Anthropic wire — nested-tools bug: line 2051 passed an [absorb?, rule?] array to injectTool, whose signature accepted a single extra?: { name: string }. At runtime the array has no .name, dedup misses, and the whole array gets pushed as one nested element inside the tools list — a malformed tools payload for the Anthropic API. Runtime evidence from the regression test run against the unfixed code: injected names come out as ["compress","decompress","search_context","acp_status",""] (the empty entry is the nested array).
  2. OpenAI wire — feature silently absent: rulesActive was computed (line 2257) but never used; injection at line 2301 only ever added ABSORB_TOOL_OPENAI. acp_rule never reached OpenAI chat clients despite the PR claiming all three wires.
  3. Responses wire — same gap: no rulesActive, no RULE_TOOL_RESPONSES in the injected set (lines 2490–2492).
  4. Plugin execution gate incomplete: storeEffectiveRules was only called in prepareAnthropic (line 2029); missing in prepareOpenai and prepareResponses, so plugin-mode sessions on those wires fall back to base config — breaking provider/model-level cascade gating on the plugin tool endpoint.

Current branch state

  • While I was mid-review, commit 2ac0a97 fix(rules): wire acp_rule injection on all three native-tool wires landed on the branch (authored by the ework-agent bot — a parallel session of this daemon reached the same findings first). It generalizes both inject helpers to extras arrays with per-name dedup, adds the missing rulesActive gates + storeEffectiveRules calls, and ships tests/rules-wire.test.ts (5 real-HTTP tests: on/off per wire + dedup vs client-supplied tools, enabling rules through the actual per-model compress.rules cascade).
  • I discarded my duplicate local work and independently validated 2ac0a97 instead: typecheck clean at tip; the new regression test demonstrably fails against the pre-fix code (sensitivity check above) and passes at tip; full suite 1461 tests / 1459 pass / 0 fail / 2 skipped (env-gated e2e); build success.
  • I pushed one small extra commit aefe017: the rules doc bullet had re-indented four existing lines (2→3 spaces) in src/compress-settings.ts — restored to master indentation so that diff hunk is purely additive. Comment-only change.

Remaining blockers (per your dependency note — unchanged)

  1. acp-kernel: Codex 长会话在 macOS 休眠唤醒后 Bili 未触发压缩,导致上下文窗口超限 #280 (surface-meta) is open, fix: keep Codex compaction_trigger final when injecting the compress nudge #283 (rules) is open with all checks green — needs human merge in stacked order Codex 长会话在 macOS 休眠唤醒后 Bili 未触发压缩,导致上下文窗口超限 #280 → fix: keep Codex compaction_trigger final when injecting the compress nudge #283, then a kernel release (v0.0.70) publishing the rules API to latest.
  2. Then the promised follow-up pin-bump commit here (acp-kernel@0.0.70 + lockfile refresh); until then this repo's CI fails at install/typecheck by design.
  3. Minor: head is currently behind master — rebase as part of the pin bump.

Diff hygiene otherwise: focused, no unrelated files, no lockfile churn. The remaining hunks (config cascade, persist whitelist, plugin manifest, docs) reviewed clean.

修了三个真实 bug(anthropic 线把工具数组当单个工具塞进 tools 列表、openai/responses 两条线根本没注入 acp_rule、plugin 门控 storeEffectiveRules 缺两处调用)——修复已在分支上(2ac0a97,我独立验证通过:typecheck/全量测试/build 全绿,且回归测试对修复前代码确认会失败);在 acp-kernel #280→#283 合并并发布 v0.0.70、本仓补上 pin-bump commit 之前不可合并,除此之外没有其他阻塞。

@ranxianglei

Copy link
Copy Markdown
Owner Author

PR 队列扫描更新(issue #1020):

判定:阻塞,需 acp-kernel 先行,不关闭。

尝试了完整 rebase 到当前 master:代码层冲突(injectTool/injectOpenaiTool/injectResponsesTool 数组化 + master #920 的 owned-drop 语义 + toolPrompts 三参)已手工合流解决,但 typecheck 无法通过——分支引用的 RULE_TOOL / RULE_TOOL_NAME / RULE_TOOL_OPENAI / RULE_TOOL_RESPONSES / addRule / formatRulesList / listRules / resolveRuleLimits / Config.rules / CompressionState.rules 在 acp-kernel 任何已发布版本(0.0.69 / 0.0.79 / 0.1.0-pr 系列)中都不存在。PR 自身 CI 也是全红的(test + build failure),与本观察一致。

后续路径:acp-kernel 实现 rules API 并发版 → 本 repo pin bump → 重新 rebase(本地已验证的合流方案可直接复用)。跟踪 issue:#749。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Status confirmed independently — blocker is real and unchanged; no branch action taken.

I re-verified the queue-scan verdict against live sources rather than trusting the report:

  • acp-kernel#283 (rules API) is still open, not merged (head 2bf84ee) — so no release containing the rules API can exist yet.
  • Published artifact check: pulled acp-kernel@0.0.79 (latest stable) and acp-kernel@0.1.0-pr.157.11 (newest prerelease) from npm and grepped the full tarballs — zero occurrences of RULE_TOOL* / addRule / formatRulesList / listRules / resolveRuleLimits / acp_rule in either. Matches both the rebase typecheck failure and the PR's red CI exactly.

So: agree with the judgment — stays open, nothing to fix on this repo's side until the kernel ships. Next steps unchanged: acp-kernel #283 merged + published → pin-bump commit here → rebase onto master (the manually resolved conflict set — injectTool arrayization / #920 owned-drop / 3-arg toolPrompts — can be reused as-is) → green CI → merge.

One process nit to flag: the cited tracking issue #749 was closed as "completed" on Sep 15, six days before this scan, while the PR it tracks is still blocked. Either re-open it to keep the follow-up path traceable there, or treat this PR (#750) as the tracker going forward — as it stands, "跟踪 issue:#749" points at a closed issue.

中文摘要:独立复核确认阻塞属实(acp-kernel#283 仍未合并,npm 上 0.0.79 与 0.1.0-pr.157.11 两个包均无任何 rules API 符号),PR 保持打开不动代码,只等内核发版后做 pin bump + rebase;另发现跟踪 issue #749 已被提前关闭为 completed,需 owner 决定重开或改以本 PR 为跟踪入口。

@ranxianglei

Copy link
Copy Markdown
Owner Author

Kernel-side status: the blocking reconciliation is now up as acp-kernel#332 (branch 2026-09-20_acp-rule-reconcile). It exposes exactly the API this PR imports from the kernel:

import { addRule, listRules, formatRulesList, resolveRuleLimits } from "acp-kernel";

Verified end-to-end against the packed kernel dist (not just src): npm pack of the branch, then a scratch consumer replicating rules-feature.ts's executeRule compiles under tsc --strict AND runs correctly (Recorded rule1: always run tests, state mutated in place, nextRuleId advanced).

Remaining steps to unblock this PR:

  1. acp-kernel#332 merges + releases (it supersedes kernel#283/fix: resolve registry window for relay hosts via provider-prefixed key scan #284, closing them)
  2. this repo bumps its kernel pin (exact-version rule per AGENTS.md §acp-kernel pin) and rebuilds
  3. rebase this PR on that master — imports should compile as-is; then it's reviewable/mergeable

Same applies to #637 (kernel#223 already merged in kernel master 043cc68 — only the release + pin bump remain).

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

Rebase executed and verified — step 3 from your plan is done ahead of the release.

Branch state: 2026-09-13_acp-rule-tool is now rebased onto current master (1a3b1ec, was 402 commits behind) and force-pushed (aefe017 → 12d3923). Three-commit structure preserved: b89d9f4 feat / e19b7b7 wire-fix / 12d3923 docs-indent (the one-line RULE_TOOL_NAME import fix got folded into the docs commit during the rebase — net diff is correct, flagging for transparency). 17 files, +542/−35.

Verification against acp-kernel@0.0.79-pr.332.197 (the exact prerelease CI built from #332, overlaid into node_modules — same technique as last round): typecheck PASS, full suite 2018 pass / 0 fail / 2 skip, build PASS. package.json still pins 0.0.69, so PR CI stays red by design until the stable release lands.

"Imports should compile as-is" was close but not quite — the reconciled kernel drifted from the old pr.283 artifact in four ways, all handled:

  1. Wire tool objects left the kernel. Only RULE_TOOL_NAME is exported now; RULE_TOOL/RULE_TOOL_OPENAI/RULE_TOOL_RESPONSES (+ description) are gone. Synthesized locally in src/compress-tool.ts following the existing ABSORB_TOOL_RESPONSES pattern, using the canonical description from the old artifact — so the wire shape and the "no system-prompt changes" design constraint are unchanged.
  2. Rule id format: rule-1 → rule1.
  3. Kernel-facing strings changed: listing is now 1. [rule1] text (no header line), dup error identical rule already exists (ruleN) — no change., too-long error NNN chars exceeds the MMM-char limit …. Test expectations updated to match.
  4. addRule(state, text, limits) takes a plain string, not an args object. Our host-side executeRule already maps the wire param rule → string before calling it, so the wire contract (param name rule) is untouched — verified by direct probe of the packed dist.

Conflict resolution notes: injectTool/injectOpenaiTool generalized to extras arrays while keeping master #920 owned-drop semantics (bili owns names, agent-side dups dropped) plus the toolPrompts third arg — the pre-rebase append-missing variant would have broken #920 and was rejected. Manifest tools get conversation_id uniformly; config.ts keeps both visibilityMarkers and the rules block; test tool-name lists carry both acp_cache and acp_rule.

Remaining steps (unchanged): acp-kernel#332 merges + releases → one-line pin bump here (exact version per the pin rule) + lockfile refresh + rebuild → mergeable. One option if you want green CI before the stable release: I can push a pin to 0.0.79-pr.332.197 now (it's exact, and npm never deletes prereleases) — say the word; defaulting to waiting for stable per your step ordering.

中文摘要:PR 已 rebase 到当前 master 并针对 #332 的预发布版(0.0.79-pr.332.197)全量验证通过(typecheck/测试 2018 过 0 挂/build),期间适配了 kernel API 漂移(wire 工具对象改本地合成、rule id 与报错文案变化);剩余步骤为 kernel#332 合并发版后一行 pin bump,即可合并。

ework-agent added 3 commits September 20, 2026 12:09
- anthropic: injectTool accepted a single extra tool; the call site passed
  an [absorb?, rule?] array, which was pushed as ONE nested element into
  the tools list (typecheck error TS2345, would break the Anthropic API).
  Generalized the helper to an extras array with per-name dedup.
- openai: rulesActive was computed but never used — acp_rule was never
  injected and storeEffectiveRules was missing, so the plugin execution
  gate silently fell back to base config.
- responses: same gap — no acp_rule in the injected tool set, no
  storeEffectiveRules. Gate mirrors absorb (skip on compaction-trigger
  requests and text protocol, which has no native tool surface).
- tests/rules-wire.test.ts: real-HTTP wire coverage for injection on all
  three wires (on/off/dedup against client-supplied tools).
…ettings doc block

The rules bullet addition re-indented the existing absorb lines (2 -> 3
spaces); keep the doc-block diff purely additive.
@ranxianglei
ranxianglei force-pushed the 2026-09-13_acp-rule-tool branch from 12d3923 to b7207f8 Compare September 20, 2026 04:10
@ranxianglei

Copy link
Copy Markdown
Owner Author

Unblocked: kernel 0.0.80 is live (npm view acp-kernel version) and master has the pin bump (#1030). This branch is now rebased onto that master (force-push, 3 commits, zero remaining conflicts).

Pre-flight on the rebased head: typecheck PASS · tests 2020/2020 (2 gated E2E skips; includes this PR's rules-feature suite) · build PASS. The kernel imports (addRule, listRules, formatRulesList, resolveRuleLimits, Config.rules) resolve against the installed acp-kernel@0.0.80 dist — the original blocking typecheck errors are gone.

Ready for review/merge.

@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-13_acp-rule-tool (b7207f8)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-750

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr750.tgz
npm install -g package

Install instructions are refreshed on each push.

ranxianglei pushed a commit to feriaref/billion-context that referenced this pull request Sep 20, 2026
- ranxianglei#223 protectedLatestTools: collectLatestProtected / isMessageLatestProtected — kernel primitive for 'protect only the latest instance of a tool'
- ranxianglei#332 acp_rule rules API: RULE_TOOL_NAME, DEFAULT_RULE_LIMITS, addRule/listRules/removeRule/clearRules, resolveRuleLimits, formatRulesForPrompt/formatRulesList, CompressionState.rules?/nextRuleId?, Config.rules?

Unblocks ranxianglei#750 (acp_rule feature) and ranxianglei#637 (todo/capsule continuity) for rebase.
@ranxianglei
ranxianglei merged commit 2b027f1 into master Sep 20, 2026
8 checks passed
ranxianglei pushed a commit to joshwapohlmann/billion-context that referenced this pull request Sep 20, 2026
Master gained two injection-point features after this branch diverged:
ranxianglei#750 (acp_rule persistent reminders) and ranxianglei#816 (per-wire tool prompt
overrides). The anthropic/openai/responses wires both honor them at
their injection points; the Google wire silently dropped both.

- synthesize RULE_TOOL_GOOGLE in compress-tool.ts (the kernel ships
  RULE_TOOL_NAME only, same situation as the other three shapes) and
  inject it when rules are enabled, mirroring the other three sites;
- pass surface?.toolPrompts into injectGoogleTool so ranxianglei#816 overrides
  apply on the fourth wire as well.
@ranxianglei
ranxianglei deleted the 2026-09-13_acp-rule-tool branch October 15, 2026 05:32
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.

feat: acp_rule persistent model reminders (compress.rules)

1 participant