billion-context-pi 0.1.34 → 0.1.36

package/README.md

@@ -148,7 +148,10 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
   "modelContextLimit": 200000,
   "delegate": true,
   "toolBashDefaultTimeout": 60,
-  "toolOutputMaxBytes": 200000
+  "toolOutputMaxBytes": 200000,
+  "maxContextLimit": "75%",
+  "emergencyThresholdPercent": "95%",
+  "nudgeGrowthTokens": 50000
 }
 ```
 
@@ -160,8 +163,11 @@ Create `~/.pi/acp.json` (global) and/or `<project>/.pi/acp.json` (project-local,
 | `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. |
+| `maxContextLimit` | `"75%"` | Context usage threshold that triggers **forced compression** nudges (bypasses growth-gate + cadence). Accepts a ratio (`0.75`) or percent string (`"75%"`). Lower = compress earlier / more aggressively. Maps to kernel `nudge.maxContextLimitPct`. |
+| `emergencyThresholdPercent` | `"95%"` | Context usage threshold that triggers **emergency truncation** of large tool outputs to keep the session alive. Accepts a ratio (`0.95`) or percent string (`"95%"`). Must be ≥ `maxContextLimit`. Maps to kernel `nudge.emergencyThresholdPct` + `truncate.threshold`. |
+| `nudgeGrowthTokens` | `50000` | Token growth step for soft compression nudges. A nudge fires roughly every time this many tokens become compressible. Lower = compress more often; higher = compress less often. Maps to kernel `nudge.growthFloor` + `nudge.growthCap`. |
 
-> **Only these six keys are read from `acp.json`.** Other tuning knobs (`preserveRecentMessages`, `protectedTools`, nudge thresholds) are code-level and not user-overridable.
+> **Only these nine keys are read from `acp.json`.** Other tuning knobs (`preserveRecentMessages`, `protectedTools`) are code-level and not user-overridable. The three nudge thresholds (`maxContextLimit`, `emergencyThresholdPercent`, `nudgeGrowthTokens`) form a three-tier escalation: growth-driven soft nudges → forced nudges at `maxContextLimit` → emergency truncation at `emergencyThresholdPercent`.
 
 ### Environment variables
 

package/README.zh-CN.md

@@ -147,7 +147,10 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
   "modelContextLimit": 200000,
   "delegate": true,
   "toolBashDefaultTimeout": 60,
-  "toolOutputMaxBytes": 200000
+  "toolOutputMaxBytes": 200000,
+  "maxContextLimit": "75%",
+  "emergencyThresholdPercent": "95%",
+  "nudgeGrowthTokens": 50000
 }
 ```
 
@@ -159,8 +162,11 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
 | `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` 关闭。 |
+| `maxContextLimit` | `"75%"` | 上下文使用率达到此值时触发**强制压缩** nudge(绕过增长门控 + 频率限制)。支持比例(`0.75`)或百分比字符串(`"75%"`)。调小 → 更早/更激进压缩。映射到内核 `nudge.maxContextLimitPct`。 |
+| `emergencyThresholdPercent` | `"95%"` | 上下文使用率达到此值时触发**紧急截断**,硬截断大块工具输出以保住会话。支持比例(`0.95`)或百分比字符串(`"95%"`)。必须 ≥ `maxContextLimit`。映射到内核 `nudge.emergencyThresholdPct` + `truncate.threshold`。 |
+| `nudgeGrowthTokens` | `50000` | 软压缩 nudge 的增长步长(token)。大约每积累这么多可压缩 token 就触发一次 nudge。调小 → 压得更频繁;调大 → 压得更少。映射到内核 `nudge.growthFloor` + `nudge.growthCap`。 |
 
-> **只有这六个 key 会被 `acp.json` 读取。** 其他调优参数(`preserveRecentMessages`、`protectedTools`、nudge 阈值)是代码级的,不向用户开放。
+> **只有这九个 key 会被 `acp.json` 读取。** 其他调优参数(`preserveRecentMessages`、`protectedTools`)是代码级的,不向用户开放。三个 nudge 阈值(`maxContextLimit`、`emergencyThresholdPercent`、`nudgeGrowthTokens`)构成三级触发:增长驱动的软 nudge → `maxContextLimit` 强制 nudge → `emergencyThresholdPercent` 紧急截断。
 
 ### 环境变量
 

package/dist/config.d.ts

@@ -1,4 +1,33 @@
 import { type Config } from "acp-kernel";
+/** Delegate sub-agent configuration. */
+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;
+    /** 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
+     *  acp_status (excluded from main totals).
+     *  "merged" — delegate token usage folded into the tool-result usage field,
+     *  counted as part of the main session totals. */
+    displayUsage?: "merged" | "separate";
+}
+/** Compression tuning. All fields accept a ratio (0.75) or percent string
+ *  ("75%") where noted. */
+export interface CompressConfig {
+    /** Context usage percentage that triggers forced compression nudges
+     *  (bypasses growth-gate + cadence). Accepts a ratio (0.75) or percent
+     *  string ("75%"). Default: 0.75. Maps to kernel nudge.maxContextLimitPct. */
+    maxContextLimit?: number | string;
+    /** Context usage percentage that triggers emergency truncation of large
+     *  tool outputs. Accepts a ratio (0.95) or percent string ("95%").
+     *  Default: 0.95. Must be >= maxContextLimit. Maps to kernel
+     *  nudge.emergencyThresholdPct + truncate.threshold. */
+    emergencyThresholdPercent?: number | string;
+    /** Token growth threshold for soft compression nudges. Default: 50000.
+     *  Maps to kernel nudge.growthFloor + nudge.growthCap. */
+    nudgeGrowthTokens?: number;
+}
 /**
  * Adapter configuration. Maps onto acp-kernel's `Config` plus Pi-specific knobs
  * (live model context window, protected tools, state persistence).
@@ -18,10 +47,6 @@ export interface AdapterConfig {
      *  warnings) are written regardless; `debug` only adds verbose diagnostics.
      *  Default: false (or env ACP_DEBUG=1/true). */
     debug?: boolean;
-    /** Enable acp_delegate tools (delegate/wait/cancel) and their system-prompt
-     *  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.
@@ -38,8 +63,24 @@ export interface AdapterConfig {
      *  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
+     *  object. Default: enabled. */
+    delegate?: boolean | DelegateConfig;
+    /** Compression tuning. */
+    compress?: CompressConfig;
+    /** Legacy flat alias for `delegate.displayUsage`. Kept for backward
+     *  compatibility with existing acp.json files. Prefer `delegate.displayUsage`. */
+    displayUsage?: "merged" | "separate";
     coreOverrides?: Partial<Config>;
 }
 export declare const DEFAULT_TOOL_BASH_TIMEOUT = 60;
 export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 200000;
+/** Resolve delegate config from the adapter, handling the boolean shorthand
+ *  and the legacy flat `displayUsage` alias. */
+export declare function resolveDelegate(adapter: AdapterConfig): {
+    enabled: boolean;
+    displayUsage: "merged" | "separate";
+};
 export declare function resolveConfig(adapter: AdapterConfig, liveContextLimit: number): Config;
+export declare function parsePercent(v: number | string): number;

package/dist/delegate-events.d.ts

@@ -1,3 +1,27 @@
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheWrite1h?: number;
+    reasoning?: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export interface UsageUpdateEvent {
+    kind: "usage-update";
+    usage: Usage;
+}
+export interface AgentSettledEvent {
+    kind: "agent-settled";
+}
+export declare function handleMessageEnd(event: Record<string, unknown>): UsageUpdateEvent | null;
 export interface ToolStartEvent {
     kind: "tool-start";
     toolName: string;
@@ -25,7 +49,7 @@ export interface ThinkingDeltaEvent {
     kind: "thinking-delta";
     delta: string;
 }
-export type ParsedEvent = ToolStartEvent | ToolUpdateEvent | ToolEndEvent | ReplyDeltaEvent | ReplyCompleteEvent | ThinkingDeltaEvent | ThinkingEndEvent | RetryStartEvent | RetryEndEvent;
+export type ParsedEvent = ToolStartEvent | ToolUpdateEvent | ToolEndEvent | ReplyDeltaEvent | ReplyCompleteEvent | ThinkingDeltaEvent | ThinkingEndEvent | RetryStartEvent | RetryEndEvent | UsageUpdateEvent | AgentSettledEvent;
 export interface ThinkingEndEvent {
     kind: "thinking-end";
 }
@@ -37,10 +61,12 @@ export interface ThinkingEndEvent {
 export declare class ThinkingCollector {
     private readonly showThinking;
     private buf;
+    private usage;
     constructor(showThinking: boolean);
     push(delta: string): void;
-    /** Return the segment line to write ("" when empty or disabled), resetting. */
+    process(ev: ParsedEvent): void;
     flush(): string;
+    getUsage(): Usage | undefined;
 }
 export interface RetryStartEvent {
     kind: "retry-start";

package/dist/delegate-tool.d.ts

@@ -1,7 +1,44 @@
-import { type SpawnOptions } from "node:child_process";
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import { Type, type Static } from "typebox";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Usage } from "./delegate-events.js";
 export declare function delegateSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): SpawnOptions;
+type RunStatus = "running" | "completed" | "failed" | "cancelled";
+interface DelegateRun {
+    runId: string;
+    agent: string;
+    task: string;
+    cwd: string;
+    startedAt: number;
+    finishedAt?: number;
+    status: RunStatus;
+    exitCode?: number | null;
+    child?: ChildProcess;
+    result?: {
+        code: number | null;
+        file: string;
+        body: string;
+    };
+    consumed?: boolean;
+    /** True once the close handler injected the result as a system
+     *  notification (sendUserMessage succeeded). Lets a later wait() avoid
+     *  re-delivering the same payload. */
+    injected?: boolean;
+    /** Watchdog reason string when the run was force-terminated ("no output for
+     *  5m", "30m limit"); surfaced in completion headers as "(timed out: ...)". */
+    timedOut?: string;
+    waiter?: () => void;
+    /** Accumulated LLM usage from the delegate (from message_end events). */
+    usage?: Usage;
+    /** True once a wait/cancel tool has returned usage — prevents double-count. */
+    usageReported?: boolean;
+    /** True once agent_settled fired; a watchdog kill after this is stuck teardown, not a timeout. */
+    agentSettled?: boolean;
+}
+export declare function addDelegateUsage(u: Usage): void;
+export declare function getDelegateUsage(): Usage | undefined;
+export declare function resetDelegateUsage(): void;
+export declare function setDelegateDisplayUsage(mode: "merged" | "separate"): void;
 /** Snapshot of currently-running delegate runs, for the TUI status widget. */
 export declare function runningRunsSnapshot(): {
     runId: string;
@@ -36,6 +73,8 @@ export interface EventApplier {
  *  never lost from the file. */
 export declare function makeEventApplier(opts: {
     showThinking: boolean;
+    onUsage?: (usage: Usage) => void;
+    onSettled?: () => void;
 }, writers: EventApplierWriters): EventApplier;
 declare const DelegateParams: Type.TObject<{
     agent: Type.TString;
@@ -53,6 +92,7 @@ declare const WaitParams: Type.TObject<{
     runId: Type.TString;
     timeout: Type.TOptional<Type.TInteger>;
 }>;
+export declare function accumulateUsage(a: Usage | undefined, b: Usage): Usage;
 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
@@ -66,6 +106,25 @@ export declare function injectedWaitMessage(run: {
         file: string;
     };
 }, runId: string, remainingLine: string): string | null;
+/** Build usage-aware return payload. Sets usageReported=true so subsequent
+ *  waits on the same run skip usage. */
+export declare function buildWaitResult(run: DelegateRun, content: string, mode?: "merged" | "separate", contentType?: "text"): {
+    details: undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    usage?: AgentToolResult<unknown>["usage"];
+};
+/** Build usage-aware result for cancel tool. */
+export declare function buildCancelResult(run: DelegateRun, content: string, mode?: "merged" | "separate"): {
+    details: undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    usage?: AgentToolResult<unknown>["usage"];
+};
 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<{
@@ -74,4 +133,5 @@ export declare function buildChildArgs(args: DelegateArgs, rolePrompt: string, c
     isAsync: boolean;
     useJsonStream: boolean;
 }>;
+export declare function injectResult(pi: ExtensionAPI, agent: string, runId: string, task: string, code: number | null, file: string, timedOut?: string, usage?: Usage, mode?: "merged" | "separate", usageAlreadyReported?: boolean): boolean;
 export {};

package/dist/delegate-watchdog.d.ts

@@ -18,6 +18,17 @@ export interface WatchdogHandle {
     poke(): void;
     /** Stop all timers (call on finalize). */
     dispose(): void;
+    /**
+     * agent_settled has been received: the agent's full flow (prompt + continue
+     * loop + retries) is over and pi emits this exactly once in the finally of
+     * _runAgentPrompt, after which the process should exit within milliseconds.
+     * If it is still alive after graceMs, the process is stuck in teardown
+     * (e.g. a provider call not returning) — kill it via killByWatchdog. graceMs
+     * is symmetric with EOF_GRACE_MS (10s): normal exits are millisecond-level,
+     * so 10s only hits genuinely hung processes. Idempotent (no-op when already
+     * settled or a grace timer is pending); dispose() clears the timer.
+     */
+    settledGrace(graceMs: number, _killGraceMs: number, reason: string): void;
 }
 /**
  * Guarantees a hung child process gets killed. A stuck child holds its stdout

package/dist/footer-status.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Mirrors pi's footer.js formatTokens: lowercase k/M, thresholds <1000/<10000/<1e6/<1e7. */
+export declare function formatCompactTokens(count: number): string;
+export declare function initFooterStatus(ctx: ExtensionContext): void;
+/** Refresh the footer delegate-usage line. Cheap: reads the accumulated total
+ *  and no-ops when the rendered text is unchanged (called on a 500ms tick). */
+export declare function updateFooterStatus(): void;
+export declare function disposeFooterStatus(): void;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
-import type { AdapterConfig } from "./config.js";
+import { type AdapterConfig } from "./config.js";
 export declare function createAcpExtension(adapter?: AdapterConfig): ExtensionFactory;
 declare const _default: ExtensionFactory;
 export default _default;