billion-context-pi 0.1.74 → 0.1.75-pr.493.309

package/README.md

@@ -76,6 +76,14 @@ pi install npm:billion-context-pi
 
 That's it. The extension auto-loads on next Pi startup. No configuration needed — it reads your model's context window automatically.
 
+**Prefer a stable channel?** Install with the `stable` dist-tag instead:
+
+```bash
+pi install npm:billion-context-pi@stable
+```
+
+Stable releases are cut explicitly (less often than regular releases). Stable installs auto-update to the newest *stable* release only — regular releases and dev prereleases never reach them. Plain installs track `latest`. Switch channels at any time by reinstalling with the other spec.
+
 > **Using another sub-agent extension?** billion-context-pi ships its own `acp_delegate` sub-agent tool (see below) at a fraction of the context cost (~600 tok vs ~7K tok/turn). Two delegation tools in one session only make the model's choice noisier, so pick one:
 > - **Use ACP's delegate** — remove the other extension: `pi remove npm:pi-subagents`
 > - **Keep your own sub-agent** — turn ACP's delegate off in `acp.json`: `{ "delegate": false }` (see *Using your own sub-agent instead* below)
@@ -104,6 +112,16 @@ This has two practical implications:
 
 2. **Even with a single compression plugin, interference is still possible in rare cases.** Load order under Pi is determined by filesystem discovery order (`fs.readdirSync` over `.pi/extensions/` → global → packages), which is not fully deterministic. If another (non-compression) extension also hooks the `context` event and happens to load *after* billion-context-pi, it could modify the compressed output. billion-context-pi rebuilds its working set from the session log rather than the chained input, which makes it robust to handlers that run *before* it — but it cannot defend against a handler that runs *after* it. This is a limitation of Pi's extension model; if you observe unexpected context behavior, check whether other installed extensions intercept the `context` event.
 
+### Sidecar contract (downstream tools)
+
+Compression state lives next to the session log in `<sessionFile>.acp.json`. For tools that read it directly (cross-session retrieval, memory layers):
+
+- The file carries `schemaVersion` and `producer` at the top level. **A missing `schemaVersion` means v1.** An unknown *newer* version means fields may have changed — skip the file, log once, never rewrite it.
+- `blocks[]` entries match the exported `BcpBlockV1` type (kernel `CompressionBlock` verbatim); unknown extra fields are additive and must be ignored.
+- The file is always replaced **atomically** (temp file + rename), so a concurrent reader sees either the previous or the next complete file, never a torn write.
+
+Import the contract from TypeScript via `import type { BcpBlockV1 } from "billion-context-pi/contract"`; a JSON Schema for offline validation is published as the `billion-context-pi/contract/schema` subpath. No runtime dependency is required — the file remains the source of truth.
+
 ## Host support
 
 billion-context-pi is built for the **Pi** coding agent (`@earendil-works/pi-coding-agent`) and detects the host at session start — the full client → package table lives in [Which do I need?](#which-do-i-need):

package/README.zh-CN.md

@@ -75,6 +75,14 @@ pi install npm:billion-context-pi
 
 完成。扩展在下次 Pi 启动时自动加载。无需配置 —— 它会自动读取模型的上下文窗口。
 
+**想用 stable 通道?** 改用 `stable` dist-tag 安装:
+
+```bash
+pi install npm:billion-context-pi@stable
+```
+
+stable 版本是显式指定发布的(频率低于常规发版)。stable 安装的自动更新只追最新的 *stable* 正式版 —— 常规正式版和 dev 预发布版都不会推给它们。普通安装跟踪 `latest`。随时可以用另一个 spec 重装来切换通道。
+
 > **你另有子代理扩展?** billion-context-pi 自带 `acp_delegate` 子代理工具(见下文),上下文成本极低(~600 tok vs ~7K tok/轮)。同一会话里两套委派工具只会让模型的选择更混乱,二选一:
 > - **用 ACP 的 delegate** —— 卸载另一个扩展:`pi remove npm:pi-subagents`
 > - **保留你自己的子代理** —— 在 `acp.json` 里关掉 ACP 的 delegate:`{ "delegate": false }`(见下文*改用你自己的子代理*)
@@ -257,6 +265,16 @@ billion-context-pi 把每个会话的压缩状态持久化在会话转录文件
 
 `.acp.json` 旁挂文件承载了你的压缩块。没有它,会话就会以完整原始历史运行,直到 ACP 再次压缩。
 
+### 旁挂文件契约(下游工具)
+
+直接读取 `<sessionFile>.acp.json` 的工具(跨会话检索、记忆层等)依赖以下契约:
+
+- 文件顶层携带 `schemaVersion` 与 `producer`。**缺失 `schemaVersion` 即视为 v1**(契约引入前的旧文件)。遇到未知的*更高*版本意味着字段可能已变化——跳过该文件、记一次日志、绝不改写它。
+- `blocks[]` 条目符合导出的 `BcpBlockV1` 类型(kernel `CompressionBlock` 原样存储);未知的额外字段是增量式的,读取方必须忽略。
+- 文件始终以**原子方式**替换(临时文件 + rename),并发读取方看到的要么是前一个完整文件、要么是后一个完整文件,绝不会读到半截写入。
+
+TypeScript 中通过 `import type { BcpBlockV1 } from "billion-context-pi/contract"` 导入契约;离线校验用的 JSON Schema 以 `billion-context-pi/contract/schema` 子路径发布。无需任何运行时依赖——文件本身仍是唯一事实来源。
+
 ### 迁移会话(跨机器拷贝 / 备份恢复)
 
 Pi 内置的导出/导入只搬运**转录**,不搬 ACP 状态。会丢失两样东西:

package/dist/chunk-FTCH7KHF.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.75" : "dev"}`;
+}
+
+export {
+  __export,
+  SIDECAR_SCHEMA_VERSION,
+  sidecarProducer
+};
+//# sourceMappingURL=chunk-FTCH7KHF.js.map

package/dist/chunk-FTCH7KHF.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,WAAkB,KAAK;AAC/F;","names":[]}

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-FTCH7KHF.js";
+export {
+  SIDECAR_SCHEMA_VERSION,
+  sidecarProducer
+};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

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