billion-context-pi 0.1.35 → 0.1.37

package/README.md

@@ -148,7 +148,18 @@ 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,
+
+  "prompts": {
+    "compressPhilosophy": "Override the compression philosophy...",
+    "howToCompressRules": "Override tier-1 rules...",
+    "tier2DistillRules": "Override tier-2 distillation rules...",
+    "tier3CondenseRules": "Override tier-3 condensation rules..."
+  },
+  "acknowledgePromptsRisk": true
 }
 ```
 
@@ -160,8 +171,13 @@ 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`. |
+| `prompts` | *(kernel defaults)* | Override acp-kernel's 4 load-bearing compression prompt rules (`compressPhilosophy`, `howToCompressRules`, `tier2DistillRules`, `tier3CondenseRules`). Each set field replaces the default verbatim; omitted fields are inherited. Non-string values are dropped. Requires `acknowledgePromptsRisk: true` — otherwise overrides are ignored and defaults are used. |
+| `acknowledgePromptsRisk` | `false` | Safety gate for `prompts` overrides. Set `true` to acknowledge that replacing the tuned compression rules may reduce summary quality (lost paths/signatures/decisions → worse retrieval) and to make overrides take effect. |
 
-> **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 eleven 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,18 @@ billion-context-pi 开箱即用,无需任何配置。可以在 JSON 配置文件
   "modelContextLimit": 200000,
   "delegate": true,
   "toolBashDefaultTimeout": 60,
-  "toolOutputMaxBytes": 200000
+  "toolOutputMaxBytes": 200000,
+  "maxContextLimit": "75%",
+  "emergencyThresholdPercent": "95%",
+  "nudgeGrowthTokens": 50000,
+
+  "prompts": {
+    "compressPhilosophy": "覆盖压缩理念……",
+    "howToCompressRules": "覆盖 tier-1 规则……",
+    "tier2DistillRules": "覆盖 tier-2 蒸馏规则……",
+    "tier3CondenseRules": "覆盖 tier-3 浓缩规则……"
+  },
+  "acknowledgePromptsRisk": true
 }
 ```
 
@@ -159,8 +170,13 @@ 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`。 |
+| `prompts` | *(内核默认)* | 覆盖 acp-kernel 的 4 条承重压缩提示词规则(`compressPhilosophy`、`howToCompressRules`、`tier2DistillRules`、`tier3CondenseRules`)。每个设置的字段逐字替换默认值;省略的字段继承默认。非字符串值被丢弃。需要 `acknowledgePromptsRisk: true`——否则覆盖被忽略,使用默认值。 |
+| `acknowledgePromptsRisk` | `false` | `prompts` 覆盖的安全门禁。设为 `true` 以确认替换调优过的压缩规则可能降低摘要质量(丢失路径/签名/决策 → 检索变差),并使覆盖生效。 |
 
-> **只有这六个 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";
+import { type Config, type Prompts } 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,16 +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;
-    /** How to display delegate usage in session totals.
-     *  "merged" — delegate usage is added to main session totals (Pi default).
-     *  "separate" — delegate usage is tracked separately, displayed in
-     *               system notifications (excluded from main session totals).
-     *  Default: "separate" */
-    displayUsage?: "merged" | "separate";
     /** 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.
@@ -44,8 +63,33 @@ 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";
+    /** 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. */
+    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
+     *  (lost paths/signatures/decisions → worse retrieval). */
+    acknowledgePromptsRisk?: boolean;
     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-tool.d.ts

@@ -3,6 +3,11 @@ import { Type, type Static } from "typebox";
 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;
+/** Resolve the pi CLI entry for delegate child processes.
+ *  argv[1] is only the pi CLI under a CLI host; embedded hosts (e.g. pi-web)
+ *  run the SDK inside another node process, so probe instead. Non-pi hosts
+ *  (omp) keep argv[1] untouched. */
+export declare function resolvePiCliEntry(argv1: string, env?: NodeJS.ProcessEnv, piHost?: boolean): string;
 type RunStatus = "running" | "completed" | "failed" | "cancelled";
 interface DelegateRun {
     runId: string;

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;