billion-context-pi-lean 0.1.56-lean.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kunkun9527
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# 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.56` for reliable behavior.
+
+## Context Savings
+
+In a local comparison against `billion-context-pi@0.1.52` with delegation disabled, persistent ACP prompt and tool metadata dropped from roughly 22,645 characters to 2,859 characters, achieving an approximate 87% reduction in static text overhead. Actual token savings may vary based on model tokenizer and prompt caching behavior.
+
+## 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.52` |
+| --- | ---: | ---: |
+| `compress` | 231 | 549 |
+| Context operations | `acp_context`: 90 | `decompress` + `search_context` + `acp_status`: 1,095 |
+| System prompt additions | 369 | 4,417 |
+| **Total** | **690** | **6,061** |
+
+This saves **5,371 tokens (88.6%)** compared to the pinned upstream package.
+The benchmark was measured on Pi 0.84.4 with `pi-context-view@0.4.3` in a fresh isolated session, excluding built-in tools, skills, context files, and unrelated extensions. Context View estimates tokens as `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).

package/README.zh-CN.md

@@ -0,0 +1,79 @@
+# billion-context-pi-lean
+
+[English](README.md)
+
+基于 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) 的精简封装。在完整保留上下文压缩引擎的同时，大幅剔除系统提示词与工具 Schema 中的冗余文本，显著降低上下文初始开销。
+
+## 核心特性
+
+* 完整上下文引擎：保留上游的对话历史压缩、分层摘要、主动提示（Nudge）、溢出恢复、重试机制与工具保护能力。
+* 优化工具布局：高频使用的 `compress` 工具直接对外暴露，其余 `decompress`、`search_context` 与 `acp_status` 操作整合为按需调用的 `acp_context` 入口。
+* 纯粹专注：主动移除了内置的 Delegation 代理分发与自动更新逻辑；如需多 Agent 协作，建议搭配独立的 Subagent 扩展使用。上游依赖版本锁定为 `billion-context-pi@0.1.56`，确保运行稳定可靠。
+
+## 精简优化成效
+
+在关闭 Delegation 的情况下，与原版 `billion-context-pi@0.1.52` 本地对比：固定的 ACP 系统提示词与工具元数据字符量从约 22,645 字符大幅缩减至 2,859 字符，常驻静态文本减少约 87%。实际 Token 节省情况会因模型分词器及 Prompt 缓存机制而略有差异。
+
+## 安装
+
+```bash
+pi install git:github.com/kunkun9527/billion-context-pi-lean
+```
+
+也可以通过本地克隆进行安装：
+
+```bash
+git clone https://github.com/kunkun9527/billion-context-pi-lean.git
+cd billion-context-pi-lean
+npm install
+pi install ./
+```
+
+请勿与其它 `billion-context-pi` 扩展同时加载，以防重复注册 ACP 工具与生命周期 Hooks。
+
+## 使用方法
+
+模型可见工具包括：
+
+```text
+compress
+acp_context
+```
+
+`acp_context` 支持 `decompress`、`search_context`、`acp_status` 和 `help`。
+
+```json
+{
+  "op": "search_context",
+  "args": {
+    "query": "authentication"
+  }
+}
+```
+
+仅在确需查看完整上游 Schema 时调用 `help`。
+
+## 初始化上下文占用对比
+
+单独启用本扩展时，注入到模型初始上下文中的 Token 占用实测如下：
+
+| 项目 | Lean 精简版 | 原版 `billion-context-pi@0.1.52` |
+| --- | ---: | ---: |
+| `compress` | 231 | 549 |
+| 上下文检索与操作 | `acp_context`: 90 | `decompress` + `search_context` + `acp_status`: 1,095 |
+| 系统提示词增量 | 369 | 4,417 |
+| **合计** | **690** | **6,061** |
+
+相比固定版本的上游扩展，初始开销减少了 **5,371 tokens（88.6%）**。
+测试环境为 Pi 0.84.4 与 `pi-context-view@0.4.3` 独立会话，排除了 Pi 内置工具、Skills、上下文文件与无关扩展。Context View 按 `ceil(字符数 / 4)` 估算。未计入不会发送给模型的纯运行时 UI 与 Slash 命令。
+
+## 本地开发
+
+```bash
+npm ci
+npm run check
+```
+
+## 开源协议与致谢
+
+MIT 协议。本包装层基于采用 MIT 协议的 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)。

package/index.ts

@@ -0,0 +1,266 @@
+// billion-context-pi-lean: keep compress direct and route low-frequency ACP tools locally.
+import type {
+  ExtensionAPI,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { createAcpExtension } from "billion-context-pi";
+import { Type } from "typebox";
+import { Check, Errors } from "typebox/value";
+
+const COLLAPSED_DISPLAY_SERVICE = Symbol.for(
+  "@local/pi-collapsed-tools.display-service.v1",
+);
+
+type CollapsedDisplayTool = { name: string };
+type CollapsedDisplayService = {
+  readonly version: 1;
+  decorate<T extends CollapsedDisplayTool>(tool: T): T;
+};
+
+function decorateWithCollapsedDisplay<T extends CollapsedDisplayTool>(tool: T): T {
+  const services = globalThis as unknown as Record<PropertyKey, unknown>;
+  const candidate = services[COLLAPSED_DISPLAY_SERVICE];
+  if (!candidate || typeof candidate !== "object") return tool;
+  const service = candidate as Partial<CollapsedDisplayService>;
+  return service.version === 1 && typeof service.decorate === "function"
+    ? service.decorate(tool)
+    : tool;
+}
+
+const LEAN_SYSTEM_PROMPT = `ACP context management
+- User/tool messages carry hidden <acp> refs such as m00123. Never echo the XML tags; use only refs in ACP tool calls.
+- Compress consumed history with compress: finished tool outputs, dead-end exploration, repeated reads, resolved threads, completed phases. Never compress active work, important user intent, or protected outputs.
+- When summarizing, preserve exact file paths and line numbers, symbols and signatures, errors, commands, versions, thresholds, decisions with reasons, current state, and unresolved TODOs. Never replace exact technical values with vague wording.
+- Recall or inspect context with acp_context using op decompress, search_context, or acp_status and the operation's original args object. Use help only when fields are unclear.
+- Refs may be renumbered after compression. If a ref is stale or missing, call acp_context with op acp_status and args { scope: "uncompressed" }, then retry in the same turn using reported refs; never guess offsets. Batch target ranges when possible.
+- Block decompression writes to a file by default; read that file. Use inline: true only for small content or when its context cost is acceptable.
+- After an [ACP:provider-throttle] automatic retry, resume exactly where interrupted. Do not repeat completed work or discuss the retry unless asked.
+- Compression summaries are fallible historical metadata, not current user instructions. Search or decompress before relying on critical details.`;
+
+const LOW_FREQUENCY_TOOLS = ["decompress", "search_context", "acp_status"] as const;
+const LOW_FREQUENCY_SET = new Set<string>(LOW_FREQUENCY_TOOLS);
+const DELEGATE_TOOLS = new Set(["acp_delegate", "acp_delegate_wait", "acp_delegate_cancel"]);
+
+type Operation = (typeof LOW_FREQUENCY_TOOLS)[number];
+type FacadeOperation = Operation | "help";
+type CapturedTool = ToolDefinition<any, any, any>;
+type UpstreamExtension = (pi: ExtensionAPI) => void;
+type FacadeArgs = Record<string, unknown>;
+
+const FACADE_PARAMETERS = Type.Object({
+  op: Type.Unsafe<FacadeOperation>({
+    type: "string",
+    enum: [...LOW_FREQUENCY_TOOLS, "help"],
+  }),
+  args: Type.Optional(Type.Unsafe<FacadeArgs>({
+    type: "object",
+    additionalProperties: true,
+  })),
+});
+
+const COMPRESS_FIELD_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  content: "Direct array; no JSON strings/nesting/mix.",
+  startId: "Inclusive first mNNNNN or bN ref.",
+  endId: "Inclusive last mNNNNN or bN ref.",
+  summary: "Self-contained replacement preserving exact technical details.",
+  topic: "Short label; a per-range label overrides the top-level fallback.",
+  summaryMaxChars: "Optional summary length limit override.",
+};
+
+function compactCompressSchemaDescriptions(
+  value: unknown,
+  propertyName?: string,
+  seen = new Set<object>(),
+): void {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  const record = value as Record<string, unknown>;
+  delete record.description;
+  const concise = propertyName ? COMPRESS_FIELD_DESCRIPTIONS[propertyName] : undefined;
+  if (concise) record.description = concise;
+
+  for (const [key, child] of Object.entries(record)) {
+    if (key === "properties" && child !== null && typeof child === "object") {
+      for (const [name, schema] of Object.entries(child as Record<string, unknown>)) {
+        compactCompressSchemaDescriptions(schema, name, seen);
+      }
+      continue;
+    }
+    compactCompressSchemaDescriptions(child, undefined, seen);
+  }
+}
+
+function appendSystemPrompt(base: unknown): string {
+  const text = Array.isArray(base) ? base.join("\n") : typeof base === "string" ? base : "";
+  return `${text}\n\n${LEAN_SYSTEM_PROMPT}`;
+}
+
+function rewriteText(text: string): string {
+  return text
+    .replace(
+      /\b(search_context|decompress|acp_status)\((\{[^\r\n]*\})\)/g,
+      (_, op: string, args: string) => `acp_context({ op: "${op}", args: ${args} })`,
+    )
+    .replace(
+      /\brun acp_status\b/gi,
+      'call acp_context({ op: "acp_status", args: {} })',
+    )
+    .replace(
+      /\buse search_context or decompress\b/gi,
+      'use acp_context with op "search_context" or "decompress"',
+    )
+    .replace(
+      /\buse search_context\b/gi,
+      'use acp_context with op "search_context"',
+    );
+}
+
+function rewriteModelFacingText(value: unknown, seen = new WeakMap<object, unknown>()): unknown {
+  if (typeof value === "string") return rewriteText(value);
+  if (value === null || typeof value !== "object") return value;
+  const cached = seen.get(value);
+  if (cached) return cached;
+
+  if (Array.isArray(value)) {
+    const copy: unknown[] = [];
+    seen.set(value, copy);
+    for (const item of value) copy.push(rewriteModelFacingText(item, seen));
+    return copy;
+  }
+
+  const copy: Record<string, unknown> = {};
+  seen.set(value, copy);
+  for (const [key, item] of Object.entries(value)) {
+    copy[key] = rewriteModelFacingText(item, seen);
+  }
+  return copy;
+}
+
+function validationError(tool: CapturedTool, args: FacadeArgs): string | undefined {
+  if (!tool.parameters || Check(tool.parameters, args)) return undefined;
+  const first = Errors(tool.parameters, args)[0];
+  const location = first?.instancePath || "/";
+  const reason = first?.message || "arguments do not match the upstream schema";
+  return `${location}: ${reason}`;
+}
+
+function helpResult(args: FacadeArgs, tools: Map<string, CapturedTool>) {
+  const requested = typeof args.tool === "string" ? args.tool : "";
+  if (!requested) {
+    return {
+      content: [{
+        type: "text" as const,
+        text: "Operations: search_context({query, limit?}), decompress({blockId, full?, toFile?, inline?}), acp_status({scope?, view?, tool?, sort?, limit?}). For a full schema, use op help with args {tool: operationName}.",
+      }],
+      details: { operation: "help" },
+    };
+  }
+  if (!LOW_FREQUENCY_SET.has(requested)) {
+    throw new Error(`acp_context help operation is unknown: ${requested}`);
+  }
+  const tool = tools.get(requested);
+  if (!tool) throw new Error(`acp_context could not find upstream tool: ${requested}`);
+  return {
+    content: [{
+      type: "text" as const,
+      text: [
+        requested,
+        tool.description,
+        "Pass args matching this schema:",
+        JSON.stringify(tool.parameters, null, 2),
+      ].filter(Boolean).join("\n\n"),
+    }],
+    details: { operation: requested },
+  };
+}
+
+function wrapCompress(tool: CapturedTool): CapturedTool {
+  return {
+    ...tool,
+    description: "Replace consumed conversation ranges with self-contained summaries using mNNNNN or bN refs.",
+    promptSnippet: "",
+    promptGuidelines: [],
+    async execute(callId, params, signal, onUpdate, ctx) {
+      const forwardUpdate = onUpdate
+        ? (update: unknown) => onUpdate(rewriteModelFacingText(update) as any)
+        : undefined;
+      const result = await tool.execute(callId, params, signal, forwardUpdate, ctx);
+      return rewriteModelFacingText(result) as any;
+    },
+  };
+}
+
+function facadeTool(tools: Map<string, CapturedTool>): ToolDefinition<typeof FACADE_PARAMETERS, unknown, unknown> {
+  return {
+    name: "acp_context",
+    label: "ACP Context",
+    description: 'Search, restore, or inspect ACP context. Pass original operation args; if unsure call { op: "help", args: { tool: "search_context" } } (replace tool as needed).',
+    promptSnippet: "",
+    promptGuidelines: [],
+    parameters: FACADE_PARAMETERS,
+    async execute(callId, params, signal, onUpdate, ctx) {
+      if (params.op === "help") return helpResult(params.args ?? {}, tools);
+      const tool = tools.get(params.op);
+      if (!tool) throw new Error(`acp_context could not find upstream tool: ${params.op}`);
+      const args = params.args ?? {};
+      const invalid = validationError(tool, args);
+      if (invalid) {
+        throw new Error(
+          `acp_context ${params.op} args invalid at ${invalid}. Use op help with args {"tool":"${params.op}"} for the full schema.`,
+        );
+      }
+      const forwardUpdate = onUpdate
+        ? (update: unknown) => onUpdate(rewriteModelFacingText(update) as any)
+        : undefined;
+      const result = await tool.execute(callId, args, signal, forwardUpdate, ctx);
+      return rewriteModelFacingText(result) as any;
+    },
+  };
+}
+
+export function createLeanAcpExtension(
+  upstream: UpstreamExtension = createAcpExtension({ delegate: false, autoUpdate: false }),
+): (pi: ExtensionAPI) => void {
+  return (pi: ExtensionAPI): void => {
+    const tools = new Map<string, CapturedTool>();
+    let promptHookRegistered = false;
+    const leanPi = new Proxy(pi, {
+      get(target, property, receiver) {
+        if (property === "registerTool") {
+          return (tool: CapturedTool) => {
+            if (DELEGATE_TOOLS.has(tool.name)) return;
+            if (LOW_FREQUENCY_SET.has(tool.name)) {
+              tools.set(tool.name, tool);
+              return;
+            }
+            if (tool.name === "compress") {
+              compactCompressSchemaDescriptions(tool.parameters);
+              target.registerTool(decorateWithCollapsedDisplay(wrapCompress(tool)));
+              return;
+            }
+            target.registerTool(decorateWithCollapsedDisplay(tool));
+          };
+        }
+        if (property === "on") {
+          return (eventName: string, handler: (...args: unknown[]) => unknown) => {
+            if (eventName !== "before_agent_start") {
+              return Reflect.apply(target.on, target, [eventName, handler]);
+            }
+            if (promptHookRegistered) return;
+            promptHookRegistered = true;
+            return Reflect.apply(target.on, target, [eventName, (event: { systemPrompt?: unknown }) => ({
+              systemPrompt: appendSystemPrompt(event.systemPrompt),
+            })]);
+          };
+        }
+        const value = Reflect.get(target, property, receiver);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+
+    upstream(leanPi);
+    pi.registerTool(decorateWithCollapsedDisplay(facadeTool(tools)));
+  };
+}
+
+export default createLeanAcpExtension();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "billion-context-pi-lean",
+  "version": "0.1.56-lean.2",
+  "type": "module",
+  "description": "Token-lean Pi facade for billion-context-pi with the full upstream context engine.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kunkun9527/billion-context-pi-lean.git"
+  },
+  "homepage": "https://github.com/kunkun9527/billion-context-pi-lean#readme",
+  "bugs": {
+    "url": "https://github.com/kunkun9527/billion-context-pi-lean/issues"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "check": "npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "billion-context-pi": "0.1.56",
+    "typebox": "1.3.7"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/tests/facade.test.mjs

@@ -0,0 +1,307 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "../node_modules/@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti.mjs";
+
+const jiti = createJiti(import.meta.url, { moduleCache: false });
+const extensionModule = await jiti.import("../index.ts");
+const extension = extensionModule.default ?? extensionModule;
+const { createLeanAcpExtension } = extensionModule;
+
+function createPi() {
+  const tools = [];
+  const handlers = new Map();
+  const noOp = () => undefined;
+  return new Proxy({
+    tools,
+    handlers,
+    registerTool(tool) {
+      tools.push(tool);
+    },
+    on(event, handler) {
+      const listeners = handlers.get(event) ?? [];
+      listeners.push(handler);
+      handlers.set(event, listeners);
+    },
+    registerCommand: noOp,
+    registerShortcut: noOp,
+    registerMessageRenderer: noOp,
+    registerProvider: noOp,
+    registerFlag: noOp,
+    getFlag: () => undefined,
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools: noOp,
+    appendEntry: noOp,
+    sendMessage: noOp,
+    events: { on: noOp, emit: noOp },
+  }, {
+    get(target, property) {
+      return property in target ? target[property] : noOp;
+    },
+  });
+}
+
+const schemas = {
+  compress: {
+    type: "object",
+    description: "large outer description",
+    properties: {
+      topic: { type: "string", description: "large top-level topic description" },
+      content: {
+        type: "array",
+        description: "large nested description",
+        items: {
+          type: "object",
+          properties: {
+            startId: { type: "string", description: "large start description" },
+            endId: { type: "string", description: "large end description" },
+            summary: { type: "string", description: "large summary description" },
+            topic: { type: "string", description: "large range topic description" },
+          },
+        },
+      },
+      summaryMaxChars: { type: "number", description: "large limit description" },
+    },
+    required: ["content"],
+  },
+  decompress: {
+    type: "object",
+    properties: {
+      blockId: { type: "string" },
+      full: { type: "boolean" },
+      toFile: { type: "string" },
+      inline: { type: "boolean" },
+    },
+    required: ["blockId"],
+  },
+  search_context: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      limit: { type: "number" },
+    },
+    required: ["query"],
+  },
+  acp_status: {
+    type: "object",
+    properties: {
+      scope: { type: "string" },
+      view: { type: "string" },
+      tool: { type: "string" },
+      sort: { type: "string" },
+      limit: { type: "number" },
+    },
+  },
+};
+
+function fakeUpstream(calls = [], executions = { count: 0 }) {
+  return (pi) => {
+    for (const name of ["compress", "decompress", "search_context", "acp_status"]) {
+      pi.registerTool({
+        name,
+        label: name,
+        description: `${name} full upstream description`,
+        parameters: structuredClone(schemas[name]),
+        async execute(...args) {
+          executions.count += 1;
+          calls.push([name, ...args]);
+          return {
+            content: [{
+              type: "text",
+              text: name === "search_context"
+                ? 'result → decompress({ blockId: "b12" })'
+                : name === "compress"
+                  ? 'Nothing to do — Run acp_status, then call compress again. Use search_context or decompress to retrieve details. Try search_context({ query: "auth token" }).'
+                  : `${name} result`,
+            }],
+          };
+        },
+      });
+    }
+    pi.registerTool({ name: "acp_delegate", async execute() {} });
+    pi.on("before_agent_start", () => ({ systemPrompt: "upstream prompt must be suppressed" }));
+  };
+}
+
+function getTool(pi, name) {
+  return pi.tools.find((tool) => tool.name === name);
+}
+
+test("registers only compress and acp_context provider tools", () => {
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream())(pi);
+  assert.deepEqual(pi.tools.map((tool) => tool.name), ["compress", "acp_context"]);
+});
+
+test("cooperates with an optional collapsed-display service without a local file dependency", () => {
+  const serviceKey = Symbol.for("@local/pi-collapsed-tools.display-service.v1");
+  const previous = globalThis[serviceKey];
+  const decorated = [];
+  globalThis[serviceKey] = {
+    version: 1,
+    decorate(tool) {
+      decorated.push(tool.name);
+      return tool;
+    },
+  };
+
+  try {
+    const pi = createPi();
+    createLeanAcpExtension(fakeUpstream())(pi);
+    assert.deepEqual(decorated, ["compress", "acp_context"]);
+  } finally {
+    if (previous === undefined) delete globalThis[serviceKey];
+    else globalThis[serviceKey] = previous;
+  }
+});
+
+test("keeps compress direct, retains concise critical descriptions, and rewrites stale status advice", async () => {
+  const calls = [];
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream(calls))(pi);
+  const tool = getTool(pi, "compress");
+  const result = await tool.execute(
+    "compress-1",
+    { content: [{ startId: "m1", endId: "m2", summary: "done" }] },
+    undefined,
+    undefined,
+    { cwd: "C:/work" },
+  );
+
+  const schema = tool.parameters;
+  const entries = schema.properties.content.items.properties;
+  assert.equal(schema.description, undefined);
+  assert.match(schema.properties.content.description, /direct array/i);
+  assert.match(schema.properties.content.description, /JSON strings|JSON-stringify/i);
+  assert.match(schema.properties.content.description, /mix/i);
+  assert.match(schema.properties.topic.description, /label/i);
+  assert.match(schema.properties.summaryMaxChars.description, /length/i);
+  assert.match(entries.startId.description, /first/i);
+  assert.match(entries.endId.description, /last/i);
+  assert.match(entries.summary.description, /exact technical details/i);
+  assert.match(entries.topic.description, /label/i);
+  assert.doesNotMatch(JSON.stringify(schema), /large .* description/);
+  const rewritten = result.content[0].text;
+  assert.match(rewritten, /acp_context\(\{ op: "acp_status", args: \{\} \}\)/);
+  assert.match(rewritten, /use acp_context with op "search_context" or "decompress"/i);
+  assert.match(rewritten, /acp_context\(\{ op: "search_context", args: \{ query: "auth token" \} \}\)/);
+  assert.doesNotMatch(rewritten, /\b(?:search_context|decompress|acp_status)\s*\(/);
+  assert.doesNotMatch(rewritten, /\brun acp_status\b/i);
+  assert.doesNotMatch(rewritten, /\buse search_context\b/i);
+  assert.equal(calls[0][0], "compress");
+  assert.deepEqual(calls[0][2], { content: [{ startId: "m1", endId: "m2", summary: "done" }] });
+});
+test("routes all three low-frequency operations with original args and execution context", async () => {
+  const cases = [
+    ["search_context", { query: "architecture", limit: 8 }],
+    ["decompress", { blockId: "b11", toFile: "R:/Temp/history.txt", full: true }],
+    ["acp_status", { scope: "uncompressed", view: "messages", sort: "size", limit: 30 }],
+  ];
+
+  for (const [op, args] of cases) {
+    const calls = [];
+    const pi = createPi();
+    createLeanAcpExtension(fakeUpstream(calls))(pi);
+    const signal = new AbortController().signal;
+    const context = { cwd: "C:/work" };
+    await getTool(pi, "acp_context").execute(
+      `call-${op}`,
+      { op, args },
+      signal,
+      undefined,
+      context,
+    );
+    assert.equal(calls[0][0], op);
+    assert.equal(calls[0][1], `call-${op}`);
+    assert.deepEqual(calls[0][2], args);
+    assert.equal(calls[0][3], signal);
+    assert.equal(calls[0][5], context);
+  }
+});
+
+test("rewrites search results to the facade call syntax", async () => {
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream())(pi);
+  const result = await getTool(pi, "acp_context").execute(
+    "search-1",
+    { op: "search_context", args: { query: "needle" } },
+  );
+  assert.equal(
+    result.content[0].text,
+    'result → acp_context({ op: "decompress", args: { blockId: "b12" } })',
+  );
+});
+
+test("facade advertises help syntax and discloses an upstream schema without executing it", async () => {
+  const executions = { count: 0 };
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream([], executions))(pi);
+  const tool = getTool(pi, "acp_context");
+  assert.match(
+    tool.description,
+    /\{ op: "help", args: \{ tool: "search_context" \} \}/,
+  );
+  const result = await tool.execute(
+    "help-1",
+    { op: "help", args: { tool: "decompress" } },
+  );
+  assert.equal(executions.count, 0);
+  assert.match(result.content[0].text, /blockId/);
+  assert.match(result.content[0].text, /toFile/);
+});
+
+test("invalid facade args fail locally with an on-demand help hint", async () => {
+  const executions = { count: 0 };
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream([], executions))(pi);
+  await assert.rejects(
+    getTool(pi, "acp_context").execute(
+      "invalid-1",
+      { op: "decompress", args: { inline: true } },
+    ),
+    /args invalid.*op help.*decompress/,
+  );
+  assert.equal(executions.count, 0);
+});
+
+test("suppresses the upstream prompt and keeps concise summary-fidelity rules", async () => {
+  const pi = createPi();
+  createLeanAcpExtension(fakeUpstream())(pi);
+  const hooks = pi.handlers.get("before_agent_start");
+  assert.equal(hooks.length, 1);
+  const result = await hooks[0]({ systemPrompt: "base prompt" });
+  assert.match(result.systemPrompt, /^base prompt/);
+  assert.match(result.systemPrompt, /Compress consumed history with compress/);
+  assert.match(result.systemPrompt, /exact file paths and line numbers/i);
+  assert.match(result.systemPrompt, /symbols and signatures/i);
+  assert.match(result.systemPrompt, /errors, commands, versions, thresholds/i);
+  assert.match(result.systemPrompt, /decisions with reasons, current state, and unresolved TODOs/i);
+  assert.match(result.systemPrompt, /Refs may be renumbered after compression/i);
+  assert.match(result.systemPrompt, /Block decompression writes to a file by default/i);
+  assert.match(result.systemPrompt, /provider-throttle.*resume exactly where interrupted/i);
+  assert.match(result.systemPrompt, /acp_context/);
+  assert.doesNotMatch(result.systemPrompt, /upstream prompt must be suppressed/);
+});
+
+test("real upstream registration exposes the intended two-tool surface", () => {
+  const pi = createPi();
+  extension(pi);
+  assert.deepEqual(pi.tools.map((tool) => tool.name), ["compress", "acp_context"]);
+});
+
+test("provider-facing metadata stays within the lean budget", () => {
+  const pi = createPi();
+  extension(pi);
+  const metadata = pi.tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    promptSnippet: tool.promptSnippet,
+    promptGuidelines: tool.promptGuidelines,
+  }));
+  const serialized = JSON.stringify(metadata);
+  assert.ok(
+    serialized.length <= 1450,
+    `lean metadata grew to ${serialized.length} characters`,
+  );
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "index.ts"
+  ]
+}