billion-context-pi 0.1.82 → 0.1.83-pr.241.511

package/README.md

@@ -216,6 +216,29 @@ Blocks: 3 active (3.7K summary, 15.2K original compressed)
   b3 (T2)  3.3K→1.0K  age=1m  "Architecture review"
 ```
 
+## `/acp compact` — dedicated compression model
+
+By default the `compress` tool's summaries are written by your **main model** — it spends output tokens producing them, and the summary-writing reasoning runs inside the main model's own turn. `/acp compact` offloads summary-writing to a **separate call** in one of two modes:
+
+- **`session`** — use the **same model as your session**, but in a separate call that **reuses the session's prompt prefix** (system prompt + active tools + the exact messages Pi just sent). Because that prefix matches what the main model already sent, the provider's **prompt cache** makes the input cheap, and the compression reasoning stays out of the main model's context. Recommended way to get isolation without switching models.
+- **`<id>`** — a model from Pi's `~/.pi/agent/models.json` (a cheaper small Qwen, `gpt-4o-mini`, …). No extra `baseUrl`/`apiKey` to duplicate. A different model has its own cache namespace, so it does **not** share the session prefix cache (input is billed in full), but you save on the model's per-token price.
+
+```
+/acp compact            # show the current compression model + list available models
+/acp compact session    # use the session model (shared prefix → prompt-cache friendly)
+/acp compact <id>       # set <id> (or <provider>/<id>) from models.json as the compression model
+/acp compact reset      # clear it — fall back to the main model
+```
+
+- **No argument** (`/acp compact`): shows the currently configured compression model (or "not set — the main model writes summaries") and lists the model ids available in `models.json` for reference.
+- **`/acp compact session`**: sets the compression model to the session model (shared-prefix mode).
+- **`/acp compact <id>`**: sets a `models.json` model. Accepts a bare id (`qwen-mini`) or an explicit `provider/id` (`openai/gpt-4o-mini`). The choice is persisted to `~/.pi/acp.json` (`compressionModelId`) and applies across sessions.
+- **`/acp compact reset`**: clears the setting; compression falls back to the main model (the default behavior).
+
+When a compression model is set, each `compress` call produces the summary in a separate call, so the **main model spends no output tokens** on summaries. If the call fails (network error, API error, empty response), the extension **falls back to the main model's summary** for that range — compression never blocks the session.
+
+> For `<id>` mode the model must have a working API key (in `models.json` or `~/.pi/agent/auth.json`); `session` mode reuses your session's existing credentials. See [CONFIGURATION.md](./CONFIGURATION.md#compressionmodelid) for details.
+
 ## `/acp-subagents` command
 
 **Optional, one-time setup — only if you also use [pi-subagents](https://github.com/nicobailon/pi-subagents).**
@@ -241,7 +264,9 @@ billion-context-pi writes a structured, always-on log to `~/.pi/acp.log` (overri
 - **Always written** (even with `debug: false`): `error`, `warn`, `info` levels — session start, every context turn (token usage / nudge decision), compress/decompress, delegate spawn/done, and **all errors and warnings** (config/state/tool failures, delegate errors, guardrail caps, update failures). Error lines include the message and stack trace.
 - **Written only when `debug: true`**: verbose `debug`-level diagnostics (full field dumps, per-turn internals).
 
-Each line: `<ISO timestamp> [<level>] [<scope>] key=value key=value`. The file rotates to `~/.pi/acp.log.old` at 10 MB.
+- **Nudge audit trail**: whenever a context-limit nudge is injected, a compact one-line record (e.g. `[ACP nudge] EMERGENCY 95% · T1 · top range m00120–m00168`) is appended as a *display-only* session entry — it survives process restarts, shows up in TUI scrollback and the session file, and is never sent to the model.
+
+Each line: `<ISO timestamp> [<level>] [<scope>] key=value key=value`. Multi-line values (e.g. the full nudge text in `nudge-injected`) are escaped (`\n` → literal `\\n`), so every entry occupies exactly **one physical line** and stays self-contained for `grep`. The file rotates to `~/.pi/acp.log.old` at 10 MB.
 
 ```sh
 tail -f ~/.pi/acp.log                 # watch the session live

package/README.zh-CN.md

@@ -229,8 +229,9 @@ billion-context-pi 会向 `~/.pi/acp.log`(可用 `ACP_LOG_FILE` 覆盖)写入结
 - `warn` — 值得注意的非致命情况:紧急 nudge 注入、配置加载失败、自动更新网络错误、工具输出被截断、委派结果注入被跳过。
 - `info` — 生命周期事件:会话启动、每轮上下文变换摘要(消息数/token/压缩比/活跃块数)、压缩/解压、delegate 派发与完成、自动更新检查。
 - `debug` —— 仅在 `debug: true` 时额外写入(细粒度的字段级事件)。
+- **Nudge 审计轨迹** — 无论何时注入上下文限制 nudge,一条紧凑的单行记录(如 `[ACP nudge] EMERGENCY 95% · T1 · top range m00120–m00168`)会作为*仅供显示*的会话条目写入——它跨进程重启存活,在 TUI 回滚历史和会话文件中可见,且永远不会发给模型。
 
-每行格式:`<ISO 时间戳> [<级别>] [<范围>] key=value key=value`。文件达到 10 MB 时轮转为 `~/.pi/acp.log.old`。
+每行格式:`<ISO 时间戳> [<级别>] [<范围>] key=value key=value`。多行字段值(如 `nudge-injected` 中的完整 nudge 正文)会被转义(`\n` → 字面量 `\\n`),保证每条日志恰好占**一行物理行**,便于 `grep`。文件达到 10 MB 时轮转为 `~/.pi/acp.log.old`。
 
 ```bash
 tail -f ~/.pi/acp.log                 # 实时观察会话

package/dist/{chunk-AKZJYVLH.js → chunk-LLFL3CNI.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.82" : "dev"}`;
+  return `billion-context-pi@${true ? "0.1.83" : "dev"}`;
 }
 
 export {
@@ -15,4 +15,4 @@ export {
   SIDECAR_SCHEMA_VERSION,
   sidecarProducer
 };
-//# sourceMappingURL=chunk-AKZJYVLH.js.map
+//# sourceMappingURL=chunk-LLFL3CNI.js.map

package/dist/compress-model.d.ts

@@ -0,0 +1,76 @@
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { Api, AssistantMessage, Context, Model, ModelsApiStreamOptions } 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 hits the provider's prompt cache — isolation without
+ *  a cheaper model. Distinct from a models.json ref (which is "provider/id"). */
+export declare const SESSION_MODEL_REF = "session";
+/** A model defined in models.json, addressed by provider + id. */
+export interface CompressionModelInfo {
+    provider: string;
+    id: string;
+    name?: string;
+}
+/** A resolved model ready for an LLM call. */
+export interface ResolvedCompressionModel {
+    provider: string;
+    id: string;
+    model: Model<Api>;
+}
+/** Result of resolving a user-supplied ref. `model` is set when the ref is
+ *  unambiguous; `ambiguous` lists candidates when a bare id matches several. */
+export interface ResolveResult {
+    model: ResolvedCompressionModel | null;
+    ambiguous: CompressionModelInfo[];
+}
+/** Injectable LLM call. Defaults to ModelRuntime.complete (streams SSE). */
+export type CompleteFn = (model: Model<Api>, context: Context, options?: ModelsApiStreamOptions<Api>) => Promise<AssistantMessage>;
+export interface CompressionModelClientOptions {
+    /** Override the models.json path (default: ~/.pi/agent/models.json). */
+    modelsPath?: string;
+    /** Injectable LLM call for tests. */
+    complete?: CompleteFn;
+    /** Injectable runtime factory for tests. */
+    createRuntime?: (opts: {
+        modelsPath?: string;
+    }) => Promise<ModelRuntime>;
+}
+/** Default models.json path — Pi's own agent dir (homedir/.pi/agent by default,
+ *  honors the PI_CODING_AGENT_DIR override). */
+export declare function defaultModelsPath(): string;
+/**
+ * Client for the dedicated compression model. Reads ~/.pi/agent/models.json for
+ * model discovery and uses a ModelRuntime (same source Pi uses) for the actual
+ * LLM call, so provider-specific request/auth handling is reused rather than
+ * re-implemented.
+ */
+export declare class CompressionModelClient {
+    private readonly modelsPath;
+    private readonly complete;
+    private readonly createRuntime;
+    private runtimePromise;
+    constructor(options?: CompressionModelClientOptions);
+    private getRuntime;
+    /** Models the user defined in models.json (NOT built-in providers). */
+    listModels(): Promise<CompressionModelInfo[]>;
+    /** Resolve a ref: "provider/id" (explicit) or a bare id (searched across
+     *  models.json first, then built-in providers). */
+    resolveModel(ref: string): Promise<ResolveResult>;
+    /** Generate a summary with the resolved model from a FULLY BUILT context
+     *  (the caller controls systemPrompt/messages/tools — used for both the
+     *  fresh single-message prompt and the shared-prefix prompt). Throws on API
+     *  error or an empty response — the caller falls back to the main model. */
+    summarizeContext(resolved: ResolvedCompressionModel, context: Context, maxTokens: number): Promise<string>;
+    /** Generate a summary of `content` with the resolved model using a fresh
+     *  single-message prompt (no session prefix reuse). */
+    summarize(resolved: ResolvedCompressionModel, content: string, systemPrompt: string, maxTokens: number): Promise<string>;
+}
+/** System prompt for the compression model: reuse the kernel's tier-1 rules so
+ *  its output matches the quality/format the main model would produce. */
+export declare function buildSummarizeSystemPrompt(prompts: {
+    compressPhilosophy: string;
+    howToCompressRules: string;
+}, topic: string | undefined): string;
+/** Truncate very large content, keeping the head (goal/early context) and tail
+ *  (most recent state) with a marker in the middle. */
+export declare function truncateContent(content: string, maxChars: number): string;

package/dist/compress-tool.d.ts

@@ -1,5 +1,5 @@
 import { Type, type Static } from "typebox";
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ToolDefinition } 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";
@@ -20,7 +20,7 @@ declare const CompressParams: Type.TObject<{
     summaryMaxChars: Type.TOptional<Type.TNumber>;
 }>;
 type CompressArgs = Static<typeof CompressParams>;
-export declare function makeCompressTool(runtime: AcpRuntime, overrides?: ToolPromptOverrides): ToolDefinition<typeof CompressParams>;
+export declare function makeCompressTool(runtime: AcpRuntime, pi: ExtensionAPI, overrides?: ToolPromptOverrides): ToolDefinition<typeof CompressParams>;
 type RangeEntry = Static<typeof RangeSpec>;
 export declare function normalizeRanges(args: CompressArgs): RangeEntry[] | string;
 export declare function tailRepair(s: string): string | undefined;

package/dist/config-dir.d.ts

@@ -1 +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[];

package/dist/config.d.ts

@@ -334,6 +334,10 @@ export interface AdapterConfig {
      *  replacing the kernel's tuned compression rules may reduce summary quality
      *  (lost paths/signatures/decisions → worse retrieval). */
     acknowledgePromptsRisk?: boolean;
+    /** Model ref (bare id or "provider/id") from models.json used to write
+     *  compression summaries with a dedicated (usually cheaper) model. Absent =
+     *  the main model writes summaries (default). Set via `/acp compact <id>`. */
+    compressionModelId?: string;
     /** 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
@@ -378,9 +382,19 @@ 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

package/dist/contract.js

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

package/dist/floor-stale.d.ts

@@ -26,6 +26,8 @@ export declare function usageAnchorPredatesCompression(entries: AnchorEntry[]):
 export interface AnchorStaleness {
     predates: boolean;
     netReclaimed: number;
+    fresh: boolean;
+    lastRealTokens: number;
 }
 export declare function compressionAnchorStaleness(entries: AnchorEntry[], blocks: readonly CompressionBlock[], countTokens: (text: string) => number): AnchorStaleness;
 export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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";
@@ -6,3 +7,4 @@ 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;