@lucascouts/claude-agent-acp-plus 0.1.0 → 0.2.0

package/dist/model-deprecation.d.ts

@@ -0,0 +1,30 @@
+import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * Heuristically decide whether a model row is deprecated.
+ *
+ * Matches {@link DEPRECATION_MARKER} (`/deprecated|legacy/i`) over `displayName`
+ * and `description` ONLY. The `value` (model id) is never inspected — an id that
+ * merely contains a "legacy"-like slug must NOT flag the row. A missing,
+ * `undefined`, or empty `displayName` or `description` is treated as an empty
+ * string, so this never throws.
+ *
+ * See the module doc for WHY this is a heuristic (SDK 0.3.204 `ModelInfo` has no
+ * deprecation field).
+ *
+ * @param info - A single SDK model row.
+ * @returns `true` when the display copy marks the model deprecated/legacy.
+ */
+export declare function isDeprecatedModel(info: ModelInfo): boolean;
+/**
+ * Return a NEW array with deprecated rows removed.
+ *
+ * Kept rows preserve their original order AND identity — the same object
+ * references are returned, not copies. Built on {@link isDeprecatedModel}, so it
+ * shares that function's heuristic and field scoping. An empty input yields an
+ * empty array.
+ *
+ * @param infos - The model catalog to filter.
+ * @returns A new array containing only the non-deprecated rows.
+ */
+export declare function filterDeprecatedModels(infos: ModelInfo[]): ModelInfo[];
+//# sourceMappingURL=model-deprecation.d.ts.map

package/dist/model-deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-deprecation.d.ts","sourceRoot":"","sources":["../src/model-deprecation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AA4BhE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAI1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAEtE"}

package/dist/model-deprecation.js

@@ -0,0 +1,58 @@
+/**
+ * Model deprecation heuristic.
+ *
+ * The Claude Agent SDK's `ModelInfo` (0.3.204) exposes NO deprecation flag —
+ * its only capability fields are `supportsEffort` / `supportedEffortLevels`,
+ * `supportsAdaptiveThinking`, `supportsFastMode`, and `supportsAutoMode`. There
+ * is therefore no authoritative, machine-readable signal telling a host that a
+ * model row has been retired.
+ *
+ * As a stand-in this module scans the human-facing copy — `displayName` and
+ * `description` — for the words "deprecated" or "legacy" (case-insensitive).
+ * This is deliberately a HEURISTIC: it can only catch models the SDK happens to
+ * label in prose, and it is intentionally scoped to those two fields. The
+ * opaque model id in `value` is NEVER inspected, because ids routinely embed
+ * version/family slugs (e.g. a "legacy"-like substring) that do not indicate an
+ * actually deprecated model and would produce false positives.
+ *
+ * When the SDK gains a real deprecation flag, replace this heuristic with a
+ * direct field read.
+ *
+ * @module model-deprecation
+ */
+/** Case-insensitive marker words the SDK uses in prose for retired models. */
+const DEPRECATION_MARKER = /deprecated|legacy/i;
+/**
+ * Heuristically decide whether a model row is deprecated.
+ *
+ * Matches {@link DEPRECATION_MARKER} (`/deprecated|legacy/i`) over `displayName`
+ * and `description` ONLY. The `value` (model id) is never inspected — an id that
+ * merely contains a "legacy"-like slug must NOT flag the row. A missing,
+ * `undefined`, or empty `displayName` or `description` is treated as an empty
+ * string, so this never throws.
+ *
+ * See the module doc for WHY this is a heuristic (SDK 0.3.204 `ModelInfo` has no
+ * deprecation field).
+ *
+ * @param info - A single SDK model row.
+ * @returns `true` when the display copy marks the model deprecated/legacy.
+ */
+export function isDeprecatedModel(info) {
+    const displayName = info.displayName ?? "";
+    const description = info.description ?? "";
+    return DEPRECATION_MARKER.test(`${displayName} ${description}`);
+}
+/**
+ * Return a NEW array with deprecated rows removed.
+ *
+ * Kept rows preserve their original order AND identity — the same object
+ * references are returned, not copies. Built on {@link isDeprecatedModel}, so it
+ * shares that function's heuristic and field scoping. An empty input yields an
+ * empty array.
+ *
+ * @param infos - The model catalog to filter.
+ * @returns A new array containing only the non-deprecated rows.
+ */
+export function filterDeprecatedModels(infos) {
+    return infos.filter((info) => !isDeprecatedModel(info));
+}

package/dist/rewind-command.d.ts

@@ -0,0 +1,140 @@
+/**
+ * All `/rewind` command logic, isolated from the ACP adapter so it can be unit
+ * tested without a live SDK session. The adapter (see acp-agent.ts) wires these
+ * helpers in by injecting the ACP client, the SDK `query` handle, and a
+ * `getSessionMessages` reader; this module never touches the transport itself.
+ *
+ * Responsibilities (story 006, R3.2–R3.6):
+ *   - parse a `/rewind` prompt into a list / restore / invalid intent
+ *     (`parseRewindInvocation`);
+ *   - derive the checkpoint list from the session transcript — real user
+ *     prompts only, most recent first, 1-based (`listCheckpoints`);
+ *   - format the user-facing strings (`formatCheckpointList`,
+ *     `formatRewindResult`, `formatRewindError`);
+ *   - orchestrate one command end to end, emitting every message through the
+ *     injected client before resolving (`handleRewindCommand`).
+ *
+ * `stripLocalCommandMetadata` is reused from acp-agent.ts (its single source of
+ * truth) rather than duplicated, so the definition of a "local-command marker
+ * row" stays in sync; the import is side-effect-free (acp-agent.ts runs nothing
+ * at module top level).
+ */
+import type { RewindFilesResult, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+/** A rewindable point in the session: a real user prompt tracked by its SDK uuid. */
+export type Checkpoint = {
+    index: number;
+    uuid: string;
+    excerpt: string;
+};
+/** Parsed intent of a `/rewind` prompt; the parser returns `null` for non-commands. */
+export type RewindInvocation = {
+    kind: "list";
+} | {
+    kind: "restore";
+    index: number;
+} | {
+    kind: "invalid";
+    raw: string;
+};
+/**
+ * Parse a raw prompt into a `/rewind` intent, or `null` when the prompt is not a
+ * `/rewind` command at all.
+ *
+ * The command token is matched exactly, so `"/rewindx"`, `"/compact"` and plain
+ * prose all return `null`. A bare `/rewind` (trailing whitespace allowed) is a
+ * `list` request; `/rewind <integer>` is a `restore` request; any other argument
+ * is `invalid`, carrying the trimmed raw argument text so the caller can echo it.
+ *
+ * The whole invocation must sit on a single line: any newline surviving the
+ * trim makes the prompt NOT a `/rewind` command (`null`). Without this,
+ * `\s+` between command and argument would accept a line break, and a pasted
+ * two-line snippet like `"/rewind\n2"` would silently restore files — a
+ * destructive surprise for what the user meant as plain text.
+ *
+ * @param promptText Raw prompt text as typed by the user.
+ */
+export declare function parseRewindInvocation(promptText: string): RewindInvocation | null;
+/**
+ * Build the rewind checkpoint list from a session transcript.
+ *
+ * Only REAL user prompts are checkpoints: rows carrying a `parent_tool_use_id`,
+ * tool_result rows, and local-command marker rows (`<command-name>…`, which
+ * `stripLocalCommandMetadata` reduces to null) are all skipped. The result is
+ * ordered most recent first with a 1-based `index` (most recent = 1); each
+ * `excerpt` is the first 60 code points of the prompt on a single line.
+ *
+ * @param messages Session transcript in chronological order (SDK messages).
+ */
+export declare function listCheckpoints(messages: SDKMessage[]): Checkpoint[];
+/**
+ * Render the checkpoint list as a numbered, user-facing message. An empty list
+ * yields a "nothing to rewind" notice instead (R3.6).
+ *
+ * @param cps Checkpoints, already ordered most recent first.
+ */
+export declare function formatCheckpointList(cps: Checkpoint[]): string;
+/**
+ * Confirm a completed rewind, naming the checkpoint that was restored by its
+ * index and excerpt (R3.4).
+ *
+ * @param cp The checkpoint whose files were restored.
+ */
+export declare function formatRewindResult(cp: Checkpoint): string;
+/**
+ * Build a `/rewind` usage/error message. Always names the `/rewind` command and,
+ * when at least one checkpoint exists, the valid index range (R3.5). An optional
+ * `detail` (e.g. the reason a restore failed) is shown ahead of the usage line —
+ * this is how the orchestrator surfaces a failure WITHOUT ever claiming success.
+ *
+ * @param checkpointCount Number of available checkpoints (0 when none/unknown).
+ * @param detail Optional human-readable explanation shown before the usage line.
+ */
+export declare function formatRewindError(checkpointCount: number, detail?: string): string;
+/** Injected collaborators for {@link handleRewindCommand}. */
+export interface RewindDeps {
+    /** ACP session the command was issued in. */
+    sessionId: string;
+    /** ACP client used to stream user-facing messages back to the editor. */
+    client: {
+        sessionUpdate(notification: {
+            sessionId: string;
+            update: {
+                sessionUpdate: "agent_message_chunk";
+                content: {
+                    type: "text";
+                    text: string;
+                };
+            };
+        }): Promise<void>;
+    };
+    /** SDK query handle exposing file checkpointing. */
+    query: {
+        rewindFiles(userMessageId: string): Promise<RewindFilesResult>;
+    };
+    /** Reader for the session transcript (chronological SDK messages). */
+    getSessionMessages(sessionId: string): Promise<SDKMessage[]>;
+}
+/**
+ * Drive a parsed `/rewind` invocation end to end, streaming every user-facing
+ * message through `deps.client` before the returned promise resolves.
+ *
+ * `list` fetches the transcript and emits the numbered checkpoint list (or the
+ * nothing-to-rewind notice). `restore` fetches + rebuilds the list, validates
+ * the requested index, and on a hit calls `query.rewindFiles` with the tracked
+ * uuid inside a try/catch — a rejection (or a `canRewind: false` result) is
+ * reported via {@link formatRewindError} and never claims success. An `invalid`
+ * invocation, an out-of-range index, or a failed transcript read each emit an
+ * error and leave files untouched (`rewindFiles` is never called); the
+ * `invalid` path still reads the transcript so its usage message can name the
+ * valid range (R3.5), degrading to the rangeless message if that read fails.
+ *
+ * Failure handling: `getSessionMessages` and `query.rewindFiles` rejections
+ * are caught and surfaced as user-facing messages. A rejection from
+ * `deps.client.sessionUpdate` itself (the channel those messages are emitted
+ * on) is NOT caught here — it propagates to the caller, which guards it.
+ *
+ * @param deps Injected client, query handle, transcript reader and session id.
+ * @param invocation Parsed `/rewind` intent from {@link parseRewindInvocation}.
+ */
+export declare function handleRewindCommand(deps: RewindDeps, invocation: RewindInvocation): Promise<void>;
+//# sourceMappingURL=rewind-command.d.ts.map

package/dist/rewind-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewind-command.d.ts","sourceRoot":"","sources":["../src/rewind-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAMpF,qFAAqF;AACrF,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAkBjF;AAkED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CA4BpE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,MAAM,CAY9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAIlF;AAED,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,MAAM,EAAE;QACN,aAAa,CAAC,YAAY,EAAE;YAC1B,SAAS,EAAE,MAAM,CAAC;YAClB,MAAM,EAAE;gBAAE,aAAa,EAAE,qBAAqB,CAAC;gBAAC,OAAO,EAAE;oBAAE,IAAI,EAAE,MAAM,CAAC;oBAAC,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAC;SAC3F,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnB,CAAC;IACF,oDAAoD;IACpD,KAAK,EAAE;QAAE,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;KAAE,CAAC;IAC1E,sEAAsE;IACtE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CAC9D;AAqBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Df"}

package/dist/rewind-command.js

@@ -0,0 +1,278 @@
+/**
+ * All `/rewind` command logic, isolated from the ACP adapter so it can be unit
+ * tested without a live SDK session. The adapter (see acp-agent.ts) wires these
+ * helpers in by injecting the ACP client, the SDK `query` handle, and a
+ * `getSessionMessages` reader; this module never touches the transport itself.
+ *
+ * Responsibilities (story 006, R3.2–R3.6):
+ *   - parse a `/rewind` prompt into a list / restore / invalid intent
+ *     (`parseRewindInvocation`);
+ *   - derive the checkpoint list from the session transcript — real user
+ *     prompts only, most recent first, 1-based (`listCheckpoints`);
+ *   - format the user-facing strings (`formatCheckpointList`,
+ *     `formatRewindResult`, `formatRewindError`);
+ *   - orchestrate one command end to end, emitting every message through the
+ *     injected client before resolving (`handleRewindCommand`).
+ *
+ * `stripLocalCommandMetadata` is reused from acp-agent.ts (its single source of
+ * truth) rather than duplicated, so the definition of a "local-command marker
+ * row" stays in sync; the import is side-effect-free (acp-agent.ts runs nothing
+ * at module top level).
+ */
+import { stripLocalCommandMetadata } from "./acp-agent.js";
+/** Maximum Unicode code points kept from a prompt when building its checkpoint excerpt. */
+const EXCERPT_MAX = 60;
+/**
+ * Parse a raw prompt into a `/rewind` intent, or `null` when the prompt is not a
+ * `/rewind` command at all.
+ *
+ * The command token is matched exactly, so `"/rewindx"`, `"/compact"` and plain
+ * prose all return `null`. A bare `/rewind` (trailing whitespace allowed) is a
+ * `list` request; `/rewind <integer>` is a `restore` request; any other argument
+ * is `invalid`, carrying the trimmed raw argument text so the caller can echo it.
+ *
+ * The whole invocation must sit on a single line: any newline surviving the
+ * trim makes the prompt NOT a `/rewind` command (`null`). Without this,
+ * `\s+` between command and argument would accept a line break, and a pasted
+ * two-line snippet like `"/rewind\n2"` would silently restore files — a
+ * destructive surprise for what the user meant as plain text.
+ *
+ * @param promptText Raw prompt text as typed by the user.
+ */
+export function parseRewindInvocation(promptText) {
+    // Single-line anchor (see doc above): `\r` is included so a CR-separated
+    // paste cannot slip past the check either.
+    if (/[\r\n]/.test(promptText.trim())) {
+        return null;
+    }
+    const match = /^\/rewind(?:\s+(.*))?$/.exec(promptText.trim());
+    if (!match) {
+        return null;
+    }
+    const arg = match[1]?.trim() ?? "";
+    if (arg === "") {
+        return { kind: "list" };
+    }
+    if (/^-?\d+$/.test(arg)) {
+        return { kind: "restore", index: Number.parseInt(arg, 10) };
+    }
+    return { kind: "invalid", raw: arg };
+}
+/** Narrow an unknown value to a plain object we can read string-keyed fields off. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Read the fields we care about from a transcript row, or `null` if not a user row. */
+function asUserRow(message) {
+    const row = message;
+    if (row.type !== "user") {
+        return null;
+    }
+    if (typeof row.uuid !== "string" || row.uuid === "") {
+        return null;
+    }
+    const parentToolUseId = typeof row.parent_tool_use_id === "string" ? row.parent_tool_use_id : null;
+    return { uuid: row.uuid, content: row.message?.content, parentToolUseId };
+}
+/** Whether `content` carries a tool_result block (a synthetic tool-output row). */
+function hasToolResultBlock(content) {
+    if (!Array.isArray(content)) {
+        return false;
+    }
+    return content.some((block) => isRecord(block) && block.type === "tool_result");
+}
+/** Flatten user-message content (a string or a block array) to its plain text. */
+function extractText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    const parts = [];
+    for (const block of content) {
+        if (isRecord(block) && block.type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+    }
+    return parts.join(" ");
+}
+/** Collapse whitespace/newlines to single spaces and clip to the excerpt length.
+ *  The clip counts Unicode code points, not UTF-16 code units: `String.slice`
+ *  at a fixed offset can split a surrogate pair (e.g. an emoji sitting on the
+ *  boundary) and emit a lone surrogate — invalid Unicode that Zed's serde_json
+ *  rejects, dropping the whole session/update notification carrying the
+ *  excerpt. `toWellFormed()` additionally scrubs any lone surrogate already
+ *  present in the transcript text (JSON.parse admits them via `\uD800`-style
+ *  escapes) for the same reason. */
+function toExcerpt(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return Array.from(collapsed).slice(0, EXCERPT_MAX).join("").toWellFormed();
+}
+/**
+ * Build the rewind checkpoint list from a session transcript.
+ *
+ * Only REAL user prompts are checkpoints: rows carrying a `parent_tool_use_id`,
+ * tool_result rows, and local-command marker rows (`<command-name>…`, which
+ * `stripLocalCommandMetadata` reduces to null) are all skipped. The result is
+ * ordered most recent first with a 1-based `index` (most recent = 1); each
+ * `excerpt` is the first 60 code points of the prompt on a single line.
+ *
+ * @param messages Session transcript in chronological order (SDK messages).
+ */
+export function listCheckpoints(messages) {
+    const prompts = [];
+    for (const message of messages) {
+        const row = asUserRow(message);
+        if (!row) {
+            continue;
+        }
+        if (row.parentToolUseId !== null) {
+            continue;
+        }
+        if (hasToolResultBlock(row.content)) {
+            continue;
+        }
+        const stripped = stripLocalCommandMetadata(row.content);
+        if (stripped === null) {
+            continue;
+        }
+        const excerpt = toExcerpt(extractText(stripped));
+        if (excerpt === "") {
+            continue;
+        }
+        prompts.push({ uuid: row.uuid, excerpt });
+    }
+    return prompts.reverse().map((prompt, position) => ({
+        index: position + 1,
+        uuid: prompt.uuid,
+        excerpt: prompt.excerpt,
+    }));
+}
+/**
+ * Render the checkpoint list as a numbered, user-facing message. An empty list
+ * yields a "nothing to rewind" notice instead (R3.6).
+ *
+ * @param cps Checkpoints, already ordered most recent first.
+ */
+export function formatCheckpointList(cps) {
+    if (cps.length === 0) {
+        return "There is nothing to rewind — this session has no earlier prompts yet.";
+    }
+    const lines = cps.map((cp) => `${cp.index}. ${cp.excerpt}`);
+    return [
+        "Rewind checkpoints (most recent first):",
+        "",
+        ...lines,
+        "",
+        "Restore files to one with `/rewind <n>`.",
+    ].join("\n");
+}
+/**
+ * Confirm a completed rewind, naming the checkpoint that was restored by its
+ * index and excerpt (R3.4).
+ *
+ * @param cp The checkpoint whose files were restored.
+ */
+export function formatRewindResult(cp) {
+    return `Rewound files to checkpoint ${cp.index}: "${cp.excerpt}".`;
+}
+/**
+ * Build a `/rewind` usage/error message. Always names the `/rewind` command and,
+ * when at least one checkpoint exists, the valid index range (R3.5). An optional
+ * `detail` (e.g. the reason a restore failed) is shown ahead of the usage line —
+ * this is how the orchestrator surfaces a failure WITHOUT ever claiming success.
+ *
+ * @param checkpointCount Number of available checkpoints (0 when none/unknown).
+ * @param detail Optional human-readable explanation shown before the usage line.
+ */
+export function formatRewindError(checkpointCount, detail) {
+    const range = checkpointCount > 0 ? ` (valid indices 1–${checkpointCount})` : "";
+    const usage = `Usage: \`/rewind\` to list checkpoints, or \`/rewind <n>\`${range} to restore.`;
+    return detail ? `${detail}\n\n${usage}` : usage;
+}
+/** Coerce an unknown thrown value into a short, human-readable reason. */
+function reasonText(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    return "unknown error";
+}
+/** Emit one user-facing text chunk through the injected ACP client. */
+async function emit(deps, text) {
+    await deps.client.sessionUpdate({
+        sessionId: deps.sessionId,
+        update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text } },
+    });
+}
+/**
+ * Drive a parsed `/rewind` invocation end to end, streaming every user-facing
+ * message through `deps.client` before the returned promise resolves.
+ *
+ * `list` fetches the transcript and emits the numbered checkpoint list (or the
+ * nothing-to-rewind notice). `restore` fetches + rebuilds the list, validates
+ * the requested index, and on a hit calls `query.rewindFiles` with the tracked
+ * uuid inside a try/catch — a rejection (or a `canRewind: false` result) is
+ * reported via {@link formatRewindError} and never claims success. An `invalid`
+ * invocation, an out-of-range index, or a failed transcript read each emit an
+ * error and leave files untouched (`rewindFiles` is never called); the
+ * `invalid` path still reads the transcript so its usage message can name the
+ * valid range (R3.5), degrading to the rangeless message if that read fails.
+ *
+ * Failure handling: `getSessionMessages` and `query.rewindFiles` rejections
+ * are caught and surfaced as user-facing messages. A rejection from
+ * `deps.client.sessionUpdate` itself (the channel those messages are emitted
+ * on) is NOT caught here — it propagates to the caller, which guards it.
+ *
+ * @param deps Injected client, query handle, transcript reader and session id.
+ * @param invocation Parsed `/rewind` intent from {@link parseRewindInvocation}.
+ */
+export async function handleRewindCommand(deps, invocation) {
+    if (invocation.kind === "invalid") {
+        // R3.5 wants errors to carry usage + the valid range; the range needs the
+        // checkpoint count, so read the transcript here too. The invalid argument
+        // is the error being reported, though, so a failed read degrades to the
+        // rangeless usage message instead of masking it with a transcript error.
+        let checkpointCount = 0;
+        try {
+            checkpointCount = listCheckpoints(await deps.getSessionMessages(deps.sessionId)).length;
+        }
+        catch {
+            // Rangeless fallback: checkpointCount stays 0.
+        }
+        await emit(deps, formatRewindError(checkpointCount, `"${invocation.raw}" is not a valid checkpoint number.`));
+        return;
+    }
+    let checkpoints;
+    try {
+        checkpoints = listCheckpoints(await deps.getSessionMessages(deps.sessionId));
+    }
+    catch (error) {
+        await emit(deps, formatRewindError(0, `Could not read the session history: ${reasonText(error)}.`));
+        return;
+    }
+    if (invocation.kind === "list") {
+        await emit(deps, formatCheckpointList(checkpoints));
+        return;
+    }
+    const checkpoint = checkpoints.find((cp) => cp.index === invocation.index);
+    if (!checkpoint) {
+        await emit(deps, formatRewindError(checkpoints.length, `There is no checkpoint ${invocation.index}.`));
+        return;
+    }
+    try {
+        const result = await deps.query.rewindFiles(checkpoint.uuid);
+        if (result.canRewind === false) {
+            await emit(deps, formatRewindError(checkpoints.length, `Rewind failed: ${result.error ?? "the SDK could not rewind these files"}.`));
+            return;
+        }
+    }
+    catch (error) {
+        await emit(deps, formatRewindError(checkpoints.length, `Rewind failed: ${reasonText(error)}.`));
+        return;
+    }
+    await emit(deps, formatRewindResult(checkpoint));
+}

package/dist/thinking-option.d.ts

@@ -0,0 +1,85 @@
+/**
+ * "Thinking" session config option (story 006, R1.1/R1.4/R1.5/R1.6): the
+ * select-option factory surfaced via `configOptions`, the value resolver for
+ * `session/set_config_option`, and the ONE precedence point that combines the
+ * session's thinking intent with the legacy `MAX_THINKING_TOKENS` env
+ * resolution into the SDK's `thinking` option.
+ *
+ * Kept self-contained (no import from the daily-churning `acp-agent.ts`,
+ * mirroring the `ask-user-question-fallback.ts` precedent) so the logic is
+ * unit-testable in isolation; `acp-agent.ts` wires it into
+ * `buildConfigOptions`/`setSessionConfigOption`/query creation in sub-tasks
+ * 1.2/1.3.
+ */
+import type { SessionConfigOption } from "@agentclientprotocol/sdk";
+import type { ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
+/** Stable id for the Thinking session config option. */
+export declare const THINKING_CONFIG_ID = "thinking";
+/** Select value that turns extended thinking on. */
+export declare const THINKING_ON = "on";
+/** Select value that turns extended thinking off. */
+export declare const THINKING_OFF = "off";
+/**
+ * Minimal logging surface this module needs — structurally compatible with
+ * acp-agent's `Logger` (`{ log, error }`), declared locally so the module
+ * stays free of `acp-agent.ts` imports.
+ */
+export interface ThinkingLogger {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Build the Thinking config option: a two-value "on"/"off" `select` in the
+ * exact shape of the Fast mode select fallback (R1.1). Unlike Fast mode there
+ * is no boolean variant — the option is select-only from day one.
+ *
+ * @param enabled Whether extended thinking is currently on for the session;
+ *   reflected in `currentValue`.
+ */
+export declare function createThinkingConfigOption(enabled: boolean): SessionConfigOption;
+/**
+ * Resolve a `session/set_config_option` value for the Thinking option into the
+ * session's thinking intent. Only the select values are meaningful: `"on"` →
+ * `true`, `"off"` → `false`. Anything else — booleans included, since the
+ * option never had a legacy boolean shape (unlike Fast mode) — resolves to
+ * `null` (unrecognized).
+ *
+ * @param value Raw value from the request (untrusted; narrowed here).
+ */
+export declare function resolveThinkingSelection(value: unknown): boolean | null;
+/**
+ * Translate the legacy `MAX_THINKING_TOKENS` env var into the SDK's `thinking`
+ * option: unset → `undefined` (SDK default, adaptive on models that support
+ * it); `0` → disabled; a positive integer → a fixed token budget. Anything
+ * else is ignored with a logged error, i.e. treated as unset.
+ *
+ * NOTE: duplicated from the unexported `resolveThinkingConfig` in
+ * `acp-agent.ts` (behavior and log message identical); sub-task 1.3 makes
+ * `acp-agent.ts` consume this export and removes the duplication.
+ *
+ * @param raw The raw `MAX_THINKING_TOKENS` value (pass
+ *   `process.env.MAX_THINKING_TOKENS`).
+ * @param logger Sink for the invalid-value error.
+ */
+export declare function resolveThinkingConfig(raw: string | undefined, logger: ThinkingLogger): ThinkingConfig | undefined;
+/**
+ * The ONE precedence point combining the session's Thinking intent with the
+ * legacy `MAX_THINKING_TOKENS` env resolution:
+ *
+ * - `intent === false` → `{ type: "disabled" }`, the SDK's documented
+ *   no-extended-thinking value — the option beats the env var (R1.5).
+ * - `intent === true` → the env resolution when the env var is set (R1.4);
+ *   with the env var unset — or invalid, which is logged and treated as unset
+ *   — the SDK's documented enabled default `{ type: "adaptive" }` ("Claude
+ *   decides when and how much to think").
+ * - `intent === undefined` → exactly today's env-driven behavior, including
+ *   `undefined` (SDK default) when the env var is unset (R1.6).
+ *
+ * @param intent The session's Thinking selection: `true`/`false` once the
+ *   client has set the option, `undefined` while untouched.
+ * @param env The raw `MAX_THINKING_TOKENS` value (pass
+ *   `process.env.MAX_THINKING_TOKENS`).
+ * @param logger Sink for the invalid-env error.
+ */
+export declare function effectiveThinkingConfig(intent: boolean | undefined, env: string | undefined, logger: ThinkingLogger): ThinkingConfig | undefined;
+//# sourceMappingURL=thinking-option.d.ts.map

package/dist/thinking-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinking-option.d.ts","sourceRoot":"","sources":["../src/thinking-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,aAAa,CAAC;AAC7C,oDAAoD;AACpD,eAAO,MAAM,WAAW,OAAO,CAAC;AAChC,qDAAqD;AACrD,eAAO,MAAM,YAAY,QAAQ,CAAC;AAGlC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAahF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAIvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,EAAE,cAAc,GACrB,cAAc,GAAG,SAAS,CAQ5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,EAAE,cAAc,GACrB,cAAc,GAAG,SAAS,CAI5B"}