@lucascouts/claude-agent-acp-plus 0.12.0 → 0.14.0

package/dist/context-compaction-meta.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The versioned `_meta` extension that carries context-compaction facts on the
+ * synthetic ACP tool call (story 010, R2.1/D3).
+ *
+ * Why an extension rather than the protocol's own variant: ACP 1.4 does define
+ * a `compaction_update`, but the Rust crate the packaged Zed links
+ * (`agent-client-protocol 2.0.0`) carries no `compaction` symbol at all, so
+ * that variant cannot be deserialised no matter what this adapter sends. The
+ * reachable pattern is the one downstream patch `0011` already proves: emit a
+ * `_meta` key no ACP variant claims, and let a downstream patch read it. The
+ * tool call renders with `ToolKind::Think`'s icon even with no patch present,
+ * so R2.1 ships and works on its own.
+ *
+ * Why the version field is not optional (D3): it is what makes the two halves
+ * independently releasable in BOTH directions — a newer adapter against an
+ * older Zed degrades to generic tool rendering, and an older adapter against a
+ * newer Zed simply never sends the key. A payload with no version is a payload
+ * a reader cannot degrade from, so it can only be guessed at.
+ *
+ * Kept self-contained — no import from `acp-agent.ts`, mirroring
+ * `thinking-option.ts` and `rewind-command.ts`. The reason is merge cost:
+ * `acp-agent.ts` is a ~9,700-line file that changes upstream almost daily, so
+ * every coupling to it is paid again at each sync.
+ */
+/** The `_meta` key the downstream Zed patch looks for. */
+export declare const CONTEXT_COMPACTION_META_KEY = "contextCompaction";
+/**
+ * Schema version of the payload under {@link CONTEXT_COMPACTION_META_KEY}.
+ * Bump it whenever a field's meaning changes; a reader that does not know the
+ * value it receives must fall back to generic tool rendering rather than
+ * interpret unknown fields.
+ */
+export declare const CONTEXT_COMPACTION_META_VERSION = 1;
+/**
+ * Why the compaction ran: `"manual"` for a user-issued `/compact`,
+ * `"automatic"` when the SDK compacted on its own to stay inside the window.
+ * Provider-neutral by design — the SDK spells the automatic case `"auto"`.
+ */
+export type ContextCompactionTrigger = "manual" | "automatic";
+/**
+ * Compaction-specific facts carried alongside the tool call. Every field
+ * except `version` is optional because the SDK frame that produced the event
+ * may not carry it: a terminal-only `status` message has no token counts, and
+ * an older CLI's `compact_boundary` omits `post_tokens`/`duration_ms`.
+ */
+export interface ContextCompactionMetadata {
+    /** Always {@link CONTEXT_COMPACTION_META_VERSION}; see D3 above. */
+    version: typeof CONTEXT_COMPACTION_META_VERSION;
+    /** Manual `/compact` or an automatic window-pressure compaction. */
+    trigger?: ContextCompactionTrigger;
+    /** Tokens occupying the context window before compaction. */
+    preTokens?: number;
+    /** Tokens occupying it after — absent on CLIs that don't report it. */
+    postTokens?: number;
+    /** How long the compaction took, in milliseconds. */
+    durationMs?: number;
+    /** Failure reason, present only on a `failed` lifecycle. */
+    error?: string;
+}
+/**
+ * Provider-neutral metadata for a synthetic ACP context-compaction tool call.
+ *
+ * The standard `toolCallId` and `status` fields own lifecycle identity and
+ * phase; this extension deliberately carries only compaction-specific facts,
+ * so a client that ignores `_meta` entirely still sees a correct tool
+ * lifecycle.
+ *
+ * @param metadata The facts known at this point in the lifecycle; the version
+ *   is stamped here rather than by each call site, so no caller can emit an
+ *   unversioned payload.
+ */
+export declare function createContextCompactionMeta(metadata?: Omit<ContextCompactionMetadata, "version">): Record<typeof CONTEXT_COMPACTION_META_KEY, ContextCompactionMetadata>;
+//# sourceMappingURL=context-compaction-meta.d.ts.map

package/dist/context-compaction-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-compaction-meta.d.ts","sourceRoot":"","sources":["../src/context-compaction-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,OAAO,EAAE,OAAO,+BAA+B,CAAC;IAChD,oEAAoE;IACpE,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,GACxD,MAAM,CAAC,OAAO,2BAA2B,EAAE,yBAAyB,CAAC,CAOvE"}

package/dist/context-compaction-meta.js

@@ -0,0 +1,53 @@
+/**
+ * The versioned `_meta` extension that carries context-compaction facts on the
+ * synthetic ACP tool call (story 010, R2.1/D3).
+ *
+ * Why an extension rather than the protocol's own variant: ACP 1.4 does define
+ * a `compaction_update`, but the Rust crate the packaged Zed links
+ * (`agent-client-protocol 2.0.0`) carries no `compaction` symbol at all, so
+ * that variant cannot be deserialised no matter what this adapter sends. The
+ * reachable pattern is the one downstream patch `0011` already proves: emit a
+ * `_meta` key no ACP variant claims, and let a downstream patch read it. The
+ * tool call renders with `ToolKind::Think`'s icon even with no patch present,
+ * so R2.1 ships and works on its own.
+ *
+ * Why the version field is not optional (D3): it is what makes the two halves
+ * independently releasable in BOTH directions — a newer adapter against an
+ * older Zed degrades to generic tool rendering, and an older adapter against a
+ * newer Zed simply never sends the key. A payload with no version is a payload
+ * a reader cannot degrade from, so it can only be guessed at.
+ *
+ * Kept self-contained — no import from `acp-agent.ts`, mirroring
+ * `thinking-option.ts` and `rewind-command.ts`. The reason is merge cost:
+ * `acp-agent.ts` is a ~9,700-line file that changes upstream almost daily, so
+ * every coupling to it is paid again at each sync.
+ */
+/** The `_meta` key the downstream Zed patch looks for. */
+export const CONTEXT_COMPACTION_META_KEY = "contextCompaction";
+/**
+ * Schema version of the payload under {@link CONTEXT_COMPACTION_META_KEY}.
+ * Bump it whenever a field's meaning changes; a reader that does not know the
+ * value it receives must fall back to generic tool rendering rather than
+ * interpret unknown fields.
+ */
+export const CONTEXT_COMPACTION_META_VERSION = 1;
+/**
+ * Provider-neutral metadata for a synthetic ACP context-compaction tool call.
+ *
+ * The standard `toolCallId` and `status` fields own lifecycle identity and
+ * phase; this extension deliberately carries only compaction-specific facts,
+ * so a client that ignores `_meta` entirely still sees a correct tool
+ * lifecycle.
+ *
+ * @param metadata The facts known at this point in the lifecycle; the version
+ *   is stamped here rather than by each call site, so no caller can emit an
+ *   unversioned payload.
+ */
+export function createContextCompactionMeta(metadata = {}) {
+    return {
+        [CONTEXT_COMPACTION_META_KEY]: {
+            version: CONTEXT_COMPACTION_META_VERSION,
+            ...metadata,
+        },
+    };
+}

package/dist/context-compaction.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Context compaction as ONE idempotent ACP tool lifecycle (story 010, R2.1/R2.2).
+ *
+ * What this replaces: the adapter used to infer compaction from a
+ * `compactionInProgress` boolean and narrate it as assistant text
+ * ("Compacting…", "Compacting completed."). The flag existed only because, in
+ * the adapter's own comment, the SDK's two terminal `status` messages were
+ * "indistinguishable" — a guess, not a signal. Once the lifecycle is explicit
+ * the guess is not merely redundant, it double-reports: the tool call says the
+ * compaction finished and the banner says so again. So the inference is
+ * DELETED, not left inert (D4) — a flag that no longer decides anything is a
+ * thing the next reader has to prove is inert.
+ *
+ * What replaces it: a small state machine that folds every event shape the SDK
+ * can produce onto a single tool call.
+ *
+ *   SDK event                                   → lifecycle call
+ *   ------------------------------------------- -----------------------------
+ *   `status` = "compacting"                     → start()      tool_call, in_progress
+ *   `stream_event` compaction block/delta       → heartbeat()  tool_call_update, in_progress
+ *   `status` with compact_result success/failed → finish()     tool_call_update, terminal
+ *   `compact_boundary` (token counts)           → finish(enrich) tool_call_update, metadata only
+ *   a terminal with no preceding "compacting"   → finish()     tool_call, terminal (standalone)
+ *   a DUPLICATED terminal                       → finish()     nothing
+ *
+ * The two hard cases pull in opposite directions and both are real:
+ *
+ *   - The SDK duplicates the terminal `compact_result` message for a single
+ *     failed compaction. Two terminals for one compaction must stay ONE report.
+ *   - One model turn can legitimately compact more than once. Two genuine
+ *     compactions must stay TWO distinguishable reports.
+ *
+ * The state machine separates them by phase rather than by identity: a
+ * terminal that arrives when the lifecycle has already terminated is a
+ * duplicate and changes nothing, while a fresh `compacting` status AFTER a
+ * terminal opens a new lifecycle with a new tool call id. A rule that instead
+ * suppressed by matching ids or payloads would satisfy one case by breaking
+ * the other.
+ *
+ * State lives until the owning turn's `result` (or an abort) rather than being
+ * cleared at each terminal, because the SDK can also omit the opening status
+ * on replay — the terminal has to be able to stand alone.
+ *
+ * Kept self-contained — no import from `acp-agent.ts`, mirroring
+ * `thinking-option.ts` and `rewind-command.ts`; what it needs from the adapter
+ * (the send chokepoint) is injected, which also leaves the whole state machine
+ * unit-testable without a live SDK session. The reason is merge cost:
+ * `acp-agent.ts` is a ~9,700-line file that changes upstream almost daily, so
+ * every coupling to it is paid again at each sync.
+ */
+import { SessionNotification } from "@agentclientprotocol/sdk";
+import { ContextCompactionMetadata } from "./context-compaction-meta.js";
+/** The phases a compaction can END in. `in_progress` is not terminal. */
+type CompactionStatus = "completed" | "failed";
+/** One compaction's identity and phase. */
+type CompactionState = {
+    /** The ACP tool call id every update for this compaction carries. */
+    toolCallId: string;
+    /** Set once the lifecycle has reported an outcome; the duplicate guard. */
+    terminalStatus?: CompactionStatus;
+    /** Stream heartbeats are collapsed to one keep-alive per lifecycle. */
+    heartbeatSent: boolean;
+};
+/**
+ * The adapter's send chokepoint, injected. Deliberately the ACP SDK's
+ * `SessionNotification` rather than an adapter-local alias, so this module
+ * needs nothing from `acp-agent.ts`.
+ */
+type SendUpdate = (notification: SessionNotification) => Promise<void>;
+/**
+ * Translates Claude's compaction signals into one idempotent ACP tool
+ * lifecycle. One instance per consumer; `reset()` at each turn boundary.
+ */
+export declare class ContextCompactionLifecycle {
+    private readonly sendUpdate;
+    private activeCompaction;
+    private outputDelivered;
+    private duplicateErrorOutput;
+    constructor(sendUpdate: SendUpdate);
+    /**
+     * Whether this turn already showed the user something about a compaction.
+     *
+     * The adapter reads it for two decisions the deleted banners used to make
+     * implicitly, by counting as delivered assistant text: an echo-less turn
+     * that only compacted (e.g. `/compact`) must not have its result text
+     * re-emitted by the issue-#453 fallback, and a replayed synthetic
+     * local-command frame from an earlier compact attempt must not be forwarded
+     * on top of the lifecycle.
+     */
+    get hasDeliveredOutput(): boolean;
+    /** Return to the unstarted state; call at each turn boundary. */
+    reset(): void;
+    /**
+     * Claude also emits a failed manual compaction's error as local-command
+     * stdout. Consume that one duplicate after the tool lifecycle already
+     * carried it, without hiding unrelated command output.
+     *
+     * Matching is by exact (trimmed) text and consumes at most once, so a
+     * command that genuinely prints the same string later still reaches the
+     * client.
+     *
+     * @returns `true` when the caller should drop this content.
+     */
+    consumeDuplicateErrorOutput(content: string): boolean;
+    /**
+     * Open the tool call the client renders. Idempotent while a compaction is
+     * still running (a repeated `compacting` status re-uses the open call); a
+     * `compacting` that arrives AFTER a terminal starts a fresh lifecycle, which
+     * is how two real compactions in one turn stay two reports.
+     *
+     * @param toolCallId The SDK message uuid — replay-stable, so a re-delivered
+     *   frame addresses the same tool call rather than inventing one.
+     */
+    start(sessionId: string, toolCallId: string): Promise<CompactionState>;
+    /**
+     * Keep the open call alive while compaction streams. Sent at most once per
+     * lifecycle: the deltas carry the generated summary, which stays internal to
+     * the agent, so repeating them would add noise and no information.
+     *
+     * @param fallbackId Used only when the opening status never arrived (replay).
+     */
+    heartbeat(sessionId: string, fallbackId: string): Promise<void>;
+    /**
+     * Report the outcome — exactly once per compaction.
+     *
+     * Three shapes converge here:
+     *  - no lifecycle open (the SDK omitted the opening status on replay): emit a
+     *    standalone terminal `tool_call`, so the event is reported rather than
+     *    dropped for lack of a start;
+     *  - the first terminal for an open lifecycle: a `tool_call_update` carrying
+     *    the status;
+     *  - a duplicate terminal: nothing at all.
+     *
+     * @param fallbackId Tool call id for the standalone shape.
+     * @param metadata Compaction facts; also emitted as `rawOutput` when non-empty,
+     *   so a client that ignores `_meta` can still show something.
+     * @param enrichTerminal Allow a SECOND update on an already-terminal
+     *   lifecycle that adds facts without re-reporting the outcome. Used by
+     *   `compact_boundary`, which arrives after the terminal `status` and is the
+     *   only frame carrying the token counts. The status field is omitted on that
+     *   update, so the client still sees exactly one terminal transition.
+     */
+    finish(sessionId: string, fallbackId: string, status: CompactionStatus, metadata?: Omit<ContextCompactionMetadata, "version">, enrichTerminal?: boolean): Promise<void>;
+    /** Arm {@link consumeDuplicateErrorOutput} for the stdout copy Claude emits. */
+    private rememberDuplicateErrorOutput;
+}
+/**
+ * Map the SDK's `compact_boundary` metadata onto the provider-neutral names of
+ * {@link ContextCompactionMetadata}. Fields an older CLI omits stay omitted
+ * rather than becoming `undefined` keys, so `rawOutput` and `_meta` never
+ * advertise a number nobody reported.
+ */
+export declare function contextCompactionMetadataFromBoundary(compactMetadata: {
+    trigger: "manual" | "auto";
+    pre_tokens: number;
+    post_tokens?: number;
+    duration_ms?: number;
+}): Omit<ContextCompactionMetadata, "version">;
+export {};
+//# sourceMappingURL=context-compaction.d.ts.map

package/dist/context-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-compaction.d.ts","sourceRoot":"","sources":["../src/context-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACL,yBAAyB,EAE1B,MAAM,8BAA8B,CAAC;AAEtC,yEAAyE;AACzE,KAAK,gBAAgB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE/C,2CAA2C;AAC3C,KAAK,eAAe,GAAG;IACrB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;GAIG;AACH,KAAK,UAAU,GAAG,CAAC,YAAY,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvE;;;GAGG;AACH,qBAAa,0BAA0B;IAKzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJvC,OAAO,CAAC,gBAAgB,CAA8B;IACtD,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,oBAAoB,CAAqB;gBAEpB,UAAU,EAAE,UAAU;IAEnD;;;;;;;;;OASG;IACH,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED,iEAAiE;IACjE,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAWrD;;;;;;;;OAQG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAqB5E;;;;;;OAMG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,GAAE,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAM,EACzD,cAAc,UAAQ,GACrB,OAAO,CAAC,IAAI,CAAC;IAgDhB,gFAAgF;IAChF,OAAO,CAAC,4BAA4B;CAQrC;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,eAAe,EAAE;IACrE,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAW7C"}

package/dist/context-compaction.js

@@ -0,0 +1,275 @@
+/**
+ * Context compaction as ONE idempotent ACP tool lifecycle (story 010, R2.1/R2.2).
+ *
+ * What this replaces: the adapter used to infer compaction from a
+ * `compactionInProgress` boolean and narrate it as assistant text
+ * ("Compacting…", "Compacting completed."). The flag existed only because, in
+ * the adapter's own comment, the SDK's two terminal `status` messages were
+ * "indistinguishable" — a guess, not a signal. Once the lifecycle is explicit
+ * the guess is not merely redundant, it double-reports: the tool call says the
+ * compaction finished and the banner says so again. So the inference is
+ * DELETED, not left inert (D4) — a flag that no longer decides anything is a
+ * thing the next reader has to prove is inert.
+ *
+ * What replaces it: a small state machine that folds every event shape the SDK
+ * can produce onto a single tool call.
+ *
+ *   SDK event                                   → lifecycle call
+ *   ------------------------------------------- -----------------------------
+ *   `status` = "compacting"                     → start()      tool_call, in_progress
+ *   `stream_event` compaction block/delta       → heartbeat()  tool_call_update, in_progress
+ *   `status` with compact_result success/failed → finish()     tool_call_update, terminal
+ *   `compact_boundary` (token counts)           → finish(enrich) tool_call_update, metadata only
+ *   a terminal with no preceding "compacting"   → finish()     tool_call, terminal (standalone)
+ *   a DUPLICATED terminal                       → finish()     nothing
+ *
+ * The two hard cases pull in opposite directions and both are real:
+ *
+ *   - The SDK duplicates the terminal `compact_result` message for a single
+ *     failed compaction. Two terminals for one compaction must stay ONE report.
+ *   - One model turn can legitimately compact more than once. Two genuine
+ *     compactions must stay TWO distinguishable reports.
+ *
+ * The state machine separates them by phase rather than by identity: a
+ * terminal that arrives when the lifecycle has already terminated is a
+ * duplicate and changes nothing, while a fresh `compacting` status AFTER a
+ * terminal opens a new lifecycle with a new tool call id. A rule that instead
+ * suppressed by matching ids or payloads would satisfy one case by breaking
+ * the other.
+ *
+ * State lives until the owning turn's `result` (or an abort) rather than being
+ * cleared at each terminal, because the SDK can also omit the opening status
+ * on replay — the terminal has to be able to stand alone.
+ *
+ * Kept self-contained — no import from `acp-agent.ts`, mirroring
+ * `thinking-option.ts` and `rewind-command.ts`; what it needs from the adapter
+ * (the send chokepoint) is injected, which also leaves the whole state machine
+ * unit-testable without a live SDK session. The reason is merge cost:
+ * `acp-agent.ts` is a ~9,700-line file that changes upstream almost daily, so
+ * every coupling to it is paid again at each sync.
+ */
+import { createContextCompactionMeta, } from "./context-compaction-meta.js";
+/**
+ * Translates Claude's compaction signals into one idempotent ACP tool
+ * lifecycle. One instance per consumer; `reset()` at each turn boundary.
+ */
+export class ContextCompactionLifecycle {
+    sendUpdate;
+    activeCompaction;
+    outputDelivered = false;
+    duplicateErrorOutput;
+    constructor(sendUpdate) {
+        this.sendUpdate = sendUpdate;
+    }
+    /**
+     * Whether this turn already showed the user something about a compaction.
+     *
+     * The adapter reads it for two decisions the deleted banners used to make
+     * implicitly, by counting as delivered assistant text: an echo-less turn
+     * that only compacted (e.g. `/compact`) must not have its result text
+     * re-emitted by the issue-#453 fallback, and a replayed synthetic
+     * local-command frame from an earlier compact attempt must not be forwarded
+     * on top of the lifecycle.
+     */
+    get hasDeliveredOutput() {
+        return this.outputDelivered;
+    }
+    /** Return to the unstarted state; call at each turn boundary. */
+    reset() {
+        this.activeCompaction = undefined;
+        this.outputDelivered = false;
+        this.duplicateErrorOutput = undefined;
+    }
+    /**
+     * Claude also emits a failed manual compaction's error as local-command
+     * stdout. Consume that one duplicate after the tool lifecycle already
+     * carried it, without hiding unrelated command output.
+     *
+     * Matching is by exact (trimmed) text and consumes at most once, so a
+     * command that genuinely prints the same string later still reaches the
+     * client.
+     *
+     * @returns `true` when the caller should drop this content.
+     */
+    consumeDuplicateErrorOutput(content) {
+        if (this.duplicateErrorOutput === undefined ||
+            content.trim() !== this.duplicateErrorOutput.trim()) {
+            return false;
+        }
+        this.duplicateErrorOutput = undefined;
+        return true;
+    }
+    /**
+     * Open the tool call the client renders. Idempotent while a compaction is
+     * still running (a repeated `compacting` status re-uses the open call); a
+     * `compacting` that arrives AFTER a terminal starts a fresh lifecycle, which
+     * is how two real compactions in one turn stay two reports.
+     *
+     * @param toolCallId The SDK message uuid — replay-stable, so a re-delivered
+     *   frame addresses the same tool call rather than inventing one.
+     */
+    async start(sessionId, toolCallId) {
+        if (this.activeCompaction && !this.activeCompaction.terminalStatus) {
+            return this.activeCompaction;
+        }
+        this.activeCompaction = { toolCallId, heartbeatSent: false };
+        this.outputDelivered = true;
+        await this.sendUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "tool_call",
+                toolCallId,
+                title: COMPACTION_TOOL_TITLE,
+                kind: "think",
+                status: "in_progress",
+                _meta: compactionToolMeta(),
+            },
+        });
+        return this.activeCompaction;
+    }
+    /**
+     * Keep the open call alive while compaction streams. Sent at most once per
+     * lifecycle: the deltas carry the generated summary, which stays internal to
+     * the agent, so repeating them would add noise and no information.
+     *
+     * @param fallbackId Used only when the opening status never arrived (replay).
+     */
+    async heartbeat(sessionId, fallbackId) {
+        const state = this.activeCompaction ?? (await this.start(sessionId, fallbackId));
+        if (state.terminalStatus || state.heartbeatSent)
+            return;
+        state.heartbeatSent = true;
+        await this.sendUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "tool_call_update",
+                toolCallId: state.toolCallId,
+                status: "in_progress",
+                _meta: compactionToolMeta(),
+            },
+        });
+    }
+    /**
+     * Report the outcome — exactly once per compaction.
+     *
+     * Three shapes converge here:
+     *  - no lifecycle open (the SDK omitted the opening status on replay): emit a
+     *    standalone terminal `tool_call`, so the event is reported rather than
+     *    dropped for lack of a start;
+     *  - the first terminal for an open lifecycle: a `tool_call_update` carrying
+     *    the status;
+     *  - a duplicate terminal: nothing at all.
+     *
+     * @param fallbackId Tool call id for the standalone shape.
+     * @param metadata Compaction facts; also emitted as `rawOutput` when non-empty,
+     *   so a client that ignores `_meta` can still show something.
+     * @param enrichTerminal Allow a SECOND update on an already-terminal
+     *   lifecycle that adds facts without re-reporting the outcome. Used by
+     *   `compact_boundary`, which arrives after the terminal `status` and is the
+     *   only frame carrying the token counts. The status field is omitted on that
+     *   update, so the client still sees exactly one terminal transition.
+     */
+    async finish(sessionId, fallbackId, status, metadata = {}, enrichTerminal = false) {
+        const rawOutput = Object.keys(metadata).length > 0 ? metadata : undefined;
+        if (!this.activeCompaction) {
+            this.activeCompaction = {
+                toolCallId: fallbackId,
+                heartbeatSent: false,
+                terminalStatus: status,
+            };
+            this.outputDelivered = true;
+            this.rememberDuplicateErrorOutput(status, metadata);
+            await this.sendUpdate({
+                sessionId,
+                update: {
+                    sessionUpdate: "tool_call",
+                    toolCallId: fallbackId,
+                    title: COMPACTION_TOOL_TITLE,
+                    kind: "think",
+                    status,
+                    ...compactionErrorFields(status, metadata),
+                    ...(rawOutput ? { rawOutput } : {}),
+                    _meta: compactionToolMeta(metadata),
+                },
+            });
+            return;
+        }
+        const state = this.activeCompaction;
+        // The duplicate guard: a terminal on an already-terminal lifecycle is the
+        // SDK repeating itself, and must change nothing the client can see.
+        if (state.terminalStatus && !enrichTerminal)
+            return;
+        const firstTerminal = state.terminalStatus === undefined;
+        if (firstTerminal)
+            state.terminalStatus = status;
+        this.rememberDuplicateErrorOutput(status, metadata);
+        await this.sendUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "tool_call_update",
+                toolCallId: state.toolCallId,
+                ...(firstTerminal ? { status } : {}),
+                ...compactionErrorFields(status, metadata),
+                ...(rawOutput ? { rawOutput } : {}),
+                _meta: compactionToolMeta(metadata),
+            },
+        });
+    }
+    /** Arm {@link consumeDuplicateErrorOutput} for the stdout copy Claude emits. */
+    rememberDuplicateErrorOutput(status, metadata) {
+        if (status === "failed" && metadata.error) {
+            this.duplicateErrorOutput = metadata.error;
+        }
+    }
+}
+/**
+ * Map the SDK's `compact_boundary` metadata onto the provider-neutral names of
+ * {@link ContextCompactionMetadata}. Fields an older CLI omits stay omitted
+ * rather than becoming `undefined` keys, so `rawOutput` and `_meta` never
+ * advertise a number nobody reported.
+ */
+export function contextCompactionMetadataFromBoundary(compactMetadata) {
+    return {
+        trigger: compactMetadata.trigger === "auto" ? "automatic" : "manual",
+        preTokens: compactMetadata.pre_tokens,
+        ...(compactMetadata.post_tokens !== undefined
+            ? { postTokens: compactMetadata.post_tokens }
+            : {}),
+        ...(compactMetadata.duration_ms !== undefined
+            ? { durationMs: compactMetadata.duration_ms }
+            : {}),
+    };
+}
+/** The title every compaction tool call carries; part of the R2.1 contract. */
+const COMPACTION_TOOL_TITLE = "Compact conversation";
+/**
+ * The `_meta` payload for a compaction tool update: the versioned extension
+ * plus the `claudeCode.toolName` every other tool call in this adapter carries,
+ * so a client keying off it treats the synthetic call like any real one.
+ *
+ * Returns a plain record rather than the adapter's `ToolUpdateMeta` to keep the
+ * module free of `acp-agent.ts` imports; the adapter widens `ToolUpdateMeta`
+ * with the matching optional field for its own call sites.
+ */
+function compactionToolMeta(metadata = {}) {
+    return {
+        ...createContextCompactionMeta(metadata),
+        claudeCode: { toolName: "compact" },
+    };
+}
+/**
+ * The failure reason as renderable tool content — `_meta` is optional for a
+ * client, the reason for a failure is not.
+ */
+function compactionErrorFields(status, metadata) {
+    if (status !== "failed" || !metadata.error)
+        return {};
+    return {
+        content: [
+            {
+                type: "content",
+                content: { type: "text", text: `Compaction failed: ${metadata.error}` },
+            },
+        ],
+    };
+}

package/dist/usage-markdown.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `/usage` rendered as Markdown, and the bounded wait that decides whether it
+ * renders at all (story 011, R2.3/R2.4, design D5).
+ *
+ * The command ALWAYS runs through Claude Code. What this module produces is a
+ * best-effort overlay on top of an answer the user already has, so every
+ * failure here costs the overlay and nothing else — the caller forwards Claude
+ * Code's own text byte-for-byte instead. Three ways out, all of them ending in
+ * `null` from {@link structuredUsageMarkdown}:
+ *
+ *   1. unavailable  — the control request rejects, or the method is gone
+ *   2. incompatible — the response does not match the shape the renderer reads
+ *   3. slow         — the response does not arrive inside the bound below
+ *
+ * THE BOUND IS LOAD-BEARING, NOT DEFENSIVE. Control requests on a fresh session
+ * are not serviced until the first turn runs (SDK issues #886/#880), and
+ * `/usage` is frequently that first turn — so an unbounded wait would withhold
+ * an answer the CLI had already printed, forever. That is why the race below
+ * has three legs and not one: the report, a timeout, and the turn's abort
+ * signal.
+ *
+ * ONE READER FOR THE REPORT'S NUMBERS. `account-usage.ts` already maps this same
+ * `SDKControlGetUsageResponse` onto the client's rate-limit `_meta`, and it owns
+ * the two scalar readings the report needs: `normalizeUtilization` (0..100 ->
+ * 0..1, clamped) and `toEpochSeconds` (ISO 8601 -> Unix seconds). Both are
+ * imported here rather than re-derived, so the bar this module draws and the bar
+ * the client's usage panel draws cannot disagree about what `utilization: 3`
+ * means. What is NOT shared is validation: `account-usage.ts` reads defensively
+ * and never rejects a report, because a missing field there costs one window,
+ * while here an unreadable report has to become a hard "no" so way out 2 can
+ * fire. Different questions, so different code — but the same answers to the
+ * two questions both of them ask.
+ *
+ * Kept self-contained — no import from `acp-agent.ts`, mirroring
+ * `thinking-option.ts` and `context-compaction.ts`. The reason is merge cost:
+ * `acp-agent.ts` is a ~9,700-line file that changes upstream almost daily, so
+ * every coupling to it is paid again at each sync. `acp-agent.ts` wires this in
+ * at the `/usage` turn: it decides which turn owns a structured render, and
+ * publishes the result at most once across the message shapes the SDK can
+ * deliver one local command through.
+ */
+import type { Query, SDKControlGetUsageResponse } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * How long the structured report may take before the original output wins.
+ *
+ * Not a guess at network latency: the request may never be serviced at all (see
+ * the header), so this is the ceiling on how long a user waits for a decoration
+ * on an answer that is already sitting in the buffer.
+ */
+export declare const STRUCTURED_USAGE_TIMEOUT_MS = 5000;
+/**
+ * Validate the experimental SDK response at the runtime boundary — way out 2.
+ * Null means "this is not a report this renderer can read", which the caller
+ * turns into Claude Code's original text.
+ */
+export declare function parseUsageResponse(value: unknown): SDKControlGetUsageResponse | null;
+/**
+ * Whether a prompt is exactly the local `/usage` command.
+ *
+ * Exact, not a prefix: `/usage now` is an argument form this renderer has no
+ * mapping for, and prose that merely mentions the word is a model turn.
+ */
+export declare function isUsageCommandText(text: string): boolean;
+/** Render the SDK's structured `/usage` response as Markdown (R2.3). */
+export declare function formatUsageResponse(usage: SDKControlGetUsageResponse): string;
+/**
+ * The one SDK surface this module needs.
+ *
+ * `Pick` on the literal method name is the compile-time tripwire the ToDo asks
+ * for: when the SDK stabilises this API and renames the method, the key stops
+ * being a `keyof Query` and the BUILD fails here. Without it, a rename would
+ * only ever surface as `/usage` degrading to way out 1 forever — a silent loss
+ * of the whole feature, indistinguishable from a session where the report is
+ * genuinely unavailable.
+ */
+export type UsageReportQuery = Pick<Query, "usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET">;
+/** The slice of the adapter's logger this module uses. */
+export type UsageMarkdownLogger = {
+    error: (message: string) => void;
+};
+/**
+ * The structured `/usage` render for one turn, or null when any of the three
+ * ways out fired (R2.4). Never throws and never resolves late: the caller is
+ * holding a completed local command's output while it awaits this.
+ *
+ * Raced against BOTH a timeout and the turn's abort signal. The timeout covers
+ * a request that is never serviced (see the header); the signal covers a turn
+ * that ended — cancelled, or settled — while the request was still in flight,
+ * so a dead turn's overlay is abandoned rather than merely ignored.
+ */
+export declare function structuredUsageMarkdown(query: UsageReportQuery, signal: AbortSignal, logger: UsageMarkdownLogger): Promise<string | null>;
+//# sourceMappingURL=usage-markdown.d.ts.map

package/dist/usage-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-markdown.d.ts","sourceRoot":"","sources":["../src/usage-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AAKxF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AA6DjD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,GAAG,IAAI,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AA0OD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAS7E;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,KAAK,EACL,2DAA2D,CAC5D,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG;IAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAQvE;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwDxB"}