billion-context-pi-lean 0.1.69-lean.1 → 0.1.83-lean.10

package/LICENSE

@@ -1,5 +1,6 @@
 MIT License
 
+Copyright (c) 2026 ranxianglei
 Copyright (c) 2026 kunkun9527
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -1,81 +1,129 @@
-# billion-context-pi-lean
-
-[简体中文](README.zh-CN.md)
-
-A lightweight Pi wrapper for [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi). It retains the upstream context compression engine while eliminating persistent system prompt bloat and redundant tool schemas.
-
-## Core Features
-
-* Full compression engine: Keeps upstream context compression, hierarchical summaries, nudges, overflow recovery, retry handling, and tool protection.
-* Streamlined tool surface: Exposes the high-frequency `compress` tool directly, while consolidating `decompress`, `search_context`, and `acp_status` into an on-demand `acp_context` interface.
-* Focused and clean: Disables built-in delegation and auto-updates by design. For delegation workflows, pair with a dedicated subagent extension.
-
-Upstream dependency is pinned to `billion-context-pi@0.1.69`; delegation remains disabled in this lean wrapper.
-
-## Context Savings
-
-The benchmark below compares the same delegation-disabled configuration against upstream `0.1.69`.
-
-## Installation
-
-```bash
-pi install git:github.com/kunkun9527/billion-context-pi-lean
-```
-
-Or install from a local clone:
-
-```bash
-git clone https://github.com/kunkun9527/billion-context-pi-lean.git
-cd billion-context-pi-lean
-npm install
-pi install ./
-```
-
-Do not load this wrapper alongside another `billion-context-pi` extension to prevent registering duplicate tools or hooks.
-
-## Usage
-
-The model interacts with two tools:
-
-```text
-compress
-acp_context
-```
-
-`acp_context` supports `decompress`, `search_context`, `acp_status`, and `help`.
-
-```json
-{
-  "op": "search_context",
-  "args": {
-    "query": "authentication"
-  }
-}
-```
-
-Use `help` only when you need to inspect the full upstream schema.
-
-## Context Footprint Benchmark
-
-With only this extension enabled, its recurring initialization overhead in the model context is:
-
-| Item | Lean | Upstream `billion-context-pi@0.1.69` |
-| --- | ---: | ---: |
-| `compress` | 231 | 549 |
-| Context operations | `acp_context`: 90 | `decompress` + `search_context` + `acp_status`: 1,095 |
-| System prompt additions | 369 | 4,158 |
-| **Total** | **690** | **5,802** |
-
-This saves **5,112 tokens (88.1%)** compared to the pinned upstream package.
-The benchmark was measured on Pi 0.85.1 with `measure-plugin-tokens-v3.mjs` in a fresh isolated session, with delegation disabled for both packages, excluding built-in tools, skills, context files, and unrelated extensions. Token estimates use `ceil(characters / 4)`. Pure runtime UI elements and slash commands are excluded as they are not sent to the model.
-
-## Development
-
-```bash
-npm ci
-npm run check
-```
-
-## License
-
-MIT. This wrapper builds on the MIT-licensed [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi).
+# billion-context-pi-lean
+
+<!-- token-benchmark:summary:start -->
+> **Token benchmark: Lean 486, upstream `billion-context-pi@0.1.83` 8,670 — 94.4% fewer.**
+<!-- token-benchmark:summary:end -->
+> [See my full setup for Pi](https://github.com/kunkun9527/my-lean-pi-setup)
+
+[中文](https://github.com/kunkun9527/billion-context-pi-lean/blob/main/README_zh-CN.md)
+
+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.
+
+## 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.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** |
+
+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](#use-a-cheap-model-for-summaries)).
+
+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.
+
+## Main differences from upstream 0.1.83
+
+| | Upstream 0.1.83 | This fork |
+|---|---|---|
+| 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 |
+| 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 |
+
+\* Estimated as `ceil(chars / 4)` from the length of the rule text in the nudge, not billed tokens.
+
+<details>
+<summary>Smaller upstream issues fixed in this fork</summary>
+
+- Emergency truncation was computed but never reached the request.
+- Emergency truncation could cut the latest user message.
+- The token meter reused an old count and ignored newly added messages.
+- Reasoning inside `compress` calls was not counted.
+- Concurrent state saves could fail (`ENOENT` on a shared temp file), and releasing the session lock could let a later caller jump the queue.
+- After `/tree` into the middle of a block, its summary could show decisions from messages the current branch never reached.
+- Decompressing to a file failed on Windows when the message ref contained `|`.
+- The test suite wrote into the real `~/.pi`.
+
+Details: [CHANGELOG.md](CHANGELOG.md), [MAINTENANCE.md](MAINTENANCE.md) (Chinese).
+
+</details>
+
+## Install
+
+```bash
+pi install npm:billion-context-pi-lean
+```
+
+Append `@<version>` to pin a version from [Releases](https://github.com/kunkun9527/billion-context-pi-lean/releases). Installing from git works too: `pi install git:github.com/kunkun9527/billion-context-pi-lean`.
+
+- The dedicated summary model needs Pi 1.x or later.
+- 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
+
+```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
+```
+
+The choice is saved as `compressionModelId` in `~/.pi/acp.json` (a project's `.pi/acp.json` takes precedence).
+
+- 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.
+
+## Configuration
+
+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 }
+        }
+      }
+    }
+  }
+}
+```
+
+## Tools the model sees
+
+- `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" } }`.
+
+## Development
+
+```bash
+npm ci
+npm run check   # typecheck, tests, build and facade checks
+npm run measure # tool + prompt footprint vs upstream (needs ../my-lean-pi-setup)
+```
+
+`dist/` is committed because Pi installs git packages without building them; commit it together with source changes. Maintenance notes: [MAINTENANCE.md](MAINTENANCE.md).
+
+## License
+
+MIT. Based on [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) by ranxianglei and contributors (MIT), including the dedicated summary model from upstream PR #241.

package/dist/abort.d.ts

@@ -0,0 +1 @@
+export declare function assertNotAborted(signal: AbortSignal | undefined): void;

package/dist/branch-guard.d.ts

@@ -0,0 +1,8 @@
+import type { CompressionCore, CompressionState, CoreMessage } from "acp-kernel";
+export declare function findOffBranchBlocks(state: CompressionState, messages: readonly CoreMessage[], persistedIds: ReadonlySet<string>): string[];
+/** Record the off-branch blocks for this state object (in-memory only). */
+export declare function markOffBranchBlocks(state: CompressionState, blockIds: readonly string[]): void;
+export declare function offBranchBlocksOf(state: CompressionState): ReadonlySet<string> | undefined;
+/** Wrap a kernel core so processTurn honours the marks above, and marks carry
+ *  over to the states processTurn / applyCompression return. */
+export declare function withBranchGuard(core: CompressionCore): CompressionCore;

package/dist/cache-tool.d.ts

@@ -0,0 +1,12 @@
+import { Type } from "typebox";
+import type { ExtensionContext, SessionEntry, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+import { type ToolPromptOverrides } from "./surface.js";
+import { type CacheSample } from "acp-kernel";
+declare const CacheParams: Type.TObject<{
+    detail: Type.TOptional<Type.TUnion<[Type.TLiteral<"summary">, Type.TLiteral<"full">]>>;
+}>;
+export declare function cacheSamples(entries: SessionEntry[]): CacheSample[];
+export declare function cacheReportText(runtime: AcpRuntime, ctx: ExtensionContext, detail?: "summary" | "full"): Promise<string>;
+export declare function makeCacheTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides): ToolDefinition<typeof CacheParams>;
+export {};

package/dist/chunk-HTPJ5GG7.js

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/contract.ts
+var SIDECAR_SCHEMA_VERSION = 1;
+function sidecarProducer() {
+  return `billion-context-pi@${true ? "0.1.83-lean.10" : "dev"}`;
+}
+
+export {
+  __export,
+  SIDECAR_SCHEMA_VERSION,
+  sidecarProducer
+};
+//# sourceMappingURL=chunk-HTPJ5GG7.js.map

package/dist/chunk-HTPJ5GG7.js.map

@@ -0,0 +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":[]}

package/dist/commands.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI, RegisteredCommand } from "@earendil-works/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+export declare function makeCommands(runtime: AcpRuntime, pi?: ExtensionAPI): Array<{
+    name: string;
+    options: CommandOptions;
+}>;
+export {};

package/dist/compat.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/**
+ * Host compatibility layer for pi vs omp (oh-my-pi) API differences.
+ *
+ * pi: systemPrompt is string, getSystemPrompt() returns string
+ * omp: systemPrompt is string[], getSystemPrompt() returns string[]
+ *
+ * These helpers normalize the differences so the rest of the codebase
+ * can work with a consistent string interface.
+ */
+/** Normalize systemPrompt to a single string (join with newlines if array). */
+export declare function normalizeSystemPrompt(input: string | string[] | undefined): string;
+/**
+ * Format systemPrompt for before_agent_start event handler.
+ * Always returns string to satisfy pi's type definition, but handles
+ * both string (pi) and string[] (omp) input types at runtime.
+ */
+export declare function formatSystemPromptForEvent(base: string | string[], append: string): string;
+/**
+ * Get the system prompt as a single string, regardless of host type.
+ * Handles both pi (string) and omp (string[]) return types.
+ */
+export declare function getSystemPromptText(ctx: ExtensionContext): string;

package/dist/compress-model.d.ts

@@ -0,0 +1,65 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Context, Model } from "@earendil-works/pi-ai";
+/** Sentinel compressionModelId value meaning "use the session's own model".
+ *  The compression call reuses the session's prompt prefix (system prompt +
+ *  tools + messages) so it can hit the provider's prompt cache. Distinct from a
+ *  model ref ("provider/id" or a bare id). */
+export declare const SESSION_MODEL_REF = "session";
+/** A model known to Pi's model registry, addressed by provider + id. */
+export interface CompressionModelInfo {
+    provider: string;
+    id: string;
+    name?: string;
+}
+/** `model` is set when the ref is unambiguous; `ambiguous` lists candidates
+ *  when a bare id matches several providers. */
+export interface ResolveResult {
+    model: Model<Api> | null;
+    ambiguous: CompressionModelInfo[];
+}
+type ModelRegistryLike = ExtensionContext["modelRegistry"];
+/** Every chat model Pi knows, including providers registered by extensions
+ *  (the session's live registry — not a private models.json-only runtime). */
+export declare function listModels(registry: ModelRegistryLike): CompressionModelInfo[];
+/** Resolve "provider/id" (explicit, split at the first slash) or a bare id. */
+export declare function resolveModel(registry: ModelRegistryLike, ref: string): ResolveResult;
+/** Run one summary call through the session's model registry (request-time
+ *  auth, extension-registered providers). Throws on host without nested
+ *  completion support, API error, abort, or empty output — the caller then
+ *  keeps the main model's fallback summary. */
+export declare function summarizeWithModel(ctx: ExtensionContext, model: Model<Api>, context: Context, maxTokens: number, signal?: AbortSignal): Promise<string>;
+/** The leaked text (trimmed) when the opening of `summary` is planning, else null. */
+export declare function detectPlanningLeak(summary: string): string | null;
+/** The echoed text when `summary` contains copied transcript entries, else null. */
+export declare function detectTranscriptEcho(summary: string): string | null;
+export type SummaryDefect = "planning" | "transcript-echo";
+/** summarizeWithModel, plus one retry when the output opens with planning
+ *  text or copies transcript entries. A second defective output throws, so
+ *  the range is not folded (the caller retries later) — never stored, never
+ *  silently stripped. */
+export declare function summarizeChecked(ctx: ExtensionContext, model: Model<Api>, context: Context, maxTokens: number, signal?: AbortSignal, onDefect?: (text: string, kind: SummaryDefect) => void): Promise<string>;
+/** System prompt for a dedicated model: reuse the kernel's tier-1 rules so
+ *  its output matches what the main model would produce. */
+export declare function buildSummarizeSystemPrompt(prompts: {
+    compressPhilosophy: string;
+    howToCompressRules: string;
+}, topic: string | undefined): string;
+/** Truncate very large content, keeping head (goal/early context) and tail
+ *  (latest state) around a marker. */
+export declare function truncateContent(content: string, maxChars: number): string;
+/** A chunk of range content; pinned chunks (earlier block summaries) are never truncated. */
+export interface ContentPart {
+    text: string;
+    pinned?: boolean;
+}
+/** Fit extracted range content into the summary model's context window
+ *  instead of a fixed 120K-char cap; truncate only what cannot fit.
+ *  When truncation is needed, pinned parts (earlier block summaries) are
+ *  kept whole and listed first, and only the raw messages are cut — the
+ *  summaries carry the decisions the new summary must inherit. Pinned parts
+ *  that cannot fit whole throw: the caller then keeps its own summary, written
+ *  by the main model that saw them in full, instead of one that lost facts. */
+export declare function fitToModel(parts: ContentPart[], model: {
+    contextWindow?: number;
+}, maxTokens: number): string;
+export {};

package/dist/compress-tool.d.ts

@@ -0,0 +1,76 @@
+import { Type, type Static } from "typebox";
+import { type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import type { AcpRuntime } from "./runtime.js";
+import { type ToolPromptOverrides } from "./surface.js";
+import { type CompressionBlock, type CompressionState } from "acp-kernel";
+declare const RangeSpec: Type.TObject<{
+    startId: Type.TString;
+    endId: Type.TString;
+    summary: Type.TString;
+    topic: Type.TOptional<Type.TString>;
+}>;
+declare const CompressParams: Type.TObject<{
+    topic: Type.TOptional<Type.TString>;
+    content: Type.TUnion<[Type.TArray<Type.TObject<{
+        startId: Type.TString;
+        endId: Type.TString;
+        summary: Type.TString;
+        topic: Type.TOptional<Type.TString>;
+    }>>, Type.TString]>;
+    summaryMaxChars: Type.TOptional<Type.TNumber>;
+}>;
+type CompressArgs = Static<typeof CompressParams>;
+export declare function makeCompressTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides, pi?: ExtensionAPI): ToolDefinition<typeof CompressParams>;
+type RangeEntry = Static<typeof RangeSpec>;
+/** Persisted in the compress toolResult's `details` (never sent to the model).
+ *  When a dedicated model writes summaries, the call's arguments hold only the
+ *  caller's short fallback, and failed ranges are not folded at all — so the
+ *  log alone cannot rebuild the blocks. `acpFolded` records exactly what was
+ *  folded; state-rebuild prefers it over the arguments. */
+export interface CompressResultDetails {
+    acpFolded?: {
+        version: 1;
+        ranges: Array<{
+            startId: string;
+            endId: string;
+            summary: string;
+            topic?: string;
+        }>;
+    };
+}
+export declare function normalizeRanges(args: CompressArgs): RangeEntry[] | string;
+export declare function tailRepair(s: string): string | undefined;
+export declare function arrayWrapRepair(s: string): string | undefined;
+/** Panel block count, or -1 for non-panels. Accepts BOTH the legacy
+ *  "… B blocks)" form (0-block runs; historical transcripts replayed by
+ *  index/floor-stale) and the #376 "… blocks: b3=m00044–m00097*, …" form. */
+export declare function compressPanelBlocks(text: string): number;
+/** Success = completed run that created >= 1 block (partial range errors
+ *  still count: progress was made). A 0-block panel must NOT be success —
+ *  it would reset the retry counter while the emergency nudge re-fires,
+ *  looping no-op compressions (issue #6). */
+export declare function isCompressSuccessText(text: string): boolean;
+/** No-op = completed run that compressed nothing (0-block panel: every
+ *  range skipped). Counted as a FAILED attempt by noteCompressOutcomes so
+ *  the retry cap applies. Non-panels ("No ranges provided.") stay neutral. */
+export declare function isCompressNoopText(text: string): boolean;
+export declare function blockSpanLabel(block: CompressionBlock, state: CompressionState): string;
+export declare function summaryFingerprintLine(blockId: string, summary: string): string;
+export declare function tierReadyHint(state: CompressionState, config: ReturnType<AcpRuntime["configFor"]>): string;
+type AgentMessage = SessionMessageEntry["message"];
+/**
+ * Lean: put each active block's full current summary back into the outbound
+ * compress-call arguments. The kernel stubs those summaries to 200 chars
+ * because it renders the full text as separate `acp_summary_` messages, but
+ * coreOutToAgentMessages drops those (pi has no slot for them), so without this
+ * the main model only ever sees its own stubbed fallback — never the summary
+ * the dedicated model wrote — and decompresses blocks just to read them.
+ * Arguments are parsed with normalizeRanges, so every shape the tool accepts
+ * (bare objects, startRef/endRef, single-range, string content) is covered.
+ * Ranges match blocks by start/end ref; a single-range call whose callId owns a
+ * single active block (legacy blocks without refs) maps directly. Ranges with
+ * no active block are dropped, as the kernel does for dead ranges.
+ */
+export declare function inlineBlockSummaries(messages: AgentMessage[], blocks: readonly CompressionBlock[]): AgentMessage[];
+export {};

package/dist/config-dir.d.ts

@@ -0,0 +1,32 @@
+export type HostConfigSurface = {
+    CONFIG_DIR_NAME?: unknown;
+    getAgentDir?: unknown;
+};
+/** Pi's name — the fallback, and what releases before fork-host resolution used on every host. */
+export declare const PI_CONFIG_DIR_NAME = ".pi";
+/**
+ * Config directory name, resolved from the host package the extension runs under.
+ *
+ * Every path in this adapter is `<home|cwd>/<name>/…`, with the agent dir at
+ * `~/<name>/agent` — Pi's layout, where CONFIG_DIR_NAME is ".pi". Resolution order:
+ * 1. the host's CONFIG_DIR_NAME, if it is a single directory name (Pi);
+ * 2. the parent of the host's getAgentDir(), if that is `~/<name>/agent` — Pi forks
+ *    that do not re-export CONFIG_DIR_NAME, or export it with other semantics (Prime:
+ *    CONFIG_DIR_NAME ".prime/agent", getAgentDir() ~/.prime/agent → ".prime");
+ * 3. ".pi".
+ * The namespace import is deliberate: a missing named export fails at link time
+ * under plain Node ESM→CJS interop and as `undefined` under loader aliasing (#364).
+ * It is the ONLY value import from the pi package. See docs/host-adapter.md §4.
+ */
+export declare function resolveConfigDirName(host: HostConfigSurface, home: string): string;
+export declare const CONFIG_DIR_NAME: string;
+/**
+ * `<root>/<name>/<segments>` for a user-authored file (acp.json, prompt packs). When
+ * `name` is not ".pi", an existing `<root>/.pi/<segments>` is still used while the
+ * host's own path does not exist: earlier releases read ".pi" on every host, and Prime
+ * users were told to put acp.json there (#467).
+ */
+export declare function userConfigPathIn(name: string, root: string, ...segments: string[]): string;
+export declare function userConfigPath(root: string, ...segments: string[]): string;
+/** Global then project acp.json; later entries override earlier ones. */
+export declare function acpJsonFiles(cwd: string): string[];