billion-context-pi-lean 0.1.69-lean.1 → 0.2.0

package/dist/live-only-tail.d.ts

@@ -0,0 +1,10 @@
+import type { SessionEntry, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+type AgentMessage = SessionMessageEntry["message"];
+export declare function liveOnlyTail(entries: SessionEntry[], live: AgentMessage[]): AgentMessage[] | null;
+/** Cached variant of liveOnlyTail keyed by session id. Behaviourally identical
+ *  (same tail or null); only the prefix proof is memoized. Doubt always falls
+ *  back to the full walk. */
+export declare function liveOnlyTailCached(sid: string, entries: SessionEntry[], live: AgentMessage[]): AgentMessage[] | null;
+/** Drop a session's alignment cache (session_shutdown for memory hygiene). */
+export declare function dropLiveOnlyTailCache(sid: string): void;
+export {};

package/dist/log.d.ts

@@ -0,0 +1,18 @@
+export declare function setDebugEnabled(enabled: boolean): void;
+export type LogLevel = "error" | "warn" | "info" | "debug";
+export declare function closeLogStream(): void;
+export declare function logError(scope: string, fields: Record<string, unknown>): void;
+export declare function logWarn(scope: string, fields: Record<string, unknown>): void;
+export declare function logInfo(scope: string, fields: Record<string, unknown>): void;
+export declare function logThrow(scope: string, err: unknown, extra?: Record<string, unknown>): void;
+export declare const debug: {
+    readonly enabled: boolean;
+    readonly logFile: string;
+    event(scope: string, fields: Record<string, unknown>): void;
+};
+export declare const logger: {
+    error: typeof logError;
+    warn: typeof logWarn;
+    info: typeof logInfo;
+    debug(scope: string, fields: Record<string, unknown>): void;
+};

package/dist/messages.d.ts

@@ -0,0 +1,85 @@
+import type { SessionEntry, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import { type Config, type CoreMessage } from "acp-kernel";
+import type { TurnBoundaryEntry } from "./turn-boundary.js";
+type AgentMessage = SessionMessageEntry["message"];
+/** Host-injected status-panel custom messages (written by src/commands.ts) —
+ *  UI-only, never projected into LLM context, so never user-like entries. */
+export declare const ACP_STATUS_CUSTOM_TYPE = "acp-status";
+/** /acp-export handoff docs (src/export.ts) — UI-only transcript output,
+ *  persistent in the session but never projected into LLM context (#255). */
+export declare const ACP_EXPORT_CUSTOM_TYPE = "acp-export";
+/** /acp-rule outputs (src/commands.ts) — UI-only transcript output, same
+ *  exclusion as acp-status/acp-export (#526): the rules themselves already
+ *  reach the model through the feature's own channel, so the human-facing
+ *  report must never be re-billed as model context. */
+export declare const ACP_RULE_CUSTOM_TYPE = "acp-rule";
+/** Nudge persistence record (issue #326): written via pi.appendEntry as a
+ *  type:"custom" entry — never projected into the sent view (see above), so
+ *  the compact one-liner stays out of model context while surviving restarts. */
+export declare const ACP_NUDGE_CUSTOM_TYPE = "acp-nudge";
+export interface AcpNudgeRecord {
+    text: string;
+}
+/** True for host-injected custom_message entries that participate in LLM
+ *  context: non-empty custom_message except the UI-only types in
+ *  CONTEXT_EXCLUDED_CUSTOM_TYPES (acp-status panels, acp-export docs,
+ *  acp-rule reports)
+ *  (Pi-native projection semantics, session-manager.d.ts). The non-empty gate
+ *  uses the exact same extractText check as the projection below, so an entry
+ *  either enters context or it doesn't — and only entries that enter context
+ *  can delimit a turn (#364 acceptance c: empty control signals start none).
+ *  Shared by the turn-boundary predicate in src/turn-boundary.ts so the two
+ *  views can never drift apart; defined here (not there) because it needs
+ *  extractText — importing that back would create a cycle. */
+export declare function isCustomMessageEntry(entry: TurnBoundaryEntry): entry is TurnBoundaryEntry & {
+    type: "custom_message";
+};
+export declare function entriesToCoreMessages(entries: SessionEntry[]): CoreMessage[];
+/** Append-only incremental cache for entriesToCoreMessages (issue #561).
+ *
+ *  Projection is a pure prefix-stable function: each entry contributes a fixed
+ *  slice of CoreMessages, so projecting entries[0..n) then appending the
+ *  projection of entries[n..m) equals projecting entries[0..m) — as long as the
+ *  first n entries are UNCHANGED. Hosts rebuild the entries array (and the entry
+ *  objects) from the append-only session jsonl every turn, so identity caching
+ *  is useless; validate structurally instead:
+ *    - count only ever GROWS (a drop = host rewind/truncate → full reproject),
+ *    - the first and last cached boundary entries still carry the same ids
+ *      (canaries against in-place rewrites the count check cannot see),
+ *    - at most MAX_INCREMENTAL_ENTRIES new entries per turn.
+ *  Any doubt → full entriesToCoreMessages, identical result, just slower. */
+export declare class EntryProjectionCache {
+    private count;
+    private firstId;
+    private lastId;
+    private cores;
+    /** Project `entries`, reusing the previous turn's work when the array is a
+     *  structural extension of the last one seen. Returns a defensive copy: the
+     *  internal array is shared across turns, and callers hand it to kernel code
+     * that must never observe (or mutate) cross-turn state. */
+    project(entries: SessionEntry[]): CoreMessage[];
+    /** Drop the cache (state rebuilt, session switched). */
+    reset(): void;
+}
+export declare function extractText(content: unknown): string;
+export declare function thinkingTokenCount(content: unknown): number;
+export declare function countImageBlocks(content: unknown): number;
+export declare function messageIdentity(message: unknown): string;
+export declare function messageRef(message: unknown): string | undefined;
+export declare const TRUNCATION_MARKER = "[truncated for context space]";
+export declare function matchesStoredText(stored: string, visible: string): boolean;
+export declare function coreOutToAgentMessages(coreOut: CoreMessage[], originalById: Map<string, AgentMessage>): AgentMessage[];
+export interface LatestUserGuardResult {
+    messages: CoreMessage[];
+    /** Id of the latest user message whose kernel truncation was undone. */
+    restoredId?: string;
+    /** Estimated request size after the guard (tokenCount scale). */
+    remainingTokens: number;
+}
+/** Lean: the kernel protects the most recent user message from compression
+ *  but its emergency truncation only protects the last N messages, so a big
+ *  prompt followed by a few tool rounds lost its body without any summary.
+ *  Undo that truncation and give the reclaimed budget to the other candidates
+ *  (the kernel's own truncator, run with the user message hidden). */
+export declare function protectLatestUserMessage(inMessages: CoreMessage[], outMessages: CoreMessage[], config: Config, tokenCount: number): LatestUserGuardResult;
+export {};

package/dist/omp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shown (and logged) when the extension detects an unsupported host and stands down.
+ *
+ * Unsupported = no Pi `buildContextEntries()` API AND no `PI_ACP_FORK_HOST` declaration
+ * (see ./host.ts). OMP (oh-my-pi) falls into this by default: its in-process live-entries
+ * integration diverges the nudge's example refs from the session's real refs, so compress
+ * calls fail with "does not exist in this session" ([#234]). The billion-context proxy runs
+ * compression server-side (it owns the ref coordinate space) and works on OMP.
+ */
+export declare const UNSUPPORTED_HOST_MESSAGE: string;
+/**
+ * Shown (and logged) when a session runs on a host that declared itself a
+ * Pi-compatible fork via PI_ACP_FORK_HOST (see ./host.ts). Live-tail refs are
+ * content-addressed and stable across context fires (#459), which assumes the
+ * host's view of the session grows append-only; a host that rewrites or
+ * shrinks in-flight messages can still drift refs, so long sessions on such
+ * hosts are safer on the proxy (it owns the ref coordinate space server-side).
+ */
+export declare const FORK_HOST_WARNING_MESSAGE: string;

package/dist/overflow-selfheal.d.ts

@@ -0,0 +1,132 @@
+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;
+export declare const NO_BODY_4XX_MARKER: RegExp;
+export declare function isNoBody4xxError(haystack: string | undefined | null): boolean;
+/** Corroboration threshold for arming on an ambiguous no-body 4xx: the
+ *  calibrated sent-view estimate must be at least this fraction of the
+ *  effective limit (same basis as the turn log's `pct`). */
+export declare const NO_BODY_ARM_RATIO = 0.5;
+/** Decision returned by OverflowEpisode.onNoBody4xx(). */
+export interface NoBodyDecision {
+    arm: boolean;
+    /** Consecutive no-body 4xx errors since the last successful assistant turn. */
+    consecutive: number;
+    /** Recorded sent-view estimate / effective limit, when both were seen. */
+    ratio: number | null;
+}
+/** Default cap on the output-headroom reservation, as a fraction of the
+ *  context window (issue #207). Reserving the FULL registered max output
+ *  capability halves the effective input budget on models whose maxTokens is a
+ *  large share of the window (e.g. 131072 on a 262144 window → the 75% force-
+ *  compress band fires at ~37% of the full window), while real per-turn
+ *  replies rarely approach that. Capping at 25% keeps the guarantee where it
+ *  matters — any single-turn reply up to the reserved amount still fits at the
+ *  95% emergency threshold — while bounding the budget loss. A reply longer
+ *  than the reservation overflows once; the overflow self-heal (learned window
+ *  + armed emergency) recovers it on the next turn. */
+export declare const DEFAULT_OUTPUT_HEADROOM_MAX_PCT = 0.25;
+/** Resolve the user's `outputHeadroomMaxPct` (ratio or "N%" string) to a
+ *  numeric cap, falling back to DEFAULT_OUTPUT_HEADROOM_MAX_PCT when unset.
+ *  Shared by every headroom call site (context transform, /acp, acp_status)
+ *  so they all measure against the SAME capped limit (issue #207/#267). */
+export declare function resolveOutputHeadroomCap(value: number | string | undefined): number;
+/**
+ * Reserve the model's output budget from the context window, so the kernel's
+ * nudge/truncate bands sit below (window - reserved) and the context 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).
+ *
+ * `capPct` bounds the reservation as a fraction of the window: reserved =
+ * min(maxOutput, capPct * window). The default (1) preserves the original
+ * full-capability reservation; the adapter passes DEFAULT_OUTPUT_HEADROOM_MAX_PCT
+ * (or the user's `outputHeadroomMaxPct`) so oversized registered capabilities
+ * no longer eat most of the input budget (issue #207). capPct semantics:
+ *   - 0            → no reservation (window returned unchanged)
+ *   - (0, 1)       → reservation capped at capPct * window
+ *   - >= 1         → legacy behavior (full maxOutput reserved)
+ *   - non-finite   → legacy behavior (treated as "not provided")
+ * 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, capPct?: 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;
+/**
+ * Apply the output-headroom reservation to a resolved config's modelContextLimit
+ * (see reserveOutputHeadroom / shouldReserveOutputHeadroom). Returns a NEW config
+ * (never mutates the input) so the shared resolved config stays untouched. Used
+ * by BOTH the live context transform and the read-only panel surfaces (/acp,
+ * acp_status) so every percentage is measured against the SAME real request
+ * limit — otherwise the panel reports against the full window while the nudge
+ * bands run against (window − maxOutput) (issue #267).
+ *
+ * `capPct` bounds the reservation as a fraction of the window (see
+ * reserveOutputHeadroom); callers pass resolveOutputHeadroomCap(
+ * adapter.outputHeadroomMaxPct) so the panel and the nudge bands share the
+ * same capped limit (issue #207). The default (1) preserves the legacy
+ * full-capability reservation for callers that don't pass a cap.
+ */
+export declare function applyOutputHeadroom<T extends {
+    modelContextLimit: number;
+}>(config: T, model: {
+    maxTokens?: number;
+    api?: string;
+} | undefined, capPct?: number): T;
+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;
+    /** Sent-view estimate + effective limit recorded by the context event —
+     *  the numbers of the request that just ended. */
+    private sentTokens;
+    private sentLimit;
+    /** Consecutive no-body 4xx errors since the last successful assistant
+     *  turn. 0 at session start (the episode is created per session). */
+    private noBody4xx;
+    noteSentView(tokens: number, limit: number): void;
+    /** A successful assistant turn unwedged the request loop: the consecutive
+     *  no-body count restarts from zero. */
+    noteSuccess(): void;
+    /**
+     * Record one ambiguous no-body 4xx and decide whether it corroborates a
+     * probable context overflow. Guards against the false positive (the same
+     * text serves non-overflow 4xx): arm only when the current sent-view
+     * estimate is >= NO_BODY_ARM_RATIO of the effective limit, OR this is the
+     * >=2nd consecutive no-body since the last success. The consecutive guard
+     * recovers the dead-loop even at a low ratio (the incident ran at ~24%:
+     * the estimate under-reported vs the input+max_tokens cap) — a genuine
+     * overflow fails identically while the context is unchanged, so repeated
+     * no-body errors with no successful turn in between are size-dependent by
+     * construction. No window can be parsed from a bodyless error, so when
+     * this arms, the emergency uses the already-resolved effective limit (no
+     * window is learned).
+     */
+    onNoBody4xx(): NoBodyDecision;
+    reset(): void;
+}

package/dist/prompt-pack.d.ts

@@ -0,0 +1,53 @@
+import { builtinSource, createDirPackSource, createPackResolver, defaultPack, isValidPackName, leanPack, sanitizePackSurface } from "acp-kernel";
+import type { Pack, PackResolver, PackSource, PackSurface, PromptPackFile, Prompts } from "acp-kernel";
+import type { AdapterConfig } from "./config.js";
+import { type PiPromptSections } from "./system-prompt.js";
+import { type AcpToolName, type NudgeSectionsConfig, type ToolPromptsConfig } from "./surface.js";
+export { builtinSource, createDirPackSource, createPackResolver, defaultPack, isValidPackName, leanPack, sanitizePackSurface };
+export type { Pack, PackResolver, PackSource, PackSurface, PromptPackFile };
+export declare function defaultPackSources(cwd: string): PackSource[];
+export declare function packResolver(cwd: string): PackResolver;
+export declare function discoverPack(name: string, cwd: string): Pack | null;
+export declare function resolvePackName(adapter: AdapterConfig, provider?: string, modelId?: string): string;
+export declare function resolveActivePack(adapter: AdapterConfig, cwd: string, provider?: string, modelId?: string, resolver?: PackResolver): Pack;
+export interface SurfaceMeta {
+    pack: string;
+    packVersion?: string;
+    host: string;
+}
+/** Surface meta from an already-resolved pack (avoids double resolution
+ *  when the caller already holds the active Pack). */
+export declare function surfaceMetaOf(pack: Pack, requested: string): SurfaceMeta;
+/** Host-declared surface facts for the kernel's status reports (acp-kernel
+ *  StatusReportMeta). Which pack is active is host policy — the kernel only
+ *  renders what the host declares about the active surface. */
+export declare function resolveSurfaceMeta(adapter: AdapterConfig, cwd: string, provider?: string, modelId?: string, resolver?: PackResolver): SurfaceMeta;
+export interface PiToolExtras {
+    promptSnippet?: string;
+    promptGuidelines?: string[];
+}
+export type PiToolExtrasConfig = Partial<Record<AcpToolName, PiToolExtras>>;
+export interface PiAdapterSurface {
+    promptSections: Partial<PiPromptSections>;
+    toolExtras: PiToolExtrasConfig;
+}
+/**
+ * Pi-specific part of a pack. `surface.adapters.pi` is opaque to the kernel,
+ * so the adapter sanitizes it here: tri-state prompt sections restricted to
+ * pi's section keys, per-tool extras with malformed fields dropped.
+ */
+export declare function piAdapterSurface(pack: Pack): PiAdapterSurface;
+export interface InlineSurface {
+    prompts?: Partial<Prompts>;
+    promptSections?: Partial<PiPromptSections>;
+    nudgeSections?: NudgeSectionsConfig;
+    toolPrompts?: ToolPromptsConfig;
+}
+export interface MergedSurface {
+    prompts: Partial<Prompts>;
+    promptSections: Partial<PiPromptSections>;
+    nudgeSections: NudgeSectionsConfig;
+    toolPrompts: ToolPromptsConfig;
+}
+export declare function mergeSurface(pack: Pack | null, inline: InlineSurface): MergedSurface;
+export declare function readToolSurfaceWithPacks(cwd: string): ToolPromptsConfig;

package/dist/proxy-detect.d.ts

@@ -0,0 +1,21 @@
+export declare function isBiliProxyBaseUrl(baseUrl: string | undefined): boolean;
+/**
+ * Shown (and logged) when the extension detects that the model's baseUrl
+ * routes through the billion-context wire proxy and stands down. The proxy
+ * runs compression server-side and owns the ref coordinate space, so running
+ * ACP in-process on top of it would double-compress every request.
+ */
+export declare const PROXY_STAND_DOWN_MESSAGE: string;
+/**
+ * Shown (and logged) when a billion-context host-native entry owns this
+ * process (issue #461): the native entry self-spawns an in-process proxy and
+ * rewrites model API traffic at the fetch layer, so running ACP in-process on
+ * top of it would double-compress every request. Its BILLION_CONTEXT_PROXY env
+ * var is written only after the proxy is up (past the synchronous extension
+ * load), and the fetch-layer rewrite keeps the configured baseUrl clean —
+ * BILLION_CONTEXT_NATIVE, set synchronously at module evaluation by the native
+ * entry (billion-context markNativeHost, #820/#824), is the only signal visible
+ * at our checkpoints. `host` is the marker value ("pi", "opencode", …) — kept
+ * in the text so a mismatched host is diagnosable from the warning alone.
+ */
+export declare function nativeStandDownMessage(host: string): string;

package/dist/reasoning-drop.d.ts

@@ -0,0 +1,68 @@
+import type { SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+type AgentMessage = SessionMessageEntry["message"];
+/** [#336] Config for dropping oversized reasoning (thinking) parts from
+ *  historical `compress` tool calls — exact alignment with opencode-acp #377.
+ *  `compress` calls are hard-exempt from compression (their tool results are
+ *  the anchors that keep block summaries addressable), so their thinking
+ *  rides along every request as an unreclaimable context floor. This pass
+ *  removes `thinking` parts at request time (persisted history is never
+ *  modified) from closed-round compress messages whose total reasoning length
+ *  exceeds `threshold`. A round is closed on ROUND EVIDENCE, not on user
+ *  messages: the compress tool result must have arrived and at least one
+ *  message must exist after it. The in-flight round (result still missing or
+ *  still the last message) is never touched [#348]. */
+export interface CompressReasoningConfig {
+    /** Master switch. Default: true. `drop: false` disables the pass entirely
+     *  (kill-switch; also the recipe for providers whose thinking items are
+     *  opaque and must round-trip unmodified, e.g. set it per-provider under
+     *  `compress.providers.<name>`). */
+    drop?: boolean;
+    /** Single-thinking size gate (chars): a closed-turn compress message's
+     *  total reasoning length (summed across parts of that message) must
+     *  STRICTLY EXCEED this to be dropped. Small thinkings are kept; lengths
+     *  are NOT accumulated across messages. Default: 2048. `0` drops any
+     *  non-empty reasoning (only zero-length reasoning survives). */
+    threshold?: number;
+}
+export declare const DEFAULT_COMPRESS_REASONING: Required<CompressReasoningConfig>;
+export declare function resolveReasoningDrop(cfg?: CompressReasoningConfig): Required<CompressReasoningConfig>;
+/** [#361] Strict-echo thinking upstreams (DeepSeek thinking mode) require
+ *  `reasoning_content` to round-trip verbatim across tool-call turns; a rebuilt
+ *  request whose closed-round assistant messages lost their reasoning is rejected
+ *  with HTTP 400 ("reasoning_content ... must be passed back"). Detect statically
+ *  from the model's configured origin/name so the request-time drop pass stands
+ *  down. Mirrors the proxy-side billion-context#690 detector, adapted to pi's
+ *  signal sources: the in-process adapter does not own the HTTP layer, so there
+ *  is no learn-on-400 self-heal here — see CONFIGURATION.md for the manual
+ *  `drop:false` escape hatch (GLM-thinking / QwQ / self-hosted mirrors). */
+export declare function isStrictReasoningEcho(provider?: string, baseUrl?: string): boolean;
+/** [#361] Force the drop pass off on a strict-echo upstream so its reasoning
+ *  round-trips unmodified. Pure: returns cfg unchanged when not strict-echo or
+ *  already disabled. Cost-free for non-thinking models on those hosts — they emit
+ *  no `thinking` parts, so the pass would be a no-op regardless. */
+export declare function applyStrictReasoningGate(cfg: Required<CompressReasoningConfig>, provider?: string, baseUrl?: string): Required<CompressReasoningConfig>;
+export declare function countThinkingChars(messages: AgentMessage[]): number;
+/** Request-time pass aligned with opencode-acp #377: remove `thinking` parts
+ *  from a message only when ALL gates hold —
+ *  1. closed round [#348]: EVERY `compress` toolCall in the message has its
+ *     tool-result message (role `toolResult`, matching `toolCallId`) at a
+ *     later index, and at least one message exists after that result (the
+ *     round has demonstrably moved on). A compress call without a result, or
+ *     whose result is still the last message, is in flight and never touched
+ *     — no user message is required, so long agentic sessions do close
+ *     rounds; a synthetic nudge pushed later cannot retroactively close one;
+ *  2. selector: the message carries a `toolCall` part with name "compress"
+ *     (only compress; other protected tools would need their own explicit
+ *     config);
+ *  3. size: the message's total reasoning length strictly exceeds
+ *     `threshold` chars (summed across parts, never across messages).
+ *  Pure: never mutates the input; idempotent; fail-safe (any error returns
+ *  the input unchanged). */
+export declare function dropCompressReasoning(messages: AgentMessage[], cfg?: CompressReasoningConfig): AgentMessage[];
+/** Lean: thinking that stays on the wire for compress-call messages.
+ *  estimateTokens skips compress cores whole, and the projection hangs a
+ *  message's thinking on its FIRST tool-call core, so count thinking only for
+ *  messages whose first call is compress, after the same drop pass the
+ *  request applies (closed, oversized rounds lose it). */
+export declare function keptCompressThinkingTokens(messages: AgentMessage[], cfg?: CompressReasoningConfig): number;
+export {};

package/dist/rule-tool.d.ts

@@ -0,0 +1,8 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+declare const RuleParams: Type.TObject<{
+    rule: Type.TOptional<Type.TString>;
+}>;
+export declare function makeRuleTool(runtime: AcpRuntime): ToolDefinition<typeof RuleParams>;
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,199 @@
+import type { ExtensionContext, SessionEntry, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import { type CompressionCore, type CompressionState, type Config, type Prompts } from "acp-kernel";
+import { type AdapterConfig } from "./config.js";
+import { type CompressReasoningConfig } from "./reasoning-drop.js";
+import type { SentViewMeterRecord } from "./tokens.js";
+import { entriesToCoreMessages } from "./messages.js";
+import { SessionStateStore } from "./state.js";
+import { ThrottleEpisode } from "./throttle-retry.js";
+import { OverflowEpisode } from "./overflow-selfheal.js";
+import { type TurnBoundaryPolicy } from "./turn-boundary.js";
+type AgentMessage = SessionMessageEntry["message"];
+export declare function readContextEntries(sm: ExtensionContext["sessionManager"]): SessionEntry[];
+export declare function isPiHost(sm: ExtensionContext["sessionManager"]): boolean;
+/** #453: key for the compress-retry circuit breaker, derived from PERSISTED
+ *  entries only. Live-merged tail ids (content-addressed since #459) can still
+ *  churn when the host's view of a not-yet-persisted message drifts, so a
+ *  breaker keyed on the merged view could reset failCount mid-episode (#452
+ *  log: cap → inject loop). Persisted entry ids are immutable; this key
+ *  changes only when a genuine new user message reaches the session log.
+ *  pi-native hosts see no change. */
+export declare function retryBreakerKey(sm: ExtensionContext["sessionManager"], policy?: TurnBoundaryPolicy): string | undefined;
+/** Minimal identity of a session for state operations that don't need a live
+ *  ExtensionContext (hosts deriving inline child sessions build these from
+ *  whatever session handles they hold). */
+export interface SessionRef {
+    sessionId: string;
+    sessionFile?: string;
+}
+export interface AcpRuntime {
+    core: CompressionCore;
+    /** Set when the host is unsupported (currently: OMP / oh-my-pi) or when the
+     *  model's baseUrl routes through the billion-context wire proxy (#296).
+     *  Once true, the extension stands down: the context transform, system-prompt
+     *  injection, compaction-cancel and ACP tools all no-op so the host runs
+     *  untouched. Set at session_start (first context event as fallback). */
+    refused: boolean;
+    /** User-facing reason shown when a refused ACP tool is invoked; null means
+     *  the default OMP refusal text applies. Set together with `refused`. */
+    refusalMessage: string | null;
+    /** 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;
+    /** Per-session tokenCount scale tracker (estimate vs provider). Returns true
+     *  when the scale just flipped (stale↔not-stale) so the caller can reset the
+     *  growth baseline — a cross-scale delta is a false artifact, not real growth
+     *  (issue #267). The first observation for a session never reports a flip. */
+    noteTokenScale: (sid: string, stale: boolean) => boolean;
+    /** Drop a session's token-scale tracker (session_shutdown). */
+    dropTokenScale: (sid: string) => void;
+    store: SessionStateStore;
+    adapter: AdapterConfig;
+    setAdapter(adapter: AdapterConfig): void;
+    prompts: Prompts;
+    setPrompts(prompts: Prompts): void;
+    markNudgeShown(sid: string, turnKey: string, tokenCount?: number): void;
+    nudgeShownFor(sid: string, turnKey: string): boolean;
+    /** tokenCount at the last actual nudge injection for this turn, for growth-aware re-inject (issue #269). */
+    nudgeShownTokensFor(sid: string, turnKey: string): number | undefined;
+    /** Clears the token-count stamps recorded by markNudgeShown — used on a token-scale flip (issue #267) so the same-turn re-inject floor (#269 / PR #316) is not computed against an old-scale stamp. */
+    clearNudgeTokenStamps(sid: string): void;
+    /** Like the nudgeShown* pair but tracks the persisted display-only session
+     *  entry (issue #326): at most one record per user turn even when the
+     *  emergency nudge re-injects on every LLM call. */
+    markNudgeRecorded(sid: string, turnKey: string): void;
+    nudgeRecordedFor(sid: string, 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. turnKey MUST be the stable persisted-boundary key
+     *  (retryBreakerKey) — a key derived from live-merged entries churns under
+     *  fork hosts and resets the counter mid-episode (#453). 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 and whether the cap was just reached. */
+    noteCompressOutcomes(sid: string, turnKey: string, outcomes: ReadonlyArray<{
+        toolCallId: string;
+        isError: boolean;
+        success: boolean;
+        noop?: boolean;
+    }>): {
+        count: number;
+        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(sid: string, turnKey: string): boolean;
+    clearNudgeTracking(sid: string): void;
+    clearCompressRetryTracking(sid: string): void;
+    liveContextLimit(ctx: ExtensionContext): number;
+    configFor(ctx: ExtensionContext): Config;
+    /** [#336] Effective compress.reasoning drop settings for the active model
+     *  (three-level merge + defaults). Feeds the request-time pass in the
+     *  context transform. */
+    reasoningDropFor(ctx: ExtensionContext): Required<CompressReasoningConfig>;
+    /** Effective historical-image strip policy for the active model (issue #321).
+     *  Host-side policy — deliberately NOT part of the kernel Config object. */
+    stripImagesFor(ctx: ExtensionContext): {
+        enabled: boolean;
+        keepRecent: number;
+    };
+    /** Re-read ~/.<dir>/acp.json + <cwd>/<dir>/acp.json and re-derive the adapter
+     *  config when the contents change. Cheap no-op when unchanged. Called at
+     *  session_start and on every context event so config edits apply live. */
+    reloadConfig(cwd: string): Promise<void>;
+    stateFor(ctx: ExtensionContext, liveMessages?: AgentMessage[]): Promise<{
+        state: CompressionState;
+        coreMessages: ReturnType<typeof entriesToCoreMessages>;
+        entries: SessionEntry[];
+    }>;
+    /** Record the EXACT sent view measured off the real processTurn output for
+     *  this turn (issue #561): `viewTokens` counts turn.messages (the pruned,
+     *  summary-injected projection that actually went on the wire), and `usable`
+     *  marks whether that count is an honest view — a turn that ran with
+     *  tokenCount at/above the truncate band may have truncated its output, so
+     *  its post-truncation size under-reports and must not be trusted next turn. */
+    noteSentViewCount(sid: string, record: SentViewMeterRecord): void;
+    /** Last turn's measured sent view, or undefined on the first turn / after a
+     *  signature change (blocks added or dropped, window re-centered). */
+    peekSentViewCount(sid: string): SentViewMeterRecord | undefined;
+    /** Drop a session's sent-view meter (session_shutdown). */
+    dropSentViewCount(sid: string): void;
+    /** Drop a session's incremental projection cache (session_shutdown): it
+     *  holds the full projected CoreMessage[] for the session history. */
+    dropProjectionCache(sid: string): void;
+    save(state: CompressionState, ctx: ExtensionContext): Promise<void>;
+    /** #364 inline child sessions (same process, e.g. Prime RLM): derive the
+     *  child's compression state from another session's. Inherits blocks /
+     *  message refs / token snapshot so decompress + search_context keep working
+     *  on inherited blocks; resets every rhythm ledger (nudge cadence, stats,
+     *  absorb). One-time: writes a derivation marker into the child sidecar and
+     *  refuses to run again; also refuses when the child already owns real
+     *  (non-derived) blocks or when the parent has no blocks. Separate-process
+     *  pi-native delegates must NOT call this — their parentSession header
+     *  already inherits verbatim. Returns true when the child state was derived. */
+    deriveChildState(child: SessionRef, parent: SessionRef): Promise<boolean>;
+    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;
+    /** Record a compress call whose every requested range is dead (refs stale or
+     *  unknown — the kernel cannot create a block from it no matter what summary
+     *  is written). Returns the failure count for this exact range fingerprint
+     *  in this session (issue #250 loop breaker). */
+    noteDeadCompress(sid: string, fingerprint: string): number;
+    /** Drop a session's dead-range repeat tracking (a successful compress is
+     *  progress — reset the #250 loop breaker for the next attempt round;
+     *  session_shutdown for memory hygiene). Compress does NOT renumber refs. */
+    clearDeadCompress(sid: string): void;
+    /** Dedicated summary model ref (`session`, `provider/id`, bare id), or undefined. */
+    getCompressionModelRef(): string | undefined;
+    /** Persist the ref to the global acp.json (null clears) and apply it now. */
+    setCompressionModelRef(value: string | null): Promise<void>;
+    /** Exact transformed messages from the latest provider-bound context pass. */
+    setLastSentMessages(sid: string, messages: AgentMessage[]): void;
+    getLastSentMessages(sid: string): AgentMessage[] | null;
+    dropLastSentMessages(sid: string): void;
+    /** Record one turn's FRESH-anchor provider usage sample and report whether
+     *  the recent window is stable enough to calibrate the internal estimate
+     *  against it (issue #455): >=3 of the last 4 samples agree within a 25%
+     *  spread. A jittering getContextUsage() must not become a moving cap, so
+     *  unstable windows report false and the raw estimate stands. */
+    noteHostUsage(sid: string, tokens: number): boolean;
+    /** Drop a session's host-usage stability window (session_shutdown). */
+    dropHostUsageSamples(sid: string): void;
+    /** Track persistent >2x internal-vs-provider size disagreement (issue #455);
+     *  returns true exactly once per episode — on the third consecutive
+     *  divergent turn — so the caller warns once instead of every turn. A
+     *  convergent turn ends the episode. */
+    noteSizeDivergence(sid: string, divergent: boolean): boolean;
+    /** Drop a session's size-divergence episode (session_shutdown). */
+    dropSizeDivergence(sid: string): void;
+    /** Track the kernel's terminal-escape signal (issue #464): returns true
+     *  exactly once per episode — the first consecutive stuck fire — so the
+     *  caller logs/notifies once instead of every turn. A non-escaping turn
+     *  ends the episode. */
+    noteTerminalEscape(sid: string, active: boolean): boolean;
+    /** Drop a session's terminal-escape episode (session_shutdown). */
+    dropTerminalEscape(sid: string): void;
+    /** Track the kernel's truncation-skipped signal (issue #464): returns true
+     *  exactly once per episode for low-frequency diagnostics. A turn that
+     *  truncates (or skips nothing) ends the episode. */
+    noteTruncationSkipped(sid: string, active: boolean): boolean;
+    /** Drop a session's truncation-skipped episode (session_shutdown). */
+    dropTruncationSkipped(sid: string): void;
+}
+/** Max FAILED compress calls per user turn before the nudge circuit breaker engages. */
+export declare const MAX_COMPRESS_ATTEMPTS = 3;
+export declare function createRuntime(adapter: AdapterConfig): AcpRuntime;
+export {};

package/dist/search-index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Search index — bridges pi's session log into acp-kernel's search.
+ *
+ * Builds SearchDoc[] from:
+ *  1. All compression blocks (active AND inactive) — via blockDocs()
+ *  2. Historical messages that compression folded into a block summary.
+ *
+ * Which messages are searchable? Those covered by SOME block's
+ * effectiveMessageIds — i.e. messages that were compressed into a summary and
+ * are no longer individually visible. Messages still live in context (not in
+ * any block) are skipped: the model can already see them.
+ *
+ * We deliberately do NOT use pi's buildContextEntries for the visible check:
+ * ACP prunes messages itself (no pi `compaction` entry is written), so pi
+ * reports ALL entries as in-context. The ACP state is the source of truth.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type SearchDoc } from "acp-kernel";
+import type { CompressionState } from "acp-kernel";
+export declare function buildSearchDocs(ctx: ExtensionContext, state: CompressionState): SearchDoc[];