billion-context-pi-lean 0.1.83-lean.10 → 0.2.0

package/README.md

@@ -9,23 +9,18 @@
 
 Context management for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent) that lets long sessions keep going: as context fills up, the model folds finished work into summary blocks, and the originals stay recoverable on demand.
 
-This is a fork of [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) **v0.1.83** that focuses on runtime stability and on spending fewer tokens. It keeps upstream's compression engine (ACP); the main additions are that **a cheap model can write the summaries** and that **context management itself costs fewer tokens**. Upstream has moved on to [`billion-context`](https://github.com/ranxianglei/billion-context); this fork stays on 0.1.83 and picks upstream fixes by hand. It is not affiliated with upstream.
+This is a fork of [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) **v0.1.83** that focuses on runtime stability and on spending fewer tokens. It keeps upstream's compression engine (ACP); the main additions are that **a cheap model can write the summaries**, that **context management itself costs fewer tokens**, and that **a long session is compressed while you are away**, before the prompt cache expires. Upstream has moved on to [`billion-context`](https://github.com/ranxianglei/billion-context); this fork stays on 0.1.83 and picks upstream fixes by hand. It is not affiliated with upstream.
 
-## Context footprint benchmark
-
-With only this extension enabled, its recurring model-facing initialization contribution is:
+## How it works
 
-| Variant | Tool and prompt contribution | Total |
-| --- | --- | ---: |
-| Lean `billion-context-pi-lean@0.1.83-lean.10` | `compress` (231) + `acp_context` (87) + prompt (168) | **486** |
-| Upstream `billion-context-pi@0.1.83` with `promptPack: "lean"` | `compress` (389) + `decompress` (271) + `search_context` (90) + `acp_status` (227) + `acp_cache` (204) + `acp_delegate` (1,452) + `acp_delegate_wait` (342) + `acp_delegate_cancel` (83) + prompt (1,819) | **4,877** |
-| Upstream `billion-context-pi@0.1.83` | `compress` (549) + `decompress` (546) + `search_context` (210) + `acp_status` (339) + `acp_cache` (204) + `acp_delegate` (1,452) + `acp_delegate_wait` (342) + `acp_delegate_cancel` (83) + prompt (4,945) | **8,670** |
+ACP does not compress on its own. When old, finished work piles up, it adds a short **compress nudge** to the next request, listing the message ranges that could be folded. The main model picks ranges and calls `compress`; the **summary model** (the main model itself unless you choose another) writes the summaries, and each range is replaced by its summary block. The originals stay in the session and can be brought back.
 
-This saves **8,184 tokens (94.4%)** against upstream's default, and 4,391 tokens (90.0%) against its `lean` prompt pack. The three `acp_delegate*` tools (1,877 tokens) belong to sub-agent delegation, which this fork removed; leaving them out, the savings are 92.8% and 83.8%.
+The model sees two tools:
 
-Compression nudges come on top of this and only when context fills up. With a dedicated summary model, the rules in each nudge drop from about 1,460 tokens to about 220 ([setup](#use-a-cheap-model-for-summaries)).
+- `compress`: fold finished message ranges into summary blocks.
+- `acp_context`: `decompress`, `search_context`, `acp_status`, `acp_cache` and `help`, e.g. `{ "op": "search_context", "args": { "query": "authentication" } }`, to bring originals back or look things up.
 
-Measured with `npm run measure` on Pi 1.3.0, each variant in a separate temporary process with an empty working directory and configuration. Built-in tools, skills, context files, session history, user messages, unrelated extensions, runtime UI, and slash commands are excluded; `before_agent_start` additions are included. Tokens are a fixed character-proxy estimate using `ceil(characters / 4)`, not provider tokenizer billing.
+With **Idle compact** on, the same nudge is also shown once when you step away, while the prompt cache is still warm, so you come back to a shorter context. When the [settings](#settings) make the nudge appear is up to you; as a last resort, at 95% of the window ACP cuts large tool outputs regardless.
 
 ## Main differences from upstream 0.1.83
 
@@ -34,6 +29,8 @@ Measured with `npm run measure` on Pi 1.3.0, each variant in a separate temporar
 | Who writes summaries | The main model, usually the expensive one | A **dedicated summary model** of your choice, e.g. a cheap one; the main model only picks the ranges |
 | Compression rules | Sent to the main model in every compression nudge (about 1,460 tokens; 720 with `promptPack: "lean"`) | Sent only to the summary model, so they no longer take up the main model's context; its nudge carries only a short range-picking note (about 220 tokens)\* |
 | Summary quality | General compression rules; only length is checked | Also: user requests are kept apart from what tools showed; open items are split into user objectives, suggestions and unverified risks. A failed or malformed summary is not folded; the range waits for a later attempt |
+| Coming back after a break | The first request rewrites the whole long context at uncached prices | **[Idle compact](#idle-compact)**: before the cache expires, the model gets one chance to compress, so the request you send on return is shorter |
+| Settings | Edit `acp.json` by hand | **[`/acp-config`](#configuration) panel**: pick values in the TUI, applied at once without restarting; `acp.json` still works |
 | Tools and resident prompt | 5 context tools + 3 delegation tools, about 8,700 tokens (4,900 with `promptPack: "lean"`) | `compress` + `acp_context`, 486 tokens ([benchmark](#context-footprint-benchmark)). The resident prompt keeps only rules needed before a call; the rest arrives with nudges, errors and tool results |
 | System prompt | Returns a whole system prompt, which on Pi 1.x drops prompt additions from extensions loaded after it | Added as its own section; other extensions keep theirs |
 | Sub-agent delegation, auto-update | Built in | Removed. Use a dedicated sub-agent extension; ACP still manages their sessions |
@@ -56,6 +53,22 @@ Details: [CHANGELOG.md](CHANGELOG.md), [MAINTENANCE.md](MAINTENANCE.md) (Chinese
 
 </details>
 
+## Context footprint benchmark
+
+With only this extension enabled, its recurring model-facing initialization contribution is:
+
+| Variant | Tool and prompt contribution | Total |
+| --- | --- | ---: |
+| Lean `billion-context-pi-lean@0.2.0` | `compress` (231) + `acp_context` (87) + prompt (168) | **486** |
+| Upstream `billion-context-pi@0.1.83` with `promptPack: "lean"` | `compress` (389) + `decompress` (271) + `search_context` (90) + `acp_status` (227) + `acp_cache` (204) + `acp_delegate` (1,452) + `acp_delegate_wait` (342) + `acp_delegate_cancel` (83) + prompt (1,819) | **4,877** |
+| Upstream `billion-context-pi@0.1.83` | `compress` (549) + `decompress` (546) + `search_context` (210) + `acp_status` (339) + `acp_cache` (204) + `acp_delegate` (1,452) + `acp_delegate_wait` (342) + `acp_delegate_cancel` (83) + prompt (4,945) | **8,670** |
+
+This saves **8,184 tokens (94.4%)** against upstream's default, and 4,391 tokens (90.0%) against its `lean` prompt pack. The three `acp_delegate*` tools (1,877 tokens) belong to sub-agent delegation, which this fork removed; leaving them out, the savings are 92.8% and 83.8%.
+
+Compression nudges come on top of this and only when context fills up. With a dedicated summary model, the rules in each nudge drop from about 1,460 tokens to about 220 ([setup](#settings)).
+
+Measured with `npm run measure` on Pi 1.3.0, each variant in a separate temporary process with an empty working directory and configuration. Built-in tools, skills, context files, session history, user messages, unrelated extensions, runtime UI, and slash commands are excluded; `before_agent_start` additions are included. Tokens are a fixed character-proxy estimate using `ceil(characters / 4)`, not provider tokenizer billing.
+
 ## Install
 
 ```bash
@@ -68,51 +81,50 @@ Append `@<version>` to pin a version from [Releases](https://github.com/kunkun95
 - Do not enable it together with `billion-context-pi` or `billion-context`: tools and hooks would register twice.
 - Pi's built-in compaction is turned off while this extension is active.
 
-## Use a cheap model for summaries
+## Configuration
 
-```text
-/acp compact                    # show the current setting
-/acp compact <provider/model>   # any model in Pi's model registry
-/acp compact session            # the session's own model, in a separate call
-/acp compact reset              # the main model writes summaries again
-```
+Type `/acp-config` in Pi to open the settings panel. Up/Down picks a setting, Enter or Space changes it, Esc closes. Changes apply at once, no restart needed.
 
-The choice is saved as `compressionModelId` in `~/.pi/acp.json` (a project's `.pi/acp.json` takes precedence).
+### Settings
 
-- Write `provider/id`. A bare id shared by several providers is rejected as ambiguous.
-- Models come from Pi's live registry, so providers registered by other extensions work too.
-- A model being listed does not mean its provider can serve it. If the call fails, that range stays uncompressed and is retried next time; `~/.pi/acp.log` records `compression-model-failed`. Only when the model cannot be resolved at all, or the host cannot make nested calls, does the main model's short summary get used, with a warning.
+The panel lists these, most used first.
 
-## Configuration
+| Setting | What it does | Default |
+|---|---|---|
+| Summary model | Who writes the summaries. `main model`: the main model writes them itself. `session`: the current model, in a separate call that reuses its cached prefix. Or pick any model Pi can use (Enter opens the list; type to filter), e.g. a cheap one. If that model's call fails, the range stays uncompressed and is tried again next time. | `main model` |
+| Idle compact | Compress once while you are away, before the prompt cache expires ([how it works](#idle-compact)). | `off` |
+| Idle minutes | How long the session must be idle first. Keep it a little under your models' cache lifetime: 29 fits a 30-minute cache. | 29 |
+| Context threshold | Share of the model's window above which the compress nudge no longer waits for Nudge interval and appears whenever Minimum benefit could be reclaimed. Lower keeps the context small; higher lets it run fuller. Not a hard cap. | 75% |
+| Nudge interval | Below Context threshold, the nudge waits until about this many tokens of old, compressible content have piled up. Bigger: fewer nudges, more folded at once. Smaller: frequent small compressions, a leaner context. | 50K |
+| Minimum benefit | No nudge, and no idle compact, when less than this could be reclaimed: rewriting a few thousand tokens is not worth breaking the cache. | larger of 5K and 1% of the window |
+| Tool output cap | A single tool result larger than this is cut, with a note telling the model where the full output is. Pi's own bash and read already stop at 50KB, so this mainly catches MCP and other extensions' tools, which can return hundreds of KB at once. `off` keeps everything. | 50K bytes |
+| bash default timeout | Seconds a bash command may run when the model gave no timeout. Pi has no default, so a stuck command would make the session wait forever; on timeout the model is told to re-run with a larger one. `off` means no limit. | 60 |
+| Debug log | Writes detailed events to `~/.pi/acp.log` for troubleshooting. Errors and the main events are always logged. | `off` |
 
-Config files are `~/.pi/acp.json` and `<project>/.pi/acp.json`. Upstream options in [CONFIGURATION.md](CONFIGURATION.md) still apply, except:
-
-- `autoUpdate` is always off.
-- The removed delegation keys (`delegate.*`, `displayUsage`, `delegatePrompt`) are ignored.
-- `promptSections.*` is ignored because the fork injects its own prompt; you get a one-time warning.
-
-Compression timing can be tuned per provider and model:
-
-```json
-{
-  "compressionModelId": "<provider>/<cheap-model>",
-  "compress": {
-    "promptPack": "lean",
-    "providers": {
-      "<provider>": {
-        "models": {
-          "<main-model>": { "maxContextLimit": 0.4, "nudgeGrowthTokens": 70000, "minPressureBenefitTokens": 30000 }
-        }
-      }
-    }
-  }
-}
-```
+Context threshold, Nudge interval and Minimum benefit depend on the model's window and price, so the panel sets them for the **current model only**; switch models to set another one. `inherit` drops the model's own value; a provider-wide or global value from `acp.json`, or else the default, applies.
 
-## Tools the model sees
+Regardless of these settings, at 95% of the window ACP cuts large tool outputs as a last resort.
 
-- `compress`: fold finished message ranges into summary blocks.
-- `acp_context`: `decompress`, `search_context`, `acp_status`, `acp_cache` and `help`, e.g. `{ "op": "search_context", "args": { "query": "authentication" } }`.
+### Idle compact
+
+Coming back to a long session after the prompt cache expired means the first request rewrites the whole context uncached. With Idle compact on, after Idle minutes without activity ACP starts one turn that shows the main model the compress nudge; the model decides whether to compress.
+
+- Activity means a real model request: your messages, and also a sub-agent waking the session, so long background work does not count as idle.
+- At most one such turn per idle period. Skipped when less than Minimum benefit could be reclaimed, outside the TUI and RPC modes, or when the timer fires more than a minute late (the machine slept).
+- During that turn only ACP tools may run. If you type or a sub-agent result arrives, it becomes a normal turn.
+- Idle minutes applies to every model. With a shorter cache (e.g. 5 minutes) that turn itself reads the long context uncached once.
+
+### Editing acp.json
+
+The panel saves to `~/.pi/acp.json` and keeps every other key there. Edit the file yourself only for what the panel cannot do:
+
+- **Per project:** `<project>/.pi/acp.json` overrides the global file. The panel shows the value in effect and warns when the project file overrides it.
+- **Per provider:** the three compression timing settings can also be set for a whole provider or globally, not only for one model ([how](CONFIGURATION.md#compressproviders--per-provider--per-model-overrides)).
+- **Options not in the panel**, e.g. `compress.emergencyThresholdPercent`. The full list is in [CONFIGURATION.md](CONFIGURATION.md), with these exceptions: `autoUpdate` and `ACP_AUTO_UPDATE` are gone (update with `pi install`); the removed delegation keys (`delegate.*`, `displayUsage`, `delegatePrompt`) are ignored; `promptSections.*` is ignored with a one-time warning, because this fork injects its own prompt.
+
+Panel settings map to these keys: Summary model `compressionModelId`, Idle compact `idleCompact.enabled`, Idle minutes `idleCompact.idleMinutes`, Tool output cap `toolOutputMaxBytes`, bash default timeout `toolBashDefaultTimeout`, Debug log `debug`.
+
+`/acp compact <provider/model>` sets the summary model from the command line (`/acp compact` shows it, `reset` returns to the main model).
 
 ## Development
 

package/dist/{chunk-HTPJ5GG7.js → chunk-PPYOZRUP.js}

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 // src/contract.ts
 var SIDECAR_SCHEMA_VERSION = 1;
 function sidecarProducer() {
-  return `billion-context-pi@${true ? "0.1.83-lean.10" : "dev"}`;
+  return `billion-context-pi@${true ? "0.2.0" : "dev"}`;
 }
 
 export {
@@ -15,4 +15,4 @@ export {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer
 };
-//# sourceMappingURL=chunk-HTPJ5GG7.js.map
+//# sourceMappingURL=chunk-PPYOZRUP.js.map

package/dist/{chunk-HTPJ5GG7.js.map → chunk-PPYOZRUP.js.map}

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

package/dist/config-panel.d.ts

@@ -0,0 +1,61 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type Component } from "@earendil-works/pi-tui";
+import type { AdapterConfig } from "./config.js";
+import { type IdleCompactHandle } from "./idle-compact.js";
+import type { AcpRuntime } from "./runtime.js";
+/** `/acp-config`: TUI settings panel over the GLOBAL ~/.pi/acp.json. Values
+ *  shown are the effective ones (project acp.json included); changes are
+ *  written to the global file and applied at once via reloadConfig. */
+export interface PanelScope {
+    provider?: string;
+    modelId?: string;
+}
+type Raw = Record<string, unknown>;
+export interface PanelItem {
+    id: string;
+    label: string;
+    description: string;
+    /** Model-scoped items need a current model. */
+    model?: boolean;
+    /** Upstream switch: while it reads off, this item shows off and is locked;
+     *  its stored value is kept so turning the switch back on restores it. */
+    dependsOn?: string;
+    values?: (current: string) => string[];
+    read(adapter: AdapterConfig, scope: PanelScope): string;
+    write(raw: Raw, value: string, scope: PanelScope): void;
+}
+/** Order = importance: summary model and idle compact first, per-model
+ *  compression next, tool guardrails and debug last. */
+export declare const PANEL_ITEMS: PanelItem[];
+export declare function panelItemsFor(scope: PanelScope): PanelItem[];
+/** Apply one panel change to a parsed acp.json object (mutates). */
+export declare function applyPanelValue(raw: Raw, id: string, value: string, scope: PanelScope): void;
+export declare function readPanelValue(adapter: AdapterConfig, id: string, scope: PanelScope): string;
+/** What the panel shows for an item: locked at off (no values to cycle) while its upstream is off. */
+export declare function panelDisplay(item: PanelItem, adapter: AdapterConfig, scope: PanelScope): {
+    currentValue: string;
+    values?: string[];
+    locked: boolean;
+};
+export declare function makeConfigCommand(runtime: AcpRuntime, idle: IdleCompactHandle | undefined): {
+    name: string;
+    options: {
+        description: string;
+        handler: (_args: string, ctx: ExtensionCommandContext) => Promise<void>;
+    };
+};
+/** Model picker for the summary-model submenu: typing filters (fuzzy, like
+ *  Pi's own pickers), arrows move, Enter picks, Esc goes back. */
+export declare class SearchableList implements Component {
+    private readonly choices;
+    private readonly close;
+    private readonly dim;
+    private readonly input;
+    private list;
+    constructor(choices: string[], current: string, close: (value?: string) => void, dim: (text: string) => string);
+    private rebuild;
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+}
+export {};

package/dist/config.d.ts

@@ -2,6 +2,7 @@ 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,
@@ -139,10 +140,6 @@ export interface AdapterConfig {
      *  protect-everything instead). */
     preserveRecentTools?: string[];
     preserveRecentMessages?: number;
-    /** Check npm for a newer billion-context-pi on startup and auto-install it. Default: true.
-     *  Disable via `autoUpdate: false` or env `ACP_AUTO_UPDATE=0` to avoid all
-     *  network calls on startup. */
-    autoUpdate?: boolean;
     /** 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.
@@ -171,6 +168,11 @@ export interface AdapterConfig {
      *  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

package/dist/contract.js

@@ -1,7 +1,7 @@
 import {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer
-} from "./chunk-HTPJ5GG7.js";
+} from "./chunk-PPYOZRUP.js";
 export {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer

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;