@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.0

package/lib/types/backends/claude/prefs.d.ts

@@ -0,0 +1,55 @@
+/** The permission modes the persisted choice may hold (the SDK's whole
+ *  vocabulary). A stored `bypassPermissions` is never started in; the next
+ *  start says so and clears it (options.ts, backend.ts). Anything else
+ *  reads as no choice. */
+export declare const CLAUDE_PERMISSION_MODES: readonly string[];
+/** What persists. */
+export interface ClaudePrefsData {
+    readonly model?: string;
+    readonly effort?: string;
+    /** The remembered `/permission` pick a later session starts in. */
+    readonly permissionMode?: string;
+    /** The session a bare `dsh-tui --backend claude --resume` opens (the
+     *  launcher reads this field directly; DSH's `resume.txt` never holds a
+     *  Claude id). */
+    readonly lastSession?: string;
+    /** This install's last use of each session (epoch ms): the session
+     *  browser's MRU note, like DSH's `last-used.json`. */
+    readonly lastUsed?: Readonly<Record<string, number>>;
+    /** The `/color` accent of each session (TUI-side: the CLI keeps none),
+     *  with when it was set — the newest {@link COLOR_LIMIT} are kept. */
+    readonly colors?: Readonly<Record<string, {
+        readonly color: string;
+        readonly at: number;
+    }>>;
+}
+/** A patch: a value sets the field, `null` clears it. */
+export interface ClaudePrefsPatch {
+    readonly model?: string | null;
+    readonly effort?: string | null;
+    readonly permissionMode?: string | null;
+    readonly lastSession?: string | null;
+}
+/** Read / patch access (injectable: tests use an in-memory store). */
+export interface ClaudePrefs {
+    read(): ClaudePrefsData;
+    /** Patch fields; `null` clears one. */
+    write(patch: ClaudePrefsPatch): void;
+    /** Note that a session was just used (MRU). */
+    touch(sessionId: string): void;
+    /** Forget a deleted session (its MRU note and the launcher marker). */
+    forget(sessionId: string): void;
+    /** A session's accent ('' = none). */
+    color(sessionId: string): string;
+    /** Set (or with '' clear) a session's accent. */
+    setColor(sessionId: string, color: string): void;
+}
+/** Session colours kept (the oldest set first is dropped). */
+export declare const COLOR_LIMIT = 200;
+/** The file-backed prefs under `<dir>` (default `~/.dsh-tui/backends/claude`). */
+export declare function fileClaudePrefs(dir?: string, debug?: (message: string) => void): ClaudePrefs;
+/** An in-memory store (tests, embedders without a home directory). */
+export declare function memoryClaudePrefs(initial?: ClaudePrefsData): ClaudePrefs & {
+    readonly data: ClaudePrefsData;
+};
+//# sourceMappingURL=prefs.d.ts.map

package/lib/types/backends/claude/prefs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefs.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/prefs.ts"],"names":[],"mappings":"AAkBA;;;0BAG0B;AAC1B,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAA+E,CAAA;AAEpI,qBAAqB;AACrB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;sBAEkB;IAClB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;2DACuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACpD;0EACsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;CAC5F;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrC;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,IAAI,IAAI,eAAe,CAAA;IACvB,uCAAuC;IACvC,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACpC,+CAA+C;IAC/C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,uEAAuE;IACvE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,sCAAsC;IACtC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACjD;AAKD,8DAA8D;AAC9D,eAAO,MAAM,WAAW,MAAM,CAAA;AA2E9B,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAA6C,EAAE,KAAK,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAsB,GAAG,WAAW,CA2BnJ;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,eAAoB,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAWjH"}

package/lib/types/backends/claude/prefs.js

@@ -0,0 +1,150 @@
+/**
+ * The Claude backend's persisted user choices
+ * (`~/.dsh-tui/backends/claude/prefs.json`): the `/model`,
+ * `/effort` and `/permission` picks a later session starts with. Backend-
+ * scoped on purpose —
+ * a Claude model id means nothing to the DSH `/model` preference, and the
+ * CLI's own settings files are never written (the user's interactive
+ * `claude` keeps its own choices).
+ *
+ * Best-effort like every `~/.dsh-tui` preference: a missing or corrupt file
+ * reads as "no choice", a failed write is reported to the caller's debug
+ * log and the session carries on.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from '../../utils/paths.js';
+import { writeFileAtomic } from '../shared/atomic-file.js';
+/** The permission modes the persisted choice may hold (the SDK's whole
+ *  vocabulary). A stored `bypassPermissions` is never started in; the next
+ *  start says so and clears it (options.ts, backend.ts). Anything else
+ *  reads as no choice. */
+export const CLAUDE_PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'auto', 'bypassPermissions'];
+const FILE = 'prefs.json';
+/** MRU notes kept (oldest dropped first): the file stays small. */
+const LAST_USED_LIMIT = 200;
+/** Session colours kept (the oldest set first is dropped). */
+export const COLOR_LIMIT = 200;
+/** Narrow a parsed document to what persists. */
+function parsePrefs(parsed) {
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return {};
+    const record = parsed;
+    const lastUsed = {};
+    const rawUsed = record.lastUsed;
+    if (rawUsed !== null && typeof rawUsed === 'object' && !Array.isArray(rawUsed)) {
+        for (const [id, value] of Object.entries(rawUsed)) {
+            if (typeof value === 'number' && Number.isFinite(value))
+                lastUsed[id] = value;
+        }
+    }
+    const colors = {};
+    const rawColors = record.colors;
+    if (rawColors !== null && typeof rawColors === 'object' && !Array.isArray(rawColors)) {
+        for (const [id, value] of Object.entries(rawColors)) {
+            const entry = value !== null && typeof value === 'object' ? value : undefined;
+            if (typeof entry?.color === 'string' && entry.color !== '' && typeof entry.at === 'number' && Number.isFinite(entry.at))
+                colors[id] = { color: entry.color, at: entry.at };
+        }
+    }
+    return {
+        ...(Object.keys(colors).length === 0 ? {} : { colors }),
+        ...(typeof record.model === 'string' && record.model !== '' ? { model: record.model } : {}),
+        ...(typeof record.effort === 'string' && record.effort !== '' ? { effort: record.effort } : {}),
+        ...(typeof record.permissionMode === 'string' && CLAUDE_PERMISSION_MODES.includes(record.permissionMode) ? { permissionMode: record.permissionMode } : {}),
+        ...(typeof record.lastSession === 'string' && record.lastSession !== '' ? { lastSession: record.lastSession } : {}),
+        ...(Object.keys(lastUsed).length === 0 ? {} : { lastUsed }),
+    };
+}
+/** Apply a patch (pure). */
+function patched(current, patch) {
+    const next = { ...current };
+    for (const key of ['model', 'effort', 'permissionMode', 'lastSession']) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        if (value === null)
+            delete next[key];
+        else
+            next[key] = value;
+    }
+    return next;
+}
+/** Record one use (pure), keeping the newest {@link LAST_USED_LIMIT}. */
+function touched(current, sessionId, now) {
+    const entries = Object.entries({ ...current.lastUsed, [sessionId]: now })
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, LAST_USED_LIMIT);
+    return { ...current, lastUsed: Object.fromEntries(entries) };
+}
+/** Set or clear one session's colour (pure), keeping the newest {@link COLOR_LIMIT}. */
+function coloured(current, sessionId, color, now) {
+    const colors = { ...current.colors };
+    delete colors[sessionId];
+    if (color !== '')
+        colors[sessionId] = { color, at: now };
+    const kept = Object.entries(colors).sort((a, b) => b[1].at - a[1].at).slice(0, COLOR_LIMIT);
+    const next = { ...current, colors: Object.fromEntries(kept) };
+    if (kept.length === 0)
+        delete next.colors;
+    return next;
+}
+/** Drop one session (pure). */
+function forgotten(current, sessionId) {
+    const lastUsed = { ...current.lastUsed };
+    delete lastUsed[sessionId];
+    const colors = { ...current.colors };
+    delete colors[sessionId];
+    const next = { ...current, lastUsed, colors };
+    if (Object.keys(lastUsed).length === 0)
+        delete next.lastUsed;
+    if (Object.keys(colors).length === 0)
+        delete next.colors;
+    if (current.lastSession === sessionId)
+        delete next.lastSession;
+    return next;
+}
+/** The file-backed prefs under `<dir>` (default `~/.dsh-tui/backends/claude`). */
+export function fileClaudePrefs(dir = join(DATA_DIR, 'backends', 'claude'), debug = () => undefined) {
+    const path = join(dir, FILE);
+    const read = () => {
+        try {
+            return parsePrefs(JSON.parse(readFileSync(path, 'utf8')));
+        }
+        catch {
+            return {};
+        }
+    };
+    const save = (next) => {
+        // Atomic: a plain `writeFileSync` truncates the target first, and
+        // another terminal's read-modify-write in that window would start from
+        // `{}` and wipe every field it does not know.
+        try {
+            writeFileAtomic(dir, FILE, `${JSON.stringify(next, null, 2)}\n`);
+        }
+        catch (error) {
+            debug(`claude: prefs write failed (${error instanceof Error ? error.message : String(error)})`);
+        }
+    };
+    return {
+        read,
+        write: patch => { save(patched(read(), patch)); },
+        touch: sessionId => { save(touched(read(), sessionId, Date.now())); },
+        forget: sessionId => { save(forgotten(read(), sessionId)); },
+        color: sessionId => read().colors?.[sessionId]?.color ?? '',
+        setColor: (sessionId, color) => { save(coloured(read(), sessionId, color, Date.now())); },
+    };
+}
+/** An in-memory store (tests, embedders without a home directory). */
+export function memoryClaudePrefs(initial = {}) {
+    let data = { ...initial };
+    return {
+        get data() { return data; },
+        read: () => data,
+        write(patch) { data = patched(data, patch); },
+        touch(sessionId) { data = touched(data, sessionId, Date.now()); },
+        forget(sessionId) { data = forgotten(data, sessionId); },
+        color: sessionId => data.colors?.[sessionId]?.color ?? '',
+        setColor(sessionId, color) { data = coloured(data, sessionId, color, Date.now()); },
+    };
+}

package/lib/types/backends/claude/process.d.ts

@@ -0,0 +1,19 @@
+/** Where the executable came from (`/doctor`). */
+export type ClaudeExecutableSource = 'env' | 'path' | 'bundled';
+export interface ClaudeExecutable {
+    /** Absolute path, or undefined to let the SDK use its bundled binary. */
+    readonly path: string | undefined;
+    readonly source: ClaudeExecutableSource;
+}
+/** Resolve the executable (never throws; the SDK binary is the fallback). */
+export declare function resolveClaudeExecutable(env?: NodeJS.ProcessEnv): Promise<ClaudeExecutable>;
+/** The child environment. */
+export declare function buildClaudeEnv(base?: NodeJS.ProcessEnv): Record<string, string>;
+/** Run `<executable> --version` and pull out the version (best-effort). */
+export declare function readClaudeVersion(executable: string): Promise<string | undefined>;
+/**
+ * The SDK `stderr` callback: chunks are split into lines; each non-empty line
+ * goes to `line` (the host's debug log + deduplicating notice reporter).
+ */
+export declare function createStderrSink(line: (text: string) => void): (data: string) => void;
+//# sourceMappingURL=process.d.ts.map

package/lib/types/backends/claude/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/process.ts"],"names":[],"mappings":"AA0BA,kDAAkD;AAClD,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;CACxC;AAgED,6EAA6E;AAC7E,wBAAsB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc7G;AAED,6BAA6B;AAC7B,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAY5F;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAWjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAOrF"}

package/lib/types/backends/claude/process.js

@@ -0,0 +1,156 @@
+/**
+ * The `claude` child process as this backend starts it:
+ * which executable, with which environment, and where its stderr goes.
+ *
+ * - Executable: `CLAUDE_CODE_EXECUTABLE` → the first `claude` on PATH that
+ *   actually launches → the SDK's own bundled binary (left to the SDK by
+ *   passing no path). A PATH binary wins over the bundled one so the session
+ *   shares the user's interactive CLI version and session store, but merely
+ *   existing is not enough to win: an npm install also ships shims this
+ *   process cannot spawn (on Windows the extensionless POSIX `sh` script
+ *   `where` reports first, and a `.cmd` Node refuses to run without a
+ *   shell), and handing one to the SDK fails the whole start with its own
+ *   misleading "native binary … failed to launch" error.
+ * - Environment: the SDK's `env` option replaces the child environment, so it
+ *   is built from `process.env`, tagged with the client app and the session
+ *   state events this backend reads, and scrubbed of the variables a parent
+ *   Claude Code terminal exports (dsh-tui may itself run inside one; the
+ *   child must not believe it is a nested entrypoint or join that session).
+ * - stderr: never inherited (it would tear the alternate screen); every line
+ *   goes to the debug log and to the host's deduplicated notice reporter.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, normalize, sep } from 'node:path';
+import { installedTuiVersion } from '../../update.js';
+/**
+ * Variables a parent Claude Code session exports that must not leak. The CLI
+ * reads several of them at start: `CLAUDE_CODE_CHILD_SESSION` and
+ * `CLAUDE_CODE_SESSION_ATTENDED` would make our child run as the parent's
+ * child session; the pid, exec path, effort, invoked skills, agent marker
+ * and trace parent would attribute it to the parent's process and trace.
+ */
+const SCRUBBED_EXACT = [
+    'CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_CHILD_SESSION', 'CLAUDE_CODE_SESSION_ATTENDED', 'CLAUDE_PID', 'AI_AGENT',
+    'TRACEPARENT', 'CLAUDE_CODE_EXECPATH', 'CLAUDE_EFFORT', 'CLAUDE_CODE_INVOKED_SKILLS',
+];
+const SCRUBBED_PREFIX = 'CLAUDE_CODE_MESSAGING_';
+/** Every existing `name` on PATH, in the platform tool's own order. */
+function whichAll(name) {
+    const win = process.platform === 'win32';
+    const tool = win ? 'where' : 'which';
+    const args = win ? [name] : ['-a', name];
+    return new Promise(resolve => {
+        try {
+            execFile(tool, args, { timeout: 5000, windowsHide: true }, (error, stdout) => {
+                // `where` exits non-zero when nothing matches; `which -a` may too.
+                if (error !== null && String(stdout).trim() === '') {
+                    resolve([]);
+                    return;
+                }
+                resolve(String(stdout).split(/\r?\n/u).map(line => line.trim()).filter(line => line !== '' && existsSync(line)));
+            });
+        }
+        catch {
+            resolve([]);
+        }
+    });
+}
+/**
+ * The real binary an unspawnable PATH shim forwards to, if it names one.
+ *
+ * npm publishes a package's bin as wrappers around the truth: an
+ * extensionless POSIX `sh` script, a `.cmd` and a `.ps1`. On Windows the
+ * first two are what `where` reports and neither can be handed to
+ * CreateProcess — but each ends in the absolute path of the real
+ * executable, which is exactly what an interactive `claude` runs, so
+ * following it keeps the user's own CLI instead of silently switching to
+ * the SDK's bundled copy. The shim is read bounded, `%~dp0` and
+ * `$basedir` are expanded, and every candidate still has to launch to win.
+ */
+function shimTarget(shim) {
+    let text;
+    try {
+        text = readFileSync(shim, 'latin1').slice(0, 64 * 1024);
+    }
+    catch {
+        return undefined;
+    }
+    const dir = dirname(shim);
+    const expanded = text
+        .replace(/%~dp0%?/giu, dir + sep)
+        .replace(/\$\{?basedir\}?/gu, dir);
+    for (const match of expanded.match(/"[^"\r\n]*?\.exe"|'[^'\r\n]*?\.exe'|[^\s"']*?\.exe/giu) ?? []) {
+        const candidate = match.replace(/^["']|["']$/gu, '').trim();
+        if (isAbsolute(candidate) && existsSync(candidate))
+            return normalize(candidate);
+    }
+    return undefined;
+}
+/** Resolve the executable (never throws; the SDK binary is the fallback). */
+export async function resolveClaudeExecutable(env = process.env) {
+    const configured = env.CLAUDE_CODE_EXECUTABLE;
+    if (configured !== undefined && configured !== '' && existsSync(configured))
+        return { path: configured, source: 'env' };
+    // A candidate that cannot report its version cannot be spawned either (a
+    // hung one is cut off by the probe's timeout), so a dead shim never
+    // shadows a working copy further down PATH — or the bundled binary. An
+    // explicit `CLAUDE_CODE_EXECUTABLE` above stays unvalidated on purpose:
+    // a typo the user made should fail loudly, not silently.
+    for (const candidate of await whichAll('claude')) {
+        if (await readClaudeVersion(candidate) !== undefined)
+            return { path: candidate, source: 'path' };
+        const target = shimTarget(candidate);
+        if (target !== undefined && await readClaudeVersion(target) !== undefined)
+            return { path: target, source: 'path' };
+    }
+    return { path: undefined, source: 'bundled' };
+}
+/** The child environment. */
+export function buildClaudeEnv(base = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined)
+            continue;
+        if (SCRUBBED_EXACT.includes(key) || key.startsWith(SCRUBBED_PREFIX))
+            continue;
+        env[key] = value;
+    }
+    env.CLAUDE_AGENT_SDK_CLIENT_APP = `dsh-tui/${installedTuiVersion() ?? 'dev'}`;
+    // `system/session_state_changed` is the authoritative idle signal; the CLI
+    // only emits it when asked.
+    env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS = '1';
+    return env;
+}
+/** Run `<executable> --version` and pull out the version (best-effort). */
+export function readClaudeVersion(executable) {
+    return new Promise(resolve => {
+        try {
+            execFile(executable, ['--version'], { timeout: 10000, windowsHide: true, env: buildClaudeEnv() }, (error, stdout) => {
+                if (error !== null) {
+                    resolve(undefined);
+                    return;
+                }
+                resolve(/\d+\.\d+\.\d+(?:[-+][\w.]+)?/u.exec(String(stdout))?.[0]);
+            });
+        }
+        catch {
+            resolve(undefined);
+        }
+    });
+}
+/**
+ * The SDK `stderr` callback: chunks are split into lines; each non-empty line
+ * goes to `line` (the host's debug log + deduplicating notice reporter).
+ */
+export function createStderrSink(line) {
+    let partial = '';
+    return data => {
+        const lines = (partial + data).split(/\r?\n/u);
+        partial = lines.pop() ?? '';
+        for (const text of lines)
+            if (text.trim() !== '')
+                line(text);
+    };
+}

package/lib/types/backends/claude/replay.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Claude session transcript → Agent Domain replay: the durable history a
+ * resumed session
+ * paints before it follows live events.
+ *
+ * Input is what the SDK's read API returns — `getSessionMessages(id,
+ * {includeSystemMessages:true})`, the model-visible chain (after a
+ * compaction: the boundary, the summary, the preserved tail and what came
+ * later) — plus each subagent's `getSubagentMessages`. Output is the same
+ * vocabulary the live translator emits, produced by the same translator
+ * (`translate.ts`): assistant blocks, tool calls and results, plan / todo /
+ * question tools and the compaction rows map exactly as they do live. Only
+ * the turn segmentation is replay's own, because the transcript has no
+ * lifecycle frames and no `result`s:
+ *
+ * - a real user prompt closes the open turn and opens a user turn (its row
+ *   anchored at the message uuid — the `uuid` the session pushed, which the
+ *   CLI keeps, so live and replayed rows rewind the same way);
+ * - a queued prompt (`isQueuedCommand`, a steer folded into a running turn)
+ *   joins the open turn, as its `started` frame does live;
+ * - `[Request interrupted by user]` closes the turn as aborted (the live
+ *   interrupt row); a `task-notification` prompt opens the notification
+ *   turn; local-command echoes (`<command-name>`, `<local-command-*>`), meta
+ *   and synthetic texts never become bubbles — a user-typed slash command
+ *   shows as the `/name args` it was typed as (`/compact` excepted, as
+ *   live); command output sent on to the model (`<bash-stdout>`, dsh-tui's
+ *   `!!`) is a prompt of its own: it closes the open turn and opens the
+ *   turn the model answers it in, shown as its output row (as live);
+ * - a compact summary (`isCompactSummary`) closes the open turn and renders
+ *   the compaction rows (`compaction.end` + the summary).
+ *
+ * Thinking: the CLI records thinking blocks with empty text (the API only
+ * returns signatures unless summaries are enabled). A step whose API message
+ * reports `output_tokens_details.thinking_tokens` replays the same one-line
+ * count row the live `thinking_tokens` estimate produces; an empty block
+ * without a count is not shown (as live: nothing to show).
+ *
+ * Subagents: the parent `Agent` call pre-creates its subagent (as live);
+ * when the session kept the subagent's transcript, a `subagent.start` with
+ * the subagent's own id completes it, followed by its messages as child-lane
+ * events (`parentCallId` = the call) — its card and panels, never the main
+ * transcript. Its `subagent.end` comes from what the main chain recorded:
+ * the call's result for a foreground subagent (the hand-back report, an
+ * error, an interruption), the `<task-notification>` naming it for a
+ * background one (whose result only acknowledges the launch); with neither,
+ * its state is `unknown` (the CLI that ran it is gone). A subagent's own
+ * delegations (nested `Agent` calls in its transcript) are tracked the same
+ * way: ended by the result in that transcript, else `unknown` at the end of
+ * the replay.
+ *
+ * Not restored from the transcript: the context window (the read API has no
+ * field for it; the first live `result` reports it) and the session cost (the
+ * resumed CLI's first `result` reports it, as for any session).
+ *
+ * Pure: no I/O, no clock (event times come from the message timestamps).
+ */
+import type { AgentEvent } from '../../agent/events.js';
+import { type ClaudeTaskSeed } from './translate.js';
+/** One subagent transcript, keyed by the `Agent` tool call that launched
+ *  it (and, for healing, by the child's own agent id). */
+export interface ClaudeSubagentTranscript {
+    readonly agentId: string;
+    readonly messages: readonly unknown[];
+    /** `parent_agent_id` of the child's messages, when recorded. */
+    readonly parentAgentId?: string;
+}
+export interface ClaudeReplayOptions {
+    readonly cwd: string;
+    /** Subagent transcripts by parent `tool_use_id`. */
+    readonly subagents?: ReadonlyMap<string, ClaudeSubagentTranscript>;
+    /** The session's title (custom or generated), when the catalog has one. */
+    readonly title?: string;
+    readonly debug?: (message: string) => void;
+}
+export interface ClaudeReplay {
+    readonly events: readonly AgentEvent[];
+    /** The counters (and model) the live translator of the resumed session
+     *  continues from. */
+    readonly start: {
+        readonly turn: number;
+        readonly seq: number;
+        readonly model?: string;
+    };
+    /** The replayed conversation's task table (the Task* family), handed to
+     *  the live translator so a resumed update finds the ids the replay
+     *  tracked. Absent when the history tracked none. */
+    readonly tasks?: readonly ClaudeTaskSeed[];
+    /**
+     * The chain began at a compaction (its boundary's uuid, or the summary's
+     * when no boundary entry led it): older history exists on disk.
+     */
+    readonly compactedFrom?: string;
+}
+/** Replay one transcript chain. */
+export declare function replayClaudeTranscript(messages: readonly unknown[], options: ClaudeReplayOptions): ClaudeReplay;
+/** A subagent's own transcript replayed as its child lane: every
+ *  user/assistant message goes through the translator the live lane uses,
+ *  with `parent_tool_use_id` forced to the child's own agent id (a message
+ *  whose metadata lacks the delegating call id must not land on the main
+ *  lane). Thinking the API only signed or counted (empty text) becomes a
+ *  `reasoning-tokens` block with the count, or a `reasoning-signature`
+ *  block when even that is unknown; the view says the body is
+ *  unavailable. The child's initial prompt stays hidden. Pure: no I/O, no
+ *  clock (times come from the message timestamps). */
+export interface ClaudeSubagentLane {
+    readonly events: readonly AgentEvent[];
+    /** `parent_agent_id` across the child's messages; null = depth-1 or
+     *  old-format metadata. */
+    readonly parentAgentId: string | null;
+    readonly uuids: readonly string[];
+}
+export declare function replayClaudeSubagentLane(agentId: string, messages: readonly unknown[], options: {
+    readonly cwd: string;
+    readonly debug?: (message: string) => void;
+}): ClaudeSubagentLane;
+/**
+ * The uuid of the chain entry right before `anchor` — where a conversation
+ * rewind cuts (`forkSession({upToMessageId})` keeps it, inclusive). Undefined
+ * when `anchor` is not in the chain or is its first entry (nothing precedes
+ * it: there is no conversation to rewind to).
+ */
+export declare function rewindCutPoint(messages: readonly unknown[], anchor: string): string | undefined;
+/** The trailing exchanges of a chain, for the browser's preview (newest last). */
+export declare function previewEntries(messages: readonly unknown[], limit: number): {
+    role: 'user' | 'assistant';
+    text: string;
+    at: number | undefined;
+}[];
+//# sourceMappingURL=replay.d.ts.map

package/lib/types/backends/claude/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../../src/backends/claude/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,uBAAuB,CAAA;AAGtE,OAAO,EAAoF,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AActI;0DAC0D;AAC1D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAA;IAClE,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC;0BACsB;IACtB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACxF;;yDAEqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC1C;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AA8FD,mCAAmC;AACnC,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA4R/G;AAED;;;;;;;;sDAQsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;IACtC;+BAC2B;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5E,kBAAkB,CAwCpB;AACD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/F;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAAE,CA4BlJ"}