billion-context-pi 0.1.35 → 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,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,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/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;

package/dist/index.js

@@ -263,7 +263,7 @@ function defaultConfig(modelContextLimit, overrides = {}) {
   const base = {
     tiers: { enabled: true, tier2Trigger: 5, tier3Trigger: 10 },
     nudge: {
-      maxContextLimitPct: 0.55,
+      maxContextLimitPct: 0.75,
       minContextLimitPct: 0.45,
       frequency: 5,
       iterationThreshold: 15,
@@ -273,10 +273,10 @@ function defaultConfig(modelContextLimit, overrides = {}) {
       growthCap: 5e4,
       minGrowthFloor: 2e4,
       minGrowthRatio: 0.45,
-      emergencyThresholdPct: 0.8
+      emergencyThresholdPct: 0.95
     },
     promotionThreshold: 5,
-    truncate: { threshold: 1 },
+    truncate: { threshold: 0.95 },
     compress: {
       minCompressRange: 5e3,
       maxSummaryLength: 2e4,
@@ -306,6 +306,11 @@ function validateConfig(config) {
       "nudge.minContextLimitPct must not exceed nudge.maxContextLimitPct"
     );
   }
+  if (config.nudge.maxContextLimitPct > config.nudge.emergencyThresholdPct) {
+    errors.push(
+      "nudge.maxContextLimitPct must not exceed nudge.emergencyThresholdPct"
+    );
+  }
   if (config.promotionThreshold < 1) {
     errors.push("promotionThreshold must be >= 1");
   }
@@ -1466,6 +1471,7 @@ function decideNudge(input) {
   const limit = config.modelContextLimit;
   const usage = limit > 0 ? tokenCount / limit : 0;
   const nudgeGrowthTokens = resolveAdaptiveGrowth(limit, config.nudge);
+  const overLimit = usage >= config.nudge.maxContextLimitPct;
   const emergencyOverride = usage >= config.nudge.emergencyThresholdPct;
   const baseline = state.nudge.lastPerMessageNudgeTokens;
   const hadPendingNudge = state.nudge.lastNudgeShownTokens > 0;
@@ -1482,7 +1488,7 @@ function decideNudge(input) {
   let injectedTier = null;
   let injectedReason = "";
   const growthReady = growthSinceReference >= growthFloor;
-  if (!emergencyOverride && growthReady) {
+  if (!overLimit && growthReady) {
     for (const tier of [1, 2, 3]) {
       if (!config.tiers.enabled && tier > 1) break;
       const info = tiers[tier];
@@ -1494,11 +1500,26 @@ function decideNudge(input) {
       injectedReason = tier === 1 ? `T1 compressible ${info.pending} >= ${nudgeGrowthTokens}, growth ${growthSinceReference}, usage ${Math.round(usage * 100)}%` : `T${tier} distill ready: ${info.targetBlocks.length} tier-${tier - 1} blocks (${info.pending} tokens) >= ${nudgeGrowthTokens}, usage ${Math.round(usage * 100)}%`;
       break;
     }
+  } else if (overLimit) {
+    for (const tier of [1, 2, 3]) {
+      if (!config.tiers.enabled && tier > 1) break;
+      const info = tiers[tier];
+      if (!info || info.pending < config.compress.minCompressRange) continue;
+      injectedTier = tier;
+      injectedReason = emergencyOverride ? `EMERGENCY: usage ${Math.round(usage * 100)}% >= ${Math.round(config.nudge.emergencyThresholdPct * 100)}%, T${tier} pending ${info.pending}` : `OVER-LIMIT: usage ${Math.round(usage * 100)}% >= ${Math.round(config.nudge.maxContextLimitPct * 100)}%, T${tier} pending ${info.pending}`;
+      break;
+    }
   }
-  const shouldInject = emergencyOverride || injectedTier !== null;
+  const shouldInject = injectedTier !== null || overLimit && (rec?.recommendedRanges?.length ?? 0) > 0;
   let reason;
-  if (emergencyOverride) {
-    reason = `EMERGENCY: usage ${Math.round(usage * 100)}% >= ${Math.round(config.nudge.emergencyThresholdPct * 100)}%`;
+  if (emergencyOverride && injectedTier !== null) {
+    reason = injectedReason;
+  } else if (emergencyOverride) {
+    reason = `EMERGENCY: usage ${Math.round(usage * 100)}% >= ${Math.round(config.nudge.emergencyThresholdPct * 100)}% (no compressible content)`;
+  } else if (overLimit && injectedTier !== null) {
+    reason = injectedReason;
+  } else if (overLimit) {
+    reason = `OVER-LIMIT: usage ${Math.round(usage * 100)}% >= ${Math.round(config.nudge.maxContextLimitPct * 100)}% (no compressible content)`;
   } else if (injectedTier !== null) {
     reason = injectedReason;
   } else {
@@ -1534,6 +1555,7 @@ function decideNudge(input) {
       nudgeGrowthTokens,
       growthFloor,
       hasPendingNudge: hasPendingNudge ? 1 : 0,
+      overLimit: overLimit ? 1 : 0,
       emergencyOverride: emergencyOverride ? 1 : 0,
       pendingT1: tiers[1].pending,
       pendingT2: tiers[2].pending,
@@ -1845,7 +1867,7 @@ function renderNudgeText(decision) {
       ].join("\n")
     };
   }
-  const isEmergency = !!decision.breakdown?.emergencyOverride;
+  const isEmergency = !!decision.breakdown?.emergencyOverride || !!decision.breakdown?.overLimit;
   if (isEmergency) {
     return {
       voice: "emergency",
@@ -2403,16 +2425,47 @@ function makePreview(text, query, len) {
 // src/config.ts
 var DEFAULT_TOOL_BASH_TIMEOUT = 60;
 var DEFAULT_TOOL_OUTPUT_MAX_BYTES = 2e5;
+function resolveDelegate(adapter) {
+  const d = adapter.delegate;
+  if (typeof d === "object" && d !== null) {
+    return {
+      enabled: d.enabled !== false,
+      displayUsage: d.displayUsage ?? adapter.displayUsage ?? "separate"
+    };
+  }
+  return {
+    enabled: d !== false,
+    displayUsage: adapter.displayUsage ?? "separate"
+  };
+}
 function resolveConfig(adapter, liveContextLimit) {
   const envLimit = process.env.ACP_MODEL_CONTEXT_LIMIT;
   const envLimitNum = envLimit ? Number(envLimit) : NaN;
   const FALLBACK_LIMIT = 15e4;
   const limit = !Number.isNaN(envLimitNum) && envLimitNum > 0 ? envLimitNum : adapter.modelContextLimit && adapter.modelContextLimit > 0 ? adapter.modelContextLimit : liveContextLimit > 0 ? liveContextLimit : FALLBACK_LIMIT;
-  return defaultConfig(limit, {
+  const config = defaultConfig(limit, {
     protectedTools: adapter.protectedTools ?? [],
     preserveRecentMessages: adapter.preserveRecentMessages ?? 5,
     ...adapter.coreOverrides
   });
+  const c = adapter.compress;
+  if (c?.maxContextLimit !== void 0) config.nudge.maxContextLimitPct = parsePercent(c.maxContextLimit);
+  if (c?.emergencyThresholdPercent !== void 0) {
+    const pct2 = parsePercent(c.emergencyThresholdPercent);
+    config.nudge.emergencyThresholdPct = pct2;
+    config.truncate.threshold = pct2;
+  }
+  if (c?.nudgeGrowthTokens !== void 0) {
+    config.nudge.growthFloor = c.nudgeGrowthTokens;
+    config.nudge.growthCap = c.nudgeGrowthTokens;
+  }
+  return config;
+}
+function parsePercent(v) {
+  if (typeof v === "number") return v;
+  const s = v.trim();
+  if (s.endsWith("%")) return Number(s.slice(0, -1)) / 100;
+  return Number(s);
 }
 
 // src/messages.ts
@@ -9172,7 +9225,7 @@ async function handleStatus(args, runtime, ctx) {
     const costStr = cost > 0 ? ` ($${cost.toFixed(4)})` : "";
     extra.push("\u2500\u2500 Session delegate usage (excluded from main totals) \u2500\u2500");
     extra.push(`Tokens: ${delegateUsage.input.toLocaleString()} in, ${delegateUsage.output.toLocaleString()} out (${delegateUsage.totalTokens.toLocaleString()} total)${costStr}`);
-  } else if (runtime.adapter.displayUsage === "merged") {
+  } else if (resolveDelegate(runtime.adapter).displayUsage === "merged") {
     extra.push("");
     extra.push("merged mode: delegate usage is included in main session totals.");
   } else {
@@ -9293,7 +9346,7 @@ async function statusReport(runtime, ctx) {
   const activeBlocksList = state.blocks.filter((b) => b.active);
   const totalBlocksList = state.blocks;
   const lines = [];
-  const versionStr = "0.1.35" ? `billion-context-pi@${"0.1.35"}` : "";
+  const versionStr = "0.1.36" ? `billion-context-pi@${"0.1.36"}` : "";
   lines.push("\u256D\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256E");
   lines.push("\u2502           ACP Context Analysis              \u2502");
   lines.push("\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256F");
@@ -9669,7 +9722,7 @@ async function checkForUpdate(autoUpdate, notify) {
     const data = await res.json();
     const latest = data.version;
     if (!latest) return;
-    const current = runtimeVersion ?? "0.1.35";
+    const current = runtimeVersion ?? "0.1.36";
     const hasUpdate = isNewer(latest, current);
     debug.event("update-check", {
       current,
@@ -9862,7 +9915,16 @@ async function loadUserConfig(cwd) {
 function join8(...parts) {
   return path3.join(...parts);
 }
-var KNOWN = /* @__PURE__ */ new Set(["debug", "autoUpdate", "modelContextLimit", "delegate", "displayUsage", "toolBashDefaultTimeout", "toolOutputMaxBytes"]);
+var KNOWN = /* @__PURE__ */ new Set([
+  "debug",
+  "autoUpdate",
+  "modelContextLimit",
+  "toolBashDefaultTimeout",
+  "toolOutputMaxBytes",
+  "delegate",
+  "compress",
+  "displayUsage"
+]);
 function pickKnown(parsed) {
   const out = {};
   for (const [k, v] of Object.entries(parsed)) {
@@ -9874,8 +9936,6 @@ function applyUserConfig(adapter, user) {
   return {
     ...adapter,
     ...user,
-    // coreOverrides / protectedTools / preserveRecentMessages are not overridable
-    // from acp.json (keep them from the factory config).
     coreOverrides: adapter.coreOverrides,
     protectedTools: adapter.protectedTools,
     preserveRecentMessages: adapter.preserveRecentMessages
@@ -9911,16 +9971,16 @@ function wireSessionLifecycle(pi, runtime) {
     resetDelegateUsage();
     setDelegateDisplayUsage("separate");
     const sid = ctx.sessionManager.getSessionId();
-    logInfo("session", { event: "start", sid, cwd: ctx.cwd, debug: runtime.adapter.debug ?? null, version: true ? "0.1.35" : null });
+    logInfo("session", { event: "start", sid, cwd: ctx.cwd, debug: runtime.adapter.debug ?? null, version: true ? "0.1.36" : null });
     try {
       const user = await loadUserConfig(ctx.cwd);
       runtime.setAdapter(applyUserConfig(runtime.adapter, user));
-      setDelegateDisplayUsage(runtime.adapter.displayUsage ?? "separate");
+      setDelegateDisplayUsage(resolveDelegate(runtime.adapter).displayUsage);
       if (runtime.adapter.debug !== void 0) setDebugEnabled(runtime.adapter.debug);
     } catch (e) {
       logThrow("config", e, { sid, phase: "session_start" });
     }
-    if (runtime.adapter.delegate !== false) {
+    if (resolveDelegate(runtime.adapter).enabled) {
       pi.registerTool(makeDelegateTool(pi));
       pi.registerTool(makeDelegateWaitTool(pi));
       pi.registerTool(makeDelegateCancelTool(pi));