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

package/lib/types/backends/codex/session/side-query.d.ts

@@ -0,0 +1,25 @@
+import { type RpcClock } from '../rpc/client.js';
+import type { CodexHub } from '../rpc/hub.js';
+import type { SettingsSnapshot } from '../translate/live.js';
+export declare function createCodexSideQuery(deps: {
+    readonly hub: CodexHub;
+    readonly settings: SettingsSnapshot;
+    readonly cwd: string;
+    readonly clock: RpcClock;
+    threadId(): string;
+    closed(): boolean;
+    debug(message: string): void;
+}): {
+    capability: {
+        ask(prompt: string, options?: {
+            readonly signal?: AbortSignal;
+            readonly onText?: (delta: string) => void;
+        }): Promise<{
+            readonly answer: string | null;
+            readonly error?: string;
+        }>;
+    };
+    reset: () => void;
+    close(): void;
+};
+//# sourceMappingURL=side-query.d.ts.map

package/lib/types/backends/codex/session/side-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-query.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/side-query.ts"],"names":[],"mappings":"AAMA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,eAAe,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,IAAI,MAAM,CAAC;IAAC,MAAM,IAAI,OAAO,CAAC;IAAC,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;;;2BA4F+3N,CAAC;2BAA8B,CAAC;;;0BAAsF,CAAC;;;iBAzF7rO,IAAI;aAuFsB,IAAI;EACrD"}

package/lib/types/backends/codex/session/side-query.js

@@ -0,0 +1,121 @@
+/** Ephemeral, read-only side answers; owned and cancelled with their session. */
+import { randomUUID } from 'node:crypto';
+import { t } from '../../../i18n.js';
+import { errorText, rec, str } from '../narrow.js';
+import { CLIENT, NOTIFY } from '../protocol/index.js';
+import { RPC_ERROR } from '../rpc/client.js';
+export function createCodexSideQuery(deps) {
+    const active = new Set();
+    let closed = false;
+    const cancelAll = () => { for (const controller of active)
+        controller.abort(); };
+    const capability = {
+        async ask(prompt, options = {}) {
+            if (options.signal?.aborted)
+                return { answer: null };
+            if (closed || deps.closed())
+                return { answer: null, error: t('codex-session-closed') };
+            const owner = new AbortController();
+            active.add(owner);
+            const signal = options.signal === undefined ? owner.signal : AbortSignal.any([owner.signal, options.signal]);
+            let childId;
+            let turnId;
+            let detach;
+            let timer;
+            let settled = false;
+            let streamed = '';
+            let answer = '';
+            let finish;
+            const result = new Promise(resolve => { finish = value => { if (!settled) {
+                settled = true;
+                resolve(value);
+            } }; });
+            const abort = () => {
+                if (childId !== undefined && turnId !== undefined)
+                    void deps.hub.call(CLIENT.turnInterrupt, { threadId: childId, turnId }).catch(() => undefined);
+                finish({ answer: null });
+            };
+            signal.addEventListener('abort', abort, { once: true });
+            const run = async () => {
+                try {
+                    // Keep a late fork response observable so its temporary thread can
+                    // be unsubscribed after cancellation; never start a turn on it.
+                    const response = rec(await deps.hub.call(CLIENT.threadFork, {
+                        threadId: deps.threadId(), ephemeral: true, excludeTurns: true, deferGoalContinuation: true,
+                        cwd: deps.cwd, model: deps.settings.model, approvalPolicy: 'never', sandbox: 'read-only',
+                        developerInstructions: 'Answer the side question using the existing conversation. Do not call tools, modify files, create goals, or start agents. Give one concise answer.',
+                    }));
+                    childId = str(rec(response?.thread)?.id);
+                    if (childId === undefined)
+                        throw new Error(t('codex-side-open-failed'));
+                    if (signal.aborted || closed || deps.closed())
+                        return { answer: null };
+                    const sink = {
+                        notification(method, params) {
+                            if (settled || signal.aborted || closed || deps.closed())
+                                return;
+                            if (method === NOTIFY.turnStarted)
+                                turnId = str(rec(params.turn)?.id);
+                            if (method === NOTIFY.agentMessageDelta) {
+                                const delta = str(params.delta) ?? '';
+                                streamed += delta;
+                                options.onText?.(delta);
+                            }
+                            if (method === NOTIFY.itemCompleted && rec(params.item)?.type === 'agentMessage') {
+                                answer = str(rec(params.item)?.text) ?? streamed;
+                                if (streamed === '' && answer !== '')
+                                    options.onText?.(answer);
+                            }
+                            if (method === NOTIFY.turnCompleted) {
+                                const turn = rec(params.turn);
+                                if (str(turn?.status) === 'failed')
+                                    finish({ answer: null, error: str(rec(turn?.error)?.message) ?? t('codex-turn-failed') });
+                                else if (str(turn?.status) === 'interrupted')
+                                    finish({ answer: null });
+                                else
+                                    finish({ answer: answer || streamed });
+                            }
+                        },
+                        serverRequest(request) { request.respondError(RPC_ERROR.methodNotFound, 'side queries do not accept tool or approval requests'); },
+                        connectionLost(error) { finish({ answer: null, error: errorText(error) }); },
+                        connectionRestored() { },
+                    };
+                    detach = deps.hub.attach(childId, sink);
+                    timer = deps.clock.setTimeout(abort, 120_000);
+                    const start = rec(await deps.hub.call(CLIENT.turnStart, {
+                        threadId: childId, clientUserMessageId: randomUUID(), input: [{ type: 'text', text: prompt, text_elements: [] }],
+                        approvalPolicy: 'never', sandboxPolicy: { type: 'readOnly', networkAccess: false },
+                        model: deps.settings.model, effort: deps.settings.effort,
+                        collaborationMode: { mode: 'default', settings: { model: deps.settings.model, reasoning_effort: deps.settings.effort, developer_instructions: 'Answer only; do not use tools or execute the plan.' } },
+                    }));
+                    turnId ??= str(rec(start?.turn)?.id);
+                    if (signal.aborted || closed || deps.closed())
+                        abort();
+                    return await result;
+                }
+                catch (error) {
+                    return signal.aborted ? { answer: null } : { answer: null, error: errorText(error) };
+                }
+                finally {
+                    if (timer !== undefined)
+                        deps.clock.clearTimeout(timer);
+                    signal.removeEventListener('abort', abort);
+                    detach?.();
+                    if (childId !== undefined) {
+                        try {
+                            await deps.hub.call(CLIENT.threadUnsubscribe, { threadId: childId }, { timeoutMs: 5000 });
+                        }
+                        catch (error) {
+                            deps.debug(`codex: side query unsubscribe failed (${errorText(error)})`);
+                        }
+                    }
+                    active.delete(owner);
+                }
+            };
+            const work = run();
+            void work.then(finish);
+            return Promise.race([work, result]);
+        },
+    };
+    return { capability, reset: cancelAll, close() { closed = true; cancelAll(); } };
+}

package/lib/types/backends/codex/session/state.d.ts

@@ -0,0 +1,57 @@
+/** Dependencies and start-up facts of one Codex session (a thread). */
+import type { OpenTarget } from '../../../agent/backend.js';
+import type { CodexAuthRuntime } from '../auth/external-tokens.js';
+import type { CodexChannelsRuntime } from '../channels.js';
+import type { Rec } from '../narrow.js';
+import type { CodexModeId } from '../modes.js';
+import type { CodexPrefs } from '../prefs.js';
+import type { RpcClock } from '../rpc/client.js';
+import type { CodexExecutable } from '../rpc/binary.js';
+import type { CodexHub } from '../rpc/hub.js';
+export interface CodexSessionDeps {
+    /** The shared connection (already retained for this session). */
+    readonly hub: CodexHub;
+    /** Give the session's retain back (the last one starts the idle close). */
+    readonly release: () => void;
+    readonly target: OpenTarget;
+    /** Where a created thread runs (a resumed one keeps its own). */
+    readonly cwd: string;
+    readonly prefs: CodexPrefs;
+    readonly config?: Rec;
+    readonly auth?: CodexAuthRuntime;
+    readonly channels?: CodexChannelsRuntime;
+    readonly executable: CodexExecutable & {
+        readonly version?: string;
+    };
+    readonly host: {
+        debug(message: string): void;
+    };
+    /** Notices to show once the channel subscribes (start-time findings). */
+    readonly startNotices?: readonly string[];
+    /** Facts `/doctor` reports beside the session's own. */
+    readonly doctor?: {
+        readonly bubblewrapMissing?: boolean;
+    };
+    readonly clock?: RpcClock;
+    /** Wall clock for event times (fixtures inject one). */
+    readonly now?: () => number;
+    /** How long an interrupt may go unanswered before the turn is closed here. */
+    readonly forceSettleMs?: number;
+}
+/** The thread settings a session opened with (from the start/resume answer). */
+export interface OpenedThread {
+    readonly threadId: string;
+    readonly cwd: string;
+    readonly model: string;
+    readonly provider: string;
+    readonly effort: string | null;
+    readonly modeId: CodexModeId | 'custom' | 'plan';
+    readonly permissionMode: CodexModeId | 'custom';
+    readonly approvalPolicy?: unknown;
+    readonly sandboxPolicy?: unknown;
+    readonly collaborationMode?: Rec;
+    readonly title?: string;
+    /** `active` when a resumed thread is mid-turn. */
+    readonly running: boolean;
+}
+//# sourceMappingURL=state.d.ts.map

package/lib/types/backends/codex/session/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/state.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAA;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpE,QAAQ,CAAC,IAAI,EAAE;QACb,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAC7B,CAAA;IACD,yEAAyE;IACzE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;IACzB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAA;IAChD,QAAQ,CAAC,cAAc,EAAE,WAAW,GAAG,QAAQ,CAAA;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,GAAG,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B"}

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

@@ -0,0 +1 @@
+export {};

package/lib/types/backends/codex/session/subagents.d.ts

@@ -0,0 +1,28 @@
+/** Parent-owned Codex subagents: independent translators and bounded history pages. */
+import type { SubagentTranscriptPage, SubagentTranscriptWindow } from '../../../agent/capabilities.js';
+import type { AgentEvent, AgentEventMeta } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import { type CodexHub } from '../rpc/hub.js';
+export declare function createCodexSubagents(deps: {
+    readonly hub: Pick<CodexHub, 'call'>;
+    readonly cwd: string;
+    threadId(): string;
+    /** One monotonic sequence shared with the parent's ItemContext. */
+    nextSeq(): number;
+    emit(events: readonly AgentEvent[], wake?: AgentEventMeta['wake']): void;
+    readonly now?: () => number;
+    debug?(message: string): void;
+}): {
+    capability: {
+        interrupt(agentId: string): Promise<boolean>;
+        history?(agentId: string, window?: SubagentTranscriptWindow): Promise<SubagentTranscriptPage>;
+        messaging?: "parent-mediated";
+        readonly messagingTool?: string;
+    };
+    decorate: (events: readonly AgentEvent[]) => AgentEvent[];
+    seed(events: readonly AgentEvent[]): void;
+    notification(method: string, params: Rec): boolean;
+    reset(): void;
+    close(): void;
+};
+//# sourceMappingURL=subagents.d.ts.map

package/lib/types/backends/codex/session/subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/subagents.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,KAAK,EAAuB,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAA;AAC3H,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAgB,MAAM,0BAA0B,CAAA;AAExF,OAAO,EAAsB,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAE3D,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAA;AA+BvD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,IAAI,MAAM,CAAA;IAClB,mEAAmE;IACnE,OAAO,IAAI,MAAM,CAAA;IACjB,IAAI,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;IACxE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;;;;;;;uBAiMsB,SAAS,UAAU,EAAE;iBAC3B,SAAS,UAAU,EAAE,GAAG,IAAI;yBACpB,MAAM,UAAU,GAAG,GAAG,OAAO;aAgBzC,IAAI;aACJ,IAAI;EAEhB"}

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

@@ -0,0 +1,286 @@
+import { t } from '../../../i18n.js';
+import { arr, num, rec, str } from '../narrow.js';
+import { CLIENT, NOTIFY } from '../protocol/index.js';
+import { threadOf } from '../rpc/hub.js';
+import { createItemContext } from '../translate/items.js';
+import { createLiveTranslator, wakeOf } from '../translate/live.js';
+import { replayTurns } from '../translate/replay.js';
+const MAX_CHILDREN = 200;
+const MAX_HELD = 128;
+const HISTORY_TURNS = 20;
+const LEAVES = new Set(['assistant.attempt.start', 'assistant.delta', 'assistant.message', 'tool.call', 'tool.result', 'tool.progress', 'tool.output']);
+/** Only the child's transcript leaves enter its lane; its own turn/context
+ * events never reach the foreground reducer. Sequence is the parent's stream. */
+function leaf(event, lane, agentId, nextSeq) {
+    switch (event.type) {
+        case 'assistant.attempt.start':
+        case 'assistant.delta':
+        case 'assistant.message':
+            return { ...event, attemptId: agentId + ':' + event.attemptId, parentCallId: lane, ...('seq' in event && event.seq !== undefined ? { seq: nextSeq() } : {}) };
+        case 'tool.call':
+        case 'tool.result':
+            return { ...event, seq: nextSeq(), parentCallId: lane };
+        case 'tool.progress':
+        case 'tool.output':
+            return { ...event, parentCallId: lane };
+        default:
+            return undefined;
+    }
+}
+export function createCodexSubagents(deps) {
+    const now = deps.now ?? Date.now;
+    const children = new Map();
+    const held = new Map();
+    const loading = new Map();
+    let generation = 0;
+    let closed = false;
+    const current = (root, epoch) => !closed && epoch === generation && root === deps.threadId();
+    const remember = (id, lane, parent, description, depth) => {
+        const existing = children.get(id);
+        if (existing !== undefined)
+            return existing;
+        const child = { id, lane, parent, description, depth, ended: false,
+            live: createLiveTranslator(createItemContext({ cwd: deps.cwd, now, debug: deps.debug }), { model: '', effort: null, modeId: 'auto' }) };
+        children.set(id, child);
+        if (children.size > MAX_CHILDREN) {
+            const stale = [...children.values()].find(entry => entry.ended);
+            if (stale !== undefined)
+                children.delete(stale.id);
+        }
+        return child;
+    };
+    const startEvent = (child, time = now()) => ({
+        type: 'subagent.start', agentId: child.id, parentCallId: child.lane, parentAgentId: child.parent,
+        description: child.prompt === undefined ? child.nickname ?? child.description : child.nickname === undefined ? child.prompt : child.nickname + ': ' + child.prompt,
+        ...(child.model === undefined ? {} : { model: child.model }),
+        background: false, depth: child.depth, time,
+    });
+    const decorate = (events, parent = deps.threadId()) => events.map(event => {
+        if (event.type === 'subagent.start') {
+            const child = remember(event.agentId, event.parentCallId ?? event.agentId, parent, event.description, event.depth ?? 1);
+            child.ended = false;
+            return { ...event, ...startEvent(child, event.time) };
+        }
+        if (event.type === 'subagent.end') {
+            const child = children.get(event.agentId);
+            if (child !== undefined)
+                child.ended = true;
+            return child?.summary === undefined ? event : { ...event, summary: child.summary };
+        }
+        return event;
+    });
+    /** Validate lineage from the authoritative thread metadata (no history scan). */
+    const ownership = async (id) => {
+        const root = deps.threadId();
+        const epoch = generation;
+        let next = id;
+        let direct;
+        let first;
+        for (let depth = 1; depth <= 8; depth += 1) {
+            const response = rec(await deps.hub.call(CLIENT.threadRead, { threadId: next, includeTurns: false }));
+            const thread = rec(response?.thread);
+            const spawn = rec(rec(rec(thread?.source)?.subAgent)?.thread_spawn);
+            const parent = str(thread?.parentThreadId) ?? str(spawn?.parent_thread_id);
+            if (!current(root, epoch) || thread === undefined || str(thread.id) !== next || parent === undefined || parent === next)
+                throw new Error(t('codex-subagent-unavailable'));
+            if (first === undefined) {
+                first = thread;
+                direct = parent;
+            }
+            if (parent === root)
+                return { parent: direct, depth, thread: first };
+            next = parent;
+        }
+        throw new Error(t('codex-subagent-unavailable'));
+    };
+    /** Spawn items report a requested model/prompt, not execution telemetry. */
+    const noteSpawn = (method, params, parent) => {
+        if (method !== NOTIFY.itemStarted && method !== NOTIFY.itemCompleted)
+            return;
+        const item = rec(params.item);
+        if (item?.type !== 'collabAgentToolCall' || item.tool !== 'spawnAgent')
+            return;
+        const receivers = arr(item.receiverThreadIds).filter((id) => typeof id === 'string');
+        for (const id of receivers) {
+            const known = children.get(id);
+            const child = remember(id, known?.lane ?? (receivers.length === 1 ? str(item.id) ?? id : id), parent, known?.description ?? id, (children.get(parent)?.depth ?? 0) + 1);
+            const before = startEvent(child).description;
+            const beforeModel = child.model;
+            const prompt = str(item.prompt);
+            if (prompt !== undefined)
+                child.prompt = prompt.slice(0, 16 * 1024);
+            child.model = str(item.model) ?? child.model;
+            if (!child.ended && (known === undefined || before !== startEvent(child).description || beforeModel !== child.model))
+                deps.emit([startEvent(child)]);
+            const spawnId = str(item.id) ?? id;
+            if (child.spawnId === spawnId)
+                continue;
+            child.spawnId = spawnId;
+            const root = deps.threadId();
+            const epoch = generation;
+            void ownership(id).then(owned => {
+                if (!current(root, epoch) || children.get(id) !== child)
+                    return;
+                const before = startEvent(child).description;
+                const beforeModel = child.model;
+                child.nickname = str(owned.thread.agentNickname) ?? child.nickname;
+                child.model ??= str(owned.thread.model);
+                child.parent = owned.parent;
+                child.depth = owned.depth;
+                if (!child.ended && (before !== startEvent(child).description || beforeModel !== child.model))
+                    deps.emit([startEvent(child)]);
+            }).catch(error => { if (current(root, epoch))
+                deps.debug?.('codex: spawn metadata unavailable (' + (error instanceof Error ? error.message : String(error)) + ')'); });
+        }
+    };
+    const discover = (id) => {
+        const pending = loading.get(id);
+        if (pending !== undefined)
+            return pending;
+        const root = deps.threadId();
+        const epoch = generation;
+        const request = (async () => {
+            try {
+                const owned = await ownership(id);
+                if (!current(root, epoch))
+                    return undefined;
+                let child = children.get(id);
+                if (child === undefined) {
+                    // A child can speak before its activity notification. The parent's
+                    // latest page may already contain its durable spawn anchor.
+                    const response = rec(await deps.hub.call(CLIENT.threadTurnsList, { threadId: owned.parent, limit: HISTORY_TURNS, sortDirection: 'desc', itemsView: 'full' }));
+                    const activity = arr(response?.data).flatMap(turn => arr(rec(turn)?.items)).map(rec)
+                        .find(item => item?.type === 'subAgentActivity' && item.kind === 'started' && item.agentThreadId === id);
+                    if (!current(root, epoch))
+                        return undefined;
+                    const path = (str(activity?.agentPath) ?? '').split('/').filter(Boolean);
+                    child = remember(id, str(activity?.id) ?? id, owned.parent, str(owned.thread.agentNickname) ?? path.at(-1) ?? id, owned.depth);
+                    child.nickname = str(owned.thread.agentNickname);
+                    child.model = str(owned.thread.model);
+                    deps.emit([startEvent(child)]);
+                }
+                for (const traffic of held.get(id) ?? [])
+                    deliver(child, traffic.method, traffic.params);
+                held.delete(id);
+                return child;
+            }
+            catch (error) {
+                held.delete(id);
+                if (current(root, epoch))
+                    deps.debug?.('codex: child metadata unavailable (' + (error instanceof Error ? error.message : String(error)) + ')');
+                return undefined;
+            }
+        })();
+        loading.set(id, request);
+        void request.finally(() => { if (loading.get(id) === request)
+            loading.delete(id); });
+        return request;
+    };
+    const deliver = (child, method, params) => {
+        noteSpawn(method, params, child.id);
+        if (method === NOTIFY.turnStarted)
+            child.activeTurn = str(rec(params.turn)?.id);
+        if (method === NOTIFY.turnCompleted)
+            child.activeTurn = undefined;
+        const item = rec(params.item);
+        if (method === NOTIFY.itemCompleted && item?.type === 'agentMessage' && item.phase === 'final_answer')
+            child.summary = (str(item.text) ?? '').slice(0, 16 * 1024);
+        const batch = [];
+        for (const event of decorate(child.live.notification(method, params), child.id)) {
+            const mapped = leaf(event, child.lane, child.id, deps.nextSeq);
+            if (mapped !== undefined)
+                batch.push(mapped);
+            else if (event.type === 'subagent.start' || event.type === 'subagent.progress' || event.type === 'subagent.end')
+                batch.push(event);
+        }
+        if (method === NOTIFY.threadTokenUsageUpdated) {
+            const usage = rec(rec(params.tokenUsage)?.total);
+            if (usage !== undefined)
+                batch.push({ type: 'subagent.progress', agentId: child.id, usage: {
+                        ...(num(usage.inputTokens) === undefined ? {} : { input: num(usage.inputTokens) }),
+                        ...(num(usage.outputTokens) === undefined ? {} : { output: num(usage.outputTokens) }),
+                        ...(num(usage.totalTokens) === undefined ? {} : { total: num(usage.totalTokens) }),
+                    } });
+        }
+        if (batch.length > 0)
+            deps.emit(batch, wakeOf(method, batch));
+    };
+    const capability = {
+        messaging: 'parent-mediated', messagingTool: 'send_input',
+        async interrupt(id) {
+            if (closed || !children.has(id))
+                return false;
+            const root = deps.threadId();
+            const epoch = generation;
+            await ownership(id);
+            const child = children.get(id);
+            let turnId = child.activeTurn;
+            if (turnId === undefined) {
+                const response = rec(await deps.hub.call(CLIENT.threadTurnsList, { threadId: id, limit: 1, sortDirection: 'desc', itemsView: 'summary' }));
+                const active = arr(response?.data).map(rec).find(turn => turn?.status === 'inProgress');
+                turnId = str(active?.id);
+            }
+            if (!current(root, epoch) || turnId === undefined)
+                return false;
+            await deps.hub.call(CLIENT.turnInterrupt, { threadId: id, turnId });
+            return current(root, epoch);
+        },
+        async history(id, window) {
+            if (closed || !children.has(id))
+                throw new Error(t('codex-subagent-unavailable'));
+            const root = deps.threadId();
+            const epoch = generation;
+            const owned = await ownership(id);
+            const response = rec(await deps.hub.call(CLIENT.threadTurnsList, { threadId: id, limit: HISTORY_TURNS, sortDirection: 'desc', itemsView: 'full', ...(window?.sourceCursor === undefined ? {} : { cursor: window.sourceCursor }) }));
+            if (!current(root, epoch))
+                throw new Error(t('codex-subagent-unavailable'));
+            const turns = [...arr(response?.data)].reverse();
+            const context = createItemContext({ cwd: str(owned.thread.cwd) ?? deps.cwd, now });
+            const child = children.get(id);
+            let seq = 0;
+            const events = replayTurns(turns, context).flatMap(event => {
+                // History is a leaf-only page: it cannot mutate the parent's state,
+                // nor create another agent roster while a detail page is opened.
+                if (!LEAVES.has(event.type))
+                    return [];
+                const mapped = leaf(event, child.lane, id, () => ++seq);
+                return mapped === undefined ? [] : [mapped];
+            });
+            const sourceCursor = str(response?.nextCursor);
+            return { events, parentAgentId: owned.parent === root ? null : owned.parent,
+                uuids: turns.flatMap(turn => arr(rec(turn)?.items).map(item => str(rec(item)?.id)).filter((id) => id !== undefined)),
+                hasOlder: sourceCursor !== undefined, skippedFromStart: 0, ...(sourceCursor === undefined ? {} : { sourceCursor }) };
+        },
+    };
+    return {
+        capability,
+        decorate: (events) => decorate(events),
+        seed(events) { decorate(events); },
+        notification(method, params) {
+            if (closed)
+                return false;
+            const from = threadOf(params);
+            if (from === undefined)
+                return false;
+            if (from === deps.threadId()) {
+                noteSpawn(method, params, from);
+                return false;
+            }
+            const child = children.get(from);
+            if (child !== undefined)
+                deliver(child, method, params);
+            else {
+                if (!held.has(from) && held.size >= MAX_CHILDREN)
+                    return true;
+                const buffer = held.get(from) ?? [];
+                if (buffer.length < MAX_HELD)
+                    buffer.push({ method, params });
+                held.set(from, buffer);
+                void discover(from);
+            }
+            return true;
+        },
+        reset() { generation += 1; children.clear(); held.clear(); loading.clear(); },
+        close() { closed = true; generation += 1; children.clear(); held.clear(); loading.clear(); },
+    };
+}

package/lib/types/backends/codex/session/tasks.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEvent } from '../../../agent/events.js';
+import { type Rec } from '../narrow.js';
+import { type RpcClock } from '../rpc/client.js';
+import type { CodexHub } from '../rpc/hub.js';
+export declare const CODEX_TASK_POLL_MS = 2000;
+export declare const CODEX_TASK_OUTPUT_BYTES: number;
+export declare function createCodexTasks(deps: {
+    readonly hub: Pick<CodexHub, 'call'>;
+    threadId(): string;
+    emit(events: readonly AgentEvent[]): void;
+    readonly now?: () => number;
+    readonly clock?: RpcClock;
+    debug?(message: string): void;
+}): {
+    readonly capability: {
+        stop(taskId: string): Promise<boolean>;
+        readOutput?(taskId: string): Promise<string>;
+    } | undefined;
+    initialize: () => Promise<void>;
+    refresh: () => Promise<void>;
+    notification(method: string, params: Rec): boolean;
+    reset(): void;
+    close(): void;
+};
+//# sourceMappingURL=tasks.d.ts.map

package/lib/types/backends/codex/session/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../../../../src/backends/codex/session/tasks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,OAAO,EAA4B,KAAK,GAAG,EAAE,MAAM,cAAc,CAAA;AAEjE,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,eAAO,MAAM,kBAAkB,OAAO,CAAA;AACtC,eAAO,MAAM,uBAAuB,QAAY,CAAA;AAWhD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACpC,QAAQ,IAAI,MAAM,CAAA;IAClB,IAAI,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAAA;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;IACzB,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;;;;;sBA6CqB,OAAO,CAAC,IAAI,CAAC;mBAAb,OAAO,CAAC,IAAI,CAAC;yBA8EV,MAAM,UAAU,GAAG,GAAG,OAAO;aAwBzC,IAAI;aACJ,IAAI;EAEhB"}