billion-context-pi 0.1.24 → 0.1.26

package/README.md

@@ -3,7 +3,7 @@
 [English](./README.md) | [中文](./README.zh-CN.md)
 
 <p align="center">
-<strong>Active Context Pruning</strong> for <a href="https://pi.dev">Pi</a>
+<strong>Billion-Context</strong> for <a href="https://pi.dev">Pi</a>
 <br />
 The model decides <em>when</em> and <em>what</em> to compress — not a hard limit.
 </p>
@@ -24,9 +24,9 @@ The model decides <em>when</em> and <em>what</em> to compress — not a hard lim
 
 ## Why?
 
-When conversations get long, the model runs out of context. Most tools hard-truncate — silently dropping earlier messages. **ACP** gives the model a `compress` tool: the LLM decides **when** and **what** to compress into high-fidelity summaries, preserving critical details (file paths, decisions, error strings) while reclaiming context space.
+When conversations get long, the model runs out of context. Most tools hard-truncate — silently dropping earlier messages. **billion-context** gives the model a `compress` tool: the LLM decides **when** and **what** to compress into high-fidelity summaries, preserving critical details (file paths, decisions, error strings) while reclaiming context space.
 
-Unlike Pi's built-in auto-compaction (which replaces everything with a single summary), ACP:
+Unlike Pi's built-in auto-compaction (which replaces everything with a single summary), billion-context:
 - **Preserves structure** — compressed ranges become labeled blocks you can decompress later
 - **Multi-tier** — summaries can be further distilled (T1 → T2 → T3) as sessions grow
 - **Searchable** — `search_context` finds information inside compressed blocks without decompressing
@@ -52,7 +52,7 @@ That's it. The extension auto-loads on next Pi startup. No configuration needed
 
 ## How it works
 
-ACP intercepts Pi's `context` event (fired before each LLM call) and runs an 8-stage pipeline:
+billion-context intercepts Pi's `context` event (fired before each LLM call) and runs an 8-stage pipeline:
 
 ```
 assign refs → sync blocks → prune → filter → hide calls → recommend → nudge → emergency truncate
@@ -60,7 +60,17 @@ assign refs → sync blocks → prune → filter → hide calls → recommend
 
 Each message gets an invisible `<acp>` ref tag (`m00001`, `m00002`, ...) visible to the model but not the user. The model uses these refs to specify compression ranges.
 
-Pi's built-in auto-compaction is cancelled — ACP is the sole context manager.
+Pi's built-in auto-compaction is cancelled — billion-context is the sole context manager.
+
+## Plugin compatibility & ordering
+
+billion-context takes over context management by intercepting Pi's `context` event. **Pi has no plugin priority mechanism** — when multiple extensions register handlers for the same event, they run in a fixed sequence (load order), with no `priority`/`weight` field and no way for the user to control the order. The `context` event specifically is a *pipeline*: every handler receives the previous handler's output, there is no short-circuit, and the **last** handler has the final say over what reaches the model.
+
+This has two practical implications:
+
+1. **Keep exactly one context-compression plugin installed.** If you run two compression plugins together (e.g. billion-context-pi alongside another), both will rewrite the message list and clobber each other's work — compressed ranges can be re-expanded or corrupted. Pi's built-in auto-compaction is already cancelled automatically by billion-context-pi, but any *third-party* compression/compaction extension should be uninstalled.
+
+2. **Even with a single compression plugin, interference is still possible in rare cases.** Load order under Pi is determined by filesystem discovery order (`fs.readdirSync` over `.pi/extensions/` → global → packages), which is not fully deterministic. If another (non-compression) extension also hooks the `context` event and happens to load *after* billion-context-pi, it could modify the compressed output. billion-context-pi rebuilds its working set from the session log rather than the chained input, which makes it robust to handlers that run *before* it — but it cannot defend against a handler that runs *after* it. This is a limitation of Pi's extension model; if you observe unexpected context behavior, check whether other installed extensions intercept the `context` event.
 
 ## Model-facing tools
 
@@ -76,17 +86,21 @@ Pi's built-in auto-compaction is cancelled — ACP is the sole context manager.
 
 ### 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 tailored tool whitelist and system prompt:
+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**:
 
 | Role | Tools | Best for |
 |------|-------|----------|
-| `reviewer` | read, bash | Read-only code review (bugs, risks, file:line) |
-| `researcher` | read, bash | Read-only codebase investigation |
+| `reviewer` | read, bash, grep, find, ls + ACP | Read-only code review (bugs, risks, file:line) |
+| `researcher` | read, bash, grep, find, ls + ACP | Read-only codebase investigation |
 | `worker` | read, edit, write, bash | Make code changes |
-| `planner` | read, bash | Analyze + propose a step-by-step plan |
-| `oracle` | read, bash | Answer questions / advise |
+| `planner` | read, bash, grep, find, ls + ACP | Analyze + propose a step-by-step plan |
+| `oracle` | read, bash, grep, find, ls + ACP | Answer questions / advise |
+
+Read-only roles (reviewer, researcher, planner, oracle) receive a restricted tool allowlist (`read, bash, grep, find, ls`) plus ACP context tools (`compress, decompress, search_context, acp_status`) so they can manage their own context. This prevents accidental file modifications, but `bash` can bypass it - **it is a guardrail, not a security boundary**.
+
+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 (`/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.
 - **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).
@@ -132,7 +146,9 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
   "debug": false,
   "autoUpdate": true,
   "modelContextLimit": 200000,
-  "delegate": true
+  "delegate": true,
+  "toolBashDefaultTimeout": 60,
+  "toolOutputMaxBytes": 200000
 }
 ```
 
@@ -142,8 +158,10 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
 | `autoUpdate` | `true` | On Pi startup, check npm for a newer version and auto-install it (throttled to one check per 3 minutes). Disable to avoid all startup network calls. |
 | `modelContextLimit` | *(auto)* | Override the context limit (in tokens). Defaults to the model's `contextWindow`. |
 | `delegate` | `true` | Enable the `acp_delegate` tools (delegate/wait/cancel) and their system-prompt section. Set `false` to skip registering them (e.g. you use a different sub-agent extension, or run headless where async injection adds no value). |
+| `toolBashDefaultTimeout` | `60` | Seconds injected into the `bash` tool when the model omits `timeout`. Pi has **no** default of its own, so without this a forgotten timeout can hang for thousands of seconds. On timeout the model is guided to re-run with a larger `timeout`. `0` restores Pi's unbounded behavior. |
+| `toolOutputMaxBytes` | `200000` | Hard byte cap on tool result text (~5000 lines at ~40 B/line; applied via the `tool_result` hook). Stops runaway output that Pi's own 50KB/2000-line cap can't catch (e.g. tools Pi doesn't cap). When it fires the model is told how to see the full output — for `bash` the full output is in its temp file (`BashToolDetails.fullOutputPath`); set lower (e.g. `8192`) for a tighter context budget, or `0` to disable. |
 
-> **Only these four keys are read from `acp.json`.** Other tuning knobs (`preserveRecentMessages`, `protectedTools`, nudge thresholds) are code-level and not user-overridable.
+> **Only these six keys are read from `acp.json`.** Other tuning knobs (`preserveRecentMessages`, `protectedTools`, nudge thresholds) are code-level and not user-overridable.
 
 ### Environment variables
 
@@ -159,7 +177,7 @@ The model receives detailed guidance (in its system prompt) on **when** to compr
 
 ### What gets protected
 
-ACP protects three categories of content from compression:
+billion-context protects three categories of content from compression:
 
 1. **Always-protected tools** — `compress` calls are hard-protected (they're load-bearing metadata; compressing them breaks decompress and the "summary is historical" contract).
 2. **Soft recent-zone** — the last N messages (default 5) and last ~5K tokens are soft-protected so the model keeps its working set. Tool results from `decompress`, `search_context`, `read`, and `bash` are **excluded** from this zone: they're large and meant to be compressible once consumed, so they don't eat the protected budget.

package/README.zh-CN.md

@@ -1,7 +1,7 @@
 [English](./README.md) | [中文](./README.zh-CN.md)
 
 <p align="center">
-<strong>主动上下文剪枝</strong> — <a href="https://pi.dev">Pi</a> 的 ACP 插件
+<strong>Billion-Context</strong> — <a href="https://pi.dev">Pi</a> 的上下文压缩插件
 <br />
 由模型决定<em>何时</em>压缩、压缩<em>什么</em> — 而非硬性截断。
 </p>
@@ -20,11 +20,11 @@
 
 ---
 
-## 为什么选择 ACP
+## 为什么选择 billion-context
 
-当对话变长,模型的上下文会耗尽。多数工具采用硬截断 —— 静默丢弃早期消息。**ACP** 把 `compress` 工具交给模型:由 LLM 决定**何时**压缩、压缩**什么**,将内容压缩成高保真摘要,在回收上下文空间的同时保留关键细节(文件路径、决策、错误字符串)。
+当对话变长,模型的上下文会耗尽。多数工具采用硬截断 —— 静默丢弃早期消息。**billion-context** 把 `compress` 工具交给模型:由 LLM 决定**何时**压缩、压缩**什么**,将内容压缩成高保真摘要,在回收上下文空间的同时保留关键细节(文件路径、决策、错误字符串)。
 
-与 Pi 内置的自动压缩(把所有内容替换成单个摘要)不同,ACP:
+与 Pi 内置的自动压缩(把所有内容替换成单个摘要)不同,billion-context:
 
 - **保留结构** — 压缩的范围变成带标签的块,可后续解压
 - **多级压缩** — 摘要可被进一步蒸馏(T1 → T2 → T3),随会话增长保持有界
@@ -51,7 +51,7 @@ pi install npm:billion-context-pi
 
 ## 工作原理
 
-ACP 拦截 Pi 的 `context` 事件(每次 LLM 调用前触发),运行一个 8 阶段管线:
+billion-context 拦截 Pi 的 `context` 事件(每次 LLM 调用前触发),运行一个 8 阶段管线:
 
 ```
 assign refs → sync blocks → prune → filter → hide calls → recommend → nudge → emergency truncate
@@ -59,7 +59,17 @@ assign refs → sync blocks → prune → filter → hide calls → recommend
 
 每条消息获得一个不可见的 `<acp>` 引用标签(`m00001`、`m00002`、...),对模型可见但用户不可见。模型用这些引用来指定压缩范围。
 
-Pi 内置的自动压缩会被取消 —— ACP 是唯一的上下文管理者。
+Pi 内置的自动压缩会被取消 —— billion-context 是唯一的上下文管理者。
+
+## 插件兼容性与排序
+
+billion-context 通过拦截 Pi 的 `context` 事件接管上下文管理。**Pi 没有插件优先级机制** —— 当多个扩展为同一个事件注册 handler 时,它们按固定顺序(加载顺序)执行,没有 `priority`/`weight` 字段,用户也无法控制顺序。`context` 事件尤其是一个*管线*:每个 handler 都接收上一个 handler 的输出,没有短路,**最后一个** handler 对发给模型的内容拥有最终决定权。
+
+这带来两个实际影响:
+
+1. **只保留一个上下文压缩插件。** 如果同时运行两个压缩插件(例如 billion-context-pi 和另一个),它们都会改写消息列表、互相覆盖 —— 已压缩的范围可能被重新展开或破坏。Pi 的内置自动压缩已由 billion-context-pi 自动取消,但任何*第三方*压缩/compaction 扩展都应卸载。
+
+2. **即使只有一个压缩插件,在少数情况下仍可能出现干扰。** Pi 下的加载顺序由文件系统发现顺序(`fs.readdirSync` 遍历 `.pi/extensions/` → 全局 → 包)决定,并不完全确定。如果另一个(非压缩类)扩展也 hook 了 `context` 事件、且恰好加载在 billion-context-pi *之后*,它可能修改压缩后的输出。billion-context-pi 从会话日志重建工作集(而非链式输入),这让它对*排在它之前*的 handler 鲁棒 —— 但无法防御*排在它之后*的 handler。这是 Pi 扩展模型的固有限制;若你观察到上下文行为异常,请检查是否有其他已安装扩展拦截了 `context` 事件。
 
 ## 模型工具
 
@@ -75,17 +85,21 @@ Pi 内置的自动压缩会被取消 —— ACP 是唯一的上下文管理者
 
 ### acp_delegate — 干净上下文委派
 
-把一个自包含的任务交给一个运行在干净上下文中的新 pi 进程。五个内置角色,各自有定制的工具白名单和系统提示:
+把一个自包含的任务交给一个运行在干净上下文中的新 pi 进程。五个内置角色,各自有系统提示和**软工具护栏**:
 
 | 角色 | 工具 | 适用场景 |
 |------|------|----------|
-| `reviewer` | read, bash | 只读代码审查(bug、风险、file:line) |
-| `researcher` | read, bash | 只读代码库调研 |
+| `reviewer` | read, bash, grep, find, ls + ACP | 只读代码审查(bug、风险、file:line) |
+| `researcher` | read, bash, grep, find, ls + ACP | 只读代码库调研 |
 | `worker` | read, edit, write, bash | 修改代码 |
-| `planner` | read, bash | 分析 + 提出分步计划 |
-| `oracle` | read, bash | 回答问题 / 建议 |
+| `planner` | read, bash, grep, find, ls + ACP | 分析 + 提出分步计划 |
+| `oracle` | read, bash, grep, find, ls + ACP | 回答问题 / 建议 |
+
+只读角色(reviewer、researcher、planner、oracle)获得受限工具白名单(`read, bash, grep, find, ls`)+ ACP 上下文工具(`compress, decompress, search_context, acp_status`),以便管理自己的上下文。这能防止意外修改文件,但 `bash` 可绕过 - **这是护栏,不是安全边界**。
+
+Worker 运行在 Pi 的完整默认工具集上 - 不应用 `--tools` 白名单,因此任何已加载的扩展或自定义工具(如 ACP、LSP、MCP)保持可用。这确保主任务委派能力完整。上表中的 `read, edit, write, bash` 仅反映核心工具。
 
-委派的完整结果保存到文件(`/tmp/acp-delegate/<runId>.out`);工具结果和注入通知只携带**任务标题 + 文件路径**(无预览)— 需要细节时用 `read` 读取。这让父上下文保持精简。
+委派的完整结果保存到文件(`/tmp/acp-delegate/<runId>.out`);工具结果和注入通知只携带**任务标题 + 文件路径**(无预览)- 需要细节时用 `read` 读取。这让父上下文保持精简。
 
 - **交互(TUI)与 RPC 模式**:`async:true`(默认)在后台运行子进程;完成时一条简短通知注入到聊天框。
 - **Print / JSON 模式**(`pi -p`、SDK):`async:true` 自动降级为**同步** — 结果在同一轮作为工具结果返回(父进程一轮后即退出,后台注入会丢失)。
@@ -131,7 +145,9 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
   "debug": false,
   "autoUpdate": true,
   "modelContextLimit": 200000,
-  "delegate": true
+  "delegate": true,
+  "toolBashDefaultTimeout": 60,
+  "toolOutputMaxBytes": 200000
 }
 ```
 
@@ -141,8 +157,10 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
 | `autoUpdate` | `true` | Pi 启动时检查 npm 是否有更新版本并自动安装(限频:每 3 分钟最多一次检查)。禁用以避免所有启动时的网络请求。 |
 | `modelContextLimit` | *(自动)* | 覆盖上下文上限(token 数)。默认为模型的 `contextWindow`。 |
 | `delegate` | `true` | 启用 `acp_delegate` 工具(delegate/wait/cancel)及其系统提示词段落。设为 `false` 则不注册这些工具(例如你用了别的子代理扩展,或跑 headless 场景异步注入没有意义)。 |
+| `toolBashDefaultTimeout` | `60` | 当模型未指定 `timeout` 时注入 `bash` 工具的超时秒数。Pi **本身没有默认超时**,不加这个,一次遗漏的超时可能挂起几千秒。超时后会提示模型用更大的 `timeout` 重跑。设为 `0` 恢复 Pi 的无界行为。 |
+| `toolOutputMaxBytes` | `200000` | 工具结果文本硬上限(字节,约 5000 行 @ ~40 字节/行,通过 `tool_result` hook 应用)。用于兜住 Pi 自身 50KB/2000 行截断管不到的输出(例如 Pi 未加限制的工具)。触发截断时会告诉模型如何查看完整输出——对 `bash`,完整输出在其临时文件(`BashToolDetails.fullOutputPath`)中;设更小(如 `8192`)可更省上下文,设 `0` 关闭。 |
 
-> **只有这四个 key 会被 `acp.json` 读取。** 其他调优参数(`preserveRecentMessages`、`protectedTools`、nudge 阈值)是代码级的,不向用户开放。
+> **只有这六个 key 会被 `acp.json` 读取。** 其他调优参数(`preserveRecentMessages`、`protectedTools`、nudge 阈值)是代码级的,不向用户开放。
 
 ### 环境变量
 
@@ -158,7 +176,7 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
 
 ### 哪些内容会被保护
 
-ACP 保护三类内容不被压缩:
+billion-context 保护三类内容不被压缩:
 
 1. **永久保护的工具** — `compress` 调用被硬保护(它们是承载关键元数据的;压缩它们会破坏 decompress 和"摘要是历史"的契约)。
 2. **软近期区** — 最后 N 条消息(默认 5)和最后约 5K token 被软保护,让模型保留工作集。来自 `decompress`、`search_context`、`read`、`bash` 的工具结果被**排除**出此区:它们体量大、消费后就该能压缩,所以不该占用保护预算。

package/dist/config.d.ts

@@ -20,6 +20,24 @@ export interface AdapterConfig {
      *  section. Default: true. Set `delegate: false` (adapter config or
      *  ~/.pi/acp.json) to skip registering them. */
     delegate?: boolean;
+    /** Default timeout in seconds injected into the bash tool when the model
+     *  omits `timeout`. Pi has NO built-in default, so without this a command
+     *  that the model forgets to time out can hang for thousands of seconds.
+     *  Default: 60 (catches hangs quickly). On timeout the model is guided to
+     *  re-run with a larger `timeout`. Set to 0 to disable (restore Pi's
+     *  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). */
+    toolOutputMaxBytes?: number;
     coreOverrides?: Partial<Config>;
 }
+export declare const DEFAULT_TOOL_BASH_TIMEOUT = 60;
+export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 200000;
 export declare function resolveConfig(adapter: AdapterConfig, liveContextLimit: number): Config;

package/dist/delegate-tool.d.ts

@@ -1,5 +1,5 @@
-import { Type } from "typebox";
-import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 /** Snapshot of currently-running delegate runs, for the TUI status widget. */
 export declare function runningRunsSnapshot(): {
     runId: string;
@@ -14,6 +14,7 @@ declare const DelegateParams: Type.TObject<{
     model: Type.TOptional<Type.TString>;
     async: Type.TOptional<Type.TBoolean>;
 }>;
+type DelegateArgs = Static<typeof DelegateParams>;
 declare const CancelParams: Type.TObject<{
     runId: Type.TString;
 }>;
@@ -22,6 +23,22 @@ declare const WaitParams: Type.TObject<{
     timeout: Type.TOptional<Type.TInteger>;
 }>;
 export declare function makeDelegateTool(pi: ExtensionAPI): ToolDefinition<typeof DelegateParams>;
+/** If the delegate already delivered its result via a system notification
+ *  (the close handler injected before this wait was called), return a short
+ *  "already delivered" message pointing at the result file, so the model
+ *  never sees the same result twice (once via the injected notification,
+ *  once via this tool result). Returns null when the run was NOT injected,
+ *  in which case the caller delivers the full payload via formatRunResult(). */
+export declare function injectedWaitMessage(run: {
+    injected?: boolean;
+    result?: {
+        file: string;
+    };
+}, runId: string, remainingLine: string): string | null;
 export declare function makeDelegateWaitTool(_pi: ExtensionAPI): ToolDefinition<typeof WaitParams>;
 export declare function makeDelegateCancelTool(_pi: ExtensionAPI): ToolDefinition<typeof CancelParams>;
+export declare function buildChildArgs(args: DelegateArgs, rolePrompt: string, ctx: ExtensionContext): Promise<{
+    cliArgs: string[];
+    tmpDir: string;
+}>;
 export {};