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

package/lib/types/backends/codex/session/tasks.js

@@ -0,0 +1,207 @@
+/** Background terminals have no exit notifications: poll their native inventory. */
+import { Buffer } from 'node:buffer';
+import { t } from '../../../i18n.js';
+import { arr, errorText, rec, str } from '../narrow.js';
+import { CLIENT, NOTIFY } from '../protocol/index.js';
+import { REAL_CLOCK, rpcCode, RPC_ERROR } from '../rpc/client.js';
+export const CODEX_TASK_POLL_MS = 2000;
+export const CODEX_TASK_OUTPUT_BYTES = 64 * 1024;
+const MAX_TERMINALS = 64; // Codex's native unified-exec inventory bound.
+const tail = (text) => {
+    const bytes = Buffer.from(text);
+    if (bytes.length <= CODEX_TASK_OUTPUT_BYTES)
+        return text;
+    let offset = bytes.length - CODEX_TASK_OUTPUT_BYTES;
+    while ((bytes[offset] & 0xc0) === 0x80)
+        offset += 1;
+    return bytes.subarray(offset).toString('utf8');
+};
+export function createCodexTasks(deps) {
+    const clock = deps.clock ?? REAL_CLOCK;
+    const now = deps.now ?? Date.now;
+    const terminals = new Map();
+    let enabled = true;
+    let closed = false;
+    let generation = 0;
+    let timer;
+    let outputTimer;
+    let inFlight;
+    const cancelTimer = () => { if (timer !== undefined)
+        clock.clearTimeout(timer); timer = undefined; };
+    const flushOutput = () => {
+        if (outputTimer !== undefined)
+            clock.clearTimeout(outputTimer);
+        outputTimer = undefined;
+        const events = [];
+        for (const entry of terminals.values())
+            if (entry.announced && entry.pending !== '') {
+                events.push({ type: 'task.output', taskId: entry.id, text: entry.pending, time: now() });
+                entry.pending = '';
+            }
+        if (!closed && events.length > 0)
+            deps.emit(events);
+    };
+    const unsupported = (error) => {
+        if (rpcCode(error) !== RPC_ERROR.methodNotFound && rpcCode(error) !== RPC_ERROR.invalidParams)
+            return false;
+        if (enabled)
+            deps.emit([{ type: 'notice', level: 'warning', key: 'codex-tasks-unsupported', text: t('codex-tasks-unsupported') }]);
+        enabled = false;
+        cancelTimer();
+        return true;
+    };
+    const remember = (id, itemId, command) => {
+        let entry = terminals.get(id);
+        if (entry === undefined) {
+            entry = { id, itemId, command, live: false, announced: false, stopped: false, output: '', pending: '' };
+            terminals.set(id, entry);
+            if (terminals.size > MAX_TERMINALS * 2) {
+                const stale = [...terminals.values()].find(item => !item.live && item.id !== id);
+                if (stale !== undefined)
+                    terminals.delete(stale.id);
+            }
+        }
+        else {
+            entry.itemId = itemId;
+            entry.command = command;
+        }
+        return entry;
+    };
+    const schedule = () => {
+        cancelTimer();
+        if (closed || !enabled || ![...terminals.values()].some(entry => entry.live))
+            return;
+        timer = clock.setTimeout(() => { timer = undefined; void refresh(); }, CODEX_TASK_POLL_MS);
+    };
+    const refresh = () => {
+        if (closed || !enabled)
+            return Promise.resolve();
+        if (inFlight !== undefined)
+            return inFlight;
+        const root = deps.threadId();
+        const epoch = generation;
+        const request = (async () => {
+            try {
+                const found = new Map();
+                let cursor;
+                let pages = 0;
+                do {
+                    pages += 1;
+                    const result = rec(await deps.hub.call(CLIENT.backgroundTerminalsList, { threadId: root, limit: MAX_TERMINALS, ...(cursor === undefined ? {} : { cursor }) }));
+                    for (const raw of arr(result?.data)) {
+                        const entry = rec(raw);
+                        const id = str(entry?.processId);
+                        if (entry !== undefined && id !== undefined)
+                            found.set(id, entry);
+                    }
+                    cursor = str(result?.nextCursor);
+                } while (cursor !== undefined && found.size < MAX_TERMINALS && pages < 4);
+                if (closed || epoch !== generation || root !== deps.threadId())
+                    return;
+                const events = [];
+                for (const [id, data] of found) {
+                    const entry = remember(id, str(data.itemId) ?? '', str(data.command) ?? '');
+                    entry.live = true;
+                    if (!entry.announced) {
+                        entry.announced = true;
+                        events.push({ type: 'task.start', taskId: id, kind: 'shell', description: entry.command, command: entry.command, ...(entry.itemId === '' ? {} : { callId: entry.itemId }), background: true, time: now() });
+                        if (entry.output !== '')
+                            events.push({ type: 'task.output', taskId: id, text: entry.output, time: now() });
+                    }
+                }
+                // Only a complete inventory can prove a process disappeared.
+                if (cursor === undefined)
+                    for (const entry of terminals.values()) {
+                        if (!entry.live || found.has(entry.id))
+                            continue;
+                        flushOutput();
+                        entry.live = false;
+                        events.push({ type: 'task.end', taskId: entry.id, status: entry.stopped ? 'stopped' : 'completed', summary: t(entry.stopped ? 'codex-terminal-stopped' : 'codex-terminal-ended'), time: now() });
+                    }
+                events.push({ type: 'tasks.snapshot', taskIds: [...terminals.values()].filter(entry => entry.live).map(entry => entry.id) });
+                if (events.length > 0)
+                    deps.emit(events);
+            }
+            catch (error) {
+                if (!closed && epoch === generation && root === deps.threadId() && !unsupported(error))
+                    deps.debug?.('codex: terminal inventory failed (' + errorText(error) + ')');
+            }
+        })();
+        inFlight = request;
+        void request.finally(() => { if (inFlight === request)
+            inFlight = undefined; if (epoch === generation)
+            schedule(); });
+        return request;
+    };
+    const capability = {
+        async stop(id) {
+            const entry = terminals.get(id);
+            if (!enabled || closed || entry?.live !== true)
+                return false;
+            const root = deps.threadId();
+            const epoch = generation;
+            try {
+                const response = rec(await deps.hub.call(CLIENT.backgroundTerminalsTerminate, { threadId: root, processId: id }));
+                if (closed || epoch !== generation || root !== deps.threadId() || response?.terminated !== true)
+                    return false;
+                entry.stopped = true;
+                await refresh();
+                return true;
+            }
+            catch (error) {
+                if (closed || epoch !== generation || root !== deps.threadId() || unsupported(error))
+                    return false;
+                throw error;
+            }
+        },
+        get readOutput() {
+            if (![...terminals.values()].some(entry => entry.output !== ''))
+                return undefined;
+            return async (id) => {
+                const output = terminals.get(id)?.output;
+                if (output === undefined || output === '')
+                    throw new Error(t('codex-terminal-no-output'));
+                return output;
+            };
+        },
+    };
+    return {
+        get capability() { return enabled && !closed ? capability : undefined; },
+        initialize: refresh,
+        refresh,
+        notification(method, params) {
+            if (closed || !enabled || str(params.threadId) !== deps.threadId())
+                return false;
+            if (method === NOTIFY.turnStarted || method === NOTIFY.turnCompleted) {
+                void refresh();
+                return false;
+            }
+            if (method === NOTIFY.itemStarted || method === NOTIFY.itemCompleted) {
+                const item = rec(params.item);
+                const id = item?.type === 'commandExecution' ? str(item.processId) : undefined;
+                if (id !== undefined) {
+                    const entry = remember(id, str(item?.id) ?? '', str(item?.command) ?? '');
+                    const output = str(item?.aggregatedOutput);
+                    if (output !== undefined && output !== '')
+                        entry.output = tail(output);
+                }
+            }
+            else if (method === NOTIFY.commandOutputDelta) {
+                const entry = [...terminals.values()].find(value => value.itemId === str(params.itemId));
+                const text = str(params.delta);
+                if (entry !== undefined && text !== undefined && text !== '') {
+                    entry.output = tail(entry.output + text);
+                    if (entry.announced) {
+                        entry.pending = tail(entry.pending + text);
+                        outputTimer ??= clock.setTimeout(flushOutput, 100);
+                    }
+                }
+            }
+            return false;
+        },
+        reset() { generation += 1; cancelTimer(); if (outputTimer !== undefined)
+            clock.clearTimeout(outputTimer); outputTimer = undefined; terminals.clear(); inFlight = undefined; },
+        close() { closed = true; generation += 1; cancelTimer(); if (outputTimer !== undefined)
+            clock.clearTimeout(outputTimer); outputTimer = undefined; },
+    };
+}

package/lib/types/backends/codex/session/tool-output.d.ts

@@ -0,0 +1,9 @@
+/** Coalesce command output per call at 10 Hz; a result flushes first. */
+import type { AgentEvent, AgentEventOf } from '../../../agent/events.js';
+import type { RpcClock } from '../rpc/client.js';
+export declare function createToolOutputBuffer(emit: (events: readonly AgentEvent[]) => void, clock: RpcClock): {
+    push(event: AgentEventOf<"tool.output">): void;
+    flush: (callId?: string) => void;
+    close(): void;
+};
+//# sourceMappingURL=tool-output.d.ts.map

package/lib/types/backends/codex/session/tool-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/tool-output.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,KAAK,IAAI,EAAE,KAAK,EAAE,QAAQ;gBAYrF,YAAY,CAAC,aAAa,CAAC,GAAG,IAAI;qBATxB,MAAM,KAAG,IAAI;aAkB1B,IAAI;EAKhB"}

package/lib/types/backends/codex/session/tool-output.js

@@ -0,0 +1,29 @@
+export function createToolOutputBuffer(emit, clock) {
+    const pending = new Map();
+    const keyOf = (event) => (event.parentCallId ?? '') + '\u0000' + event.callId;
+    const flush = (callId) => {
+        for (const [id, value] of pending) {
+            if (callId !== undefined && value.event.callId !== callId)
+                continue;
+            pending.delete(id);
+            clock.clearTimeout(value.timer);
+            emit([value.event]);
+        }
+    };
+    return {
+        push(event) {
+            const value = pending.get(keyOf(event));
+            if (value !== undefined) {
+                value.event = { ...event, text: value.event.text + event.text };
+                return;
+            }
+            pending.set(keyOf(event), { event, timer: clock.setTimeout(() => flush(event.callId), 100) });
+        },
+        flush,
+        close() {
+            for (const value of pending.values())
+                clock.clearTimeout(value.timer);
+            pending.clear();
+        },
+    };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The script inside a shell wrapper, unwrapped losslessly; undefined when
+ * the command is not a recognised wrapper or its quoting is not one plain
+ * word. Approval prompts show this (or the raw command): what they show is
+ * exactly what will run.
+ */
+export declare function unwrapShell(command: string): string | undefined;
+/** A card title's command: the unwrapped script, else (one parsed action)
+ *  Codex's own reading of it, else the command as given. */
+export declare function unwrapCommand(command: string, actions?: unknown): string;
+/** A one-line title: the first line, `…` when more follow. */
+export declare function commandTitle(command: string): string;
+/** What a command does, from its parsed actions. */
+export type CommandKind = {
+    readonly kind: 'read';
+    readonly paths: readonly string[];
+} | {
+    readonly kind: 'search';
+    readonly query?: string;
+    readonly path?: string;
+} | {
+    readonly kind: 'list';
+    readonly path?: string;
+} | {
+    readonly kind: 'exec';
+};
+/** Classify by `commandActions`: only a uniform read/search/list command
+ *  is not a terminal. */
+export declare function classifyCommand(actions: unknown): CommandKind;
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/translate/commands.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM/D;AAED;4DAC4D;AAC5D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,OAAY,GAAG,MAAM,CAS5E;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED,oDAAoD;AACpD,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7B;yBACyB;AACzB,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CA8B7D"}

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

@@ -0,0 +1,103 @@
+/**
+ * Command display (docs/codex-backend-design.md §8.1): the shell wrapper
+ * Codex runs a command in is not what the user should read, and a command
+ * whose every parsed action only reads, searches or lists files renders as
+ * that, not as a terminal (D12).
+ */
+import { arr, rec, str } from '../narrow.js';
+/** `bash -lc '…'` at any path (`/bin/bash`, `/opt/homebrew/bin/bash`, a
+ *  bare `bash`), also `sh`/`zsh`/`dash`/`ksh` and any `-c` flag cluster. */
+const POSIX_WRAPPER = /^(?:\S*\/)?(?:ba|z|da|k)?sh\s+-[a-z]*c[a-z]*\s+([\s\S]+)$/u;
+/** `powershell.exe -Command …` / `pwsh -c …`, a quoted path allowed, with
+ *  the usual switches before the script (any case). */
+const POWERSHELL_WRAPPER = /^(?:"[^"]*?(?:powershell|pwsh)(?:\.exe)?"|\S*?(?:powershell|pwsh)(?:\.exe)?)(?:\s+-(?:NoProfile|NoLogo|NonInteractive|ExecutionPolicy\s+\S+))*\s+-(?:Command|c)\s+([\s\S]+)$/iu;
+/**
+ * Undo one level of shell quoting when the whole script is exactly one
+ * quoted word; undefined when it is not (several words, unbalanced quotes):
+ * the caller then keeps the script as written, never a guess.
+ */
+function unquote(script) {
+    const trimmed = script.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('\'') && trimmed.endsWith('\'')) {
+        // POSIX single quotes: `'"'"'` / `'\''` spell a literal quote inside.
+        const inner = trimmed.slice(1, -1).replaceAll('\'"\'"\'', '\u0000').replaceAll('\'\\\'\'', '\u0000');
+        return inner.includes('\'') ? undefined : inner.replaceAll('\u0000', '\'');
+    }
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        const inner = trimmed.slice(1, -1);
+        return /(?<!\\)"/u.test(inner) ? undefined : inner.replace(/\\(["\\$`])/gu, '$1');
+    }
+    return /['"]/u.test(trimmed) ? undefined : trimmed;
+}
+/**
+ * The script inside a shell wrapper, unwrapped losslessly; undefined when
+ * the command is not a recognised wrapper or its quoting is not one plain
+ * word. Approval prompts show this (or the raw command): what they show is
+ * exactly what will run.
+ */
+export function unwrapShell(command) {
+    const posix = POSIX_WRAPPER.exec(command.trim());
+    if (posix !== null)
+        return unquote(posix[1]);
+    const powershell = POWERSHELL_WRAPPER.exec(command.trim());
+    if (powershell !== null)
+        return unquote(powershell[1]);
+    return undefined;
+}
+/** A card title's command: the unwrapped script, else (one parsed action)
+ *  Codex's own reading of it, else the command as given. */
+export function unwrapCommand(command, actions = []) {
+    const unwrapped = unwrapShell(command);
+    if (unwrapped !== undefined)
+        return unwrapped;
+    const list = arr(actions);
+    if (list.length === 1) {
+        const only = str(rec(list[0])?.command);
+        if (only !== undefined && only !== '')
+            return only;
+    }
+    return command;
+}
+/** A one-line title: the first line, `…` when more follow. */
+export function commandTitle(command) {
+    const lines = command.split('\n');
+    const first = lines[0].trimEnd();
+    return lines.length > 1 ? `${first} …` : first;
+}
+/** Classify by `commandActions`: only a uniform read/search/list command
+ *  is not a terminal. */
+export function classifyCommand(actions) {
+    const list = arr(actions).flatMap(action => {
+        const value = rec(action);
+        return value === undefined ? [] : [value];
+    });
+    if (list.length === 0)
+        return { kind: 'exec' };
+    const types = new Set(list.map(action => str(action.type)));
+    if (types.size !== 1)
+        return { kind: 'exec' };
+    switch ([...types][0]) {
+        case 'read': {
+            const paths = list.flatMap(action => {
+                const path = str(action.path) ?? str(action.name);
+                return path === undefined || path === '' ? [] : [path];
+            });
+            return paths.length === 0 ? { kind: 'exec' } : { kind: 'read', paths };
+        }
+        case 'search': {
+            if (list.length !== 1)
+                return { kind: 'exec' };
+            const query = str(list[0].query);
+            const path = str(list[0].path);
+            return { kind: 'search', ...(query === undefined || query === '' ? {} : { query }), ...(path === undefined || path === '' ? {} : { path }) };
+        }
+        case 'listFiles': {
+            if (list.length !== 1)
+                return { kind: 'exec' };
+            const path = str(list[0].path);
+            return { kind: 'list', ...(path === undefined || path === '' ? {} : { path }) };
+        }
+        default:
+            return { kind: 'exec' };
+    }
+}

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

@@ -0,0 +1,9 @@
+/** Declare which Agent Domain events the Codex backend emits. */
+import type { AgentEventType } from '../../../agent/events.js';
+/**
+ * The Codex backend's decision for every Agent Domain event type (checked by
+ * `verify:agent-domain`): a new `AgentEvent` variant fails `tsc` here until
+ * this backend decides whether it emits it.
+ */
+export declare function codexEmits(type: AgentEventType): boolean;
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/translate/events.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAE9D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAiExD"}

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

@@ -0,0 +1,71 @@
+/**
+ * The Codex backend's decision for every Agent Domain event type (checked by
+ * `verify:agent-domain`): a new `AgentEvent` variant fails `tsc` here until
+ * this backend decides whether it emits it.
+ */
+export function codexEmits(type) {
+    switch (type) {
+        case 'subagent.start':
+        case 'subagent.progress':
+        case 'subagent.end':
+        case 'task.start':
+        case 'task.output':
+        case 'task.end':
+        case 'tasks.snapshot':
+        case 'goal.change':
+        case 'commands.changed':
+        case 'session.color':
+        case 'session.reset':
+        case 'session.ready':
+        case 'session.title':
+        case 'session.status':
+        case 'turn.start':
+        case 'turn.end':
+        case 'step.start':
+        case 'step.end':
+        case 'user.message':
+        case 'pending.changed':
+        case 'assistant.attempt.start':
+        case 'assistant.delta':
+        case 'assistant.message':
+        case 'assistant.attempt.end':
+        case 'usage':
+        case 'context.usage':
+        case 'tool.call':
+        case 'tool.result':
+        case 'tool.progress':
+        // Running command output (N4, wired in C2).
+        case 'tool.output':
+        case 'compaction.start':
+        case 'compaction.end':
+        case 'context.capacity':
+        case 'model.changed':
+        case 'effort.changed':
+        case 'mode.changed':
+        case 'todo.write':
+        case 'notice':
+        case 'rate-limit':
+        // Item types without a mapping reach the plugin renderer seam.
+        case 'custom':
+            return true;
+        // Emitted by the session's approval bridge (session/approvals.ts).
+        case 'permission.request':
+        case 'permission.settled':
+        case 'question.request':
+        case 'question.settled':
+            return true;
+        // No native source: task metadata patches, compaction summary progress,
+        // DSH presets/prompts/request headers, or direct agent-message receipts.
+        case 'task.update':
+        case 'compaction.progress':
+        case 'preset.selected':
+        case 'system.prompt':
+        case 'request.header':
+        case 'agent.message':
+            return false;
+        default: {
+            const unhandled = type;
+            return unhandled;
+        }
+    }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Codex thread items → Agent Domain events: the one mapping live
+ * notifications and history replay share (docs/codex-backend-design.md §7.1).
+ * `live.ts` calls {@link itemEvents} on `item/started` / `item/completed`
+ * and adds the stream deltas; `replay.ts` calls it with `started` then
+ * `completed` for every item of every recorded turn. Any mapping lives here
+ * once; `verify-codex-live-replay` keeps the two paths equal.
+ *
+ * Turns, steps and attempts (§7.2–§7.3):
+ *  - a turn opens with its first item (a user message → a user turn, a
+ *    `userShell` command → a user turn, anything else → a system turn) and
+ *    closes with `turn/completed` (live) / the end of the recorded turn;
+ *  - one model reply is one attempt (`<turnId>#<step>`) in its own step:
+ *    reasoning, message and plan items open it, a message or plan completing
+ *    settles it as one canonical `assistant.message`; a tool item settles a
+ *    reasoning-only attempt and joins the current step;
+ *  - a tool item still open when its turn closes was interrupted (an
+ *    interrupted item never completes and never reaches history, F11).
+ *
+ * Identity: `user.message.id` is the client id the channel submitted (the
+ * item id for another client's message); its `anchor` is the item id, the
+ * native fork/rewind anchor, and each anchor maps to its turn id.
+ */
+import type { AgentEvent, AgentEventOf, TurnEndReason, UsageDelta } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import { type ResultWords } from './presentation.js';
+/** The attempt (one model reply) being assembled. */
+export interface OpenAttempt {
+    readonly id: string;
+    readonly step: number;
+    reasoning: string;
+    text: string;
+    /** Reasoning streamed so far (a new summary part starts a paragraph). */
+    streamedReasoning: string;
+    /** Text streamed so far: what an interrupted reply settles with when its
+     *  item never completed. */
+    streamedText: string;
+    /** Items whose raw reasoning stream is shown (no summary was streamed). */
+    readonly rawReasoning: Set<string>;
+    /** Items whose summary streamed (their raw text stream stays hidden). */
+    readonly summarized: Set<string>;
+}
+/** A tool item that started and has not completed. */
+export interface OpenTool {
+    readonly name: string;
+    readonly startedAt: number;
+}
+export interface ItemContextOptions {
+    readonly cwd: string;
+    readonly now?: () => number;
+    readonly debug?: (message: string) => void;
+    /** Where the numbering continues (a live translator after a replay). */
+    readonly start?: {
+        readonly turn: number;
+        readonly seq: number;
+    };
+    readonly model?: string;
+}
+/** The translator state live and replay share (and hand over). */
+export interface ItemContext {
+    readonly cwd: string;
+    readonly debug: (message: string) => void;
+    now(): number;
+    nextSeq(): number;
+    readonly seq: number;
+    model: string;
+    turn: number;
+    turnOpen: boolean;
+    /** The native id of the open (or last) turn. */
+    turnId: string;
+    step: number;
+    stepOpen: boolean;
+    attempt: OpenAttempt | undefined;
+    readonly openTools: Map<string, OpenTool>;
+    /** User-message anchor → native turn id (fork / rewind). */
+    readonly anchorTurns: Map<string, string>;
+    /** A `/compact` this session asked for is running (manual trigger). */
+    compactRequested: boolean;
+    /** A compaction item ran in the open turn. */
+    compactionSeen: boolean;
+    /** Usage reported in the open turn (its `turn.end`). */
+    turnUsage: UsageDelta | undefined;
+    readonly words: ResultWords;
+}
+export declare function createItemContext(options: ItemContextOptions): ItemContext;
+/** Open a turn (no-op when one is open). */
+export declare function openTurn(ctx: ItemContext, out: AgentEvent[], origin: AgentEventOf<'turn.start'>['origin'], time: number, userMessageId?: string): void;
+export declare function closeStep(ctx: ItemContext, out: AgentEvent[]): void;
+/** A step for a tool that no reply opened (a turn's first item is a tool). */
+export declare function ensureStep(ctx: ItemContext, out: AgentEvent[]): void;
+/** The open attempt, or a new one in a new step. */
+export declare function ensureAttempt(ctx: ItemContext, out: AgentEvent[], firstTokenTime?: number): OpenAttempt;
+/** Settle the open attempt as one canonical assistant message. */
+export declare function settleAttempt(ctx: ItemContext, out: AgentEvent[], time: number, interrupted?: boolean): void;
+/**
+ * Close the open turn: settle the reply, end the still-open tools as
+ * interrupted, close the step, `turn.end`, then the failure's hint. A turn
+ * that produced no item opens first (a turn that failed at once).
+ */
+export declare function closeTurn(ctx: ItemContext, out: AgentEvent[], reason: TurnEndReason, time: number): void;
+/** Meter one model call without manufacturing or changing a message.
+ *
+ * `attribution` names the turn the WIRE notification carried: a straggler
+ * usage for an already-closed turn (arriving after a newer turn opened) is
+ * booked under ITS turn and never folded into the live turn's ledger. */
+export declare function reportUsage(ctx: ItemContext, out: AgentEvent[], usage: UsageDelta, time: number, attribution?: {
+    turn: number;
+    stale: boolean;
+}): void;
+/** One item's events for one phase (see the module comment). */
+export declare function itemEvents(item: Rec, phase: 'started' | 'completed', ctx: ItemContext, time: number): AgentEvent[];
+//# sourceMappingURL=items.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"items.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/translate/items.ts"],"names":[],"mappings":"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"}