@khorsheed/dsh-local-agent-codex 0.2.0-rc.3 → 0.2.0

package/lib/types/client/icons.d.ts

@@ -1,6 +1,6 @@
 /**
  * Generated by scripts/sync-icon-artwork.mts from @deepseek-ai/dsh-client-ui-primitives
- * (v0.1.7-rc.1, harness 46a7f68b09) — do not edit by hand. The 0.1.5 and rc.1 host lines
+ * (v0.2.1-rc.1, harness 1600d8a1e1) — do not edit by hand. The 0.1.5 and rc.1 host lines
  * share no icon export name, so the rc.1 artwork is inlined here: pure SVG,
  * no host runtime identity, identical on every line. Re-run the generator
  * after adding an icon import or bumping the harness checkout.

package/lib/types/codex-cli-provider.d.ts

@@ -13,7 +13,7 @@
  * it too (a deliberate user re-enable conflicts loud, by design).
  * @module @khorsheed/dsh-local-agent-codex/codex-cli-provider
  */
-import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, ReasoningEffortId, TokenUsage } from '@deepseek-ai/dsh-llm';
 import { type ResolvedSubagentStartRequest, type SubagentCapabilities, type SubagentProvider, type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
@@ -21,6 +21,14 @@ import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-sub
 import type { DelegationExecTarget, LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
 import type { CodexLiveDriver } from './live-driver.ts';
 import { type CodexEndpointAuth } from './endpoint-auth.ts';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a killed run, or a result-less item type like web_search_call). The
+ * released-log contract resolves every advertised call before its step
+ * closes, so an interrupted call folds with this error result. Same text as
+ * the kimi provider's placeholder, for family consistency.
+ */
+export declare const CODEX_INTERRUPTED_TOOL_RESULT = "\uFF08\u5DE5\u5177\u8C03\u7528\u88AB\u4E2D\u65AD\uFF0C\u672A\u80FD\u8BB0\u5F55\u8FD4\u56DE\u7ED3\u679C\uFF09";
 /** Default POSIX grace between subprocess termination tiers. */
 export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
 /**
@@ -308,7 +316,8 @@ export declare class CodexStreamParser implements CodexStreamFoldState {
  * not put one on the wire; the settle path then reads the rollout's
  * turn_context). Item types covered: `reasoning` (thinking), `agent_message`
  * (reply text), `command_execution` (shell command with aggregated output),
- * `web_search_call`, and `function_call_output`. The last `agent_message`
+ * `web_search_call`, `custom_tool_call`/`custom_tool_call_output` (deferred
+ * and dynamic tools), and `function_call_output`. The last `agent_message`
  * wins as the run output (the final answer), and `turn.completed` carries the
  * turn's usage. Malformed lines are skipped.
  * @param stream - the collected stdout NDJSON text.
@@ -336,6 +345,17 @@ export declare function parseCodexJsonStream(stream: string): {
  * @returns the published run after the child starts.
  */
 export declare function startCodexCliRun(request: SubagentStartRequest, spec: CodexCliRunSpec): Promise<SubagentRun>;
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export declare function appendCodexRequestHeader(childSession: Session, config: {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+}): void;
 /** One assistant-role message event, attributed to the codex route. */
 export declare function codexAssistantEvent(blocks: readonly ContentBlock[]): import("@deepseek-ai/dsh-llm").AssistantMessage;
 /**
@@ -344,8 +364,17 @@ export declare function codexAssistantEvent(blocks: readonly ContentBlock[]): im
  * assembler requires: without a boundary the step never enters the location
  * index, the line's assistant message resolves to a turn-level location, and
  * the real-time view renders nothing (only a full rebuild, which mints step
- * drafts from the explicit coordinates, recovers it). Tool cards escape that
- * fate only because their definition does not consult the step location.
+ * drafts from the explicit coordinates, recovers it).
+ *
+ * A tool line folds the NATIVE lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, then its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes.
+ * Every fold sees a COMPLETED item (the exec live mirror holds the volatile
+ * last line; the live driver folds at item/completed), so a result the
+ * stream has not recorded by fold time will never arrive — the call folds
+ * with the synthesized interrupted result instead of leaving the step
+ * unresolvable.
  * @returns whether the line folded (false when the options skipped it).
  */
 export declare function appendCodexTranscriptLine(childSession: Session, turn: number, step: number, line: CodexTranscriptLine, usage: TokenUsage | undefined): boolean;

package/lib/types/codex-cli-provider.js

@@ -23,6 +23,14 @@ import { LiveChannelUnavailableError } from './live-driver.js';
 import { endpointAuthEnv, endpointConfigOverrides, hasEndpointCredential } from './endpoint-auth.js';
 import { readCodexBaseUrl } from './provision.js';
 import { codexRolloutRoundFacts, usageFromCodex } from './records.js';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a killed run, or a result-less item type like web_search_call). The
+ * released-log contract resolves every advertised call before its step
+ * closes, so an interrupted call folds with this error result. Same text as
+ * the kimi provider's placeholder, for family consistency.
+ */
+export const CODEX_INTERRUPTED_TOOL_RESULT = '（工具调用被中断，未能记录返回结果）';
 /** Quote one TOML basic string for the `-c` config override. */
 function tomlString(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -50,7 +58,10 @@ export function registerCodexMemberRun(ctx, childSessionId, parentSessionId) {
         + `command=${tomlString(bridge.command)},`
         + `args=[${bridge.args.map(tomlString).join(',')}],`
         + `env={${MEMBER_BRIDGE_SOCKET_ENV}=${tomlString(registry.memberBridgeSocketPath())},${MEMBER_BRIDGE_TOKEN_ENV}=${tomlString(token)}},`
-        + `default_tools_approval_mode=${tomlString('approve')}`
+        + `default_tools_approval_mode=${tomlString('approve')},`
+        // A bridge call may wait for the human (ask_user_question, a mode tool's
+        // approval): Codex's 60s MCP default would fail it first.
+        + `tool_timeout_sec=1800`
         + `}`;
     let released = false;
     return {
@@ -651,6 +662,40 @@ function foldCodexStreamLine(state, raw) {
             }
         }
     }
+    else if (item.type === 'custom_tool_call') {
+        // Custom tools (the deferred `exec` discovery tool, dynamic tools): the
+        // call rides `input`, its result the paired custom_tool_call_output.
+        // Without this branch a tool-loop round mirrored as two bare adjacent
+        // replies with the call between them invisible.
+        countToolCall(state, 'custom_tool_call');
+        state.lines.push({
+            kind: 'tool',
+            id: typeof item.id === 'string' ? item.id : `codex-tool-${state.lines.length}`,
+            name: item.name ?? 'custom',
+            ...typeof item.input === 'string' && item.input !== '' ? { args: item.input } : {},
+        });
+    }
+    else if (item.type === 'custom_tool_call_output') {
+        // {call_id, output: string | content blocks} — pair by recency, the same
+        // idiom function_call_output uses (the stream orders a result right
+        // behind its call).
+        const output = typeof item.output === 'string' ? item.output
+            : Array.isArray(item.output)
+                ? item.output
+                    .filter((block) => typeof block === 'object' && block !== null && typeof block.text === 'string')
+                    .map(block => block.text)
+                    .join('\n')
+                : undefined;
+        if (output !== undefined && output.trim() !== '') {
+            const last = state.lines[state.lines.length - 1];
+            if (last !== undefined && last.kind === 'tool') {
+                state.lines[state.lines.length - 1] = {
+                    ...last,
+                    result: last.result === undefined ? output : `${last.result}\n${output}`,
+                };
+            }
+        }
+    }
 }
 /**
  * Incremental `codex exec --json` parser: feed stdout chunks as they arrive
@@ -685,7 +730,8 @@ export class CodexStreamParser {
  * not put one on the wire; the settle path then reads the rollout's
  * turn_context). Item types covered: `reasoning` (thinking), `agent_message`
  * (reply text), `command_execution` (shell command with aggregated output),
- * `web_search_call`, and `function_call_output`. The last `agent_message`
+ * `web_search_call`, `custom_tool_call`/`custom_tool_call_output` (deferred
+ * and dynamic tools), and `function_call_output`. The last `agent_message`
  * wins as the run output (the final answer), and `turn.completed` carries the
  * turn's usage. Malformed lines are skipped.
  * @param stream - the collected stdout NDJSON text.
@@ -772,6 +818,17 @@ export function startCodexCliRun(request, spec) {
     // The turn opens at the real spawn moment so the timing projection
     // measures actual CLI runtime, not the post-hoc append time.
     spec.childSession?.append('turn/start', { turn });
+    // The provider's own launch facts are the child log's request config —
+    // codex's stream never carries model/effort, so the argv the provider
+    // spawns with is the authoritative source. The header contract requires a
+    // model: an unconfigured round records nothing rather than inventing one.
+    if (spec.model !== undefined && spec.childSession !== undefined) {
+        appendCodexRequestHeader(spec.childSession, {
+            provider: 'codex-local',
+            model: spec.model,
+            ...spec.effort === undefined ? {} : { reasoningEffort: spec.effort },
+        });
+    }
     // Live mirror: fold the NDJSON stream as chunks arrive so the child session
     // shows the run's progress before settle; the settle mirror below resumes
     // from the live counters and stays a no-op when live mirroring kept up.
@@ -896,29 +953,12 @@ export function startCodexCliRun(request, spec) {
         signal: request.signal,
         onAbort,
     }).then((settled) => {
-        // Every terminal path closes the turn so the timing window never stays
-        // open on a failed or cancelled run: success settles 'completed', a
-        // non-zero exit 'error', and a locally cancelled run 'aborted'. The
-        // turn/end timestamp is the real settle moment.
         // A completed round proves the scoped credential is live — the endpoint
         // answered. Reported here rather than from the mirror so it lands whether
-        // or not the round is session-backed.
+        // or not the round is session-backed. The turn boundary itself is the
+        // post-exit chain's job (it must follow the settle mirror).
         if (settled.stopReason === 'completed')
             spec.onAuthSuccess?.();
-        if (spec.childSession !== undefined) {
-            if (settled.stopReason === 'completed') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
-            }
-            else if (settled.stopReason === 'aborted') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
-            }
-            else {
-                spec.childSession.append('turn/end', {
-                    turn,
-                    reason: { kind: 'error', error: { message: `codex exec exited with code ${String(exitCode)}`, code: 'UNKNOWN' } },
-                });
-            }
-        }
         return settled;
     });
     // After the child EXITS — however it ended (completed, killed by dispose, or
@@ -926,9 +966,13 @@ export function startCodexCliRun(request, spec) {
     // subagent session, so a cancelled round still preserves its partial work
     // (reasoning, commands, replies) and real token usage. The thread id is
     // recorded even on abort so the partial thread stays resumable. Waits for
-    // the settle chain first (so turn/end is already appended) AND for the
-    // process to actually exit (so stdout is drained before parsing).
-    void result.then(() => child.done).then(() => {
+    // the settle chain first AND for the process to actually exit (so stdout is
+    // drained before parsing). The turn closes AFTER the settle mirror, still
+    // serialized behind the live mirror's queue: every mirrored step must land
+    // before turn/end — the released-log reader rejects a step outside an open
+    // turn on every cold read. The run's result still settles at the real
+    // moment (abort latency unchanged); only the boundary event moves.
+    void result.then(() => child.done).then(async () => {
         if (spec.onAuthFailure !== undefined) {
             // The seam's collected buffers are complete at process exit; the
             // streamed variables can lag `done` by a tick.
@@ -939,7 +983,30 @@ export function startCodexCliRun(request, spec) {
                 spec.onAuthFailure(authDetail.split('\n').find(line => line.trim() !== '') ?? 'auth failure');
             }
         }
-        return mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
+        await mirrorCodexAfterExit(spec, task, turn, output, liveMirror, startedAtMs);
+        // Every terminal path closes the turn so the timing window never stays
+        // open on a failed or cancelled run: success settles 'completed', a
+        // non-zero exit 'error', and a locally cancelled run 'aborted'.
+        if (spec.childSession !== undefined) {
+            const settled = await result;
+            if (settled.stopReason === 'completed') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+            }
+            else if (settled.stopReason === 'aborted') {
+                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+            }
+            else {
+                spec.childSession.append('turn/end', {
+                    turn,
+                    reason: { kind: 'error', error: { message: `codex exec exited with code ${String(exitCode)}`, code: 'UNKNOWN' } },
+                });
+            }
+            if (spec.ctx !== undefined) {
+                await persistChildSession(spec.ctx, spec.childSession).catch((error) => {
+                    spec.ctx?.logger.warn(`subagent-codex: turn/end persistence failed: ${thrown(error).message}`);
+                });
+            }
+        }
     }, () => { });
     return Promise.resolve(subprocessRunHandle({
         // Host 0.2.1: the published run id is a fresh PER-EXECUTION identity —
@@ -955,6 +1022,27 @@ export function startCodexCliRun(request, spec) {
         teardown: disposeProcess,
     }));
 }
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export function appendCodexRequestHeader(childSession, config) {
+    const serialized = JSON.stringify(config);
+    let last;
+    for (const event of childSession.snapshotEvents()) {
+        if (event.type === 'request/header') {
+            last = JSON.stringify(event.data.header?.config);
+        }
+    }
+    if (last === serialized)
+        return;
+    childSession.append('request/header', {
+        header: { config },
+        reason: last === undefined ? 'initial' : 'change',
+    });
+}
 /** One assistant-role message event, attributed to the codex route. */
 export function codexAssistantEvent(blocks) {
     return createAssistantMessage({
@@ -968,35 +1056,48 @@ export function codexAssistantEvent(blocks) {
  * assembler requires: without a boundary the step never enters the location
  * index, the line's assistant message resolves to a turn-level location, and
  * the real-time view renders nothing (only a full rebuild, which mints step
- * drafts from the explicit coordinates, recovers it). Tool cards escape that
- * fate only because their definition does not consult the step location.
+ * drafts from the explicit coordinates, recovers it).
+ *
+ * A tool line folds the NATIVE lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, then its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes.
+ * Every fold sees a COMPLETED item (the exec live mirror holds the volatile
+ * last line; the live driver folds at item/completed), so a result the
+ * stream has not recorded by fold time will never arrive — the call folds
+ * with the synthesized interrupted result instead of leaving the step
+ * unresolvable.
  * @returns whether the line folded (false when the options skipped it).
  */
 export function appendCodexTranscriptLine(childSession, turn, step, line, usage) {
     childSession.append('step/start', { turn, step });
     if (line.kind === 'tool') {
-        // Native tool card: the call event now, the result event when the stream
-        // already carries it. Tool lines never carry the round's usage — the
-        // callers attach usage to the round's final line, which is an agent
-        // message on every well-formed stream.
+        // A tool-only call's usage rides the advertising assistant/message (the
+        // tool/call and tool/result events themselves have no usage slot).
+        const args = line.args ?? '';
+        childSession.append('assistant/message', {
+            turn,
+            step,
+            message: codexAssistantEvent([{ type: 'tool-call', id: line.id, name: line.name, arguments: args }]),
+            stream: [],
+            ...usage === undefined ? {} : { usage },
+        }, { surfaceOp: 'append' });
         const call = childSession.append('tool/call', {
             turn,
             step,
             callId: line.id,
             name: line.name,
-            arguments: line.args ?? '',
+            arguments: args,
         });
-        if (line.result !== undefined) {
-            childSession.append('tool/result', {
-                turn,
-                step,
-                message: createToolResultMessage({
-                    callId: line.id,
-                    content: [{ type: 'text', text: line.result }],
-                    isError: false,
-                }),
-            }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
-        }
+        childSession.append('tool/result', {
+            turn,
+            step,
+            message: createToolResultMessage({
+                callId: line.id,
+                content: [{ type: 'text', text: line.result ?? CODEX_INTERRUPTED_TOOL_RESULT }],
+                isError: line.result === undefined,
+            }),
+        }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
         childSession.append('step/end', { turn, step });
         return true;
     }

package/lib/types/live-driver.d.ts

@@ -42,11 +42,6 @@ export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
 export declare const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 50;
 /** Default minimum text growth between one streaming item's snapshot messages. */
 export declare const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The app-server channel could not come up (spawn failure or handshake
- * timeout/mismatch). The provider catches exactly this and falls back to the
- * exec one-shot; any other error is a real round failure.
- */
 export declare class LiveChannelUnavailableError extends Error {
     constructor(message: string);
 }