billion-context-pi 0.1.41 → 0.1.45

package/dist/overflow-selfheal.d.ts

@@ -0,0 +1,45 @@
+export declare const OVERFLOW_MARKER: RegExp;
+export interface OverflowInfo {
+    isOverflow: boolean;
+    /** The real context window, when the provider stated it in the error. */
+    window?: number;
+    message: string;
+}
+export declare function inspectOverflowMessage(haystack: string | undefined | null): OverflowInfo;
+/**
+ * Reserve the model's output budget from the context window, so the kernel's
+ * nudge/truncate bands sit below (window - maxOutput) and the context always
+ * leaves room for the model's reply. This prevents the "context + output >
+ * window" overflow on a small window (agents routinely set a large max output).
+ * Returns the window unchanged when maxOutput is not usable (non-positive,
+ * non-finite, or >= window — a maxOutput >= window request is degenerate and is
+ * left to the overflow self-heal).
+ */
+export declare function reserveOutputHeadroom(window: number, maxOutput: number): number;
+/**
+ * Whether the OUTPUT budget should be reserved from the context window at
+ * all. Anthropic's Messages API enforces the input limit INDEPENDENTLY of
+ * max_tokens (the output budget is separate — input up to the window works
+ * with any max_tokens), so reserving the model's output capability would
+ * shift the nudge/truncate bands down by maxTokens on every session with no
+ * safety gain (e.g. a 200k model with a 64k output budget would start
+ * compressing around 136k). The OpenAI-family APIs count output against the
+ * window, so the reservation is only needed there. Unknown APIs reserve
+ * (conservative — a missed reservation at worst overflows once and the
+ * self-heal corrects it).
+ */
+export declare function shouldReserveOutputHeadroom(api: string | undefined): boolean;
+export declare class OverflowEpisode {
+    /** Real windows learned from overflow errors, keyed by model id. A learned
+     *  window is model-specific: switching to a bigger model mid-session must
+     *  not inherit the smaller model's learned limit (that would re-center the
+     *  bands below the new model's real window → premature compression). */
+    private learned;
+    learnedWindowFor(modelId: string): number | null;
+    setLearnedWindow(modelId: string, window: number): void;
+    /** When true, the next context event forces usage >=95% (emergency). Kept
+     *  session-scoped (not per-model): the context did not shrink, so the next
+     *  turn needs the emergency regardless of which model answers it. */
+    armed: boolean;
+    reset(): void;
+}

package/dist/runtime.d.ts

@@ -4,11 +4,22 @@ import { type AdapterConfig } from "./config.js";
 import { DensityEstimator } from "./density.js";
 import { entriesToCoreMessages } from "./messages.js";
 import { SessionStateStore } from "./state.js";
+import { ThrottleEpisode } from "./throttle-retry.js";
+import { OverflowEpisode } from "./overflow-selfheal.js";
 type AgentMessage = SessionMessageEntry["message"];
 export declare function readContextEntries(sm: ExtensionContext["sessionManager"]): SessionEntry[];
 export declare function isPiHost(sm: ExtensionContext["sessionManager"]): boolean;
 export interface AcpRuntime {
     core: CompressionCore;
+    /** Per-session provider-throttle retry episode (attempt budget + kick
+     *  pacing), keyed by session id so concurrent sessions in one extension
+     *  instance cannot share an episode. Reset on session_start and on any
+     *  real progress / user input. */
+    throttleFor: (sid: string) => ThrottleEpisode;
+    /** Drop a session's throttle episode entirely (session_shutdown): aborts a
+     *  pending kick sleep and releases the map entry so a long-lived process
+     *  that cycles through many sessions doesn't accumulate them. */
+    throttleDrop: (sid: string) => void;
     store: SessionStateStore;
     density: DensityEstimator;
     /** 设置 countTokens 闭包使用的 modelId（每轮 context 事件调用）。 */
@@ -22,11 +33,34 @@ export interface AcpRuntime {
     /** Drop per-session tracking state (session_start). */
     clearSessionTracking(sid: string): void;
     adapter: AdapterConfig;
+    setAdapter(adapter: AdapterConfig): void;
     prompts: Prompts;
     setPrompts(prompts: Prompts): void;
     markNudgeShown(turnKey: string): void;
     nudgeShownFor(turnKey: string): boolean;
+    /** Process compress toolResults for the CURRENT user turn only (the caller
+     *  scopes the list — see collectCompressOutcomes in src/index.ts); idempotent
+     *  per toolCallId. Outcome classes: isError or noop (0-block panel) →
+     *  failure (count++), success panel (>= 1 block) → reset, other non-error
+     *  text → neutral (count unchanged). Returns the failure count, the
+     *  toolCallId of the newest failure that still needs a retry prompt (null
+     *  when none, capped, or count 0), and whether the cap was just reached. */
+    noteCompressOutcomes(turnKey: string, outcomes: ReadonlyArray<{
+        toolCallId: string;
+        isError: boolean;
+        success: boolean;
+        noop?: boolean;
+    }>): {
+        count: number;
+        retryFor: string | null;
+        cappedNow: boolean;
+    };
+    /** True when this turn already burned MAX_COMPRESS_ATTEMPTS failed/no-op
+     *  compress calls — used to stop re-injecting the (dedup-exempt) emergency
+     *  nudge that would otherwise keep looping no-op compressions (issue #6). */
+    compressRetryCappedFor(turnKey: string): boolean;
     clearNudgeTracking(): void;
+    clearCompressRetryTracking(): void;
     liveContextLimit(ctx: ExtensionContext): number;
     configFor(ctx: ExtensionContext): Config;
     /** Re-read ~/.<dir>/acp.json + <cwd>/<dir>/acp.json and re-derive the adapter
@@ -40,6 +74,15 @@ export interface AcpRuntime {
     }>;
     save(state: CompressionState, ctx: ExtensionContext): Promise<void>;
     acquireLock(sid: string): Promise<() => void>;
+    /** Per-session overflow self-heal state (learned window + armed emergency).
+     *  Keyed by session id so concurrent sessions cannot share an episode. */
+    overflowFor(sid: string): OverflowEpisode;
+    /** Drop a session's overflow episode entirely (session_shutdown): releases
+     *  the map entry so a long-lived process cycling through many sessions
+     *  doesn't accumulate them. */
+    overflowDrop(sid: string): void;
 }
+/** Max FAILED compress calls that get a retry prompt per user turn. */
+export declare const MAX_COMPRESS_ATTEMPTS = 3;
 export declare function createRuntime(adapter: AdapterConfig): AcpRuntime;
 export {};

package/dist/setup-subagent-tools.d.ts

@@ -1,8 +1,51 @@
-export declare function resolveAgentDir(): string;
+/** The four ACP tools to ensure on every pi-subagents builtin agent. */
+export declare const ACP_TOOLS: readonly ["compress", "decompress", "search_context", "acp_status"];
 export interface SetupResult {
     path: string;
     action: "skipped" | "updated" | "failed";
     reason?: string;
 }
-export declare function ensureSubagentAcpTools(settingsPath?: string): Promise<SetupResult>;
-export declare function runSetupAndNotify(notify?: (msg: string) => void): Promise<SetupResult>;
+export interface SetupOptions {
+    /** Injectable agent directory (defaults to env PI_CODING_AGENT_DIR or ~/.pi/agent). */
+    agentDir?: string;
+    /** Injectable cwd for project-scope detection (defaults to process.cwd()). */
+    cwd?: string;
+    /** Explicit install directory (skips detection; for git installs or forks). */
+    installDir?: string;
+}
+/**
+ * Resolve the pi agent config directory (e.g. ~/.pi/agent), honoring the
+ * PI_CODING_AGENT_DIR environment variable (mirroring pi's own resolution).
+ */
+export declare function resolveAgentDir(): string;
+interface ParsedBuiltin {
+    name: string;
+    /** Frontmatter `tools` list; undefined when the agent is unrestricted. */
+    tools?: string[];
+}
+/**
+ * Detect an installed pi-subagents package and return its directory, or null
+ * when no installation is found.
+ *
+ * Checked in priority order:
+ *  1. user-scope npm install:    <agentDir>/npm/node_modules/pi-subagents
+ *  2. project-scope npm install: <cwd>/.pi/npm/node_modules/pi-subagents
+ *  3. user-scope extension dir:  <agentDir>/extensions/<name>/package.json where name === "pi-subagents"
+ *  4. project-scope extension dir: <cwd>/.pi/extensions/<name>/package.json
+ *
+ * Git installs and the legacy global npm location are intentionally not
+ * checked: a miss there is a safe no-op (ACP tools stay un-injected).
+ */
+export declare function findPiSubagentsInstall(agentDir: string, cwd: string): string | null;
+/**
+ * Discover the builtin agents shipped by the detected pi-subagents package
+ * from its agents/*.md frontmatter (name + tools). Returns an empty list
+ * when the package ships no agents directory.
+ */
+export declare function discoverBuiltinAgents(installDir: string): ParsedBuiltin[];
+/**
+ * Ensure ACP context tools are present in pi-subagents' agent overrides.
+ * No-op (skipped) unless a pi-subagents installation is detected.
+ */
+export declare function ensureSubagentAcpTools(settingsPath?: string, options?: SetupOptions): SetupResult;
+export {};

package/dist/throttle-retry.d.ts

@@ -0,0 +1,52 @@
+export declare const THROTTLE_RETRY_ERROR_MESSAGE = "429 rate limit: Too many tokens, please wait before trying again.";
+export declare const THROTTLE_KICK_SENTINEL = "[ACP:provider-throttle]";
+export declare const THROTTLE_KICK_TEXT = "[ACP:provider-throttle] The previous assistant response was interrupted by a provider rate limit (transient, not a real failure). Resume the task exactly where it left off \u2014 do not re-run completed steps and do not discuss the interruption unless asked.";
+export interface ThrottleErrorProbe {
+    role: string;
+    stopReason?: string;
+    errorMessage?: string;
+    content: unknown;
+}
+export declare function isThrottleError(msg: ThrottleErrorProbe): boolean;
+export declare function isKickMessage(msg: {
+    role: string;
+    content: unknown;
+}): boolean;
+export interface ThrottleRetryConfig {
+    enabled?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMode?: "exponential" | "fixed";
+}
+export interface ResolvedThrottleRetry {
+    enabled: boolean;
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    backoffMode: "exponential" | "fixed";
+}
+export declare const DEFAULT_THROTTLE_RETRY: ResolvedThrottleRetry;
+export declare function resolveThrottleRetry(cfg: boolean | ThrottleRetryConfig | undefined): ResolvedThrottleRetry;
+export declare function throttleDelayMs(kickNumber: number, r: ResolvedThrottleRetry): number;
+export interface ThrottleEpisodeState {
+    attempts: number;
+    kicks: number;
+    candidate: boolean;
+}
+export declare const INITIAL_THROTTLE_STATE: ThrottleEpisodeState;
+export declare class ThrottleEpisode {
+    state: ThrottleEpisodeState;
+    private cancel;
+    reset(): void;
+    onProgress(): void;
+    onUserMessage(kick: boolean): void;
+    onThrottleError(maxRetries: number): "rewrite" | "exhausted";
+    onNonThrottleError(): void;
+    readyToKick(maxRetries: number): boolean;
+    onKickStarted(): void;
+    onKickCancelled(): void;
+    sleepController(): AbortController;
+    cancelSleep(): void;
+}
+export declare function abortableSleep(ms: number, signal: AbortSignal): Promise<"ok" | "aborted">;

package/dist/update.d.ts

@@ -1,2 +1,28 @@
+export type NpmRunner = (args: string[], opts: {
+    cwd?: string;
+    timeout: number;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const runNpm: NpmRunner;
+export declare function setRunNpmForTest(impl: NpmRunner): void;
+export type NodeRunner = (args: string[], opts: {
+    timeout: number;
+}) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const runNode: NodeRunner;
+export declare function setRunNodeForTest(impl: NodeRunner): void;
+export declare function isNewer(latest: string, current: string): boolean;
 export declare function findNpmRoot(extDir: string): string | undefined;
+export type InstallOutcome = "ok" | "failed" | "rolled-back";
+export declare function verifyInstall(npmDir: string, latest: string): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare function autoInstallLatest(latest: string, extDirOverride?: string): Promise<InstallOutcome>;
 export declare function checkForUpdate(autoUpdate: boolean, notify?: (msg: string) => void): Promise<void>;

package/dist/user-config.d.ts

@@ -1,5 +1,6 @@
 import type { Prompts } from "acp-kernel";
 import type { AdapterConfig, CompressConfig, DelegateConfig } from "./config.js";
+import type { ThrottleRetryConfig } from "./throttle-retry.js";
 /** User-facing config keys (subset of AdapterConfig). Loaded from
  *  ~/.<CONFIG_DIR_NAME>/acp.json (global) and <cwd>/.<CONFIG_DIR_NAME>/acp.json
  *  (project-local overrides project-global). Project wins over global. */
@@ -11,6 +12,7 @@ export interface UserAcpConfig {
     toolOutputMaxBytes?: number;
     delegate?: boolean | DelegateConfig;
     compress?: CompressConfig;
+    throttleRetry?: boolean | ThrottleRetryConfig;
     displayUsage?: "merged" | "separate";
     prompts?: Partial<Prompts>;
     acknowledgePromptsRisk?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "billion-context-pi",
-	"version": "0.1.41",
+	"version": "0.1.45",
 	"description": "One billion, not one million. Model-driven context management for the Pi coding agent.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -60,7 +60,7 @@
 	"devDependencies": {
 		"@earendil-works/pi-coding-agent": "0.83.0",
 		"@types/node": "^26.1.2",
-		"acp-kernel": "0.0.28",
+		"acp-kernel": "0.0.32",
 		"billion-context-kit": "0.2.0",
 		"tsup": "^8.5.1",
 		"tsx": "^4.23.1",