@lucascouts/claude-agent-acp-plus 0.11.1 → 0.13.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/ultracode.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The "Ultracode" entry of the Effort picker.
+ *
+ * **Ultracode is not a sixth effort level, and reading it as one produces the
+ * wrong control.** Claude Code's VS Code extension models it as a boolean that
+ * turns on two things at once — `xhigh` effort *and* standing dynamic-workflow
+ * orchestration — and its own tooltip says so: `"Ultracode - xhigh +
+ * workflows"`. Its five real levels are `low` `medium` `high` `xhigh` `max`;
+ * Ultracode is drawn as one extra notch past the last of them, styled
+ * differently, and selecting any ordinary level clears it.
+ *
+ * ACP has no compound control to carry that, so the adapter projects it the way
+ * the extension's UI reads rather than the way its state is stored: one more
+ * entry in the `effort` select. The compound stays here, in one module, instead
+ * of being spread across the three places `acp-agent.ts` applies effort.
+ *
+ * The SDK carries both halves and names the channel: `Settings.ultracode` is
+ * *"xhigh effort plus standing dynamic-workflow orchestration. Session-scoped —
+ * typically provided via --settings or the apply_flag_settings control
+ * request"*. `apply_flag_settings` is already how the effort option is applied,
+ * so no new transport is involved.
+ *
+ * Kept self-contained — no import from `acp-agent.ts` — for the reason
+ * `thinking-option.ts` and `rewind-command.ts` state: that file is ~9,900 lines
+ * and moves upstream almost daily, so every coupling to it is paid again at
+ * each sync.
+ */
+import type { EffortLevel, Settings } from "@anthropic-ai/claude-agent-sdk";
+/** Value of the synthetic "Ultracode" entry in the effort picker. It is a
+ *  reserved sentinel: no `EffortLevel` is spelled this way, so it cannot
+ *  collide with a level the SDK reports in `supportedEffortLevels`. */
+export declare const ULTRACODE_OPTION_VALUE = "ultracode";
+/** Display name of that entry, matching the extension's own label. */
+export declare const ULTRACODE_OPTION_NAME = "Ultracode";
+/** The effort level Ultracode implies. Not configurable: the extension hardcodes
+ *  `xhigh` in `enableUltracode()`, and the SDK's own description of the setting
+ *  names the same level. A different level here would silently mean something
+ *  else than it does in the reference client. */
+export declare const ULTRACODE_EFFORT_LEVEL: EffortLevel;
+/** Display state for the Ultracode entry, resolved by the caller. Mirrors the
+ *  shape `FastModeOptionState` uses for the same job — availability and current
+ *  value are two different questions, and folding them into one boolean loses
+ *  the case where the entry should render but not be selected. */
+export interface UltracodeOptionState {
+    /** Whether the entry should appear at all. */
+    available: boolean;
+    /** Whether it is the currently selected effort. */
+    enabled: boolean;
+}
+/**
+ * Whether the Ultracode entry may be offered, under the same two conditions the
+ * extension checks in its own `ultracodeAvailable`:
+ *
+ * 1. workflows are not disabled — Ultracode *is* the workflow half, so offering
+ *    it where `disableWorkflows` is set would advertise something that cannot
+ *    happen;
+ * 2. the current model supports `xhigh` — Ultracode has no meaning on a model
+ *    that cannot reach the level it implies.
+ *
+ * Both are read rather than assumed: an unknown settings shape leaves
+ * `disableWorkflows` undefined, which is *not* `true`, so the gate opens — the
+ * same direction the extension's `=== !0` comparison takes.
+ */
+export declare function isUltracodeAvailable(supportedEffortLevels: readonly string[], settings: Pick<Settings, "disableWorkflows"> | undefined): boolean;
+/** Whether a picker value denotes Ultracode rather than a plain effort level. */
+export declare function isUltracodeValue(value: string | undefined): boolean;
+/**
+ * The `apply_flag_settings` payload for an effort selection, Ultracode included.
+ *
+ * **The `null` is the load-bearing part.** The SDK shallow-merges flag settings
+ * and only clears a key when an explicit `null` arrives — `undefined` is dropped
+ * by JSON transport and leaves the previous value standing. So every selection
+ * has to say something about `ultracode`, not just the one that turns it on:
+ * without the clear, picking `High` after Ultracode would lower the effort and
+ * leave workflow orchestration running, which is a state no picker entry names.
+ * The same reasoning applies to `effortLevel` — this function absorbed the older
+ * `toSdkEffortLevel` helper for exactly that reason: both keys are decided in
+ * one place, so neither can be forgotten on a path the other takes.
+ *
+ * @param value the picker value — `"default"`, an `EffortLevel`, or the
+ *   Ultracode sentinel. `undefined` means the option is absent for this model.
+ */
+export declare function ultracodeFlagSettings(value: string | undefined): {
+    effortLevel: EffortLevel | null;
+    ultracode: boolean | null;
+};
+/**
+ * The picker value to display, given the persisted effort level and whether the
+ * Ultracode flag is on.
+ *
+ * The flag wins over the level, and only when it is *available*: a session that
+ * carries `ultracode: true` from settings while the current model cannot reach
+ * `xhigh` must not show an entry the picker is not rendering. The extension
+ * reaches the same state through `adoptAppliedEffort`, which reads
+ * `applied.ultracode` first and falls back to inferring it from `xhigh`; we do
+ * not infer, because `xhigh` alone is a legitimate selection that is not
+ * Ultracode, and guessing would silently turn workflows on in the label.
+ */
+export declare function effortOptionValue(effortLevel: string | undefined, ultracode: UltracodeOptionState | undefined): string | undefined;
+//# sourceMappingURL=ultracode.d.ts.map