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

package/lib/types/backends/codex/translate/presentation.js

@@ -0,0 +1,237 @@
+import { displayPath } from '../../shared/display-path.js';
+import { arr, num, rec, str } from '../narrow.js';
+import { classifyCommand, commandTitle, unwrapCommand } from './commands.js';
+/** The item types this module renders as tool cards. */
+export const TOOL_ITEM_TYPES = new Set([
+    'commandExecution', 'fileChange', 'mcpToolCall', 'dynamicToolCall', 'webSearch',
+    'imageView', 'imageGeneration', 'sleep', 'collabAgentToolCall',
+]);
+const EXEC = { displayKey: 'tool-name-bash', category: 'exec' };
+const READ = { displayKey: 'tool-name-read', category: 'other' };
+const GREP = { displayKey: 'tool-name-grep', category: 'other' };
+const GLOB = { displayKey: 'tool-name-glob', category: 'other' };
+const EDIT = { displayKey: 'tool-name-edit', category: 'mutate' };
+const WRITE = { displayKey: 'tool-name-write', category: 'mutate' };
+const SEARCH = { displayKey: 'tool-name-web_search', category: 'other' };
+/** The command a `commandExecution` item ran, unwrapped (§8.1). */
+const commandOf = (item) => unwrapCommand(str(item.command) ?? '', item.commandActions);
+/** The kind and title of a command item. */
+function commandShape(item, cwd) {
+    const command = commandOf(item);
+    const kind = classifyCommand(item.commandActions);
+    const shell = str(item.source) === 'userShell';
+    switch (kind.kind) {
+        case 'read':
+            return { kind, title: kind.paths.map(path => displayPath(path, cwd)).join(', '), meta: READ };
+        case 'search': {
+            const where = kind.path === undefined ? undefined : displayPath(kind.path, cwd);
+            const title = kind.query === undefined ? (where ?? commandTitle(command)) : where === undefined ? kind.query : `${kind.query} · ${where}`;
+            return { kind, title, meta: GREP };
+        }
+        case 'list':
+            return { kind, title: kind.path === undefined ? '.' : displayPath(kind.path, cwd), meta: GLOB };
+        default:
+            return { kind, title: `${shell ? '!' : ''}${commandTitle(command)}`, meta: EXEC };
+    }
+}
+/** Rebuild old/new text from an unheaded unified hunk (the C1 fallback). */
+export function hunkTexts(patch) {
+    const before = [];
+    const after = [];
+    const lines = patch.split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    for (const line of lines) {
+        if (line.startsWith('@@') || line.startsWith('--- ') || line.startsWith('+++ ') || line.startsWith('\\'))
+            continue;
+        const mark = line[0];
+        const body = line.slice(1);
+        if (mark === '-')
+            before.push(body);
+        else if (mark === '+')
+            after.push(body);
+        else {
+            // ' ' (context) — or an empty line some writers leave unprefixed.
+            before.push(mark === ' ' ? body : line);
+            after.push(mark === ' ' ? body : line);
+        }
+    }
+    const joined = (list) => list.length === 0 ? '' : `${list.join('\n')}\n`;
+    return { oldText: joined(before), newText: joined(after) };
+}
+/** The file diffs of a `fileChange` item. */
+function diffsOf(item) {
+    return arr(item.changes).flatMap((raw) => {
+        const change = rec(raw);
+        const path = str(change?.path);
+        if (change === undefined || path === undefined)
+            return [];
+        const diff = str(change.diff) ?? '';
+        const kind = rec(change.kind);
+        switch (str(kind?.type)) {
+            case 'add':
+                return [{ path, oldText: null, newText: diff }];
+            case 'delete':
+                return [{ path, oldText: diff, newText: '' }];
+            default: {
+                const moved = str(kind?.move_path);
+                return [{ path, patch: diff, change: 'update', ...(moved === undefined ? {} : { movePath: moved }) }];
+            }
+        }
+    });
+}
+/** The title of a `fileChange` card: the file (or files) it touches. */
+function changeTitle(item, cwd) {
+    return arr(item.changes).flatMap(raw => {
+        const change = rec(raw);
+        const path = str(change?.path);
+        if (path === undefined)
+            return [];
+        const moved = str(rec(change?.kind)?.move_path);
+        return [moved === undefined ? displayPath(path, cwd) : `${displayPath(path, cwd)} → ${displayPath(moved, cwd)}`];
+    }).join(', ');
+}
+const allAdds = (item) => {
+    const changes = arr(item.changes);
+    return changes.length > 0 && changes.every(raw => str(rec(rec(raw)?.kind)?.type) === 'add');
+};
+/** How a tool item's call is recorded; undefined for a non-tool item. */
+export function toolCallOf(item, cwd) {
+    const type = str(item.type);
+    if (type === undefined || !TOOL_ITEM_TYPES.has(type))
+        return undefined;
+    switch (type) {
+        case 'commandExecution': {
+            const shape = commandShape(item, cwd);
+            const name = str(item.source) === 'userShell' ? 'user_shell' : 'shell';
+            const argsJson = JSON.stringify({ command: commandOf(item), cwd: str(item.cwd) ?? cwd });
+            const presentation = shape.kind.kind === 'read'
+                ? { card: 'generic', title: shape.title, ...shape.meta }
+                : { card: 'terminal', title: shape.title, cwd: str(item.cwd) ?? cwd, ...shape.meta };
+            return { name, argsJson, presentation };
+        }
+        case 'fileChange': {
+            const changes = arr(item.changes).map(raw => {
+                const change = rec(raw);
+                return { path: str(change?.path) ?? '', kind: str(rec(change?.kind)?.type) ?? 'update' };
+            });
+            return {
+                name: 'apply_patch',
+                argsJson: JSON.stringify({ changes }),
+                presentation: { card: 'diff', title: changeTitle(item, cwd), diffs: diffsOf(item), ...(allAdds(item) ? WRITE : EDIT) },
+            };
+        }
+        case 'mcpToolCall': {
+            const server = str(item.server) ?? 'mcp';
+            const tool = str(item.tool) ?? 'tool';
+            return { name: `mcp__${server}__${tool}`, argsJson: JSON.stringify(item.arguments ?? {}), presentation: { card: 'generic', title: `${server} › ${tool}` } };
+        }
+        case 'dynamicToolCall': {
+            const namespace = str(item.namespace);
+            const tool = str(item.tool) ?? 'tool';
+            const label = namespace === undefined ? tool : `${namespace}.${tool}`;
+            return { name: label, argsJson: JSON.stringify(item.arguments ?? {}), presentation: { card: 'generic', title: label } };
+        }
+        case 'webSearch': {
+            const action = rec(item.action);
+            const query = str(item.query) || str(action?.query) || str(action?.url) || '';
+            return { name: 'web_search', argsJson: JSON.stringify({ query }), presentation: { card: 'generic', title: query, ...SEARCH } };
+        }
+        case 'imageView': {
+            const path = str(item.path) ?? '';
+            return { name: 'view_image', argsJson: JSON.stringify({ path }), presentation: { card: 'generic', title: displayPath(path, cwd) } };
+        }
+        case 'imageGeneration':
+            return { name: 'image_generation', argsJson: JSON.stringify({ prompt: str(item.revisedPrompt) ?? '' }), presentation: { card: 'generic', title: str(item.revisedPrompt) ?? '' } };
+        case 'sleep': {
+            const ms = num(item.durationMs);
+            return { name: 'sleep', argsJson: JSON.stringify({ durationMs: ms ?? null }), presentation: { card: 'generic', title: ms === undefined ? '' : `${Math.round(ms / 1000)}s` } };
+        }
+        case 'collabAgentToolCall':
+            return { name: 'collab_agent', argsJson: JSON.stringify({ tool: str(item.tool) ?? '', prompt: str(item.prompt) ?? null }), presentation: { card: 'subagent' } };
+        default:
+            return undefined;
+    }
+}
+const textBlocks = (text) => text === '' ? [] : [{ type: 'text', text }];
+/** A failed command's card text: its output, then the exit code. */
+function failureText(output, exitCode, failed) {
+    const tail = exitCode === undefined ? failed : `exit ${exitCode}`;
+    return output.trim() === '' ? tail : `${output.trimEnd()}\n${tail}`;
+}
+/** How a settled tool item's result is recorded. */
+export function toolResultOf(item, cwd, words) {
+    const type = str(item.type);
+    const status = str(item.status);
+    switch (type) {
+        case 'commandExecution': {
+            const output = str(item.aggregatedOutput) ?? '';
+            const exitCode = num(item.exitCode);
+            if (status === 'declined')
+                return { isError: true, text: '', content: [], errorText: words.declined };
+            const failed = status !== 'completed' || (exitCode ?? 0) !== 0;
+            const shape = commandShape(item, cwd);
+            if (!failed && shape.kind.kind === 'read') {
+                const presentation = shape.kind.paths.length === 1
+                    ? { card: 'read', title: shape.title, path: shape.kind.paths[0], content: [{ type: 'text', text: output }], ...shape.meta }
+                    : { card: 'generic', title: shape.title, content: [{ type: 'text', text: output }], ...shape.meta };
+                return { isError: false, text: output, content: textBlocks(output), presentation };
+            }
+            const presentation = { card: 'terminal', output, ...(exitCode === undefined ? {} : { exitCode }), ...shape.meta };
+            return failed
+                ? { isError: true, text: '', content: [], errorText: failureText(output, exitCode, words.failed), presentation }
+                : { isError: false, text: output, content: textBlocks(output), presentation };
+        }
+        case 'fileChange': {
+            if (status === 'declined')
+                return { isError: true, text: '', content: [], errorText: words.declined };
+            const presentation = { card: 'diff', title: changeTitle(item, cwd), diffs: diffsOf(item), ...(allAdds(item) ? WRITE : EDIT) };
+            if (status !== 'completed')
+                return { isError: true, text: '', content: [], errorText: words.failed, presentation };
+            return { isError: false, text: '', content: [], presentation };
+        }
+        case 'mcpToolCall': {
+            const result = rec(item.result);
+            const error = str(rec(item.error)?.message);
+            const content = arr(result?.content).flatMap(raw => {
+                const block = rec(raw);
+                const kind = str(block?.type);
+                if (block === undefined || kind === undefined)
+                    return [];
+                return [kind === 'text' ? { type: 'text', text: str(block.text) ?? '' } : { type: kind }];
+            });
+            const text = content.flatMap(block => block.type === 'text' && block.text !== undefined ? [block.text] : []).join('\n');
+            const failed = error !== undefined || status === 'failed';
+            return failed
+                ? { isError: true, text: '', content, errorText: error ?? words.failed }
+                : { isError: false, text, content, ...(result?.structuredContent === undefined || result.structuredContent === null ? {} : { structured: result.structuredContent }) };
+        }
+        case 'dynamicToolCall': {
+            const content = arr(item.contentItems).flatMap(raw => {
+                const block = rec(raw);
+                const kind = str(block?.type);
+                if (block === undefined || kind === undefined)
+                    return [];
+                return [kind === 'inputText' ? { type: 'text', text: str(block.text) ?? '' } : { type: kind }];
+            });
+            const text = content.flatMap(block => block.type === 'text' && block.text !== undefined ? [block.text] : []).join('\n');
+            const failed = item.success === false || status === 'failed';
+            return failed ? { isError: true, text: '', content, errorText: text !== '' ? text : words.failed } : { isError: false, text, content };
+        }
+        case 'webSearch': {
+            const action = rec(item.action);
+            const queries = arr(action?.queries).filter((query) => typeof query === 'string');
+            const summary = str(action?.url) ?? (queries.length > 0 ? queries.join('\n') : str(action?.query) ?? str(item.query) ?? '');
+            return { isError: false, text: summary, content: textBlocks(summary) };
+        }
+        case 'imageGeneration': {
+            const failure = rec(item.failure);
+            if (failure !== undefined || status === 'failed')
+                return { isError: true, text: '', content: [], errorText: str(failure?.message) ?? words.failed };
+            const saved = str(item.savedPath) ?? '';
+            return { isError: false, text: saved, content: textBlocks(saved) };
+        }
+        default:
+            return { isError: status === 'failed', text: '', content: [], ...(status === 'failed' ? { errorText: words.failed } : {}) };
+    }
+}

package/lib/types/backends/codex/translate/replay.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Recorded Codex turns → Agent Domain events (docs/codex-backend-design.md
+ * §7.6): every item of every turn through the shared mapping (`items.ts`),
+ * `started` then `completed`, oldest turn first. The context is handed on
+ * to the live translator afterwards, so live numbering continues where the
+ * replay ended.
+ *
+ * - Turns must carry full items (`itemsView: 'full'`, C0 V4).
+ * - Times: a turn's `startedAt` / `completedAt` (seconds) when recorded.
+ * - An in-progress turn (the last one of a running thread) stays open: its
+ *   in-progress items only start, and live traffic completes them.
+ * - History carries no approvals, questions, stream deltas or token usage.
+ */
+import type { AgentEvent } from '../../../agent/events.js';
+import { type ItemContext } from './items.js';
+/** Replay turns (oldest first) into events, advancing `ctx`. */
+export declare function replayTurns(turns: readonly unknown[], ctx: ItemContext): AgentEvent[];
+//# sourceMappingURL=replay.d.ts.map

package/lib/types/backends/codex/translate/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/translate/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAA;AAGpE,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,EAAE,CAuBrF"}

package/lib/types/backends/codex/translate/replay.js

@@ -0,0 +1,33 @@
+import { arr, num, rec, str } from '../narrow.js';
+import { closeTurn, itemEvents } from './items.js';
+import { turnEndReason } from './notices.js';
+/** Replay turns (oldest first) into events, advancing `ctx`. */
+export function replayTurns(turns, ctx) {
+    const out = [];
+    for (const raw of turns) {
+        const turn = rec(raw);
+        if (turn === undefined)
+            continue;
+        const id = str(turn.id);
+        if (id !== undefined)
+            ctx.turnId = id;
+        const startedAt = num(turn.startedAt);
+        const completedAt = num(turn.completedAt);
+        const start = startedAt === undefined ? ctx.now() : startedAt * 1000;
+        const end = completedAt === undefined ? start : completedAt * 1000;
+        const running = str(turn.status) === 'inProgress';
+        for (const entry of arr(turn.items)) {
+            const item = rec(entry);
+            if (item === undefined)
+                continue;
+            out.push(...itemEvents(item, 'started', ctx, start));
+            // A running turn's unfinished item completes live.
+            if (running && str(item.status) === 'inProgress')
+                continue;
+            out.push(...itemEvents(item, 'completed', ctx, start));
+        }
+        if (!running)
+            closeTurn(ctx, out, turnEndReason(turn), end);
+    }
+    return out;
+}

package/lib/types/backends/codex/translate/usage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Token usage and rate limits (docs/codex-backend-design.md §7.5).
+ *
+ * `thread/tokenUsage/updated` reports `last` (the latest model call) and
+ * `total`. OpenAI counts cached and cache-written prompt tokens inside
+ * `inputTokens`; the shared vocabulary keeps them apart (occupancy is
+ * input + cacheRead + cacheWrite), so the uncached share is what remains.
+ */
+import type { RateLimitView, UsageDelta } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+/** One `TokenUsageBreakdown` in the shared vocabulary. */
+export declare function usageOf(breakdown: unknown): UsageDelta | undefined;
+/** Sum two usages (absent counts stay absent only when both are). */
+export declare function addUsage(a: UsageDelta | undefined, b: UsageDelta | undefined): UsageDelta | undefined;
+/** A `thread/tokenUsage/updated` payload: the latest call and the window. */
+export declare function tokenUsageOf(params: Rec): {
+    readonly last?: UsageDelta;
+    readonly window?: number;
+};
+/** The status line's window name for a window length (5 h / 7 d keep the
+ *  names the status line localizes; anything else reads as minutes). */
+export declare function windowName(minutes: number | undefined): string;
+/** `account/rateLimits/updated` → the shared view; undefined when the
+ *  snapshot carries no window (a relay reports none). */
+export declare function rateLimitOf(params: Rec): {
+    readonly view?: RateLimitView;
+    readonly reached?: string;
+};
+//# sourceMappingURL=usage.d.ts.map

package/lib/types/backends/codex/translate/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/translate/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACzE,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAEjD,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,SAAS,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAclE;AAED,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CASrG;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,GAAG,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAKlG;AAED;wEACwE;AACxE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED;yDACyD;AACzD,wBAAgB,WAAW,CAAC,MAAM,EAAE,GAAG,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAWrG"}

package/lib/types/backends/codex/translate/usage.js

@@ -0,0 +1,65 @@
+import { num, rec } from '../narrow.js';
+/** One `TokenUsageBreakdown` in the shared vocabulary. */
+export function usageOf(breakdown) {
+    const value = rec(breakdown);
+    if (value === undefined)
+        return undefined;
+    const input = num(value.inputTokens);
+    const output = num(value.outputTokens);
+    if (input === undefined && output === undefined)
+        return undefined;
+    const cacheRead = num(value.cachedInputTokens) ?? 0;
+    const cacheWrite = num(value.cacheWriteInputTokens) ?? 0;
+    return {
+        input: Math.max(0, (input ?? 0) - cacheRead - cacheWrite),
+        output: output ?? 0,
+        cacheRead,
+        cacheWrite,
+    };
+}
+/** Sum two usages (absent counts stay absent only when both are). */
+export function addUsage(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return {
+        input: (a.input ?? 0) + (b.input ?? 0),
+        output: (a.output ?? 0) + (b.output ?? 0),
+        cacheRead: (a.cacheRead ?? 0) + (b.cacheRead ?? 0),
+        cacheWrite: (a.cacheWrite ?? 0) + (b.cacheWrite ?? 0),
+    };
+}
+/** A `thread/tokenUsage/updated` payload: the latest call and the window. */
+export function tokenUsageOf(params) {
+    const usage = rec(params.tokenUsage);
+    const last = usageOf(usage?.last);
+    const window = num(usage?.modelContextWindow);
+    return { ...(last === undefined ? {} : { last }), ...(window === undefined || window <= 0 ? {} : { window }) };
+}
+/** The status line's window name for a window length (5 h / 7 d keep the
+ *  names the status line localizes; anything else reads as minutes). */
+export function windowName(minutes) {
+    if (minutes === 300)
+        return 'five_hour';
+    if (minutes === 10_080)
+        return 'seven_day';
+    if (minutes === undefined)
+        return 'window';
+    return minutes % 1440 === 0 ? `${minutes / 1440}d` : minutes % 60 === 0 ? `${minutes / 60}h` : `${minutes}m`;
+}
+/** `account/rateLimits/updated` → the shared view; undefined when the
+ *  snapshot carries no window (a relay reports none). */
+export function rateLimitOf(params) {
+    const snapshot = rec(params.rateLimits);
+    const windows = [snapshot?.primary, snapshot?.secondary].flatMap(raw => {
+        const window = rec(raw);
+        const used = num(window?.usedPercent);
+        if (window === undefined || used === undefined)
+            return [];
+        const resetsAt = num(window.resetsAt);
+        return [{ name: windowName(num(window.windowDurationMins)), utilization: used / 100, ...(resetsAt === undefined ? {} : { resetsAt: resetsAt * 1000 }) }];
+    });
+    const reached = typeof snapshot?.rateLimitReachedType === 'string' ? snapshot.rateLimitReachedType : undefined;
+    return { ...(windows.length === 0 ? {} : { view: { windows } }), ...(reached === undefined ? {} : { reached }) };
+}

package/lib/types/backends/shared/atomic-file.d.ts

@@ -0,0 +1,4 @@
+/** Replace `<dir>/<file>` with `text`. Throws when it cannot; the previous
+ *  document is then intact and no temporary is left behind. */
+export declare function writeFileAtomic(dir: string, file: string, text: string): void;
+//# sourceMappingURL=atomic-file.d.ts.map

package/lib/types/backends/shared/atomic-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../../../src/backends/shared/atomic-file.ts"],"names":[],"mappings":"AAmCA;+DAC+D;AAC/D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAc7E"}

package/lib/types/backends/shared/atomic-file.js

@@ -0,0 +1,52 @@
+/**
+ * Atomic replace of the small files a backend keeps (prefs, channel
+ * profiles, the channel-token store; shared by every backend, D15): a same-directory temporary renamed
+ * over the target. A reader — or another terminal's read-modify-write — sees
+ * the old document or the new one, never a truncated one, and a failed write
+ * leaves the old document in place. The temporary is created owner-only:
+ * these files hold user choices and credentials.
+ */
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Keeps two commits in the same millisecond on distinct temporaries. */
+let sequence = 0;
+/** The cell `Atomics.wait` sleeps on between rename retries. */
+const waitCell = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Windows can refuse the rename for a moment while another process holds
+ * the target open (EPERM/EBUSY): on Windows that pair alone is retried with
+ * a short synchronous pause. Any other refusal is real and thrown at once.
+ */
+function renameIntoPlace(temporary, target) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(temporary, target);
+            return;
+        }
+        catch (error) {
+            const code = typeof error === 'object' && error !== null ? String(error.code) : '';
+            if (process.platform !== 'win32' || attempt >= 7 || (code !== 'EPERM' && code !== 'EBUSY'))
+                throw error;
+            Atomics.wait(waitCell, 0, 0, 2 ** attempt);
+        }
+    }
+}
+/** Replace `<dir>/<file>` with `text`. Throws when it cannot; the previous
+ *  document is then intact and no temporary is left behind. */
+export function writeFileAtomic(dir, file, text) {
+    const temporary = join(dir, `${file}.${process.pid}.${Date.now()}.${sequence++}.tmp`);
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(temporary, text, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        renameIntoPlace(temporary, join(dir, file));
+    }
+    catch (error) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // The previous document is still intact; nothing else is safe to do.
+        }
+        throw error;
+    }
+}

package/lib/types/backends/shared/channel-tokens.d.ts

@@ -0,0 +1,29 @@
+/** The credential ref of one channel id (the deriveKeyRef convention:
+ *  uppercase, runs of non-alphanumerics → `_`). */
+export declare function channelTokenRef(id: string): string;
+/** Read/write/erase access (injectable: tests use an in-memory store). */
+export interface ChannelTokenStore {
+    /** The stored token, or undefined when the ref holds nothing. */
+    read(ref: string): string | undefined;
+    /** Store `value` under `ref` (best-effort: a failure reports to the
+     *  debug log and the session carries on without the token). */
+    write(ref: string, value: string): void;
+    /** Remove `ref` (a missing ref is fine). */
+    erase(ref: string): void;
+    /** Whether `ref` is declared (the roster's `hasToken`). */
+    declared(ref: string): boolean;
+}
+/** The file-backed token store under `home` (default the DSH home that owns
+ * `~/.dsh/.credentials.yaml`). */
+export declare function fileChannelTokens(home?: string, debug?: (message: string) => void): ChannelTokenStore;
+/** An in-memory store (tests, embedders). */
+export declare function memoryChannelTokens(initial?: Record<string, string>): ChannelTokenStore & {
+    readonly data: Readonly<Record<string, string>>;
+};
+/** @deprecated The pre-D15 name (kept for one phase): {@link ChannelTokenStore}. */
+export type ClaudeChannelTokens = ChannelTokenStore;
+/** @deprecated The pre-D15 name (kept for one phase): {@link fileChannelTokens}. */
+export declare const fileClaudeChannelTokens: typeof fileChannelTokens;
+/** @deprecated The pre-D15 name (kept for one phase): {@link memoryChannelTokens}. */
+export declare const memoryClaudeChannelTokens: typeof memoryChannelTokens;
+//# sourceMappingURL=channel-tokens.d.ts.map

package/lib/types/backends/shared/channel-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-tokens.d.ts","sourceRoot":"","sources":["../../../../src/backends/shared/channel-tokens.ts"],"names":[],"mappings":"AAmCA;mDACmD;AACnD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACrC;mEAC+D;IAC/D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,4CAA4C;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAC/B;AAID;kCACkC;AAClC,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAqB,EAAE,KAAK,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAsB,GAAG,iBAAiB,CAuFpI;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,iBAAiB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CASjJ;AAED,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAA;AACnD,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,0BAAoB,CAAA;AACxD,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,4BAAsB,CAAA"}

package/lib/types/backends/shared/channel-tokens.js

@@ -0,0 +1,161 @@
+/**
+ * The credential seam of a backend's channel profiles (shared by every
+ * backend, docs/codex-backend-design.md D15): channel
+ * tokens live in the DSH credential store — the same `~/.dsh/.credentials.yaml`
+ * (0600) the /provider wizard writes through the dsh credentials service
+ * (providerWizard.ts's deriveKeyRef convention) — and channels.json holds
+ * only the derived `tokenRef`, never a literal token.
+ *
+ * This module is a direct, host-side file view of that store (a non-DSH
+ * backend has no cordis context to resolve `ctx.get('credentials')` from).
+ * The store is edited through a YAML document parser (`yaml`): the top-level
+ * `refs` mapping is found in block or flow style, quoted keys included;
+ * foreign fields, comments and multiline scalars keep their meaning, and a
+ * commit must parse back clean before it replaces the file (the store is
+ * shared with the host, so a duplicate `refs:` key would break it for every
+ * strict reader). A store that cannot be read or does not parse is never
+ * rebuilt over: reads answer undefined and writes refuse.
+ * Commits are atomic (atomic-file.ts).
+ * The ref namespace is `CHANNEL_<SLUG>_TOKEN` — derived from the channel id
+ * the way deriveKeyRef derives `<ROUTE>_API_KEY`, so a re-import (or a hand
+ * edit of the name's slug) refreshes the same credential row.
+ *
+ * Token material never reaches a log, notice or event (each backend's
+ * credential contract): this module only ever moves it between the file and
+ * the spawn pipeline.
+ *
+ * Backend-neutral: no vendor package and no backend directory is imported
+ * here (`verify:boundary`).
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isMap, parseDocument } from 'yaml';
+import { dshHomeDir } from '../../utils/credentials.js';
+import { writeFileAtomic } from './atomic-file.js';
+/** The credential ref of one channel id (the deriveKeyRef convention:
+ *  uppercase, runs of non-alphanumerics → `_`). */
+export function channelTokenRef(id) {
+    const cleaned = id.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return 'CHANNEL_' + (cleaned === '' ? 'CHANNEL' : cleaned) + '_TOKEN';
+}
+const FILE = '.credentials.yaml';
+/** The file-backed token store under `home` (default the DSH home that owns
+ * `~/.dsh/.credentials.yaml`). */
+export function fileChannelTokens(home = dshHomeDir(), debug = () => undefined) {
+    const path = join(home, FILE);
+    /** Parse the store into a YAML document; undefined for a file that
+     *  cannot be read or does not parse (never rebuilt over). An absent file
+     *  parses as an empty document, so the first write can create it. */
+    const load = () => {
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return parseDocument('');
+            debug('dsh-tui: channel token store unreadable (' + (error instanceof Error ? error.message : String(error)) + '); refusing to touch it');
+            return undefined;
+        }
+        const doc = parseDocument(text);
+        if (doc.errors.length > 0) {
+            debug('dsh-tui: channel token store is not valid YAML (' + doc.errors.length + ' parse errors); refusing to touch it');
+            return undefined;
+        }
+        return doc;
+    };
+    /** The top-level `refs` mapping: undefined when absent, null when the
+     *  document holds a `refs` entry that is not a mapping (writes refuse on
+     *  that shape instead of guessing around it). */
+    const refsOf = (doc) => {
+        if (doc.contents === null)
+            return undefined;
+        if (!isMap(doc.contents))
+            return null;
+        const refs = doc.contents.get('refs');
+        if (refs === undefined)
+            return undefined;
+        return isMap(refs) ? refs : null;
+    };
+    const commit = (next) => {
+        try {
+            writeFileAtomic(home, FILE, next);
+        }
+        catch (error) {
+            debug('dsh-tui: channel token write failed (' + (error instanceof Error ? error.message : String(error)) + ')');
+        }
+    };
+    return {
+        read: ref => {
+            const doc = load();
+            if (doc === undefined)
+                return undefined;
+            const refs = refsOf(doc);
+            if (refs === undefined || refs === null)
+                return undefined;
+            const value = refs.get(ref);
+            // Only a non-empty string scalar is a token; null/number/boolean
+            // scalars are declared but not usable credential material.
+            return typeof value === 'string' && value !== '' ? value : undefined;
+        },
+        write: (ref, value) => {
+            const doc = load();
+            if (doc === undefined)
+                return;
+            const refs = refsOf(doc);
+            if (refs === null) {
+                debug('dsh-tui: channel token store refs is not a mapping; refusing to write');
+                return;
+            }
+            if (refs === undefined)
+                doc.set('refs', { [ref]: value });
+            else
+                refs.set(ref, value);
+            // lineWidth 0: a token is one scalar and must never be line-folded.
+            const next = doc.toString({ lineWidth: 0 });
+            // Nothing is committed unless it parses back clean.
+            if (parseDocument(next).errors.length > 0) {
+                debug('dsh-tui: channel token write self-check failed; refusing to commit');
+                return;
+            }
+            if (next !== '')
+                commit(next);
+        },
+        erase: ref => {
+            const doc = load();
+            if (doc === undefined)
+                return;
+            const refs = refsOf(doc);
+            if (refs === undefined || refs === null)
+                return;
+            if (!refs.has(ref))
+                return;
+            refs.delete(ref);
+            commit(doc.toString({ lineWidth: 0 }));
+        },
+        declared: ref => {
+            const doc = load();
+            if (doc === undefined)
+                return false;
+            const refs = refsOf(doc);
+            return refs !== undefined && refs !== null && refs.has(ref);
+        },
+    };
+}
+/** An in-memory store (tests, embedders). */
+export function memoryChannelTokens(initial = {}) {
+    let data = { ...initial };
+    return {
+        get data() { return data; },
+        read: ref => data[ref],
+        write: (ref, value) => { data = { ...data, [ref]: value }; },
+        erase: ref => { const next = {}; for (const [key, value] of Object.entries(data))
+            if (key !== ref)
+                next[key] = value; data = next; },
+        declared: ref => Object.hasOwn(data, ref),
+    };
+}
+/** @deprecated The pre-D15 name (kept for one phase): {@link fileChannelTokens}. */
+export const fileClaudeChannelTokens = fileChannelTokens;
+/** @deprecated The pre-D15 name (kept for one phase): {@link memoryChannelTokens}. */
+export const memoryClaudeChannelTokens = memoryChannelTokens;

package/lib/types/backends/shared/display-path.d.ts

@@ -0,0 +1,3 @@
+/** A path for a title: relative to the session cwd when inside it. */
+export declare function displayPath(path: string, cwd: string): string;
+//# sourceMappingURL=display-path.d.ts.map