billion-context-pi 0.1.68 → 0.1.69-pr.416.231

package/README.md

@@ -10,6 +10,16 @@ The model decides <em>when</em> and <em>what</em> to compress — not a hard lim
 
 ---
 
+## 📄 Paper / Preprint
+
+- **[Model-Driven Incremental Hierarchical Compression: Training-Free Multi-Generational Context Management for Long-Lived Coding Agents](./paper/model-driven-incremental-hierarchical-compression-training-free-multi-generational-context-management-for-long-lived-coding-agents.md)** (English, v0.2)
+
+> 📝 **The paper itself is open-sourced under the MIT License as part of the codebase (`paper/`). It is a living document — anyone may edit it; improvements are welcome via pull request.**
+
+A production-scale longitudinal study: 4.5 months, three hosts, 174,327 model calls, 18.76B cumulative input tokens (~24.7B across all hosts), zero window violations on 204,800-token models, marathon sessions of 8,584–12,049 calls.
+
+---
+
 <p align="center">
 <a href="https://www.npmjs.com/package/billion-context-pi"><img src="https://img.shields.io/npm/v/billion-context-pi.svg?style=flat-square" alt="npm"></a>
 <a href="https://github.com/ranxianglei/billion-context-pi/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-pi.svg?style=flat-square" alt="license"></a>
@@ -66,10 +76,11 @@ pi install npm:billion-context-pi
 
 That's it. The extension auto-loads on next Pi startup. No configuration needed — it reads your model's context window automatically.
 
-> **Uninstall `pi-subagents` first (optional, recommended).** billion-context-pi ships its own `acp_delegate` sub-agent tool (see below) that replaces pi-subagents at a fraction of the context cost (~600 tok vs ~7K tok/turn). If you have pi-subagents installed, remove it to avoid duplicate delegation tools:
-> ```bash
-> pi remove npm:pi-subagents
-> ```
+> **Using another sub-agent extension?** billion-context-pi ships its own `acp_delegate` sub-agent tool (see below) at a fraction of the context cost (~600 tok vs ~7K tok/turn). Two delegation tools in one session only make the model's choice noisier, so pick one:
+> - **Use ACP's delegate** — remove the other extension: `pi remove npm:pi-subagents`
+> - **Keep your own sub-agent** — turn ACP's delegate off in `acp.json`: `{ "delegate": false }` (see *Using your own sub-agent instead* below)
+>
+> If you keep `pi-subagents` installed, billion-context-pi detects it at session start: a **project-level** install (`<cwd>/.pi/npm` or the project extensions dir) automatically stands `acp_delegate` down for that project — a reminder then tells you how to give pi-subagents' agents ACP compression via `/acp-subagents`. A **user-level-only** install (`~/.pi/npm`, user extensions dir) leaves `acp_delegate` active and logs a warning instead. Set `"delegate": { "forceEnable": true }` in `acp.json` to keep `acp_delegate` active regardless of detection.
 
 ## How it works
 
@@ -123,6 +134,8 @@ billion-context-pi is built for the **Pi** coding agent (`@earendil-works/pi-cod
 | `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.
+
 ### acp_delegate — clean-context delegation
 
 Hand a self-contained task to a fresh pi process running in a clean context. Five built-in roles, each with a system prompt and a **soft tool guardrail**:
@@ -147,6 +160,20 @@ The full delegate result is saved to a file (`/tmp/acp-delegate/<runId>.out`); t
 
 In the **interactive TUI**, async runs also show a live status widget below the editor (agent, elapsed seconds, task preview), so you always know what's running and for how long. Disabled automatically in RPC/print/JSON.
 
+#### Using your own sub-agent instead
+
+If you already run another sub-agent extension (pi-subagents, pi-lens, …), turn ACP's delegate off so the model is offered only one way to delegate. In `~/.pi/acp.json` (global) or `<project>/.pi/acp.json` (per project):
+
+```json
+{ "delegate": false }
+```
+
+- Equivalent object form: `{ "delegate": { "enabled": false } }`.
+- **What it removes:** the `acp_delegate`, `acp_delegate_wait` and `acp_delegate_cancel` tools, the `ACP_DELEGATE NOTIFICATIONS` system-prompt section, and the `ctrl+alt+f` fleet shortcut (`/acp-fleet` then reports that delegate is off). Compression is unaffected — `compress`, `decompress`, `search_context` and `acp_status` stay.
+- **When it applies:** the three tools are registered at session start, so a change needs a **new session** (or a Pi restart). The system-prompt section is resolved live on every turn, so it can disappear mid-session before the tools do.
+- Want to drop only the prompt section and keep the tools? Set `{ "delegatePrompt": null }`.
+- Pi's `--exclude-tools acp_delegate,acp_delegate_wait,acp_delegate_cancel` is **not** a substitute: it hides the tools but the model still receives the `ACP_DELEGATE NOTIFICATIONS` section describing tools it cannot call. Use `delegate: false`.
+
 ## `/acp` command
 
 Rich status display for the user:

package/README.zh-CN.md

@@ -8,6 +8,16 @@
 
 ---
 
+## 📄 论文 / 预印本
+
+- **[模型驱动的分层增量压缩:面向长寿命编码 Agent 的免训练多代上下文管理](./paper/模型驱动的分层增量压缩-免训练多代上下文管理.md)**(中文版,v0.2)
+
+> 📝 **论文本身与代码一同以 MIT 许可开源(位于 `paper/` 目录),是代码库的一部分 —— 这是一份活文档,任何人都可以编辑,欢迎提 PR 改进。**
+
+生产规模纵向研究:四个半月、三宿主、174,327 次模型调用、187.6 亿累计输入 token(三宿主合计约 247 亿),204,800-token 窗口零违规,马拉松会话 8,584–12,049 次调用。
+
+---
+
 <p align="center">
 <a href="https://www.npmjs.com/package/billion-context-pi"><img src="https://img.shields.io/npm/v/billion-context-pi.svg?style=flat-square" alt="npm"></a>
 <a href="https://github.com/ranxianglei/billion-context-pi/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/billion-context-pi.svg?style=flat-square" alt="license"></a>
@@ -65,10 +75,11 @@ pi install npm:billion-context-pi
 
 完成。扩展在下次 Pi 启动时自动加载。无需配置 —— 它会自动读取模型的上下文窗口。
 
-> **建议先卸载 `pi-subagents`(可选,推荐)。** billion-context-pi 自带 `acp_delegate` 子代理工具(见下文),以极低的上下文成本(~600 tok vs ~7K tok/轮)替代 pi-subagents。如果你已安装 pi-subagents,卸载它以避免重复的委派工具:
-> ```bash
-> pi remove npm:pi-subagents
-> ```
+> **你另有子代理扩展?** billion-context-pi 自带 `acp_delegate` 子代理工具(见下文),上下文成本极低(~600 tok vs ~7K tok/轮)。同一会话里两套委派工具只会让模型的选择更混乱,二选一:
+> - **用 ACP 的 delegate** —— 卸载另一个扩展:`pi remove npm:pi-subagents`
+> - **保留你自己的子代理** —— 在 `acp.json` 里关掉 ACP 的 delegate:`{ "delegate": false }`(见下文*改用你自己的子代理*)
+>
+> 若保留已安装的 `pi-subagents`,billion-context-pi 会在会话启动时检测:**项目级**安装(`<cwd>/.pi/npm` 或项目内 extensions 目录)会自动停用该项目的 `acp_delegate`,并提醒你运行 `/acp-subagents` 让 pi-subagents 的子代理获得 ACP 压缩;仅**用户级**(全局)安装时只记一条警告日志,`acp_delegate` 保持启用。在 `acp.json` 中设置 `"delegate": { "forceEnable": true }` 可在检测到第三方子代理时仍强制保留 `acp_delegate`。
 
 ## 工作原理
 
@@ -122,6 +133,8 @@ billion-context-pi 面向 **Pi** 编码代理(`@earendil-works/pi-coding-agent`)
 | `acp_delegate_wait` | 阻塞等待委派任务完成(返回结果,否则超时) |
 | `acp_delegate_cancel` | 按 runId 取消正在运行的委派任务 |
 
+`acp_delegate*` 四个工具是可选的:如果你自带子代理扩展,一个 `acp.json` 键即可关闭 —— 见下文*改用你自己的子代理*。
+
 ### acp_delegate — 干净上下文委派
 
 把一个自包含的任务交给一个运行在干净上下文中的新 pi 进程。五个内置角色,各自有系统提示和**软工具护栏**:
@@ -145,6 +158,20 @@ Worker 运行在 Pi 的完整默认工具集上 - 不应用 `--tools` 白名单,
 
 在**交互 TUI** 中,异步运行还会在编辑器下方显示一个实时状态 widget(角色、已运行秒数、任务预览),让你随时知道什么在跑、跑了多久。RPC/print/JSON 模式自动禁用。
 
+#### 改用你自己的子代理
+
+如果你已经在用别的子代理扩展(pi-subagents、pi-lens 等),关掉 ACP 的 delegate,让模型只有一条委派路径。在 `~/.pi/acp.json`(全局)或 `<项目>/.pi/acp.json`(项目级):
+
+```json
+{ "delegate": false }
+```
+
+- 等价对象写法:`{ "delegate": { "enabled": false } }`。
+- **关掉的是什么:**`acp_delegate`、`acp_delegate_wait`、`acp_delegate_cancel` 三个工具,`ACP_DELEGATE NOTIFICATIONS` 系统提示段,以及 `ctrl+alt+f` 快捷键(此时 `/acp-fleet` 会提示 delegate 未启用)。压缩本身不受影响 —— `compress`、`decompress`、`search_context`、`acp_status` 全部保留。
+- **生效时机:**三个工具在会话启动时注册,因此需要**新会话**(或重启 Pi)。系统提示段每回合实时解析,可能在工具之前先消失。
+- 只想去掉提示段、保留工具?设 `{ "delegatePrompt": null }`。
+- Pi 原生的 `--exclude-tools acp_delegate,acp_delegate_wait,acp_delegate_cancel` **不能**替代:它藏起工具,但模型仍会收到描述这些工具的 `ACP_DELEGATE NOTIFICATIONS` 段。请用 `delegate: false`。
+
 ## `/acp` 命令
 
 为用户提供丰富的状态显示:

package/dist/compress-tool.d.ts

@@ -1,6 +1,7 @@
 import { Type, type Static } from "typebox";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AcpRuntime } from "./runtime.js";
+import { type ToolPromptOverrides } from "./surface.js";
 import { type CompressionBlock, type CompressionState } from "acp-kernel";
 declare const RangeSpec: Type.TObject<{
     startId: Type.TString;
@@ -19,7 +20,7 @@ declare const CompressParams: Type.TObject<{
     summaryMaxChars: Type.TOptional<Type.TNumber>;
 }>;
 type CompressArgs = Static<typeof CompressParams>;
-export declare function makeCompressTool(runtime: AcpRuntime): ToolDefinition<typeof CompressParams>;
+export declare function makeCompressTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides): ToolDefinition<typeof CompressParams>;
 type RangeEntry = Static<typeof RangeSpec>;
 export declare function normalizeRanges(args: CompressArgs): RangeEntry[] | string;
 export declare function tailRepair(s: string): string | undefined;

package/dist/config.d.ts

@@ -2,6 +2,12 @@ import { type Config, type Prompts } from "acp-kernel";
 import type { CompressReasoningConfig } from "./reasoning-drop.js";
 import type { DegenerationGuardConfig } from "./degeneration.js";
 import type { ThrottleRetryConfig } from "./throttle-retry.js";
+import type { PiPromptSections } from "./system-prompt.js";
+import type { NudgeSectionsConfig, ToolPromptsConfig } from "./surface.js";
+/** Default TUI shortcut for the acp_delegate fleet inspector. Moved off
+ *  "ctrl+alt+f" (also claimed by pi-subagents) to avoid a cross-extension
+ *  conflict Pi's loader only warns about — last-loaded silently wins (#412). */
+export declare const DEFAULT_FLEET_SHORTCUT = "ctrl+alt+d";
 /** Per-role delegate defaults. Lets long-lived automation pin a cheaper or
  *  more capable model and a thinking level per delegate role, so the main
  *  agent doesn't have to fill them in on every `acp_delegate()` call. */
@@ -23,6 +29,13 @@ export interface DelegateConfig {
     /** Enable acp_delegate tools (delegate/wait/cancel) and their system-prompt
      *  section. Default: true. Set `enabled: false` to skip registering them. */
     enabled?: boolean;
+    /** Keep acp_delegate active even when a third-party subagent extension
+     *  (pi-subagents) is installed. Default: false — when pi-subagents is
+     *  detected at session start, acp_delegate stands down (tools, fleet
+     *  shortcut and system-prompt section skipped) to avoid two overlapping
+     *  sub-agent systems, and a reminder points at /acp-subagents so the
+     *  third-party agents can still get ACP compression tools (#415). */
+    forceEnable?: boolean;
     /** How delegate usage is reported back to the main session.
      *  "separate" (default) — delegate tokens tracked in a separate accumulator;
      *  main session totals stay clean, delegate usage shows as its own block in
@@ -70,12 +83,22 @@ export interface DelegateConfig {
      *  saw the result, so re-injecting it would only waste context.
      *  "always" — always inject the notification (previous behavior). */
     notifyIfRead?: "skip" | "always";
+    /** Keybinding for the interactive TUI shortcut that opens the acp_delegate
+     *  fleet inspector (live list + transcript). Default: "ctrl+alt+d". Set to
+     *  "" (empty string) to disable keyboard registration entirely — the
+     *  inspector stays reachable via /acp-fleet. Moved off the previous hardcoded
+     *  "ctrl+alt+f" because pi-subagents also claims ctrl+alt+f, and Pi's loader
+     *  only warns + last-loaded-wins on cross-extension conflicts (#412). */
+    fleetShortcut?: string;
 }
 /** Resolved delegate policy: what actually takes effect after merging acp.json,
  *  env overrides and defaults. Timeout fields are milliseconds; null means the
  *  corresponding timeout/watchdog is disabled. */
 export interface DelegatePolicy {
     enabled: boolean;
+    /** Resolved delegate.forceEnable (default false): keep acp_delegate even
+     *  when a third-party subagent extension (pi-subagents) is installed (#415). */
+    forceEnable: boolean;
     displayUsage: "merged" | "separate";
     maxDepth: number;
     syncTimeoutMs: number | null;
@@ -90,6 +113,8 @@ export interface DelegatePolicy {
     /** Whether to suppress the completion notification when the model already
      *  read the result file after the run finished. Always resolved ("skip" default). */
     notifyIfRead: "skip" | "always";
+    /** Resolved TUI shortcut for the fleet inspector ("" = registration disabled). */
+    fleetShortcut: string;
 }
 export declare const DEFAULT_DELEGATE_POLICY: DelegatePolicy;
 /** Compression tuning fields, shared by all three levels (global, provider,
@@ -120,6 +145,13 @@ export interface CompressSettings {
      *  tool calls — see CompressReasoningConfig in src/reasoning-drop.ts.
      *  Merged field-wise (drop, threshold) across the three levels. */
     reasoning?: CompressReasoningConfig;
+    /** Active prompt pack name (see CONFIGURATION.md “Prompt packs”). Base
+     *  level; override per provider/model via `providers`. "default" or unset =
+     *  built-in defaults. Resolved per request against the live model, so
+     *  switching models mid-session switches the pack. Packs ship text-level
+     *  overrides only; a pack's `toolPrompts` follow the base selection (tool
+     *  definitions freeze at extension load, before the model is known). */
+    promptPack?: string;
 }
 /** Per-provider compression overrides. Carries the same tuning fields as the
  *  global level, plus an optional per-model map keyed by model id. */
@@ -193,13 +225,13 @@ export interface AdapterConfig {
      *  unbounded behavior). */
     toolBashDefaultTimeout?: number;
     /** Hard byte cap applied to tool result text via the `tool_result` hook.
-     *  Default: 200000 (~200KB, roughly 5000 lines at ~40 bytes/line) — a
-     *  generous ceiling that stops runaway output. Pi already caps bash/read/grep
-     *  at 50KB/2000 lines (bash full output is saved to a temp file), so this
-     *  default mainly caps tools Pi doesn't cap. Set lower (e.g. 8192) for a
-     *  tighter context budget, or 0 to disable. When capped, oversized text is
-     *  head-truncated with a notice telling the model how to see the full output
-     *  (bash: read BashToolDetails.fullOutputPath). */
+     *  Default: 50000 (~50KB) — aligned with Pi's own bash/read/grep cap so
+     *  every tool path lands under one ceiling; the net still catches runaway
+     *  output from tools Pi does not cap (MCP/custom). Set higher for large
+     *  MCP outputs, lower (e.g. 8192) for a tighter context budget, or 0 to
+     *  disable. When capped, oversized text is head-truncated with a notice
+     *  telling the model how to see the full output (bash: read
+     *  BashToolDetails.fullOutputPath). */
     toolOutputMaxBytes?: number;
     /** Delegate sub-agent config. Accepts a boolean shorthand (`true` →
      *  `{ enabled: true }`, `false` → `{ enabled: false }`) or a DelegateConfig
@@ -252,10 +284,25 @@ export interface AdapterConfig {
      *  replacing the kernel's tuned compression rules may reduce summary quality
      *  (lost paths/signatures/decisions → worse retrieval). */
     acknowledgePromptsRisk?: boolean;
+    /** Override structural sections of the ACP system prompt (ACP TAGS, TOOLS,
+     *  WHEN TO COMPRESS, ...). Tri-state per section: string = replace, null =
+     *  remove, omitted = default. Not risk-gated — these are documentation
+     *  sections, not compression rules. Set via acp.json. */
+    promptSections?: Partial<PiPromptSections>;
+    /** Override guidance-class nudge texts (efficiencyNote, emergencyHeader,
+     *  t2Guidance, t3Guidance). Same tri-state semantics. Not risk-gated. */
+    nudgeSections?: NudgeSectionsConfig;
+    /** Override the four ACP tool definitions' LLM-facing text (description,
+     *  paramDescriptions, promptSnippet, promptGuidelines). Read synchronously
+     *  at extension load — tool defs are frozen at registration time. */
+    toolPrompts?: ToolPromptsConfig;
+    /** Replace (string) or remove (null) the ACP_DELEGATE_NOTIFICATIONS appendix
+     *  injected when the delegate tool is enabled. */
+    delegatePrompt?: string | null;
     coreOverrides?: Partial<Config>;
 }
 export declare const DEFAULT_TOOL_BASH_TIMEOUT = 60;
-export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 200000;
+export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 50000;
 /** Resolve delegate config from the adapter, handling the boolean shorthand
  *  and the legacy flat `displayUsage` alias. Precedence: env > acp.json >
  *  default (same convention as ACP_MODEL_CONTEXT_LIMIT). Invalid values fall

package/dist/decompress-tool.d.ts

@@ -1,11 +1,12 @@
 import { Type } from "typebox";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AcpRuntime } from "./runtime.js";
+import { type ToolPromptOverrides } from "./surface.js";
 declare const DecompressParams: Type.TObject<{
     blockId: Type.TString;
     full: Type.TOptional<Type.TBoolean>;
     toFile: Type.TOptional<Type.TString>;
     inline: Type.TOptional<Type.TBoolean>;
 }>;
-export declare function makeDecompressTool(runtime: AcpRuntime): ToolDefinition<typeof DecompressParams>;
+export declare function makeDecompressTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides): ToolDefinition<typeof DecompressParams>;
 export {};

package/dist/fleet-widget.d.ts

@@ -6,8 +6,9 @@ interface WidgetRun {
     startedAt: number;
 }
 type RunsSnapshot = () => WidgetRun[];
+export declare function formatShortcutLabel(shortcut: string): string;
 export declare const delegateStatusWidget: {
-    setContext(ctx: ExtensionContext, snapshot: RunsSnapshot): void;
+    setContext(ctx: ExtensionContext, snapshot: RunsSnapshot, shortcut?: string): void;
     dispose(): void;
     poke(): void;
 };