@co0ontty/wand 1.20.4 → 1.21.5

package/dist/structured-session-manager.js

@@ -1,7 +1,25 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { prepareSessionWorktree } from "./git-worktree.js";
+import { truncateMessagesForTransport } from "./message-truncator.js";
+function defaultStructuredRunner(provider) {
+    return provider === "codex" ? "codex-cli-exec" : "claude-cli-print";
+}
+function defaultStructuredState(provider, runner = defaultStructuredRunner(provider)) {
+    return {
+        provider,
+        runner,
+        lastError: null,
+        inFlight: false,
+        activeRequestId: null,
+    };
+}
 const STREAM_EMIT_DEBOUNCE_MS = 16;
+/** Min interval between full saveSession() calls for an in-progress streaming turn.
+ *  saveSession serializes the entire messages array, so doing it on every NDJSON
+ *  event is N². close-path always calls saveSession unconditionally to take the
+ *  authoritative final snapshot. */
+const STREAM_SAVE_THROTTLE_MS = 200;
 const ARCHIVE_AFTER_MS = 1000 * 60 * 60 * 24;
 function isRunningAsRoot() {
     return process.getuid?.() === 0 || process.geteuid?.() === 0;
@@ -70,37 +88,55 @@ function buildStructuredOutputPayload(snapshot) {
         structuredState: snapshot.structuredState,
     };
 }
-function buildIncrementalStructuredPayload(snapshot) {
+function buildIncrementalStructuredPayload(snapshot, cardDefaults) {
     const messages = snapshot.messages ?? [];
+    const lastTurn = messages.length > 0 ? messages[messages.length - 1] : undefined;
+    // Streaming turn (index 0 here) is preserved verbatim; truncation only kicks
+    // in if the live response is already bigger than the transport threshold,
+    // matching the PTY runner's behaviour in process-manager.ts.
+    const lastMessage = lastTurn ? truncateMessagesForTransport([lastTurn], cardDefaults, 0)[0] : undefined;
     return {
         incremental: true,
         queuedMessages: snapshot.queuedMessages,
         sessionKind: "structured",
         structuredState: snapshot.structuredState,
-        lastMessage: messages.length > 0 ? messages[messages.length - 1] : undefined,
+        lastMessage,
         messageCount: messages.length,
     };
 }
 export class StructuredSessionManager {
     storage;
     config;
+    logger;
     sessions = new Map();
     pendingChildren = new Map();
+    pendingSdkAbort = new Map();
     interruptedWith = new Map();
+    /** Last wall-clock time (ms) we did a full saveSession for a streaming session. */
+    lastStreamSaveAt = new Map();
+    /**
+     * Idempotency keys we've already accepted, mapped to their wall-clock timestamp.
+     * Android WebView 在进程恢复时偶尔会重发上一个未收到响应的 POST（HTTP/2 stream
+     * reset 等场景），客户端 JS 没有重试逻辑也拦不住。这里用 (sessionId, key) 永
+     * 久去重，重复就抛错让前端弹 toast 提示，**不**做任何处理。timestamp 仅用于
+     * map 大小溢出时按时间裁剪。
+     */
+    seenIdempotencyKeys = new Map();
     emitEvent = null;
     archiveTimer = null;
-    constructor(storage, config) {
+    constructor(storage, config, logger = null) {
         this.storage = storage;
         this.config = config;
+        this.logger = logger;
         for (const snapshot of this.storage.loadSessions()) {
             if ((snapshot.sessionKind ?? "pty") !== "structured")
                 continue;
-            const restoredStatus = snapshot.status === "running" ? "stopped" : snapshot.status;
+            const restoredStatus = snapshot.status === "running" ? "idle" : snapshot.status;
             const restored = {
                 ...snapshot,
                 sessionKind: "structured",
-                provider: snapshot.provider ?? "claude",
-                runner: snapshot.runner ?? "claude-cli-print",
+                provider: snapshot.provider ?? snapshot.structuredState?.provider ?? "claude",
+                runner: snapshot.runner ?? snapshot.structuredState?.runner ?? defaultStructuredRunner(snapshot.provider ?? snapshot.structuredState?.provider ?? "claude"),
                 status: restoredStatus,
                 autoApprovePermissions: snapshot.autoApprovePermissions ?? shouldAutoApproveForMode(snapshot.mode),
                 approvalStats: snapshot.approvalStats ?? { tool: 0, command: 0, file: 0, total: 0 },
@@ -109,7 +145,7 @@ export class StructuredSessionManager {
                 permissionBlocked: false,
                 structuredState: {
                     provider: snapshot.structuredState?.provider ?? snapshot.provider ?? "claude",
-                    runner: snapshot.runner ?? "claude-cli-print",
+                    runner: snapshot.runner ?? snapshot.structuredState?.runner ?? defaultStructuredRunner(snapshot.structuredState?.provider ?? snapshot.provider ?? "claude"),
                     model: snapshot.structuredState?.model ?? snapshot.selectedModel ?? undefined,
                     lastError: snapshot.structuredState?.lastError ?? null,
                     inFlight: false,
@@ -148,6 +184,20 @@ export class StructuredSessionManager {
     setEventEmitter(emitEvent) {
         this.emitEvent = emitEvent;
     }
+    /**
+     * In-memory snapshot is updated unconditionally; the SQLite write is rate-
+     * limited to once per STREAM_SAVE_THROTTLE_MS. Caller must still invoke
+     * `storage.saveSession` directly at terminal events (close / failure) so the
+     * final state is durable.
+     */
+    saveStreamingSnapshot(snapshot) {
+        const now = Date.now();
+        const last = this.lastStreamSaveAt.get(snapshot.id) ?? 0;
+        if (now - last < STREAM_SAVE_THROTTLE_MS)
+            return;
+        this.lastStreamSaveAt.set(snapshot.id, now);
+        this.storage.saveSession(snapshot);
+    }
     list() {
         return Array.from(this.sessions.values())
             .map(withSummary)
@@ -171,6 +221,8 @@ export class StructuredSessionManager {
         const id = randomUUID();
         const startedAt = new Date().toISOString();
         const prompt = options.prompt?.trim();
+        const provider = options.provider === "codex" ? "codex" : "claude";
+        const runner = options.runner ?? defaultStructuredRunner(provider);
         const worktreeSetup = options.worktreeEnabled
             ? prepareSessionWorktree({ cwd: options.cwd, sessionId: id })
             : null;
@@ -178,14 +230,14 @@ export class StructuredSessionManager {
         const snapshot = {
             id,
             sessionKind: "structured",
-            provider: "claude",
-            runner: options.runner ?? "claude-cli-print",
-            command: "claude -p --output-format stream-json",
+            provider,
+            runner,
+            command: provider === "codex" ? "codex exec --json" : "claude -p --output-format stream-json",
             cwd: worktreeSetup?.cwd ?? options.cwd,
             mode: options.mode,
             worktreeEnabled: Boolean(worktreeSetup),
             worktree: worktreeSetup?.worktree ?? null,
-            status: "running",
+            status: "idle",
             exitCode: null,
             startedAt,
             endedAt: null,
@@ -196,8 +248,8 @@ export class StructuredSessionManager {
             messages: [],
             queuedMessages: [],
             structuredState: {
-                provider: "claude",
-                runner: options.runner ?? "claude-cli-print",
+                provider,
+                runner,
                 model: selectedModel ?? undefined,
                 inFlight: false,
                 activeRequestId: null,
@@ -211,9 +263,6 @@ export class StructuredSessionManager {
         this.sessions.set(id, snapshot);
         this.storage.saveSession(snapshot);
         this.emit({ type: "started", sessionId: id, data: { sessionKind: "structured" } });
-        if (prompt) {
-            void this.sendMessage(id, prompt);
-        }
         return snapshot;
     }
     async sendMessage(id, input, opts) {
@@ -221,7 +270,23 @@ export class StructuredSessionManager {
         const prompt = input.trim();
         if (!prompt)
             return session;
-        console.log("[WAND] StructuredSessionManager.sendMessage id:", id, "inFlight:", session.structuredState?.inFlight, "hasPendingChild:", this.pendingChildren.has(id), "status:", session.status);
+        if (opts?.idempotencyKey) {
+            const mapKey = `${id}:${opts.idempotencyKey}`;
+            if (this.seenIdempotencyKeys.has(mapKey)) {
+                console.log("[WAND] sendMessage: duplicate idempotency key rejected", { id, key: opts.idempotencyKey });
+                const err = new Error("检测到重复发送，已拦截。");
+                err.code = "duplicate_idempotency_key";
+                throw err;
+            }
+            this.seenIdempotencyKeys.set(mapKey, Date.now());
+            // 防止 map 无限增长：超过 1024 条时按时间裁掉一半最早的
+            if (this.seenIdempotencyKeys.size > 1024) {
+                const sorted = Array.from(this.seenIdempotencyKeys.entries()).sort((a, b) => a[1] - b[1]);
+                for (let i = 0; i < sorted.length / 2; i++) {
+                    this.seenIdempotencyKeys.delete(sorted[i][0]);
+                }
+            }
+        }
         if (session.structuredState?.inFlight) {
             const child = this.pendingChildren.get(id);
             const childAlive = child && !child.killed && child.exitCode === null;
@@ -230,7 +295,7 @@ export class StructuredSessionManager {
                     this.pendingChildren.delete(id);
                 const recovered = {
                     ...session,
-                    status: "stopped",
+                    status: "idle",
                     endedAt: session.endedAt ?? new Date().toISOString(),
                     structuredState: {
                         ...session.structuredState,
@@ -248,6 +313,9 @@ export class StructuredSessionManager {
                     child.kill("SIGTERM");
                 }
                 catch (_err) { /* ignore */ }
+                const sdkAbort = this.pendingSdkAbort.get(id);
+                if (sdkAbort)
+                    sdkAbort.abort();
                 return session;
             }
             else {
@@ -293,7 +361,7 @@ export class StructuredSessionManager {
             endedAt: null,
             messages: [...(session.messages ?? []), userTurn],
             structuredState: {
-                ...(session.structuredState ?? { provider: "claude", runner: "claude-cli-print", lastError: null, inFlight: false, activeRequestId: null }),
+                ...(session.structuredState ?? defaultStructuredState(session.provider ?? "claude", session.runner)),
                 inFlight: true,
                 activeRequestId: requestId,
                 lastError: null,
@@ -313,7 +381,15 @@ export class StructuredSessionManager {
             ? `[对刚才 AskUserQuestion 工具的回答 — 结构化模式不支持工具结果回传，下面是用户从选项中的选择]\n${prompt}`
             : prompt;
         try {
-            await this.runClaudeStreaming(id, updated, claudePrompt);
+            if ((updated.provider ?? "claude") === "codex") {
+                await this.runCodexStreaming(id, updated, prompt);
+            }
+            else if (this.config.structuredRunner === "sdk") {
+                await this.runClaudeSdkStreaming(id, updated, claudePrompt);
+            }
+            else {
+                await this.runClaudeStreaming(id, updated, claudePrompt);
+            }
             const finished = this.requireSession(id);
             return finished;
         }
@@ -364,7 +440,7 @@ export class StructuredSessionManager {
             ...session,
             selectedModel: normalized,
             structuredState: {
-                ...(session.structuredState ?? { provider: "claude", runner: "claude-cli-print", inFlight: false, activeRequestId: null, lastError: null }),
+                ...(session.structuredState ?? defaultStructuredState(session.provider ?? "claude", session.runner)),
                 model: normalized ?? undefined,
             },
         };
@@ -421,6 +497,11 @@ export class StructuredSessionManager {
             child.kill();
             this.pendingChildren.delete(id);
         }
+        const sdkAbort = this.pendingSdkAbort.get(id);
+        if (sdkAbort) {
+            sdkAbort.abort();
+            this.pendingSdkAbort.delete(id);
+        }
         const stopped = {
             ...session,
             status: "stopped",
@@ -428,7 +509,7 @@ export class StructuredSessionManager {
             pendingEscalation: null,
             permissionBlocked: false,
             structuredState: {
-                ...(session.structuredState ?? { provider: "claude", runner: "claude-cli-print", lastError: null, inFlight: false, activeRequestId: null }),
+                ...(session.structuredState ?? defaultStructuredState(session.provider ?? "claude", session.runner)),
                 inFlight: false,
                 activeRequestId: null,
             },
@@ -444,8 +525,15 @@ export class StructuredSessionManager {
             child.kill();
             this.pendingChildren.delete(id);
         }
+        const sdkAbort = this.pendingSdkAbort.get(id);
+        if (sdkAbort) {
+            sdkAbort.abort();
+            this.pendingSdkAbort.delete(id);
+        }
         this.sessions.delete(id);
+        this.lastStreamSaveAt.delete(id);
         this.storage.deleteSession(id);
+        this.logger?.deleteSession(id);
     }
     // ---------------------------------------------------------------------------
     // Private helpers
@@ -507,6 +595,17 @@ export class StructuredSessionManager {
         }
         catch (error) {
             console.error("[WAND] flushNextQueuedMessage failed:", error);
+            // 发送失败时把消息放回队首，避免永久丢失
+            const afterFail = this.sessions.get(sessionId);
+            if (afterFail) {
+                const rescued = {
+                    ...afterFail,
+                    queuedMessages: [nextInput, ...(afterFail.queuedMessages ?? [])],
+                };
+                this.sessions.set(sessionId, rescued);
+                this.storage.saveSession(rescued);
+                this.emitStructuredSnapshot(rescued);
+            }
         }
     }
     emit(event) {
@@ -580,6 +679,314 @@ export class StructuredSessionManager {
         }
         return [];
     }
+    buildCodexArgs(session) {
+        const args = ["exec", "--json", "--color", "never"];
+        const shouldBypass = session.autoApprovePermissions === true || session.mode === "full-access" || session.mode === "managed";
+        if (shouldBypass) {
+            args.push("--dangerously-bypass-approvals-and-sandbox");
+        }
+        else if (session.mode === "auto-edit" || session.mode === "agent" || session.mode === "agent-max") {
+            args.push("--sandbox", "workspace-write");
+        }
+        else {
+            args.push("--sandbox", "read-only");
+        }
+        args.push("--skip-git-repo-check");
+        const modelChoice = session.selectedModel?.trim();
+        if (modelChoice && modelChoice !== "default") {
+            args.push("--model", modelChoice);
+        }
+        if (session.claudeSessionId) {
+            args.push("resume", session.claudeSessionId, "-");
+        }
+        else {
+            args.push("-");
+        }
+        return args;
+    }
+    // ---------------------------------------------------------------------------
+    // Streaming codex exec --json execution
+    // ---------------------------------------------------------------------------
+    runCodexStreaming(sessionId, session, prompt) {
+        return new Promise((resolve, reject) => {
+            const args = this.buildCodexArgs(session);
+            const spawnedAt = new Date().toISOString();
+            const child = spawn("codex", args, {
+                cwd: session.cwd,
+                env: process.env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            this.logger?.appendStructuredSpawn(sessionId, {
+                kind: "codex-exec",
+                provider: "codex",
+                pid: child.pid ?? null,
+                cwd: session.cwd,
+                args,
+                prompt: prompt.slice(0, 2048),
+                promptLength: prompt.length,
+                threadId: session.claudeSessionId,
+                spawnedAt,
+            });
+            this.pendingChildren.set(sessionId, child);
+            child.stdin?.end(prompt);
+            const turnState = {
+                blocks: [],
+                result: "",
+                sessionId: session.claudeSessionId,
+                model: session.selectedModel ?? session.structuredState?.model,
+                usage: undefined,
+            };
+            let lineBuf = "";
+            let stderr = "";
+            let emitTimer = null;
+            // codex 把所有错误（包括重试日志和最终失败原因）都通过 stdout 的 NDJSON 事件
+            // 输出，stderr 通常是空的。我们在 processLine 里收集这些，然后在 close 中
+            // 决定真正的报错文本。
+            const codexErrors = [];
+            let codexTurnFailed = null;
+            const flushEmit = () => {
+                if (emitTimer) {
+                    clearTimeout(emitTimer);
+                    emitTimer = null;
+                }
+                const current = this.sessions.get(sessionId);
+                if (!current)
+                    return;
+                this.emit({ type: "output", sessionId, data: buildIncrementalStructuredPayload(current, this.config.cardDefaults ?? {}) });
+            };
+            const scheduleEmit = () => {
+                if (!emitTimer)
+                    emitTimer = setTimeout(flushEmit, STREAM_EMIT_DEBOUNCE_MS);
+            };
+            const syncSnapshot = () => {
+                const current = this.sessions.get(sessionId);
+                if (!current)
+                    return;
+                const inProgressTurn = {
+                    role: "assistant",
+                    content: this.compactContentBlocks([...turnState.blocks], turnState.result),
+                    usage: turnState.usage,
+                };
+                const msgs = [...(current.messages ?? [])];
+                const lastMsg = msgs[msgs.length - 1];
+                if (lastMsg && lastMsg.role === "assistant") {
+                    msgs[msgs.length - 1] = inProgressTurn;
+                }
+                else {
+                    msgs.push(inProgressTurn);
+                }
+                const patched = {
+                    ...current,
+                    claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
+                    messages: msgs,
+                    output: turnState.result || current.output,
+                    structuredState: {
+                        ...current.structuredState,
+                        model: turnState.model ?? current.structuredState?.model,
+                    },
+                };
+                this.sessions.set(sessionId, patched);
+                this.saveStreamingSnapshot(patched);
+            };
+            const processLine = (line) => {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    return;
+                let parsed;
+                try {
+                    parsed = JSON.parse(trimmed);
+                }
+                catch {
+                    return;
+                }
+                this.logger?.appendStreamEvent(sessionId, parsed);
+                if (parsed?.type === "thread.started" && typeof parsed.thread_id === "string") {
+                    turnState.sessionId = parsed.thread_id;
+                    syncSnapshot();
+                    return;
+                }
+                if (parsed?.type === "item.started" && parsed.item) {
+                    const block = this.extractCodexItemBlock(parsed.item, false);
+                    if (block) {
+                        turnState.blocks.push(block);
+                        syncSnapshot();
+                        scheduleEmit();
+                    }
+                    return;
+                }
+                if (parsed?.type === "item.completed" && parsed.item) {
+                    const block = this.extractCodexItemBlock(parsed.item, true);
+                    if (block) {
+                        if (block.type === "text")
+                            turnState.result = block.text;
+                        this.upsertCodexBlock(turnState.blocks, block);
+                        syncSnapshot();
+                        scheduleEmit();
+                    }
+                    return;
+                }
+                if (parsed?.type === "turn.completed") {
+                    turnState.usage = this.extractCodexUsage(parsed.usage) ?? turnState.usage;
+                    syncSnapshot();
+                    scheduleEmit();
+                    return;
+                }
+                if (parsed?.type === "error") {
+                    const message = typeof parsed.message === "string" ? parsed.message : "";
+                    if (message)
+                        codexErrors.push(message);
+                    return;
+                }
+                if (parsed?.type === "turn.failed") {
+                    const errObj = (parsed.error && typeof parsed.error === "object") ? parsed.error : null;
+                    const message = (errObj && typeof errObj.message === "string" && errObj.message)
+                        || (typeof parsed.message === "string" ? parsed.message : "")
+                        || "codex turn failed";
+                    codexTurnFailed = message;
+                    return;
+                }
+            };
+            child.stdout?.on("data", (chunk) => {
+                const text = chunk.toString();
+                this.logger?.appendStructuredStdout(sessionId, text);
+                lineBuf += text;
+                const lines = lineBuf.split("\n");
+                lineBuf = lines.pop() ?? "";
+                for (const line of lines)
+                    processLine(line);
+            });
+            child.stderr?.on("data", (chunk) => {
+                const text = chunk.toString();
+                this.logger?.appendStructuredStderr(sessionId, text);
+                stderr += text;
+            });
+            child.on("error", (error) => {
+                this.pendingChildren.delete(sessionId);
+                this.lastStreamSaveAt.delete(sessionId);
+                if (emitTimer)
+                    clearTimeout(emitTimer);
+                this.logger?.appendStructuredSpawn(sessionId, {
+                    kind: "codex-exec-error",
+                    pid: child.pid ?? null,
+                    spawnedAt,
+                    closedAt: new Date().toISOString(),
+                    spawnError: error.message,
+                });
+                reject(error);
+            });
+            child.on("close", (code) => {
+                this.pendingChildren.delete(sessionId);
+                this.lastStreamSaveAt.delete(sessionId);
+                if (lineBuf.trim()) {
+                    processLine(lineBuf);
+                    lineBuf = "";
+                }
+                flushEmit();
+                const closedAt = new Date().toISOString();
+                this.logger?.appendStructuredSpawn(sessionId, {
+                    kind: "codex-exec-close",
+                    pid: child.pid ?? null,
+                    spawnedAt,
+                    closedAt,
+                    exitCode: code,
+                    stderrTail: stderr.slice(-2048),
+                    codexErrors,
+                    codexTurnFailed,
+                });
+                const current = this.sessions.get(sessionId);
+                if (!current) {
+                    reject(new Error("Session removed during execution."));
+                    return;
+                }
+                // 主动中断时（interruptedWith 里有新消息），不走失败路径
+                const interruptedByUser = this.interruptedWith.has(sessionId);
+                const interruptPrompt = this.interruptedWith.get(sessionId);
+                // codex 把模型/网络/沙箱等错误写到 stdout 的 NDJSON 流（type: error / turn.failed），
+                // 而不是 stderr。我们以 turn.failed 的 message 为准，其次是最后一个 error 事件。
+                const codexFailed = codexTurnFailed !== null;
+                if ((codexFailed || (code !== 0 && code !== null)) && !interruptedByUser) {
+                    const errorText = (codexTurnFailed && codexTurnFailed.trim())
+                        || (codexErrors.length > 0 ? codexErrors[codexErrors.length - 1] : "")
+                        || stderr.trim()
+                        || `codex exec exited with code ${code}`;
+                    const exitForSnapshot = typeof code === "number" ? code : 1;
+                    const failed = this.finishStructuredFailure(current, exitForSnapshot, errorText, turnState);
+                    this.sessions.set(sessionId, failed);
+                    this.storage.saveSession(failed);
+                    this.emitStructuredSnapshot(failed);
+                    this.emitStructuredSnapshot(failed, "ended");
+                    reject(new Error(errorText));
+                    return;
+                }
+                const assistantTurn = {
+                    role: "assistant",
+                    content: this.compactContentBlocks([...turnState.blocks], turnState.result),
+                    usage: turnState.usage,
+                };
+                const msgs = [...(current.messages ?? [])];
+                const lastMsg = msgs[msgs.length - 1];
+                if (lastMsg && lastMsg.role === "assistant")
+                    msgs[msgs.length - 1] = assistantTurn;
+                else
+                    msgs.push(assistantTurn);
+                const keepRunning = !!interruptPrompt;
+                const finished = {
+                    ...current,
+                    status: keepRunning ? "running" : "idle",
+                    exitCode: keepRunning ? null : 0,
+                    endedAt: keepRunning ? null : new Date().toISOString(),
+                    output: turnState.result,
+                    claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
+                    messages: msgs,
+                    queuedMessages: interruptPrompt ? [] : current.queuedMessages,
+                    pendingEscalation: null,
+                    permissionBlocked: false,
+                    structuredState: {
+                        ...current.structuredState,
+                        model: turnState.model ?? current.structuredState?.model,
+                        inFlight: false,
+                        activeRequestId: null,
+                        lastError: null,
+                    },
+                };
+                this.sessions.set(sessionId, finished);
+                this.storage.saveSession(finished);
+                this.emitStructuredSnapshot(finished);
+                if (!keepRunning) {
+                    this.emitStructuredSnapshot(finished, "ended");
+                }
+                if (interruptPrompt) {
+                    this.interruptedWith.delete(sessionId);
+                    resolve();
+                    setImmediate(() => {
+                        this.sendMessage(sessionId, interruptPrompt).catch((err) => {
+                            console.error("[WAND] codex interrupt-and-send failed:", err);
+                            const afterFail = this.sessions.get(sessionId);
+                            if (afterFail) {
+                                const recovered = {
+                                    ...afterFail,
+                                    status: "idle",
+                                    exitCode: 0,
+                                    endedAt: new Date().toISOString(),
+                                    structuredState: {
+                                        ...afterFail.structuredState,
+                                        inFlight: false,
+                                        activeRequestId: null,
+                                    },
+                                };
+                                this.sessions.set(sessionId, recovered);
+                                this.storage.saveSession(recovered);
+                                this.emitStructuredSnapshot(recovered);
+                            }
+                        });
+                    });
+                    return;
+                }
+                resolve();
+                setImmediate(() => { void this.flushNextQueuedMessage(sessionId); });
+            });
+        });
+    }
     // ---------------------------------------------------------------------------
     // Streaming claude -p execution
     // ---------------------------------------------------------------------------
@@ -597,7 +1004,6 @@ export class StructuredSessionManager {
     runClaudeStreaming(sessionId, session, prompt) {
         return new Promise((resolve, reject) => {
             const args = ["-p", "--verbose", "--output-format", "stream-json"];
-            console.log("[WAND] runClaudeStreaming sessionId:", sessionId, "mode:", session.mode, "claudeSessionId:", session.claudeSessionId);
             // Add permission args based on mode + autoApprovePermissions toggle
             const permArgs = this.buildPermissionArgs(session.mode, session.autoApprovePermissions ?? false);
             args.push(...permArgs);
@@ -633,12 +1039,23 @@ export class StructuredSessionManager {
             // variadic 参数贪婪吞掉（commander 的 <tools...> 会一直吃 positional 直到
             // 下一个 flag）。表现为 claude 报 "Input must be provided either through
             // stdin or as a prompt argument when using --print"。
+            const spawnedAt = new Date().toISOString();
             const child = spawn("claude", args, {
                 cwd: session.cwd,
                 env: process.env,
                 stdio: ["pipe", "pipe", "pipe"],
             });
-            console.log("[WAND] spawned claude -p pid:", child.pid, "args:", args.join(" "));
+            this.logger?.appendStructuredSpawn(sessionId, {
+                kind: "claude-print",
+                provider: "claude",
+                pid: child.pid ?? null,
+                cwd: session.cwd,
+                args,
+                prompt: prompt.slice(0, 2048),
+                promptLength: prompt.length,
+                claudeSessionId: session.claudeSessionId,
+                spawnedAt,
+            });
             this.pendingChildren.set(sessionId, child);
             child.stdin?.end(prompt);
             const turnState = {
@@ -667,7 +1084,7 @@ export class StructuredSessionManager {
                 this.emit({
                     type: "output",
                     sessionId,
-                    data: buildIncrementalStructuredPayload(current),
+                    data: buildIncrementalStructuredPayload(current, this.config.cardDefaults ?? {}),
                 });
             };
             const scheduleEmit = () => {
@@ -706,8 +1123,9 @@ export class StructuredSessionManager {
                 };
                 this.sessions.set(sessionId, patched);
                 // Persist streaming progress so a server restart does not roll back the
-                // latest assistant turn to the pre-stream snapshot.
-                this.storage.saveSession(patched);
+                // latest assistant turn to the pre-stream snapshot. Throttled because
+                // saveSession serializes the full messages array.
+                this.saveStreamingSnapshot(patched);
             };
             const processLine = (line) => {
                 const trimmed = line.trim();
@@ -720,6 +1138,7 @@ export class StructuredSessionManager {
                 catch {
                     return;
                 }
+                this.logger?.appendStreamEvent(sessionId, parsed);
                 if (parsed && parsed.type === "assistant" && parsed.message) {
                     const extracted = this.extractAssistantMessage(parsed.message);
                     if (extracted.content.length > 0) {
@@ -776,7 +1195,9 @@ export class StructuredSessionManager {
             };
             let stderr = "";
             child.stdout?.on("data", (chunk) => {
-                lineBuf += chunk.toString();
+                const text = chunk.toString();
+                this.logger?.appendStructuredStdout(sessionId, text);
+                lineBuf += text;
                 const lines = lineBuf.split("\n");
                 // Keep the last (possibly incomplete) segment in the buffer.
                 lineBuf = lines.pop() ?? "";
@@ -785,18 +1206,35 @@ export class StructuredSessionManager {
                 }
             });
             child.stderr?.on("data", (chunk) => {
-                stderr += chunk.toString();
+                const text = chunk.toString();
+                this.logger?.appendStructuredStderr(sessionId, text);
+                stderr += text;
             });
             child.on("error", (error) => {
-                console.log("[WAND] claude -p child error:", error.message);
                 this.pendingChildren.delete(sessionId);
+                this.lastStreamSaveAt.delete(sessionId);
                 if (emitTimer)
                     clearTimeout(emitTimer);
+                this.logger?.appendStructuredSpawn(sessionId, {
+                    kind: "claude-print-error",
+                    pid: child.pid ?? null,
+                    spawnedAt,
+                    closedAt: new Date().toISOString(),
+                    spawnError: error.message,
+                });
                 reject(error);
             });
             child.on("close", (code) => {
-                console.log("[WAND] claude -p child close code:", code, "stderr:", stderr.substring(0, 200));
                 this.pendingChildren.delete(sessionId);
+                this.lastStreamSaveAt.delete(sessionId);
+                this.logger?.appendStructuredSpawn(sessionId, {
+                    kind: "claude-print-close",
+                    pid: child.pid ?? null,
+                    spawnedAt,
+                    closedAt: new Date().toISOString(),
+                    exitCode: code,
+                    stderrTail: stderr.slice(-2048),
+                });
                 // Process any remaining data in the line buffer.
                 if (lineBuf.trim()) {
                     processLine(lineBuf);
@@ -810,7 +1248,11 @@ export class StructuredSessionManager {
                     reject(new Error("Session removed during execution."));
                     return;
                 }
-                if (code !== 0 && code !== null) {
+                // 如果是用户主动中断（interruptedWith 里有新消息），claude -p 收到 SIGTERM 后
+                // 可能以非零 exit code 退出（内部 handler 调了 exit(1)）。这种情况属于正常
+                // 中断流程，不应走失败路径——后续 interruptedWith 逻辑会发送新消息。
+                const interruptedByUser = this.interruptedWith.has(sessionId);
+                if (code !== 0 && code !== null && !interruptedByUser) {
                     const errorText = stderr.trim() || `claude -p exited with code ${code}`;
                     const failureTurn = {
                         role: "assistant",
@@ -871,7 +1313,7 @@ export class StructuredSessionManager {
                 const keepRunning = killedForAskUserQuestion || !!interruptPrompt;
                 const finished = {
                     ...current,
-                    status: keepRunning ? "running" : "stopped",
+                    status: keepRunning ? "running" : "idle",
                     exitCode: keepRunning ? null : 0,
                     endedAt: keepRunning ? null : new Date().toISOString(),
                     output: turnState.result,
@@ -902,11 +1344,28 @@ export class StructuredSessionManager {
                 // 用户中断当前回复：保存部分回复后立即发送新消息。
                 if (interruptPrompt) {
                     this.interruptedWith.delete(sessionId);
-                    console.log("[WAND] interrupt-and-send for session:", sessionId, "prompt:", interruptPrompt.substring(0, 50));
                     resolve();
                     setImmediate(() => {
                         this.sendMessage(sessionId, interruptPrompt).catch((err) => {
                             console.error("[WAND] interrupt-and-send failed:", err);
+                            // 续接失败：把状态回滚到 idle，让用户可以重新输入而不是卡在 running 状态
+                            const afterFail = this.sessions.get(sessionId);
+                            if (afterFail) {
+                                const recovered = {
+                                    ...afterFail,
+                                    status: "idle",
+                                    exitCode: 0,
+                                    endedAt: new Date().toISOString(),
+                                    structuredState: {
+                                        ...afterFail.structuredState,
+                                        inFlight: false,
+                                        activeRequestId: null,
+                                    },
+                                };
+                                this.sessions.set(sessionId, recovered);
+                                this.storage.saveSession(recovered);
+                                this.emitStructuredSnapshot(recovered);
+                            }
                         });
                     });
                     return;
@@ -917,7 +1376,6 @@ export class StructuredSessionManager {
                 // so the plan is actually carried out.
                 const lastToolUse = [...turnState.blocks].reverse().find((b) => b.type === "tool_use");
                 if (lastToolUse && lastToolUse.name === "ExitPlanMode" && turnState.sessionId) {
-                    console.log("[WAND] ExitPlanMode detected – auto-continuing plan execution for session:", sessionId);
                     resolve();
                     setImmediate(() => {
                         this.sendMessage(sessionId, "Plan approved. Proceed with the implementation.").catch((err) => {
@@ -934,6 +1392,396 @@ export class StructuredSessionManager {
         });
     }
     // ---------------------------------------------------------------------------
+    // Streaming claude-agent-sdk execution
+    // ---------------------------------------------------------------------------
+    /**
+     * Use @anthropic-ai/claude-agent-sdk instead of spawning claude -p directly.
+     * The SDK still spawns the claude binary but provides typed AsyncGenerator<SDKMessage>
+     * messages, so we skip NDJSON parsing. Options are 1:1 with the CLI flags.
+     *
+     * Streaming is enabled via includePartialMessages: true — the SDK emits
+     * SDKPartialAssistantMessage (type: "stream_event") with BetaRawMessageStreamEvent
+     * payloads for incremental text/thinking/tool_use updates, followed by a final
+     * SDKAssistantMessage with the authoritative complete content.
+     */
+    runClaudeSdkStreaming(sessionId, session, prompt) {
+        return new Promise((resolve, reject) => {
+            void this._runClaudeSdkStreamingAsync(sessionId, session, prompt).then(resolve, reject);
+        });
+    }
+    async _runClaudeSdkStreamingAsync(sessionId, session, prompt) {
+        let sdkQuery;
+        try {
+            const sdkMod = await import("@anthropic-ai/claude-agent-sdk");
+            sdkQuery = sdkMod.query;
+        }
+        catch {
+            throw new Error("@anthropic-ai/claude-agent-sdk 未安装，无法使用 SDK runner。");
+        }
+        const abortController = new AbortController();
+        this.pendingSdkAbort.set(sessionId, abortController);
+        const isManaged = session.mode === "managed";
+        let killedForAskUserQuestion = false;
+        // Derive permission mode (mirrors buildPermissionArgs logic)
+        const shouldBypass = (session.autoApprovePermissions ?? false) || session.mode === "full-access" || session.mode === "managed";
+        const shouldAcceptEdits = session.mode === "auto-edit";
+        let permissionMode = "default";
+        let allowedToolsForRoot;
+        if (!isRunningAsRoot()) {
+            if (shouldBypass)
+                permissionMode = "bypassPermissions";
+            else if (shouldAcceptEdits)
+                permissionMode = "acceptEdits";
+        }
+        else {
+            // Root: acceptEdits + allowedTools (same workaround as CLI runner)
+            if (shouldBypass || shouldAcceptEdits) {
+                permissionMode = "acceptEdits";
+                allowedToolsForRoot = ["Bash", "Edit", "Write", "Read", "Glob", "Grep", "NotebookEdit", "WebFetch", "WebSearch"];
+            }
+        }
+        // System prompt additions
+        const isChinese = this.config.language?.trim() === "中文";
+        const systemPromptParts = [];
+        if (isManaged) {
+            systemPromptParts.push(isChinese
+                ? "你正在完全托管的自主模式下运行。用户可能无法及时回复问题或确认。你必须独立做出所有决策——自行选择最佳方案，而不是向用户询问偏好、确认或澄清。如果有多种可行方案，选择你认为最合适的并继续执行。除非任务本身存在根本性的歧义且无法合理推断，否则不要等待用户输入。果断行动，自主决策。"
+                : "You are running in a fully managed, autonomous mode. The user may not be available to respond to questions or confirmations in a timely manner. You MUST make all decisions independently — choose the best approach yourself instead of asking the user for preferences, confirmations, or clarifications. If multiple approaches are viable, pick the one you judge most appropriate and proceed. Never block on user input unless the task is fundamentally ambiguous and cannot be reasonably inferred. Be decisive and self-directed.");
+        }
+        const language = this.config.language?.trim();
+        if (language) {
+            systemPromptParts.push(isChinese
+                ? "请使用中文回复。所有解释、注释和对话文本都使用中文。"
+                : `Please respond in ${language}. Use ${language} for all your explanations, comments, and conversational text.`);
+        }
+        const sdkOptions = {
+            cwd: session.cwd,
+            abortController,
+            permissionMode,
+            ...(permissionMode === "bypassPermissions" ? { allowDangerouslySkipPermissions: true } : {}),
+            ...(allowedToolsForRoot ? { allowedTools: allowedToolsForRoot } : {}),
+            ...(isManaged ? { disallowedTools: ["AskUserQuestion"] } : {}),
+            includePartialMessages: true,
+            ...(systemPromptParts.length > 0 ? { appendSystemPrompt: systemPromptParts.join("\n\n") } : {}),
+        };
+        if (session.claudeSessionId)
+            sdkOptions.resume = session.claudeSessionId;
+        const modelChoice = session.selectedModel?.trim();
+        if (modelChoice && modelChoice !== "default")
+            sdkOptions.model = modelChoice;
+        const turnState = {
+            blocks: [],
+            result: "",
+            sessionId: null,
+            model: undefined,
+            usage: undefined,
+        };
+        // Tracks in-progress streaming blocks keyed by content_block index from stream_event
+        const streamingBlockByIndex = new Map();
+        let emitTimer = null;
+        const flushEmit = () => {
+            if (emitTimer) {
+                clearTimeout(emitTimer);
+                emitTimer = null;
+            }
+            const current = this.sessions.get(sessionId);
+            if (!current)
+                return;
+            this.emit({ type: "output", sessionId, data: buildIncrementalStructuredPayload(current, this.config.cardDefaults ?? {}) });
+        };
+        const scheduleEmit = () => {
+            if (!emitTimer)
+                emitTimer = setTimeout(flushEmit, STREAM_EMIT_DEBOUNCE_MS);
+        };
+        // Rebuild ContentBlock[] from the in-progress streaming blocks map
+        const rebuildStreamingBlocks = () => {
+            const sorted = [...streamingBlockByIndex.entries()].sort((a, b) => a[0] - b[0]);
+            const blocks = [];
+            for (const [, sb] of sorted) {
+                if (sb.type === "text") {
+                    blocks.push({ type: "text", text: sb.text });
+                }
+                else if (sb.type === "thinking") {
+                    blocks.push({ type: "thinking", thinking: sb.thinking });
+                }
+                else if (sb.type === "tool_use" && sb.id && sb.name) {
+                    let input = {};
+                    if (sb.finalized && sb.partialInput) {
+                        try {
+                            input = JSON.parse(sb.partialInput);
+                        }
+                        catch { /* partial json */ }
+                    }
+                    blocks.push({ type: "tool_use", id: sb.id, name: sb.name, input });
+                }
+            }
+            return blocks;
+        };
+        const syncSnapshot = () => {
+            const current = this.sessions.get(sessionId);
+            if (!current)
+                return;
+            const inProgressTurn = {
+                role: "assistant",
+                content: this.compactContentBlocks([...turnState.blocks], turnState.result),
+                usage: turnState.usage,
+            };
+            const msgs = [...(current.messages ?? [])];
+            const lastMsg = msgs[msgs.length - 1];
+            if (lastMsg && lastMsg.role === "assistant")
+                msgs[msgs.length - 1] = inProgressTurn;
+            else
+                msgs.push(inProgressTurn);
+            const patched = {
+                ...current,
+                claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
+                messages: msgs,
+                output: turnState.result || current.output,
+                structuredState: {
+                    ...current.structuredState,
+                    model: turnState.model ?? current.structuredState?.model,
+                },
+            };
+            this.sessions.set(sessionId, patched);
+            this.saveStreamingSnapshot(patched);
+        };
+        const spawnedAt = new Date().toISOString();
+        this.logger?.appendStructuredSpawn(sessionId, {
+            kind: "claude-sdk",
+            provider: "claude",
+            cwd: session.cwd,
+            permissionMode,
+            prompt: prompt.slice(0, 2048),
+            promptLength: prompt.length,
+            claudeSessionId: session.claudeSessionId,
+            spawnedAt,
+        });
+        try {
+            for await (const msg of sdkQuery({ prompt, options: sdkOptions })) {
+                if (abortController.signal.aborted)
+                    break;
+                // Incremental streaming events (opt-in via includePartialMessages: true)
+                if (msg.type === "stream_event") {
+                    const ev = msg.event;
+                    if (ev.type === "content_block_start") {
+                        const cb = ev.content_block;
+                        const blockType = cb.type;
+                        if (blockType === "text" || blockType === "thinking" || blockType === "tool_use") {
+                            streamingBlockByIndex.set(ev.index, {
+                                type: blockType,
+                                id: typeof cb.id === "string" ? cb.id : undefined,
+                                name: typeof cb.name === "string" ? cb.name : undefined,
+                                text: typeof cb.text === "string" ? cb.text : "",
+                                thinking: typeof cb.thinking === "string" ? cb.thinking : "",
+                                partialInput: "",
+                                finalized: false,
+                            });
+                            turnState.blocks = rebuildStreamingBlocks();
+                            syncSnapshot();
+                            scheduleEmit();
+                        }
+                    }
+                    else if (ev.type === "content_block_delta") {
+                        const sb = streamingBlockByIndex.get(ev.index);
+                        if (sb) {
+                            const delta = ev.delta;
+                            if (delta.type === "text_delta" && typeof delta.text === "string") {
+                                sb.text += delta.text;
+                                turnState.result = sb.text;
+                            }
+                            else if (delta.type === "thinking_delta" && typeof delta.thinking === "string") {
+                                sb.thinking += delta.thinking;
+                            }
+                            else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+                                sb.partialInput += delta.partial_json;
+                            }
+                            turnState.blocks = rebuildStreamingBlocks();
+                            syncSnapshot();
+                            scheduleEmit();
+                        }
+                    }
+                    else if (ev.type === "content_block_stop") {
+                        const sb = streamingBlockByIndex.get(ev.index);
+                        if (sb) {
+                            sb.finalized = true;
+                            turnState.blocks = rebuildStreamingBlocks();
+                            syncSnapshot();
+                            scheduleEmit();
+                        }
+                    }
+                    continue;
+                }
+                // Complete assistant turn — authoritative content replaces streaming blocks
+                if (msg.type === "assistant") {
+                    const assistantMsg = msg;
+                    const extracted = this.extractAssistantMessage(assistantMsg.message);
+                    // Keep tool_result blocks from previous user messages, replace streaming assistant content
+                    const toolResults = turnState.blocks.filter(b => b.type === "tool_result");
+                    turnState.blocks = [...extracted.content, ...toolResults];
+                    streamingBlockByIndex.clear();
+                    if (assistantMsg.session_id)
+                        turnState.sessionId = assistantMsg.session_id;
+                    syncSnapshot();
+                    scheduleEmit();
+                    // Non-managed mode: detect AskUserQuestion, abort to let user answer
+                    if (!isManaged && !killedForAskUserQuestion) {
+                        const askBlock = extracted.content.find((b) => b.type === "tool_use" && b.name === "AskUserQuestion");
+                        if (askBlock) {
+                            killedForAskUserQuestion = true;
+                            flushEmit();
+                            abortController.abort();
+                        }
+                    }
+                    continue;
+                }
+                // Tool results fed back from the claude subprocess
+                if (msg.type === "user") {
+                    const userMsg = msg;
+                    const content = Array.isArray(userMsg.message?.content) ? userMsg.message.content : [];
+                    for (const block of content) {
+                        const b = block;
+                        if (b?.type === "tool_result") {
+                            turnState.blocks.push({
+                                type: "tool_result",
+                                tool_use_id: typeof b.tool_use_id === "string" ? b.tool_use_id : "",
+                                content: this.normalizeToolResultContent(b.content),
+                                is_error: b.is_error === true,
+                            });
+                        }
+                    }
+                    syncSnapshot();
+                    scheduleEmit();
+                    continue;
+                }
+                // Final result — capture session_id, usage, model
+                if (msg.type === "result") {
+                    const resultMsg = msg;
+                    if (typeof resultMsg.result === "string")
+                        turnState.result = resultMsg.result.trim();
+                    if (typeof resultMsg.session_id === "string")
+                        turnState.sessionId = resultMsg.session_id;
+                    turnState.model = this.extractModelName(resultMsg.modelUsage) ?? turnState.model;
+                    turnState.usage = this.extractSdkUsage(resultMsg);
+                    syncSnapshot();
+                    scheduleEmit();
+                    continue;
+                }
+            }
+        }
+        catch (err) {
+            // AbortError from abortController.abort() is intentional — fall through to finish logic
+            const isAbort = abortController.signal.aborted || (err instanceof Error && err.name === "AbortError");
+            if (!isAbort) {
+                this.pendingSdkAbort.delete(sessionId);
+                this.lastStreamSaveAt.delete(sessionId);
+                if (emitTimer)
+                    clearTimeout(emitTimer);
+                this.logger?.appendStructuredSpawn(sessionId, {
+                    kind: "claude-sdk-error",
+                    spawnedAt,
+                    closedAt: new Date().toISOString(),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                throw err;
+            }
+        }
+        // Cleanup
+        this.pendingSdkAbort.delete(sessionId);
+        this.lastStreamSaveAt.delete(sessionId);
+        if (emitTimer)
+            clearTimeout(emitTimer);
+        flushEmit();
+        const current = this.sessions.get(sessionId);
+        if (!current)
+            throw new Error("Session removed during execution.");
+        this.logger?.appendStructuredSpawn(sessionId, {
+            kind: "claude-sdk-close",
+            spawnedAt,
+            closedAt: new Date().toISOString(),
+            killedForAskUserQuestion,
+            sessionId: turnState.sessionId,
+        });
+        const interruptedByUser = this.interruptedWith.has(sessionId);
+        // Build final assistant turn
+        const finalContent = this.compactContentBlocks([...turnState.blocks], turnState.result);
+        const assistantTurn = {
+            role: "assistant",
+            content: finalContent,
+            usage: turnState.usage,
+        };
+        const msgs = [...(current.messages ?? [])];
+        const lastMsg = msgs[msgs.length - 1];
+        if (lastMsg && lastMsg.role === "assistant")
+            msgs[msgs.length - 1] = assistantTurn;
+        else
+            msgs.push(assistantTurn);
+        const interruptPrompt = this.interruptedWith.get(sessionId);
+        const keepRunning = killedForAskUserQuestion || !!interruptPrompt;
+        const finished = {
+            ...current,
+            status: keepRunning ? "running" : "idle",
+            exitCode: keepRunning ? null : 0,
+            endedAt: keepRunning ? null : new Date().toISOString(),
+            output: turnState.result,
+            claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
+            messages: msgs,
+            queuedMessages: interruptPrompt ? [] : current.queuedMessages,
+            pendingEscalation: null,
+            permissionBlocked: false,
+            structuredState: {
+                ...current.structuredState,
+                model: turnState.model ?? current.structuredState?.model,
+                inFlight: false,
+                activeRequestId: null,
+                lastError: null,
+            },
+        };
+        this.sessions.set(sessionId, finished);
+        this.storage.saveSession(finished);
+        this.emitStructuredSnapshot(finished);
+        if (!keepRunning)
+            this.emitStructuredSnapshot(finished, "ended");
+        if (killedForAskUserQuestion)
+            return;
+        if (interruptPrompt) {
+            this.interruptedWith.delete(sessionId);
+            setImmediate(() => {
+                this.sendMessage(sessionId, interruptPrompt).catch((err) => {
+                    console.error("[WAND] sdk interrupt-and-send failed:", err);
+                    const afterFail = this.sessions.get(sessionId);
+                    if (afterFail) {
+                        const recovered = {
+                            ...afterFail,
+                            status: "idle",
+                            exitCode: 0,
+                            endedAt: new Date().toISOString(),
+                            structuredState: {
+                                ...afterFail.structuredState,
+                                inFlight: false,
+                                activeRequestId: null,
+                            },
+                        };
+                        this.sessions.set(sessionId, recovered);
+                        this.storage.saveSession(recovered);
+                        this.emitStructuredSnapshot(recovered);
+                    }
+                });
+            });
+            return;
+        }
+        // Auto-continue after ExitPlanMode (same as CLI runner)
+        const lastToolUse = [...turnState.blocks].reverse().find((b) => b.type === "tool_use");
+        if (lastToolUse && lastToolUse.name === "ExitPlanMode" && turnState.sessionId) {
+            setImmediate(() => {
+                this.sendMessage(sessionId, "Plan approved. Proceed with the implementation.").catch((err) => {
+                    console.error("[WAND] sdk auto-continue after ExitPlanMode failed:", err);
+                });
+            });
+            return;
+        }
+        setImmediate(() => { void this.flushNextQueuedMessage(sessionId); });
+    }
+    // ---------------------------------------------------------------------------
     // Parsing helpers (unchanged logic, extracted from previous implementation)
     // ---------------------------------------------------------------------------
     extractAssistantMessage(message) {
@@ -1002,6 +1850,106 @@ export class StructuredSessionManager {
         }
         return typeof content === "undefined" || content === null ? "" : String(content);
     }
+    extractCodexText(value) {
+        if (typeof value === "string")
+            return value;
+        if (!value || typeof value !== "object")
+            return "";
+        if (Array.isArray(value)) {
+            return value.map((item) => this.extractCodexText(item)).filter(Boolean).join("");
+        }
+        const record = value;
+        for (const key of ["text", "output_text", "message", "content", "summary"]) {
+            const extracted = this.extractCodexText(record[key]);
+            if (extracted)
+                return extracted;
+        }
+        return "";
+    }
+    extractCodexItemBlock(item, completed) {
+        const id = typeof item.id === "string" ? item.id : randomUUID();
+        const type = typeof item.type === "string" ? item.type : "unknown";
+        if (type === "agent_message") {
+            const text = this.extractCodexText(item);
+            return text ? { type: "text", text } : null;
+        }
+        if (type === "reasoning") {
+            const text = this.extractCodexText(item);
+            return text ? { type: "thinking", thinking: text } : null;
+        }
+        if (type === "command_execution") {
+            const command = typeof item.command === "string" ? item.command : "";
+            const aggregatedOutput = typeof item.aggregated_output === "string" ? item.aggregated_output : "";
+            const exitCode = typeof item.exit_code === "number" ? item.exit_code : null;
+            const status = typeof item.status === "string" ? item.status : completed ? "completed" : "in_progress";
+            if (!completed) {
+                return {
+                    type: "tool_use",
+                    id,
+                    name: "Bash",
+                    input: { command, status },
+                };
+            }
+            return {
+                type: "tool_result",
+                tool_use_id: id,
+                content: aggregatedOutput || (exitCode === null ? "" : `exit_code: ${exitCode}`),
+                is_error: typeof exitCode === "number" && exitCode !== 0,
+            };
+        }
+        if (completed) {
+            const text = this.extractCodexText(item);
+            if (text)
+                return { type: "text", text };
+        }
+        return null;
+    }
+    upsertCodexBlock(blocks, block) {
+        if (block.type === "tool_result") {
+            const toolUseIndex = blocks.findIndex((existing) => existing.type === "tool_use" && existing.id === block.tool_use_id);
+            if (toolUseIndex >= 0) {
+                const nextIndex = toolUseIndex + 1;
+                if (blocks[nextIndex]?.type === "tool_result" && blocks[nextIndex].tool_use_id === block.tool_use_id) {
+                    blocks[nextIndex] = block;
+                }
+                else {
+                    blocks.splice(nextIndex, 0, block);
+                }
+                return;
+            }
+        }
+        blocks.push(block);
+    }
+    finishStructuredFailure(current, code, errorText, turnState) {
+        const failureTurn = {
+            role: "assistant",
+            content: [{ type: "text", text: `结构化会话执行失败：${errorText}` }],
+        };
+        const msgs = [...(current.messages ?? [])];
+        const lastMsg = msgs[msgs.length - 1];
+        if (lastMsg && lastMsg.role === "assistant")
+            msgs[msgs.length - 1] = failureTurn;
+        else
+            msgs.push(failureTurn);
+        return {
+            ...current,
+            status: "failed",
+            exitCode: code,
+            endedAt: new Date().toISOString(),
+            output: errorText,
+            claudeSessionId: turnState.sessionId ?? current.claudeSessionId,
+            messages: msgs,
+            pendingEscalation: null,
+            permissionBlocked: false,
+            structuredState: {
+                ...current.structuredState,
+                model: turnState.model ?? current.structuredState?.model,
+                inFlight: false,
+                activeRequestId: null,
+                lastError: errorText,
+            },
+        };
+    }
     extractModelName(modelUsage) {
         if (!modelUsage)
             return undefined;
@@ -1029,4 +1977,31 @@ export class StructuredSessionManager {
         }
         return value;
     }
+    /** Extract usage from an SDKResultSuccess message (sdk runner). */
+    extractSdkUsage(result) {
+        const usage = result?.usage;
+        const value = {
+            inputTokens: typeof usage?.input_tokens === "number" ? usage.input_tokens : undefined,
+            outputTokens: typeof usage?.output_tokens === "number" ? usage.output_tokens : undefined,
+            cacheReadInputTokens: typeof usage?.cache_read_input_tokens === "number" ? usage.cache_read_input_tokens : undefined,
+            cacheCreationInputTokens: typeof usage?.cache_creation_input_tokens === "number" ? usage.cache_creation_input_tokens : undefined,
+            totalCostUsd: typeof result?.total_cost_usd === "number" ? result.total_cost_usd : undefined,
+        };
+        if (Object.values(value).every(v => v === undefined))
+            return undefined;
+        return value;
+    }
+    extractCodexUsage(source) {
+        if (!source || typeof source !== "object")
+            return undefined;
+        const value = {
+            inputTokens: typeof source.input_tokens === "number" ? source.input_tokens : undefined,
+            outputTokens: typeof source.output_tokens === "number" ? source.output_tokens : undefined,
+            cacheReadInputTokens: typeof source.cached_input_tokens === "number" ? source.cached_input_tokens : undefined,
+        };
+        if (value.inputTokens === undefined && value.outputTokens === undefined && value.cacheReadInputTokens === undefined) {
+            return undefined;
+        }
+        return value;
+    }
 }