billion-context-pi 0.1.77 → 0.1.78-pr.232.364

package/README.md

@@ -145,11 +145,12 @@ billion-context-pi is built for the **Pi** coding agent (`@earendil-works/pi-cod
 | `search_context` | Search compressed block summaries (and visible messages) by keyword |
 | `acp_status` | Show context usage, compressed blocks, compressible ranges |
 | `acp_cache` | Prompt-cache reconciliation: grand ledger (input/cached/hit rate), per-request miss attribution, per-fold economics |
+| `acp_rule` | Record a short, principle-level reminder that survives compression (opt-in: `"rules": true`) |
 | `acp_delegate` | Spawn a clean-context sub-agent for a task (review / research / implement / plan / advise) |
 | `acp_delegate_wait` | Block until a delegate run finishes (returns its result; times out otherwise) |
 | `acp_delegate_cancel` | Cancel a running delegate by runId |
 
-The four `acp_delegate*` tools are optional: if you bring your own sub-agent extension, disable them with one `acp.json` key — see *Using your own sub-agent instead* below.
+The four `acp_delegate*` tools are optional: if you bring your own sub-agent extension, disable them with one `acp.json` key — see *Using your own sub-agent instead* below. `acp_rule` is likewise opt-in — off by default, enable it with `"rules": true`.
 
 ### acp_delegate — clean-context delegation
 
@@ -167,7 +168,7 @@ Read-only roles (reviewer, researcher, planner, oracle) receive a restricted too
 
 Worker runs on Pi's full default toolset - no `--tools` allowlist is applied, so any loaded extension or custom tools (e.g. ACP, LSP, MCP) remain available. This keeps primary-task delegation fully capable. The `read, edit, write, bash` listing above reflects core tools only.
 
-The full delegate result is saved to a file (`/tmp/acp-delegate/<runId>.out`); the tool result and injected notification carry only the **task title + file path** (no preview) - use `read` for the details. This keeps the parent context lean.
+The full delegate result is saved to a file (`$TMPDIR/acp-delegate/<runId>.out`, defaulting to `/tmp/acp-delegate/<runId>.out`); the tool result and injected notification carry only the **task title + file path** (no preview) - use `read` for the details. This keeps the parent context lean.
 
 - **Interactive (TUI) & RPC modes**: `async:true` (default) runs the child in the background; a short completion notification is injected into the chat when it finishes — **unless the model already read the result file after the run finished** (detected via the `read` tool or a bash command referencing the file), in which case the notification is skipped: the model already has the result, so re-injecting it would only waste context. Set `delegate: { notifyIfRead: "always" }` in `acp.json` to restore the always-inject behavior.
 - **Print / JSON modes** (`pi -p`, SDK): `async:true` auto-downgrades to **synchronous** — the result returns as the tool result in the same turn (the parent exits after one turn, so background injection would be lost).
@@ -231,7 +232,7 @@ It discovers the agents and their tool baselines from the installed pi-subagents
 
 billion-context-pi works out of the box with no configuration — it reads your model's context window automatically and applies sensible defaults.
 
-Behavior is tuned via an optional `acp.json` config file (`~/.pi/acp.json` for global defaults, `<project>/.pi/acp.json` for per-project overrides) plus a few environment variables. For the complete reference — every key, type, default, and the precedence order — see **[CONFIGURATION.md](./CONFIGURATION.md)** ([中文](./CONFIGURATION.zh-CN.md)).
+Behavior is tuned via an optional `acp.json` config file (`~/.pi/agent/acp.json` for global defaults, `<project>/.pi/agent/acp.json` for per-project overrides) plus a few environment variables. The legacy locations (`~/.pi/acp.json`, `<project>/.pi/acp.json`) are still read for backward compatibility when the new one is absent. For the complete reference — every key, type, default, and the precedence order — see **[CONFIGURATION.md](./CONFIGURATION.md)** ([中文](./CONFIGURATION.zh-CN.md)).
 
 ### Logging
 

package/README.zh-CN.md

@@ -133,11 +133,12 @@ billion-context-pi 面向 **Pi** 编码代理(`@earendil-works/pi-coding-agent`)
 | `decompress` | 恢复之前压缩的块内容 |
 | `search_context` | 按关键词搜索已压缩块摘要(及可见消息) |
 | `acp_status` | 显示上下文用量、已压缩块、可压缩范围 |
+| `acp_rule` | 记录一条简短、原则性的提醒,穿越压缩保留(可选:`"rules": true`) |
 | `acp_delegate` | 为某个任务派生一个干净上下文的子代理(审查 / 调研 / 实现 / 规划 / 建议) |
 | `acp_delegate_wait` | 阻塞等待委派任务完成(返回结果,否则超时) |
 | `acp_delegate_cancel` | 按 runId 取消正在运行的委派任务 |
 
-`acp_delegate*` 四个工具是可选的:如果你自带子代理扩展,一个 `acp.json` 键即可关闭 —— 见下文*改用你自己的子代理*。
+`acp_delegate*` 四个工具是可选的:如果你自带子代理扩展,一个 `acp.json` 键即可关闭 —— 见下文*改用你自己的子代理*。`acp_rule` 同样是可选项 —— 默认关闭,在 `acp.json` 中设置 `"rules": true` 启用。
 
 ### acp_delegate — 干净上下文委派
 
@@ -155,7 +156,7 @@ billion-context-pi 面向 **Pi** 编码代理(`@earendil-works/pi-coding-agent`)
 
 Worker 运行在 Pi 的完整默认工具集上 - 不应用 `--tools` 白名单,因此任何已加载的扩展或自定义工具(如 ACP、LSP、MCP)保持可用。这确保主任务委派能力完整。上表中的 `read, edit, write, bash` 仅反映核心工具。
 
-委派的完整结果保存到文件(`/tmp/acp-delegate/<runId>.out`);工具结果和注入通知只携带**任务标题 + 文件路径**(无预览)- 需要细节时用 `read` 读取。这让父上下文保持精简。
+委派的完整结果保存到文件(`$TMPDIR/acp-delegate/<runId>.out`,默认 `/tmp/acp-delegate/<runId>.out`);工具结果和注入通知只携带**任务标题 + 文件路径**(无预览)- 需要细节时用 `read` 读取。这让父上下文保持精简。
 
 - **交互(TUI)与 RPC 模式**:`async:true`(默认)在后台运行子进程;完成时一条简短通知注入到聊天框。
 - **Print / JSON 模式**(`pi -p`、SDK):`async:true` 自动降级为**同步** — 结果在同一轮作为工具结果返回(父进程一轮后即退出,后台注入会丢失)。
@@ -218,7 +219,7 @@ billion-context-pi 自带的 `acp_delegate` 工具可独立工作。如果你另
 
 billion-context-pi 开箱即用,无需任何配置——它会自动读取模型的上下文窗口并应用合理的默认值。
 
-行为通过可选的 `acp.json` 配置文件(`~/.pi/acp.json` 为全局默认,`<项目>/.pi/acp.json` 为项目级覆盖)以及若干环境变量来调优。完整参考——每个 key、类型、默认值与优先级顺序——请查阅 **[CONFIGURATION.zh-CN.md](./CONFIGURATION.zh-CN.md)** ([English](./CONFIGURATION.md))。
+行为通过可选的 `acp.json` 配置文件(`~/.pi/agent/acp.json` 为全局默认,`<项目>/.pi/agent/acp.json` 为项目级覆盖)以及若干环境变量来调优。旧位置(`~/.pi/acp.json`、`<项目>/.pi/acp.json`)在新位置不存在时仍会被读取(向后兼容)。完整参考——每个 key、类型、默认值与优先级顺序——请查阅 **[CONFIGURATION.zh-CN.md](./CONFIGURATION.zh-CN.md)** ([English](./CONFIGURATION.md))。
 
 ### 日志
 

package/dist/{chunk-BKSJVDJY.js → chunk-TNMZCJIL.js}

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 // src/contract.ts
 var SIDECAR_SCHEMA_VERSION = 1;
 function sidecarProducer() {
-  return `billion-context-pi@${true ? "0.1.77" : "dev"}`;
+  return `billion-context-pi@${true ? "0.1.78" : "dev"}`;
 }
 
 export {
@@ -15,4 +15,4 @@ export {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer
 };
-//# sourceMappingURL=chunk-BKSJVDJY.js.map
+//# sourceMappingURL=chunk-TNMZCJIL.js.map

package/dist/compress-tool.d.ts

@@ -39,5 +39,6 @@ export declare function isCompressSuccessText(text: string): boolean;
  *  the retry cap applies. Non-panels ("No ranges provided.") stay neutral. */
 export declare function isCompressNoopText(text: string): boolean;
 export declare function blockSpanLabel(block: CompressionBlock, state: CompressionState): string;
+export declare function summaryFingerprintLine(blockId: string, summary: string): string;
 export declare function tierReadyHint(state: CompressionState, config: ReturnType<AcpRuntime["configFor"]>): string;
 export {};

package/dist/config-dir.d.ts

@@ -1 +1,12 @@
 export declare const CONFIG_DIR_NAME: string;
+/**
+ * Agent dir (e.g. ~/.pi/agent) with a host feature-detection fallback.
+ *
+ * Pi's getAgentDir() honors the host's agent-dir env override (<APP>_CODING_AGENT_DIR)
+ * and defaults to <home>/<CONFIG_DIR_NAME>/agent. Aliased hosts that do not re-export
+ * it would break a static named import exactly like the missing CONFIG_DIR_NAME did in
+ * #364, so we feature-detect through the same namespace import and fall back to Pi's
+ * default path shape. On such hosts the env override does not apply to this path
+ * (documented limitation; all real hosts running pi's code export it).
+ */
+export declare function getAgentDir(): string;

package/dist/config.d.ts

@@ -228,6 +228,29 @@ export interface AdapterConfig {
      *  none. Intended for cumulative-snapshot tools where each call supersedes
      *  the last. Settable via acp.json since #499. */
     protectedLatestTools?: string[];
+    /** Tool-name patterns (glob suffix allowed) EXCLUDED from the soft-protected
+     *  recent zone: matching tool results inside the recent window fold
+     *  immediately instead of aging out first (kernel >= 0.0.92). Default:
+     *  unset → kernel built-in ["decompress", "search_context", "read",
+     *  "bash"]. The built-in keeps read/bash compressible — the largest
+     *  reclaimable mass — but that also folds freshly-read files in batch-read
+     *  workflows (#1198-style fold→re-read loop, bili #1277). Recommended
+     *  remedy: ["decompress", "search_context", "bash"] (remove only read).
+     *  ⚠ Unlike the two protection keys, an EMPTY ARRAY IS VALID — it excludes
+     *  nothing and gives every tool recent-zone protection (escape hatch); do
+     *  not re-include decompress/search_context or just-restored blocks get
+     *  pinned in the recent zone and become unreclaimable. */
+    neverPreserveRecentTools?: string[];
+    /** The positive counterpart of neverPreserveRecentTools: tool-name
+     *  patterns REMOVED from the effective recent-zone exclusion list (kernel
+     *  >= 0.0.93) — `(neverPreserveRecentTools ?? built-in) minus
+     *  preserveRecentTools`. The one-entry #1198/#1277 batch-read fold→re-read
+     *  remedy: ["read"] protects fresh read results without restating (or
+     *  freezing a stale copy of) the built-in list. Default: unset → no
+     *  subtraction. Unlike neverPreserveRecentTools an EMPTY ARRAY IS
+     *  INVALID here (pure no-op — use neverPreserveRecentTools: [] for
+     *  protect-everything instead). */
+    preserveRecentTools?: string[];
     preserveRecentMessages?: number;
     /** Check npm for a newer billion-context-pi on startup and auto-install it. Default: true.
      *  Disable via `autoUpdate: false` or env `ACP_AUTO_UPDATE=0` to avoid all
@@ -293,13 +316,20 @@ export interface AdapterConfig {
      *  multi-session hosts (Prime RLM & co.) whose injected agent messages must
      *  delimit real turns. See docs/host-adapter.md. */
     hostSession?: boolean | HostSessionConfig;
+    /** Persistent-rules feature gate (#526): opt-in `rules: true` in acp.json.
+     *  Gates the human `/acp-rule` command (list + record + remove + clear — kernel
+     *  `listRules`/`addRule`/`removeRule`/`clearRules` against the session `.acp.json` sidecar state) and
+     *  the model-side `acp_rule` tool (#490). Custom limits via
+     *  coreOverrides.rules ({ maxRules?, maxRuleChars? }). */
+    rules?: boolean;
     /** Legacy flat alias for `delegate.displayUsage`. Kept for backward
      *  compatibility with existing acp.json files. Prefer `delegate.displayUsage`. */
     displayUsage?: "merged" | "separate";
     /** Override acp-kernel's load-bearing compression prompt rules (the 4
      *  Prompts fields). Each set field replaces the kernel default verbatim.
      *  Requires acknowledgePromptsRisk: true — without it, overrides are dropped
-     *  (defaults used) and a warning is logged. Set via ~/.pi/acp.json. */
+     *  (defaults used) and a warning is logged. Set via acp.json (see
+     *  CONFIGURATION.md for locations). */
     prompts?: Partial<Prompts>;
     /** Must be true for `prompts` overrides to take effect. Acknowledges that
      *  replacing the kernel's tuned compression rules may reduce summary quality

package/dist/contract.js

@@ -1,7 +1,7 @@
 import {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer
-} from "./chunk-BKSJVDJY.js";
+} from "./chunk-TNMZCJIL.js";
 export {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer