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

package/dist/config.d.ts

@@ -0,0 +1,296 @@
+import { type Config, type Prompts } from "acp-kernel";
+import type { CompressReasoningConfig } from "./reasoning-drop.js";
+import type { DegenerationGuardConfig } from "./degeneration.js";
+import type { ThrottleRetryConfig } from "./throttle-retry.js";
+import type { IdleCompactConfig } from "./idle-compact.js";
+import type { PiPromptSections } from "./system-prompt.js";
+import type { NudgeSectionsConfig, ToolPromptsConfig } from "./surface.js";
+/** Compression tuning fields, shared by all three levels (global, provider,
+ *  model). Percentage fields accept a ratio (0.75) or percent string ("75%").
+ *  Resolution is per-field, deepest-wins (model > provider > global); an
+ *  undefined field at a deeper level does NOT clear a shallower value. */
+export interface CompressSettings {
+    /** 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;
+    /** Minimum reclaimable tokens for a pressure-band nudge (kernel #198).
+     *  Default: max(5000, round(limit×0.01)). Explicit 0 restores the legacy
+     *  any-pending behavior — useful for tiny windows (e.g. e2e scenarios with
+     *  modelContextLimit 1500) where a fixed 5000-token floor exceeds the whole
+     *  window and would suppress every nudge. Maps to kernel
+     *  nudge.minPressureBenefitTokens. */
+    minPressureBenefitTokens?: number;
+    /** [#336] Drop oversized reasoning (thinking) from historical `compress`
+     *  tool calls — see CompressReasoningConfig in src/reasoning-drop.ts.
+     *  Merged field-wise (drop, threshold) across the three levels. */
+    reasoning?: CompressReasoningConfig;
+    /** Active prompt pack name (see CONFIGURATION.md “Prompt packs”). Base
+     *  level; override per provider/model via `providers`. "default" or unset =
+     *  built-in defaults. Resolved per request against the live model, so
+     *  switching models mid-session switches the pack. Packs ship text-level
+     *  overrides only; a pack's `toolPrompts` follow the base selection (tool
+     *  definitions freeze at extension load, before the model is known). */
+    promptPack?: string;
+    /** Opt-in wire-level strip of historical image payloads (issue #321, kernel
+     *  #215). Default: false (images ride along verbatim, current behavior).
+     *  When true, every message older than `stripImagesKeepRecent` has its image
+     *  parts dropped from the outbound provider body (image-only messages
+     *  collapse to a "[image]" text placeholder). Host-side policy only — the
+     *  strip primitive lives in acp-kernel's wire layer. */
+    stripImages?: boolean;
+    /** How many of the MOST RECENT messages keep their image payloads when
+     *  `stripImages` is enabled. Default: 5. Ignored when stripImages is off. */
+    stripImagesKeepRecent?: number;
+}
+/** Per-provider compression overrides. Carries the same tuning fields as the
+ *  global level, plus an optional per-model map keyed by model id. */
+export interface ProviderCompress extends CompressSettings {
+    /** Per-model overrides within this provider, keyed by model id
+     *  (e.g. "claude-sonnet-4-5"). */
+    models?: Record<string, CompressSettings>;
+}
+/** Compression tuning. Top-level fields are global defaults; `providers`
+ *  optionally narrows them per Pi provider name and per model id. The active
+ *  entry is resolved live each turn from the current model
+ *  (`ctx.model.provider` / `ctx.model.id`). */
+export interface CompressConfig extends CompressSettings {
+    /** Per-provider (and per-model) overrides, keyed by Pi provider name
+     *  (e.g. "anthropic", "openai", "zhipu") — the same name used in
+     *  models.json and `pi --provider`. */
+    providers?: Record<string, ProviderCompress>;
+}
+/** Generic tool-call repetition guard. Detects the same tool being called
+ *  repeatedly with byte-identical arguments — a sequence-level attractor that
+ *  token-level penalties cannot break (greedy small models loop on e.g.
+ *  acp_status or bash polls forever, each round adding protected tokens that
+ *  the compression protection band then refuses to reclaim). Consecutive
+ *  identical calls accumulate per session: at `warn` a strong warning is
+ *  appended to that call's toolResult; at `abort` the call is refused (blocked,
+ *  error toolResult) and the turn aborted so the attractor breaks. Any change
+ *  to the arguments (or a switch to a different tool) resets the counter.
+ *  Accepts a boolean shorthand (`false` disables) or an object. Default:
+ *  enabled, warn=3, abort=5. See issue #308. */
+export interface RepetitionGuardConfig {
+    /** Enable/disable the guard. Default: true. */
+    enabled?: boolean;
+    /** Consecutive identical calls before a strong warning is appended to the
+     *  matching toolResult. Default: 3. */
+    warn?: number;
+    /** Consecutive identical calls before the call is refused and the turn
+     *  aborted. Default: 5. Must be greater than `warn`; clamped up
+     *  automatically if not. */
+    abort?: number;
+}
+/**
+ * Adapter configuration. Maps onto acp-kernel's `Config` plus Pi-specific knobs
+ *  (live model context window, protected tools, state persistence).
+ */
+export interface AdapterConfig {
+    /** Master switch. Default: true. Set `enabled: false` in acp.json (or
+     *  programmatically) to turn the whole adapter off — no tools, no system
+     *  prompt, no context transform — for models too small to handle ACP, where
+     *  Pi's native context management should run instead. Checked at extension
+     *  load; requires a Pi restart to take effect. */
+    enabled?: boolean;
+    /** When omitted, the adapter reads `ctx.model.contextWindow` live each turn.
+     *  Set explicitly for tests/headless runs. */
+    modelContextLimit?: number;
+    /** Tool-name patterns (glob suffix allowed) whose EVERY call+result pair is
+     *  hard-excluded from compression — matching refs render as BLOCKED in every
+     *  view. Default: none. Intended for low-frequency high-value tools whose
+     *  outputs are independent content (e.g. skill loads); do NOT use for chatty
+     *  tools — protecting every instance grows context unboundedly (#639
+     *  rationale). Settable via acp.json since #499. */
+    protectedTools?: string[];
+    /** Tool-name patterns (glob suffix allowed) whose LATEST call+result pair is
+     *  hard-excluded from compression; older pairs remain compressible. Default:
+     *  none. Intended for cumulative-snapshot tools where each call supersedes
+     *  the last. Settable via acp.json since #499. */
+    protectedLatestTools?: string[];
+    /** Tool-name patterns (glob suffix allowed) EXCLUDED from the soft-protected
+     *  recent zone: matching tool results inside the recent window fold
+     *  immediately instead of aging out first (kernel >= 0.0.92). Default:
+     *  unset → kernel built-in ["decompress", "search_context", "read",
+     *  "bash"]. The built-in keeps read/bash compressible — the largest
+     *  reclaimable mass — but that also folds freshly-read files in batch-read
+     *  workflows (#1198-style fold→re-read loop, bili #1277). Recommended
+     *  remedy: ["decompress", "search_context", "bash"] (remove only read).
+     *  ⚠ Unlike the two protection keys, an EMPTY ARRAY IS VALID — it excludes
+     *  nothing and gives every tool recent-zone protection (escape hatch); do
+     *  not re-include decompress/search_context or just-restored blocks get
+     *  pinned in the recent zone and become unreclaimable. */
+    neverPreserveRecentTools?: string[];
+    /** The positive counterpart of neverPreserveRecentTools: tool-name
+     *  patterns REMOVED from the effective recent-zone exclusion list (kernel
+     *  >= 0.0.93) — `(neverPreserveRecentTools ?? built-in) minus
+     *  preserveRecentTools`. The one-entry #1198/#1277 batch-read fold→re-read
+     *  remedy: ["read"] protects fresh read results without restating (or
+     *  freezing a stale copy of) the built-in list. Default: unset → no
+     *  subtraction. Unlike neverPreserveRecentTools an EMPTY ARRAY IS
+     *  INVALID here (pure no-op — use neverPreserveRecentTools: [] for
+     *  protect-everything instead). */
+    preserveRecentTools?: string[];
+    preserveRecentMessages?: number;
+    /** Enable debug-level events in the ACP log file (default ~/.pi/acp.log).
+     *  Always-on events (session/turn/compress lifecycle, all errors and
+     *  warnings) are written regardless; `debug` only adds verbose diagnostics.
+     *  Default: false (or env ACP_DEBUG=1/true). */
+    debug?: 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.
+     *  Default: 60 (catches hangs quickly). On timeout the model is guided to
+     *  re-run with a larger `timeout`. Set to 0 to disable (restore Pi's
+     *  unbounded behavior). */
+    toolBashDefaultTimeout?: number;
+    /** Hard byte cap applied to tool result text via the `tool_result` hook.
+     *  Default: 50000 (~50KB) — aligned with Pi's own bash/read/grep cap so
+     *  every tool path lands under one ceiling; the net still catches runaway
+     *  output from tools Pi does not cap (MCP/custom). Set higher for large
+     *  MCP outputs, lower (e.g. 8192) for a tighter context budget, or 0 to
+     *  disable. When capped, oversized text is head-truncated with a notice
+     *  telling the model how to see the full output (bash: read
+     *  BashToolDetails.fullOutputPath). */
+    toolOutputMaxBytes?: number;
+    /** Compression tuning. */
+    compress?: CompressConfig;
+    /** Provider token-throttle (Bedrock "Too many tokens, please wait before
+     *  trying again.") auto-retry. Accepts a boolean shorthand (`false`
+     *  disables) or a ThrottleRetryConfig object. Default: enabled, 10 retries,
+     *  60s exponential base capped at 300s per kick. */
+    throttleRetry?: boolean | ThrottleRetryConfig;
+    /** Lean: idle compaction check (src/idle-compact.ts). After `idleMinutes`
+     *  (default 29) of idle time, one turn shows the main model the compress
+     *  nudge so it can compress while the prefix is still cached.
+     *  `true` or `{ enabled: true, idleMinutes: 29 }`. Default: off. */
+    idleCompact?: boolean | IdleCompactConfig;
+    /** Cap on the output-headroom reservation as a fraction of the context
+     *  window: reserved = min(model.maxTokens, pct * window). Accepts a ratio
+     *  (0.25) or percent string ("25%"). Default: 0.25. Set 0 to disable the
+     *  reservation entirely; >= 1 restores the legacy full-capability
+     *  reservation (issue #207). */
+    outputHeadroomMaxPct?: number | string;
+    /** Generic tool-call repetition guard (see RepetitionGuardConfig). Accepts a
+     *  boolean shorthand (`false` disables) or an object. Default: enabled,
+     *  warn=3, abort=5. Stops greedy small models looping on byte-identical
+     *  tool calls (issue #308). */
+    repetitionGuard?: boolean | RepetitionGuardConfig;
+    /** Character-level degenerate-repeat guard (see DegenerationGuardConfig).
+     *  Collapses long single-codepoint runs (e.g. 4655×「【」) in assistant
+     *  text/thinking of the outgoing view and injects a one-shot recovery notice
+     *  after a degenerated turn — breaking the abort loop where pi replays the
+     *  degenerated thinking back to the provider on every request (issue #351).
+     *  Distinct from `repetitionGuard`, which is tool-call level. Accepts a
+     *  boolean shorthand (`false` disables) or an object. Default: enabled,
+     *  minRun=200. */
+    degenerationGuard?: boolean | DegenerationGuardConfig;
+    /** Host multi-session turn-boundary policy (#364). Accepts a boolean
+     *  shorthand (`true` → count host-injected custom_message entries as turn
+     *  boundaries) or a HostSessionConfig object. Default: off — pi-native
+     *  behavior where only genuine user-role messages start a turn, so existing
+     *  single-session users' nudge cadence is unchanged. Enable for inline
+     *  multi-session hosts (Prime RLM & co.) whose injected agent messages must
+     *  delimit real turns. See docs/host-adapter.md. */
+    hostSession?: boolean | HostSessionConfig;
+    /** Persistent-rules feature gate (#526): opt-in `rules: true` in acp.json.
+     *  Gates the human `/acp-rule` command (list + record + remove + clear — kernel
+     *  `listRules`/`addRule`/`removeRule`/`clearRules` against the session `.acp.json` sidecar state) and
+     *  the model-side `acp_rule` tool (#490). Custom limits via
+     *  coreOverrides.rules ({ maxRules?, maxRuleChars? }). */
+    rules?: boolean;
+    /** 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;
+    /** Override structural sections of the ACP system prompt (ACP TAGS, TOOLS,
+     *  WHEN TO COMPRESS, ...). Tri-state per section: string = replace, null =
+     *  remove, omitted = default. Not risk-gated — these are documentation
+     *  sections, not compression rules. Set via acp.json. */
+    promptSections?: Partial<PiPromptSections>;
+    /** Override guidance-class nudge texts (efficiencyNote, emergencyHeader,
+     *  t2Guidance, t3Guidance). Same tri-state semantics. Not risk-gated. */
+    nudgeSections?: NudgeSectionsConfig;
+    /** Override the four ACP tool definitions' LLM-facing text (description,
+     *  paramDescriptions, promptSnippet, promptGuidelines). Read synchronously
+     *  at extension load — tool defs are frozen at registration time. */
+    toolPrompts?: ToolPromptsConfig;
+    /** Dedicated summary model (#241 port). `session` reuses the active model
+     *  and the captured prompt prefix; `provider/id` or a bare id resolves via
+     *  Pi's model registry. Omitted = the main model writes summaries. Managed
+     *  by `/acp compact`. */
+    compressionModelId?: string;
+    coreOverrides?: Partial<Config>;
+    /** Host-only (never read from acp.json): the embedding extension replaces
+     *  the ACP system prompt with its own text. The before_agent_start handler
+     *  still runs its side effects (pack stamp, summary rules), and config keys
+     *  that only shape the replaced prompt (promptSections) are
+     *  reported once as ignored instead of silently dropped. */
+    externalSystemPrompt?: boolean;
+}
+export declare const DEFAULT_TOOL_BASH_TIMEOUT = 60;
+export declare const DEFAULT_TOOL_OUTPUT_MAX_BYTES = 50000;
+/** Defaults for the generic tool-call repetition guard (issue #308). */
+export declare const REPETITION_GUARD_DEFAULTS: {
+    readonly warn: 3;
+    readonly abort: 5;
+};
+/** Resolve the repetition-guard configuration from the adapter, handling the
+ *  boolean shorthand (`false` disables) and clamping `abort` to stay strictly
+ *  above `warn` (a guard that aborts at or before its warn threshold would be
+ *  meaningless). Non-numeric / out-of-range values fall back to defaults. */
+export declare function resolveRepetitionGuard(adapter: AdapterConfig): {
+    enabled: boolean;
+    warn: number;
+    abort: number;
+};
+/** Host multi-session turn-boundary policy (#364). See TurnBoundaryPolicy in
+ *  src/turn-boundary.ts for the semantics this resolves. */
+export interface HostSessionConfig {
+    /** Count host-injected custom_message entries (agent_message) as turn
+     *  boundaries. Default: false (pi-native behavior). */
+    countCustomMessages?: boolean;
+    /** #578: optional customType allowlist refining countCustomMessages — when
+     *  set (with countCustomMessages:true), only injected entries whose
+     *  customType is listed start a turn, keeping metadata injections
+     *  (harness_digest, ipython_state) out of nudge/retry accounting. Ignored
+     *  unless countCustomMessages:true; malformed values warn and fall back to
+     *  "all injected types count". */
+    customMessageTypes?: string[];
+}
+export interface ResolvedHostSession {
+    countCustomMessages: boolean;
+    /** Present only when countCustomMessages is on and a valid allowlist was
+     *  configured (#578). */
+    customMessageTypes?: readonly string[];
+}
+/** Resolve the host-session turn-boundary policy from the adapter, handling
+ *  the boolean shorthand (`true` enables countCustomMessages). Invalid values
+ *  fall back to the pi-native default (off) with a logged warning — they never
+ *  fail the session. */
+export declare function resolveHostSession(adapter: AdapterConfig): ResolvedHostSession;
+/** Per-field deepest-wins merge of the three compression levels (global →
+ *  provider → model). An undefined field at a deeper level does NOT clear a
+ *  value set at a shallower level — only a defined value overrides. */
+export declare function mergeCompress(global?: CompressSettings, provider?: CompressSettings, model?: CompressSettings): CompressSettings;
+/** Resolve the effective compression settings for the active model: global →
+ *  provider (matched by Pi provider name) → model (matched by model id).
+ *  Returns a CompressSettings whose fields are undefined when nothing is set
+ *  at any level. The Pi adapter keys providers by name (ctx.model.provider),
+ *  not URL — it never sees the upstream URL the way the proxy does. */
+export declare function resolveCompress(compress: CompressConfig | undefined, provider: string | undefined, modelId: string | undefined): CompressSettings;
+export declare function resolveConfig(adapter: AdapterConfig, liveContextLimit: number, provider?: string, modelId?: string): Config;
+export declare function parsePercent(v: number | string): number;

package/dist/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Machine-readable contract for the `<sessionFile>.acp.json` sidecar (#368).
+ *
+ * Downstream tools (e.g. pi-billion-memory) glob the sidecar directly instead
+ * of running inside pi. To keep that stable across releases:
+ *
+ *  - `schemaVersion` is written on every save. A MISSING version means v1
+ *    (pre-contract files). An unknown NEWER version means "fields may have
+ *    changed" — skip it, log once, never rewrite the file.
+ *  - `producer` identifies the writer (`billion-context-pi@x.y.z`).
+ *  - The file is replaced atomically (tmp + rename), so a reader either sees
+ *    the previous or the next complete file, never a torn write.
+ *  - Blocks are stored verbatim as the kernel's CompressionBlock; unknown
+ *    extra fields are additive and must be ignored by readers.
+ */
+export declare const SIDECAR_SCHEMA_VERSION = 1;
+/**
+ * One compressed block, as persisted in the sidecar's `blocks[]`. Mirrors the
+ * kernel's CompressionBlock (acp-kernel 0.0.81) — inlined rather than aliased
+ * so this subpath carries no type dependency on acp-kernel (dev-only, bundled
+ * at build time). Fields the kernel adds later are additive; tests assert the
+ * kernel shape still covers this one.
+ */
+export interface BcpBlockV1 {
+    blockId: string;
+    runId: string;
+    tier: 1 | 2 | 3;
+    topic?: string;
+    summary: string;
+    directMessageIds: string[];
+    effectiveMessageIds: string[];
+    directBlockIds: string[];
+    compressedTokens: number;
+    createdAt: number;
+    survivedCount: number;
+    generation: "young" | "old";
+    active: boolean;
+    expanded?: boolean;
+    durationMs?: number;
+    compressCallId?: string;
+    startRef?: string;
+    endRef?: string;
+}
+/** Top-level shape of the sidecar (state fields beyond the contract allowed). */
+export interface BcpSidecarV1 {
+    schemaVersion: number;
+    producer: string;
+    blocks: BcpBlockV1[];
+    [extra: string]: unknown;
+}
+export declare function sidecarProducer(): string;

package/dist/contract.js

@@ -0,0 +1,9 @@
+import {
+  SIDECAR_SCHEMA_VERSION,
+  sidecarProducer
+} from "./chunk-PPYOZRUP.js";
+export {
+  SIDECAR_SCHEMA_VERSION,
+  sidecarProducer
+};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/decompress-tool.d.ts

@@ -0,0 +1,19 @@
+import { Type } from "typebox";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+import { type ToolPromptOverrides } from "./surface.js";
+declare const DecompressParams: Type.TObject<{
+    blockId: Type.TString;
+    full: Type.TOptional<Type.TBoolean>;
+    toFile: Type.TOptional<Type.TString>;
+    inline: Type.TOptional<Type.TBoolean>;
+}>;
+export declare function makeDecompressTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides): ToolDefinition<typeof DecompressParams>;
+/** Generate a unique auto file path for a block. Uses a timestamp so repeated
+ *  decompressions of the same block never overwrite each other. */
+/** Lean: filename stem for a message ref. Raw entry refs can carry
+ *  characters Windows rejects in filenames (e.g. `4d9e965e#toolu_x|fc_toolu_x`);
+ *  keep safe refs readable and give unsafe ones a sanitized prefix plus a
+ *  short hash so distinct refs never collide. */
+export declare function messageFileStem(ref: string): string;
+export {};

package/dist/degeneration.d.ts

@@ -0,0 +1,98 @@
+import type { SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+type AgentMessage = SessionMessageEntry["message"];
+/** [#351] Character-level degenerate-repeat guard. Models occasionally
+ *  degenerate into long single-codepoint runs (observed in the wild: a
+ *  5968-char thinking block ending in 4655 consecutive 「【」, escalating over
+ *  turns until the turn aborts). This is distinct from `repetitionGuard`
+ *  (issue #308), which breaks byte-identical TOOL-CALL loops; here the
+ *  attractor is inside the generated text/thinking itself.
+ *
+ *  Why the adapter must act: pi replays prior assistant thinking back to the
+ *  provider on every subsequent request (openai-completions sends it as
+ *  `reasoning_content`, or as plain text when `requiresThinkingAsText`), and
+ *  an aborted turn's partial message persists in the session log. A
+ *  degenerated tail therefore rides along every later prompt, where the model
+ *  sees its own previous output ending in thousands of repeated characters —
+ *  a continuation bias that re-triggers the same degeneration, aborting the
+ *  next turn too. The session dies in an abort loop with no recovery path.
+ *
+ *  The pass below collapses runs >= minRun in assistant text/thinking of the
+ *  OUTGOING view (persisted history is never modified) and appends a one-shot
+ *  recovery notice while the degenerated message is the most recent assistant
+ *  turn. Position-based self-limiting: a fresh model turn makes the old
+ *  message non-last, so the notice stops appearing without any persistent
+ *  state (and cannot accumulate — #223 lesson). */
+export interface DegenerationGuardConfig {
+    /** Master switch. Default: true. `false` disables the pass entirely
+     *  (kill-switch). */
+    enabled?: boolean;
+    /** Minimum length of a single-codepoint run (counted in codepoints) before
+     *  it is treated as degeneration. Legitimate single-char runs in coding
+     *  sessions (markdown hrules, dotted leaders, comment banners) stay well
+     *  under this; observed pre-degeneration drift maxed at ~60 before the
+     *  catastrophic 4655×「【」 run. Default: 200. Values below 8 are raised to
+     *  8: the collapse marker must stay shorter than any detectable run, and a
+     *  sub-8 threshold would start matching ordinary dotted leaders/hrules. */
+    minRun?: number;
+}
+export declare const DEFAULT_DEGENERATION_GUARD: Required<DegenerationGuardConfig>;
+/** Resolve the guard config, handling the boolean shorthand (`false`
+ *  disables). Invalid minRun values (< 2 or non-numeric) fall back to the
+ *  default with a logged warning — they never fail the session. Valid values
+ *  below MIN_VALID_MIN_RUN are raised to it. */
+export declare function resolveDegenerationGuard(cfg?: boolean | DegenerationGuardConfig): Required<DegenerationGuardConfig>;
+/** One maximal run of a repeated codepoint. */
+export interface DegenerateRun {
+    /** The repeated codepoint (string of length 1 or 2 — surrogate pairs kept whole). */
+    char: string;
+    /** Run length in codepoints. */
+    count: number;
+    /** UTF-16 index of the run start in the original string. */
+    index: number;
+}
+/** Find maximal runs of a single repeated codepoint with length >= minRun.
+ *  Codepoint-safe: surrogate pairs count as one unit, so a run of astral
+ *  characters is detected like any other. Returns [] for empty input or
+ *  minRun < 2 (a "run" shorter than 2 carries no signal). */
+export declare function findDegenerateRuns(text: string, minRun: number): DegenerateRun[];
+/** Collapse every degenerate run in `text` into a short marker that names the
+ *  character and its original count. Pure, idempotent, fail-safe. Returns the
+ *  input unchanged when there is nothing to collapse. */
+export declare function collapseDegenerateRuns(text: string, minRun: number): string;
+/** Evidence of one rewritten message: which blocks changed and what was collapsed. */
+export interface CollapseEvidence {
+    /** Index of the rewritten message in the input array. */
+    msgIndex: number;
+    /** Block kinds rewritten ("content" for string content, else "text"/"thinking"). */
+    blocks: string[];
+    /** Runs collapsed across those blocks. */
+    runs: DegenerateRun[];
+}
+/** Request-time pass: collapse degenerate single-codepoint runs in ASSISTANT
+ *  messages' text/thinking blocks (string content included). Every position is
+ *  scanned — including the current turn's partial assistant message, which is
+ *  exactly the one pi will replay back to the provider on the next request.
+ *  Tool-call arguments are never touched (rewriting them would desync the
+ *  model's view from the call that actually executed). Pure: returns the same
+ *  array reference when nothing changed; idempotent; fail-safe (any error
+ *  returns the input unchanged). Persisted history is never modified. */
+export declare function collapseAssistantDegeneration(messages: AgentMessage[], cfg?: boolean | DegenerationGuardConfig): {
+    messages: AgentMessage[];
+    evidence: CollapseEvidence[];
+};
+/** Scan backward for the LAST assistant message and collect its degenerate
+ *  runs. Call it with the PERSISTED originals in session order (not the
+ *  outgoing view): thinking-only aborted turns never reach the outgoing view
+ *  (projectMessage drops them), yet they are still "the previous turn".
+ *  Returns null when absent or clean. Gates the recovery notice: because the
+ *  notice fires only while the degenerated message is the most recent
+ *  assistant turn, it self-limits — once the model produces a new turn the
+ *  old message is no longer last and the notice disappears on the next
+ *  rebuild (no persistent state needed). */
+export declare function lastAssistantRuns(messages: AgentMessage[], minRun: number): DegenerateRun[] | null;
+/** One-shot recovery notice appended while a degenerated assistant message is
+ *  the most recent turn: tells the model the repeated segment carries no
+ *  information and was truncated, and to resume from the last valid step
+ *  instead of continuing the attractor. */
+export declare function degenerationNotice(runs: DegenerateRun[]): AgentMessage;
+export {};

package/dist/export.d.ts

@@ -0,0 +1,20 @@
+export interface ExportOptions {
+    output?: string;
+    full?: boolean;
+}
+export interface SessionSummary {
+    id: string;
+    title?: string;
+    label?: string;
+    savedAt?: number;
+    contextTokens?: number;
+    blocks: number;
+}
+export declare function listSessions(sessionDir: string): Promise<SessionSummary[]>;
+export declare function exportSession(selector: string | undefined, opts: ExportOptions, sessionDir: string): Promise<string>;
+export declare function parseExportArgs(args: string): {
+    selector?: string;
+    full: boolean;
+    output?: string;
+    error?: string;
+};

package/dist/floor-stale.d.ts

@@ -0,0 +1,31 @@
+import type { CompressionBlock } from "acp-kernel";
+type UsageLike = {
+    totalTokens?: number;
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+} | null | undefined;
+type AnchorEntry = {
+    type: string;
+    message?: {
+        role?: string;
+        stopReason?: string;
+        usage?: UsageLike;
+        toolName?: string;
+        toolCallId?: string;
+        isError?: boolean;
+        content?: unknown;
+    };
+};
+/** True when the last valid assistant usage anchor comes strictly BEFORE the
+ *  last successful compress toolResult — the host's provider-usage number
+ *  still reflects the pre-compression request. Failed/no-op compresses don't
+ *  count (nothing was reclaimed). */
+export declare function usageAnchorPredatesCompression(entries: AnchorEntry[]): boolean;
+export interface AnchorStaleness {
+    predates: boolean;
+    netReclaimed: number;
+}
+export declare function compressionAnchorStaleness(entries: AnchorEntry[], blocks: readonly CompressionBlock[], countTokens: (text: string) => number): AnchorStaleness;
+export {};

package/dist/host.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Which session-entry source API the host exposes (same precedence as readContextEntries). */
+export type EntrySourceKind = "buildContextEntries" | "getBranch";
+export declare function entrySourceOf(sm: ExtensionContext["sessionManager"]): EntrySourceKind | null;
+/**
+ * Whether the host declared itself a Pi-compatible fork via environment.
+ *
+ * The SessionManager shape alone cannot distinguish e.g. Prime from OMP — both are
+ * Pi forks exposing `getBranch()` but not `buildContextEntries()` — so an
+ * unsupported shape requires an explicit declaration before the adapter runs.
+ * Read at call time so hosts can set it per-launch. See docs/host-adapter.md.
+ */
+export declare function isDeclaredForkHost(): boolean;
+/** Unsupported host: not Pi-shaped and not declared as a fork. OMP stays blocked by default. */
+export declare function isUnsupportedHost(sm: ExtensionContext["sessionManager"]): boolean;

package/dist/idle-compact.d.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { NudgeDecision } from "acp-kernel";
+import type { AcpRuntime } from "./runtime.js";
+/**
+ * Idle compaction check (Lean). After the session has been idle for
+ * `idleMinutes` (default 29, just inside a 30-minute prompt cache), start one
+ * turn that shows the main model the regular compress nudge and lets it decide
+ * whether to compress. If the cache is still warm, that turn reads the long
+ * prefix from cache, and the request the user sends on return carries the
+ * shorter context instead of rewriting the long one uncached.
+ *
+ * Timing follows pi-keepwarm: the anchor is the start of the last provider
+ * request of a run. Any run counts (user input, sub-agent wake, throttle kick)
+ * except the idle check itself, so one idle period gets at most one check.
+ */
+export declare const IDLE_CHECK_CUSTOM_TYPE = "acp-idle-check";
+export declare const DEFAULT_IDLE_MINUTES = 29;
+/** Timer woke this much later than planned (machine slept): the cache is likely cold, skip. */
+export declare const IDLE_LATE_MS = 60000;
+export interface IdleCompactConfig {
+    enabled?: boolean;
+    /** Minutes of idle time before the check. Default 29. */
+    idleMinutes?: number;
+}
+export interface ResolvedIdleCompact {
+    enabled: boolean;
+    idleMinutes: number;
+}
+export declare function resolveIdleCompact(cfg: boolean | IdleCompactConfig | undefined): ResolvedIdleCompact;
+export declare function idleCheckText(awayMinutes: number): string;
+export interface IdleCompactHandle {
+    /** Record the last context event's compressible mass (context hook, every event). */
+    noteNudge(sid: string, nudge: NudgeDecision | undefined): void;
+    /** True once per idle check: the context hook appends the nudge even below its usual thresholds. */
+    takeForcedNudge(sid: string): boolean;
+    /** Re-plan the pending timer after the config changed (settings panel). */
+    rearm(): void;
+}
+export declare function wireIdleCompact(pi: ExtensionAPI, runtime: AcpRuntime): IdleCompactHandle;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { NudgeDecision } from "acp-kernel";
+import { type AdapterConfig } from "./config.js";
+export { createRuntime } from "./runtime.js";
+export type { AcpRuntime, SessionRef } from "./runtime.js";
+export { deriveChildState } from "./state.js";
+export declare function createAcpExtension(adapter?: AdapterConfig): ExtensionFactory;
+declare const _default: ExtensionFactory;
+export default _default;
+export declare function formatNudgeRecord(nudge: NudgeDecision, emergency: boolean): string;