@xcanwin/manyoyo 8.6.5 → 8.6.7

package/lib/web/server.js

@@ -58,6 +58,9 @@ const {
 const { FileEventStore } = require('../core/event-store');
 const historyStore = require('./history-store');
 const messagesView = require('./messages-view');
+const agentRunControl = require('./agent-run-control');
+const agentQueue = require('./agent-queue');
+const { EventEmitter } = require('events');
 const zlib = require('zlib');
 const { buildManyoyoLogPath, getLocalDateTag } = require('../log-path');
 const { isValidLogDateTag, readServeLogEntries } = require('../serve-log-reader');
@@ -216,7 +219,9 @@ function createEmptyWebAgentSession(agentId, agentName) {
         lastResumeError: '',
         engineSessionId: '',
         usageTotal: null,
-        model: ''
+        model: '',
+        queue: [],
+        queuePaused: false
     };
 }
 
@@ -268,7 +273,9 @@ function normalizeWebAgentSessionRecord(agentId, rawAgent) {
         lastResumeError: typeof source.lastResumeError === 'string' ? source.lastResumeError : '',
         engineSessionId: typeof source.engineSessionId === 'string' ? source.engineSessionId : '',
         usageTotal: normalizeWebAgentUsageTotal(source.usageTotal),
-        model: normalizeStoredAgentModelValue(source.model)
+        model: normalizeStoredAgentModelValue(source.model),
+        queue: agentQueue.normalizeStoredQueue(source.queue),
+        queuePaused: source.queuePaused === true
     };
 }
 
@@ -933,14 +940,26 @@ function buildClaudeAgentExecCommand(template, prompt, options = {}) {
     if (model) {
         flagSpecs.push({ flag: `--model ${quoteBashSingleValue(model)}`, pattern: /(?:^|\s)--model(?:\s|$)/ });
     }
+    // 子 Agent 说的话和思考默认不转发（v2.1.211+ 才有 --forward-subagent-text，旧版本不认这个参数会直接报错）。
+    // 'auto'：在容器里随命令探测（claude --help 约 50ms），支持就展开成这个参数、不支持展开成空；true：直接加。
+    // 'auto' 的参数放在整条命令末尾，不改变前面已有参数的相对顺序
+    const forwardSubagentText = options && options.forwardSubagentText;
+    const templateHasForward = /(?:^|\s)--forward-subagent-text(?:\s|$)/.test(templateText);
+    if (forwardSubagentText === true) {
+        flagSpecs.push({ flag: '--forward-subagent-text', pattern: /(?:^|\s)--forward-subagent-text(?:\s|$)/ });
+    }
     const claudeTemplate = prependAgentFlags(
         templateText,
         /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)claude\b)(.*)$/,
         flagSpecs
     );
-    return claudeTemplate === templateText
+    const rendered = claudeTemplate === templateText
         ? renderAgentPromptCommand(templateText, prompt)
         : renderAgentPromptCommand(claudeTemplate, prompt);
+    if (forwardSubagentText === 'auto' && !templateHasForward) {
+        return `MANYOYO_FWD_SUBAGENT="$(claude --help 2>&1 | grep -q -- '--forward-subagent-text' && echo --forward-subagent-text)"; ${rendered} $MANYOYO_FWD_SUBAGENT`;
+    }
+    return rendered;
 }
 
 function buildGeminiAgentExecCommand(template, prompt, options = {}) {
@@ -1043,7 +1062,7 @@ function extractClaudeAgentMessage(text) {
     let lastMessage = '';
     for (const rawLine of String(text || '').split('\n')) {
         const payload = parseJsonObjectLine(rawLine);
-        if (!payload || payload.type !== 'assistant') {
+        if (!payload || payload.type !== 'assistant' || pickFirstString(payload.parent_tool_use_id)) {
             continue;
         }
         const message = toPlainObject(payload.message);
@@ -1594,7 +1613,21 @@ function createStructuredTraceEvent(provider, kind, eventType, textValue, extra
     };
 }
 
+// 派生子 Agent 的工具：v2.1.63 起叫 Agent，旧名字 Task 仍是别名，两个都认
+const CLAUDE_SUBAGENT_TOOL_NAMES = new Set(['Agent', 'Task']);
+
+// 子 Agent 里的 assistant / user 消息带 parent_tool_use_id（发起它的那次 Agent 调用的 id），主对话里是 null。
+// 只给事件加 parentToolId 字段，不改已有字段的含义
 function prepareClaudeTraceEvents(payload, state) {
+    const events = prepareClaudeTraceEventsBase(payload, state);
+    const parentToolId = pickFirstString(payload && payload.parent_tool_use_id);
+    if (parentToolId) {
+        events.forEach(event => { event.parentToolId = parentToolId; });
+    }
+    return events;
+}
+
+function prepareClaudeTraceEventsBase(payload, state) {
     const eventType = pickFirstString(payload.type);
     const subtype = pickFirstString(payload.subtype);
     const message = toPlainObject(payload.message);
@@ -1632,6 +1665,23 @@ function prepareClaudeTraceEvents(payload, state) {
                 if (toolId) {
                     toolNamesById.set(toolId, toolName);
                 }
+                if (CLAUDE_SUBAGENT_TOOL_NAMES.has(toolName)) {
+                    const input = toPlainObject(item.input);
+                    const subagentType = pickFirstString(input.subagent_type, input.name);
+                    const description = pickFirstString(input.description, input.name);
+                    events.push(createStructuredTraceEvent('claude', 'subagent', eventType, `[子 Agent] ${[subagentType, description].filter(Boolean).join(' ') || toolName}`, {
+                        phase: 'started',
+                        status: 'in_progress',
+                        toolName,
+                        toolId,
+                        subagentType,
+                        description,
+                        prompt: pickFirstString(input.prompt),
+                        arguments: input,
+                        argumentSummary: summarizeTraceArguments(input)
+                    }));
+                    return;
+                }
                 const summary = summarizeTraceArguments(toPlainObject(item.input));
                 events.push(createStructuredTraceEvent(
                     'claude',
@@ -1659,7 +1709,7 @@ function prepareClaudeTraceEvents(payload, state) {
             const toolId = pickFirstString(item.tool_use_id);
             const toolName = pickFirstString(toolNamesById.get(toolId), toolId, 'tool');
             const status = item.is_error === true ? 'error' : 'success';
-            events.push(createStructuredTraceEvent('claude', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
+            events.push(createStructuredTraceEvent('claude', CLAUDE_SUBAGENT_TOOL_NAMES.has(toolName) ? 'subagent' : 'tool', eventType, `[${CLAUDE_SUBAGENT_TOOL_NAMES.has(toolName) ? '子 Agent 完成' : '工具完成'}] ${toolName} (${status})`, {
                 phase: 'completed',
                 status,
                 toolName,
@@ -1867,6 +1917,9 @@ function extractContentDeltaFromPayload(agentProgram, payload, state = {}) {
         // 一轮里可能有多条 assistant 消息（正文→工具→正文），message_start 清空累计，
         // 语义与下面整条 assistant 消息的 reset 一致
         if (payloadType === 'stream_event') {
+            if (pickFirstString(payload.parent_tool_use_id)) {
+                return null;
+            }
             const streamEvent = toPlainObject(payload.event);
             const streamEventType = pickFirstString(streamEvent.type);
             if (streamEventType === 'message_start') {
@@ -1890,6 +1943,10 @@ function extractContentDeltaFromPayload(agentProgram, payload, state = {}) {
         if (payloadType !== 'assistant') {
             return null;
         }
+        // 子 Agent 说的话（--forward-subagent-text）只属于执行过程，不是主 Agent 的回复
+        if (pickFirstString(payload.parent_tool_use_id)) {
+            return null;
+        }
         const message = toPlainObject(payload.message);
         const content = Array.isArray(message.content) ? message.content : [];
         const text = content
@@ -2215,7 +2272,8 @@ async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
         : buildAgentPromptWithHistory(agentSession, prompt);
     const command = buildWebAgentExecCommand(effectiveTemplate, effectivePrompt, agentMeta.agentProgram, {
         sessionId: sessionIdForRun,
-        model: agentSession.model || ''
+        model: agentSession.model || '',
+        forwardSubagentText: agentMeta.agentProgram === 'claude' ? 'auto' : false
     });
     const contextMode = resumeSucceeded ? 'resume' : (hasPriorConversation ? 'history-injected' : 'first-turn');
 
@@ -3498,6 +3556,7 @@ async function startContainerServices(ctx, state) {
     const reconcile = () => reconcileContainerServices(ctx, state, manager);
     state.networkWatch = manager.watchStarts({ onReconnect: reconcile });
     await reconcile();
+    resumeQueuedAgentTurns(ctx, state).catch(() => {});
 }
 
 // 拉起 autostartOnServe 的容器并恢复端口暴露：serve 启动时做一次，运行时重启后（事件流重连）再做一次，幂等
@@ -4151,7 +4210,8 @@ async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerNa
         process = spawnContainerExec(
             ctx,
             sessionRef.containerName,
-            { command: ['/bin/bash', '-lc', command] },
+            // 包一层：新会话 + MANYOYO_RUN_ID + PID 文件，停止 / 打断时才能进到容器里按进程组发信号
+            { command: ['/bin/bash', '-lc', agentRunControl.wrapAgentCommand(command, runState.runId)] },
             { stdio: ['ignore', 'pipe', 'pipe'] }
         );
     } catch (e) {
@@ -4166,11 +4226,7 @@ async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerNa
     state.agentRuns.set(sessionRef.containerName, runState);
     // 准备阶段（拉起容器等）用户就点了停止：进程刚 spawn 出来立刻收掉
     if (runState.stopping === true) {
-        try {
-            process.kill('SIGTERM');
-        } catch (e) {
-            // 进程可能已经退出，忽略
-        }
+        terminateWebAgentRun(ctx, runState);
     }
 
     return await new Promise((resolve, reject) => {
@@ -4290,10 +4346,12 @@ async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerNa
 
         process.on('error', error => {
             releaseWebAgentRun(state, sessionRef.containerName, runState);
+            runState.markClosed();
             reject(error);
         });
         process.on('close', code => {
             releaseWebAgentRun(state, sessionRef.containerName, runState);
+            runState.markClosed();
             if (stdoutPending) {
                 emitStdoutTraceLine(stdoutPending);
                 stdoutPending = '';
@@ -4313,7 +4371,8 @@ async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerNa
                 exitCode,
                 output,
                 stdout: clippedStdout,
-                interrupted: exitCode !== 0 && runState.stopping === true
+                // 真实的 claude 收到 SIGINT 会正常收尾、退出码为 0（L3 实测）：发过信号就算被打断，不能只看退出码
+                interrupted: runState.stopping === true && (exitCode !== 0 || runState.signaled === true)
             });
         });
     });
@@ -4361,15 +4420,16 @@ function readClientMessageId(res, payload) {
 
 // 同一个 clientMessageId 已经出现在该 agent 的消息里：这条提示词服务端已经收到过，不能再执行一遍
 // （前端在网络中断后重发同一条时，靠它兜住“服务端其实已经收到”的情况）
-function rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId) {
+function rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId, options = {}) {
     if (!clientMessageId) {
         return false;
     }
     const history = loadWebSessionHistory(webHistoryDir, sessionRef.containerName);
     const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
-    const duplicated = Boolean(agentSession) && agentSession.messages.some(
+    // includeQueue：排队中的也算收到过（追加请求网络中断后，前端把原文放回输入框再发，不能执行两次）
+    const duplicated = Boolean(agentSession) && (agentSession.messages.some(
         message => message && message.role === 'user' && message.clientMessageId === clientMessageId
-    );
+    ) || (options.includeQueue === true && agentQueue.getQueue(agentSession).some(item => item.clientMessageId === clientMessageId)));
     if (!duplicated) {
         return false;
     }
@@ -4385,7 +4445,7 @@ function claimClientMessage(res, webHistoryDir, sessionRef, clientMessageId) {
     if (!clientMessageId) {
         return () => {};
     }
-    if (rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId)) {
+    if (rejectDuplicateClientMessage(res, webHistoryDir, sessionRef, clientMessageId, { includeQueue: true })) {
         return null;
     }
     const key = `${path.resolve(webHistoryDir)}|${buildWebSessionKey(sessionRef.containerName, sessionRef.agentId)}|${clientMessageId}`;
@@ -4502,12 +4562,18 @@ function resolveWebStreamControlEventType(event) {
 function reserveWebAgentRun(state, sessionRef) {
     const runState = {
         containerName: sessionRef.containerName,
+        sessionRef: { containerName: sessionRef.containerName, agentId: sessionRef.agentId },
         sessionKey: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
         process: null,
         command: '',
         startedAt: new Date().toISOString(),
-        stopping: false
+        stopping: false,
+        // 进程 close 时 resolve：停止 / 打断时据此判断容器里的进程有没有退出（见 agent-run-control.js）
+        runId: agentRunControl.createRunId(),
+        closed: null,
+        markClosed: null
     };
+    runState.closed = new Promise(resolve => { runState.markClosed = resolve; });
     state.agentRuns.set(sessionRef.containerName, runState);
     return runState;
 }
@@ -4519,11 +4585,172 @@ function releaseWebAgentRun(state, containerName, runState) {
     }
 }
 
-function stopWebAgentRun(state, containerName) {
+// 追加提示词时打断当前这一轮（立即 / 当前步骤结束后 / 步骤超时）：和用户停止一样走进程组信号，
+// 区别是不置 userStopped，这一轮结束后会接着发队首
+function steerWebAgentRun(ctx, runState, reason, state = null) {
+    if (!runState || runState.steered || runState.stopping) {
+        return false;
+    }
+    // 排队的 now / step 项已被取消：不要白白打断正在跑的任务
+    if (state && !queueHasSteerItems(state, runState.sessionRef)) {
+        clearTimeout(runState.stepTimer);
+        runState.stepPending = false;
+        return false;
+    }
+    clearTimeout(runState.stepTimer);
+    runState.steered = reason;
+    runState.stopping = true;
+    if (runState.process) {
+        terminateWebAgentRun(ctx, runState);
+    }
+    return true;
+}
+
+function queueHasSteerItems(state, sessionRef) {
+    return peekAgentQueue(state, sessionRef).some(item => item.when === 'now' || item.when === 'step');
+}
+
+function armStepSteer(ctx, state, runState) {
+    if (runState.steered || runState.stopping || runState.stepPending) {
+        return;
+    }
+    runState.stepPending = true;
+    runState.stepTimer = setTimeout(() => {
+        if (steerWebAgentRun(ctx, runState, 'step-timeout', state)) {
+            ctx.logger.warn('agent steer step fallback to now', { session: runState.sessionKey });
+        }
+    }, ctx.agentStepFallbackMs || agentQueue.STEP_FALLBACK_MS);
+    if (typeof runState.stepTimer.unref === 'function') {
+        runState.stepTimer.unref();
+    }
+}
+
+// 没有前端连着时顶替 res：事件照常落盘，只是没人收
+function createHeadlessResponse() {
+    const sink = new EventEmitter();
+    sink.writableEnded = false;
+    sink.writableFinished = false;
+    sink.destroyed = false;
+    sink.writeHead = () => {};
+    sink.write = () => true;
+    sink.end = () => {
+        sink.writableEnded = true;
+        sink.writableFinished = true;
+        sink.emit('close');
+    };
+    return sink;
+}
+
+function peekAgentSession(state, sessionRef) {
+    const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+    return getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+}
+
+function peekAgentQueue(state, sessionRef) {
+    const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    return agentSession && Array.isArray(agentSession.queue) ? agentSession.queue : [];
+}
+
+// 同步取出队首并开始新一轮（取出和占锁之间没有 await，提示词不会丢也不会重复发）。
+// 开不起来（容器忙、准备失败）就放回队首，由用户决定
+// force：用户点了“继续发送”，解除暂停后发；其余（自动调度）遇到暂停的队列不发
+function dispatchNextQueued(ctx, state, sessionRef, { force = false } = {}) {
+    if (state.agentRuns.has(sessionRef.containerName)) {
+        return false;
+    }
+    const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+    const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+    if (!agentSession || !agentQueue.getQueue(agentSession).length) {
+        return false;
+    }
+    if (force) {
+        agentQueue.resumeQueue(agentSession);
+    } else if (agentQueue.isPaused(agentSession)) {
+        return false;
+    }
+    const item = agentQueue.takeNext(agentSession);
+    saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
+    const putBack = reason => {
+        const latest = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+        const latestSession = getWebAgentSession(latest, sessionRef.agentId, { includeArchived: true });
+        if (latestSession) {
+            agentQueue.getQueue(latestSession).unshift(item);
+            saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, latest);
+        }
+        ctx.logger.warn('queued prompt put back', { session: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), reason });
+    };
+    runWebAgentStreamTurn(ctx, state, sessionRef, item.text, item.clientMessageId || '', createHeadlessResponse())
+        .then(turn => {
+            if (turn && turn.busy) putBack('busy');
+            else if (turn && turn.error) putBack(turn.error);
+        })
+        .catch(e => putBack(e && e.message ? e.message : 'failed'));
+    return true;
+}
+
+// 容器里还活着的运行 id（上一个 serve 留下的孤儿任务，或另一个 serve 实例正在跑的任务）；读不到当作没有
+function listLiveRunsInContainer(ctx, containerName) {
+    return new Promise(resolve => {
+        let child;
+        try {
+            child = spawnContainerExec(ctx, containerName, { command: agentRunControl.buildLiveRunsCommand() }, { stdio: ['ignore', 'pipe', 'ignore'] });
+        } catch (e) {
+            resolve([]);
+            return;
+        }
+        let out = '';
+        child.stdout.on('data', chunk => { out += chunk; });
+        child.once('close', () => resolve(out.split('\n').map(line => line.trim()).filter(agentRunControl.isValidRunId)));
+        child.once('error', () => resolve([]));
+    });
+}
+
+// serve 重启后：队列里还有内容（用户停止过的除外）、又没有在跑的任务，就当作“这一轮结束后发送”处理。
+// 容器里还有活着的 Agent 进程时不发：那是上一个 serve 留下的孤儿任务或另一个 serve 实例的任务，
+// 再开一轮会和它并发；排队保留，由用户在界面上“继续发送”
+async function resumeQueuedAgentTurns(ctx, state) {
+    let containers = {};
+    try {
+        containers = listWebManyoyoContainers(ctx);
+    } catch (e) {
+        return;
+    }
+    for (const containerName of Object.keys(containers)) {
+        const history = loadWebSessionHistory(state.webHistoryDir, containerName);
+        const agentIds = Object.keys(history.agents || {}).filter(agentId => agentQueue.shouldAutoDispatch(history.agents[agentId]));
+        if (!agentIds.length) {
+            continue;
+        }
+        const live = await listLiveRunsInContainer(ctx, containerName);
+        if (live.length) {
+            ctx.logger.warn('queued prompts kept: agent still running in container', { container: containerName, runs: live.length });
+            continue;
+        }
+        for (const agentId of agentIds) {
+            dispatchNextQueued(ctx, state, { containerName, agentId });
+        }
+    }
+}
+
+// signals：默认 INT → TERM → KILL（用户点停止）；ctx 缺省时退回只杀宿主机上的客户端
+function stopWebAgentRun(state, containerName, ctx = null) {
     const runState = state.agentRuns.get(containerName);
     if (!runState) {
         return false;
     }
+    // 用户主动停止：排队的提示词不再自动发送（队列保留，由用户决定取消或继续）。
+    // 暂停要落盘：只记在这一轮的内存里的话，serve 重启或下一轮结束后会被自动发出去
+    runState.userStopped = true;
+    if (runState.sessionRef) {
+        const history = loadWebSessionHistory(state.webHistoryDir, runState.sessionRef.containerName);
+        const agentSession = getWebAgentSession(history, runState.sessionRef.agentId, { includeArchived: true });
+        if (agentSession && agentQueue.getQueue(agentSession).length && !agentQueue.isPaused(agentSession)) {
+            agentQueue.pauseQueue(agentSession);
+            saveWebSessionHistory(state.webHistoryDir, runState.sessionRef.containerName, history);
+        }
+    }
+    clearTimeout(runState.stepTimer);
     if (!runState.process) {
         // 还在准备阶段（拉起容器 / 探测 resume），进程尚未 spawn：先记下停止意图，
         // execAgentInWebContainerStream 拿到进程后会立刻收掉它
@@ -4534,14 +4761,42 @@ function stopWebAgentRun(state, containerName) {
         return false;
     }
     runState.stopping = true;
-    try {
-        runState.process.kill('SIGTERM');
-    } catch (e) {
-        // 进程可能已自行退出，视为停止成功（close 事件会收尾）
+    if (!ctx) {
+        try {
+            runState.process.kill('SIGTERM');
+        } catch (e) {
+            // 进程可能已自行退出，视为停止成功（close 事件会收尾）
+        }
+        return true;
     }
+    terminateWebAgentRun(ctx, runState);
     return true;
 }
 
+// 进到容器里按进程组停：只杀宿主机上的 exec 客户端，容器里的进程会继续跑（实测）
+function terminateWebAgentRun(ctx, runState) {
+    if (runState.terminating) {
+        return runState.terminating;
+    }
+    runState.terminating = agentRunControl.terminateRun({
+        runState,
+        graceMs: ctx.agentStopGraceMs || agentRunControl.DEFAULT_GRACE_MS,
+        killInContainer: (runId, signal) => new Promise(resolve => {
+            runState.signaled = true;
+            let child;
+            try {
+                child = spawnContainerExec(ctx, runState.containerName, { command: agentRunControl.buildRunKillCommand(runId, signal) }, { stdio: 'ignore' });
+            } catch (e) {
+                resolve();
+                return;
+            }
+            child.once('close', resolve);
+            child.once('error', resolve);
+        })
+    }).catch(() => {});
+    return runState.terminating;
+}
+
 // serve 重启等原因会丢失 agentRuns 运行登记，但消息里可能残留 pending 标记
 // （孤儿任务：容器里的进程或许还在跑，但再没有任何代码会去收尾这些消息）。
 // 前端把 pending 视为"任务进行中"会永久禁用输入，这里把它们标记为已中断
@@ -4568,6 +4823,310 @@ function interruptOrphanPendingMessages(webHistoryDir, sessionRef) {
     saveWebSessionHistory(webHistoryDir, sessionRef.containerName, history);
 }
 
+// 一轮 agent 对话的完整流程（占锁 → 落盘 → 执行 → 收尾）。res 是 NDJSON 响应；
+// 排队的提示词在没有前端连接时由 createHeadlessResponse() 顶替，事件照常落盘。
+// 返回 { busy } / { error }（没开始）或 { started: true }（跑完了）
+async function runWebAgentStreamTurn(ctx, state, sessionRef, prompt, clientMessageId, res) {
+    if (state.agentRuns.has(sessionRef.containerName)) {
+        // 锁是容器级的：同一容器里其他 agent 会话在跑任务时同样命中这里
+        return { busy: true };
+    }
+    // 紧接着检查同步占位，中间不能有 await，否则并发请求会同时穿过上面这道检查
+    const runState = reserveWebAgentRun(state, sessionRef);
+
+    let userMessage;
+    let traceMessage;
+    try {
+        userMessage = appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
+            mode: 'agent',
+            pending: true,
+            ...(clientMessageId ? { clientMessageId: clientMessageId } : {})
+        });
+        traceMessage = appendWebAgentTraceMessage(
+            state.webHistoryDir,
+            sessionRef,
+            '[执行过程]\n等待 Agent 启动…',
+            {
+                traceEvents: [],
+                pending: true
+            }
+        );
+    } catch (e) {
+        // 落盘失败（磁盘错误等）：锁必须放掉，否则这个容器永远发不出消息
+        releaseWebAgentRun(state, sessionRef.containerName, runState);
+        throw e;
+    }
+
+    let prepared = null;
+    try {
+        prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
+    } catch (e) {
+        releaseWebAgentRun(state, sessionRef.containerName, runState);
+        removeWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id);
+        removeWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id);
+        return { error: e && e.message ? e.message : 'Agent 执行准备失败' };
+    }
+
+    const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError, engineSessionId } = prepared;
+    const traceLines = ['[执行过程]'];
+    const traceEvents = [];
+    let streamingReplyMessageId = '';
+    patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
+        pending: true,
+        contextMode
+    });
+
+    res.writeHead(200, {
+        'Content-Type': 'application/x-ndjson; charset=utf-8',
+        'Cache-Control': 'no-store',
+        'X-Accel-Buffering': 'no'
+    });
+    // agent 流的生命周期日志：每轮最多三条（开始 / 客户端断开 / 结束），
+    // 不是逐事件打点。没有这几条的话，用户报"跑到一半断流了"时服务端
+    // 日志里查不到任何痕迹——断连本身只发生在客户端侧，服务端不主动感知
+    const turnStartedAt = Date.now();
+    const turnSessionKey = buildWebSessionKey(sessionRef.containerName, sessionRef.agentId);
+    ctx.logger.info('agent turn started', {
+        session: turnSessionKey,
+        agentProgram: agentMeta.agentProgram,
+        contextMode,
+        resumeAttempted,
+        resumeSucceeded
+    });
+    // 'close' 先于 'finish' 触发且 writableFinished 仍为 false，说明是
+    // 客户端/反代把连接掐了，而不是我们正常收尾。此时容器里的任务还在跑，
+    // 前端会转入恢复轮询——日志要把这个区别写清楚，否则事后无法归因
+    res.on('close', () => {
+        if (res.writableFinished) {
+            return;
+        }
+        ctx.logger.warn('agent stream client disconnected', {
+            session: turnSessionKey,
+            elapsedMs: Date.now() - turnStartedAt,
+            runContinues: state.agentRuns.has(sessionRef.containerName)
+        });
+    });
+    // agent 可能几十秒不产生任何输出（长 WebSearch、长 Bash、长思考），
+    // 而反向代理按"上游多久没发字节"计空闲超时（nginx proxy_read_timeout
+    // 默认 60s），超时会 RST 掉这条流，浏览器侧抛 network error。这里定期
+    // 发一行 ping 保活；前端忽略该事件，也不写入会话事件日志
+    const heartbeatMs = ctx.agentStreamHeartbeatMs || DEFAULT_AGENT_STREAM_HEARTBEAT_MS;
+    let lastStreamWriteAt = Date.now();
+    const heartbeatTimer = setInterval(() => {
+        if (res.writableEnded || res.destroyed) {
+            return;
+        }
+        if (Date.now() - lastStreamWriteAt < heartbeatMs) {
+            return;
+        }
+        sendNdjson(res, { type: 'ping' });
+        lastStreamWriteAt = Date.now();
+    }, Math.max(50, Math.floor(heartbeatMs / 2)));
+    if (typeof heartbeatTimer.unref === 'function') {
+        heartbeatTimer.unref();
+    }
+    const rawEmitStreamEvent = createWebStreamEmitter(res, state.webHistoryDir, sessionRef);
+    const emitStreamEvent = (...args) => {
+        lastStreamWriteAt = Date.now();
+        return rawEmitStreamEvent(...args);
+    };
+    emitStreamEvent({
+        type: 'meta',
+        containerName: sessionRef.containerName,
+        sessionName: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
+        // 前端用这两个 id 把本地乐观占位（local-* / __streaming_trace__）换成
+        // 服务端持久化 id，轮询对账时 React key 才能对得上、DOM 不整体重建
+        userMessageId: userMessage && userMessage.id,
+        traceMessageId: traceMessage && traceMessage.id,
+        contextMode,
+        resumeAttempted,
+        resumeSucceeded,
+        agentProgram: agentMeta.agentProgram
+    }, 'session.ready', { agentProgram: agentMeta.agentProgram });
+    if (contextMode) {
+        traceLines.push(`上下文模式: ${contextMode}`);
+    }
+    if (resumeAttempted) {
+        traceLines.push(resumeSucceeded ? '会话恢复成功' : '会话恢复失败，已回退到历史注入');
+    }
+    patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
+        content: traceLines.join('\n'),
+        traceEvents: traceEvents.slice(),
+        contextMode,
+        resumeAttempted,
+        resumeSucceeded,
+        pending: true
+    });
+
+    let lastPartialPersistAt = 0;
+    const handleStreamEvent = event => {
+        if (runState.stepPending && agentQueue.isStepBoundary(event)) {
+            steerWebAgentRun(ctx, runState, 'step', state);
+        }
+        // token 级增量：只走网线，不进事件日志，历史落盘按
+        // AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS 节流
+        const isPartialDelta = event && event.type === 'content_delta' && event.partial === true;
+        if (event && event.type === 'trace' && event.text) {
+            traceLines.push(String(event.text));
+            if (event.traceEvent && typeof event.traceEvent === 'object') {
+                traceEvents.push(event.traceEvent);
+            }
+            patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
+                content: traceLines.join('\n'),
+                traceEvents: traceEvents.slice(),
+                pending: true
+            }, { defer: true });
+        }
+        if (event && event.type === 'content_delta' && typeof event.content === 'string') {
+            const now = Date.now();
+            const shouldPersist = !isPartialDelta
+                || now - lastPartialPersistAt >= AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS;
+            if (!streamingReplyMessageId) {
+                const streamingReplyMessage = appendWebSessionMessage(
+                    state.webHistoryDir,
+                    sessionRef,
+                    'assistant',
+                    event.content,
+                    {
+                        mode: 'agent',
+                        streamingReply: true,
+                        pending: true
+                    }
+                );
+                streamingReplyMessageId = streamingReplyMessage && streamingReplyMessage.id
+                    ? streamingReplyMessage.id
+                    : '';
+                lastPartialPersistAt = now;
+            } else if (shouldPersist) {
+                patchWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId, {
+                    content: event.content,
+                    pending: true
+                }, { defer: true });
+                lastPartialPersistAt = now;
+            }
+        }
+        if (isPartialDelta) {
+            lastStreamWriteAt = Date.now();
+            // 只发增量片段：前端在 content_chunk 上做追加，
+            // reset 表示换了一条 assistant 消息、从空白重新开始
+            sendNdjson(res, event.chunkReset === true
+                ? { type: 'content_chunk', text: '', reset: true }
+                : { type: 'content_chunk', text: event.chunk });
+            return;
+        }
+        emitStreamEvent(event, resolveWebStreamControlEventType(event), {
+            transportType: event && event.type ? event.type : '',
+            text: event && (event.text || event.content) ? String(event.text || event.content) : ''
+        });
+
+    };
+    // 有域名规则时被过滤代理拦下的新域名：对话进行中立即提示一次
+    const deniedNotifier = createWebDeniedNotifier(ctx, sessionRef, text => handleStreamEvent({ type: 'trace', stream: 'stdout', text }));
+    try {
+        if (deniedNotifier) deniedNotifier.start();
+        let result;
+        try {
+            result = await execAgentInWebContainerStream(ctx, state, sessionRef, command, {
+                agentProgram: agentMeta.agentProgram,
+                // 复用路由入口占好的那把锁，而不是另起一份运行登记
+                runState,
+                onEvent: handleStreamEvent
+            });
+        } finally {
+            if (deniedNotifier) deniedNotifier.stop();
+        }
+        ctx.logger.info('agent turn finished', {
+            session: turnSessionKey,
+            durationMs: Date.now() - turnStartedAt,
+            exitCode: result.exitCode,
+            interrupted: result.interrupted === true
+        });
+        traceLines.push(result.interrupted === true
+            ? (runState.steered && runState.userStopped !== true ? '[任务] 已打断，继续执行新的提示词' : '[任务] 已停止')
+            : '[任务] 已完成');
+        patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
+            pending: false,
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded
+        });
+        patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
+            content: traceLines.join('\n'),
+            traceEvents,
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded,
+            interrupted: result.interrupted === true,
+            pending: false
+        });
+        if (streamingReplyMessageId) {
+            removeWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId);
+        }
+        const replyMessage = finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded,
+            resumeError,
+            engineSessionId
+        }, result);
+        emitStreamEvent({
+            type: 'result',
+            exitCode: result.exitCode,
+            output: result.output,
+            // 最终 assistant 消息的持久化 id：前端把 __streaming__ 占位换成它，
+            // 发送后的首次对账才不会重建整个消息列表 DOM（滚动位置/选区保持）
+            replyMessageId: replyMessage && replyMessage.id,
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded,
+            interrupted: result.interrupted === true
+        }, result.interrupted === true ? 'process.interrupted' : 'process.exited', { exitCode: result.exitCode });
+    } catch (e) {
+        ctx.logger.error('agent turn failed', {
+            session: turnSessionKey,
+            durationMs: Date.now() - turnStartedAt,
+            message: e && e.message ? e.message : 'Agent 执行失败'
+        });
+        traceLines.push(`[错误] ${e && e.message ? e.message : 'Agent 执行失败'}`);
+        patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
+            pending: false,
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded
+        });
+        patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
+            content: traceLines.join('\n'),
+            traceEvents,
+            contextMode,
+            resumeAttempted,
+            resumeSucceeded,
+            interrupted: true,
+            pending: false
+        });
+        if (streamingReplyMessageId) {
+            removeWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId);
+        }
+        emitStreamEvent({
+            type: 'error',
+            error: e && e.message ? e.message : 'Agent 执行失败'
+        }, 'agent.turn.failed', { error: e && e.message ? e.message : 'Agent 执行失败' });
+    } finally {
+        clearInterval(heartbeatTimer);
+        clearTimeout(runState.stepTimer);
+        // 用户停止的不自动发；其余（完成 / 失败 / 被追加打断）有排队就接着发队首
+        const hasNext = runState.userStopped !== true && agentQueue.shouldAutoDispatch(peekAgentSession(state, sessionRef));
+        if (hasNext && !res.writableEnded && !res.destroyed) {
+            // 前端收到后改为跟随下一轮（走掉线恢复的那套轮询）
+            sendNdjson(res, { type: 'queue_next' });
+        }
+        res.end();
+        if (hasNext) {
+            setImmediate(() => dispatchNextQueued(ctx, state, sessionRef));
+        }
+    }
+    return { started: true };
+}
+
 function sendHtml(res, statusCode, html, extraHeaders = {}, options = {}) {
     sendBody(res, statusCode, 'text/html; charset=utf-8', html, extraHeaders, options);
 }
@@ -6143,6 +6702,8 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                     name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
                     containerName: sessionRef.containerName,
                     agentId: sessionRef.agentId,
+                    queue: agentQueue.publicQueue(agentSession),
+                    queuePaused: agentQueue.isPaused(agentSession),
                     ...view
                 }, {}, { etag });
             }
@@ -6689,285 +7250,109 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 if (!streamClientId) {
                     return;
                 }
-                if (rejectDuplicateClientMessage(res, state.webHistoryDir, sessionRef, streamClientId.value)) {
+                if (rejectDuplicateClientMessage(res, state.webHistoryDir, sessionRef, streamClientId.value, { includeQueue: true })) {
                     return;
                 }
-                if (state.agentRuns.has(sessionRef.containerName)) {
-                    // 锁是容器级的：同一容器里其他 agent 会话在跑任务时同样命中这里
+                const turn = await runWebAgentStreamTurn(ctx, state, sessionRef, prompt, streamClientId.value, res);
+                if (turn.busy) {
                     sendJson(res, 409, { error: '当前容器已有运行中的 agent 任务，请等它结束或先停止' });
+                } else if (turn.error) {
+                    sendJson(res, 400, { error: turn.error });
+                }
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/queue$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
                     return;
                 }
-                // 紧接着检查同步占位，中间不能有 await，否则并发请求会同时穿过上面这道检查
-                const runState = reserveWebAgentRun(state, sessionRef);
-
-                const userMessage = appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
-                    mode: 'agent',
-                    pending: true,
-                    ...(streamClientId.value ? { clientMessageId: streamClientId.value } : {})
-                });
-                const traceMessage = appendWebAgentTraceMessage(
-                    state.webHistoryDir,
-                    sessionRef,
-                    '[执行过程]\n等待 Agent 启动…',
-                    {
-                        traceEvents: [],
-                        pending: true
-                    }
-                );
-
-                let prepared = null;
-                try {
-                    prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
-                } catch (e) {
-                    releaseWebAgentRun(state, sessionRef.containerName, runState);
-                    removeWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id);
-                    removeWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id);
-                    sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
+                const payload = await readJsonBody(req);
+                const text = (payload.prompt || '').trim();
+                if (!text) {
+                    sendJson(res, 400, { error: 'prompt 不能为空' });
                     return;
                 }
-
-                const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError, engineSessionId } = prepared;
-                const traceLines = ['[执行过程]'];
-                const traceEvents = [];
-                let streamingReplyMessageId = '';
-                patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
-                    pending: true,
-                    contextMode
-                });
-
-                res.writeHead(200, {
-                    'Content-Type': 'application/x-ndjson; charset=utf-8',
-                    'Cache-Control': 'no-store',
-                    'X-Accel-Buffering': 'no'
-                });
-                // agent 流的生命周期日志：每轮最多三条（开始 / 客户端断开 / 结束），
-                // 不是逐事件打点。没有这几条的话，用户报"跑到一半断流了"时服务端
-                // 日志里查不到任何痕迹——断连本身只发生在客户端侧，服务端不主动感知
-                const turnStartedAt = Date.now();
-                const turnSessionKey = buildWebSessionKey(sessionRef.containerName, sessionRef.agentId);
-                ctx.logger.info('agent turn started', {
-                    session: turnSessionKey,
-                    agentProgram: agentMeta.agentProgram,
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded
-                });
-                // 'close' 先于 'finish' 触发且 writableFinished 仍为 false，说明是
-                // 客户端/反代把连接掐了，而不是我们正常收尾。此时容器里的任务还在跑，
-                // 前端会转入恢复轮询——日志要把这个区别写清楚，否则事后无法归因
-                res.on('close', () => {
-                    if (res.writableFinished) {
-                        return;
-                    }
-                    ctx.logger.warn('agent stream client disconnected', {
-                        session: turnSessionKey,
-                        elapsedMs: Date.now() - turnStartedAt,
-                        runContinues: state.agentRuns.has(sessionRef.containerName)
-                    });
-                });
-                // agent 可能几十秒不产生任何输出（长 WebSearch、长 Bash、长思考），
-                // 而反向代理按"上游多久没发字节"计空闲超时（nginx proxy_read_timeout
-                // 默认 60s），超时会 RST 掉这条流，浏览器侧抛 network error。这里定期
-                // 发一行 ping 保活；前端忽略该事件，也不写入会话事件日志
-                const heartbeatMs = ctx.agentStreamHeartbeatMs || DEFAULT_AGENT_STREAM_HEARTBEAT_MS;
-                let lastStreamWriteAt = Date.now();
-                const heartbeatTimer = setInterval(() => {
-                    if (res.writableEnded || res.destroyed) {
-                        return;
-                    }
-                    if (Date.now() - lastStreamWriteAt < heartbeatMs) {
-                        return;
-                    }
-                    sendNdjson(res, { type: 'ping' });
-                    lastStreamWriteAt = Date.now();
-                }, Math.max(50, Math.floor(heartbeatMs / 2)));
-                if (typeof heartbeatTimer.unref === 'function') {
-                    heartbeatTimer.unref();
-                }
-                const rawEmitStreamEvent = createWebStreamEmitter(res, state.webHistoryDir, sessionRef);
-                const emitStreamEvent = (...args) => {
-                    lastStreamWriteAt = Date.now();
-                    return rawEmitStreamEvent(...args);
-                };
-                emitStreamEvent({
-                    type: 'meta',
-                    containerName: sessionRef.containerName,
-                    sessionName: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
-                    // 前端用这两个 id 把本地乐观占位（local-* / __streaming_trace__）换成
-                    // 服务端持久化 id，轮询对账时 React key 才能对得上、DOM 不整体重建
-                    userMessageId: userMessage && userMessage.id,
-                    traceMessageId: traceMessage && traceMessage.id,
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded,
-                    agentProgram: agentMeta.agentProgram
-                }, 'session.ready', { agentProgram: agentMeta.agentProgram });
-                if (contextMode) {
-                    traceLines.push(`上下文模式: ${contextMode}`);
+                const when = agentQueue.normalizeWhen(payload.when === undefined ? 'turn' : payload.when);
+                if (!when) {
+                    sendJson(res, 400, { error: 'when 只能是 now、step 或 turn' });
+                    return;
                 }
-                if (resumeAttempted) {
-                    traceLines.push(resumeSucceeded ? '会话恢复成功' : '会话恢复失败，已回退到历史注入');
+                const queueClientId = readClientMessageId(res, payload);
+                if (!queueClientId) {
+                    return;
                 }
-                patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
-                    content: traceLines.join('\n'),
-                    traceEvents: traceEvents.slice(),
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded,
-                    pending: true
-                });
-
-                let lastPartialPersistAt = 0;
-                const handleStreamEvent = event => {
-                    // token 级增量：只走网线，不进事件日志，历史落盘按
-                    // AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS 节流
-                    const isPartialDelta = event && event.type === 'content_delta' && event.partial === true;
-                    if (event && event.type === 'trace' && event.text) {
-                        traceLines.push(String(event.text));
-                        if (event.traceEvent && typeof event.traceEvent === 'object') {
-                            traceEvents.push(event.traceEvent);
-                        }
-                        patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
-                            content: traceLines.join('\n'),
-                            traceEvents: traceEvents.slice(),
-                            pending: true
-                        }, { defer: true });
-                    }
-                    if (event && event.type === 'content_delta' && typeof event.content === 'string') {
-                        const now = Date.now();
-                        const shouldPersist = !isPartialDelta
-                            || now - lastPartialPersistAt >= AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS;
-                        if (!streamingReplyMessageId) {
-                            const streamingReplyMessage = appendWebSessionMessage(
-                                state.webHistoryDir,
-                                sessionRef,
-                                'assistant',
-                                event.content,
-                                {
-                                    mode: 'agent',
-                                    streamingReply: true,
-                                    pending: true
-                                }
-                            );
-                            streamingReplyMessageId = streamingReplyMessage && streamingReplyMessage.id
-                                ? streamingReplyMessage.id
-                                : '';
-                            lastPartialPersistAt = now;
-                        } else if (shouldPersist) {
-                            patchWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId, {
-                                content: event.content,
-                                pending: true
-                            }, { defer: true });
-                            lastPartialPersistAt = now;
-                        }
-                    }
-                    if (isPartialDelta) {
-                        lastStreamWriteAt = Date.now();
-                        // 只发增量片段：前端在 content_chunk 上做追加，
-                        // reset 表示换了一条 assistant 消息、从空白重新开始
-                        sendNdjson(res, event.chunkReset === true
-                            ? { type: 'content_chunk', text: '', reset: true }
-                            : { type: 'content_chunk', text: event.chunk });
-                        return;
-                    }
-                    emitStreamEvent(event, resolveWebStreamControlEventType(event), {
-                        transportType: event && event.type ? event.type : '',
-                        text: event && (event.text || event.content) ? String(event.text || event.content) : ''
-                    });
-
-                };
-                // 有域名规则时被过滤代理拦下的新域名：对话进行中立即提示一次
-                const deniedNotifier = createWebDeniedNotifier(ctx, sessionRef, text => handleStreamEvent({ type: 'trace', stream: 'stdout', text }));
-                try {
-                    if (deniedNotifier) deniedNotifier.start();
-                    let result;
-                    try {
-                        result = await execAgentInWebContainerStream(ctx, state, sessionRef, command, {
-                            agentProgram: agentMeta.agentProgram,
-                            // 复用路由入口占好的那把锁，而不是另起一份运行登记
-                            runState,
-                            onEvent: handleStreamEvent
-                        });
-                    } finally {
-                        if (deniedNotifier) deniedNotifier.stop();
-                    }
-                    ctx.logger.info('agent turn finished', {
-                        session: turnSessionKey,
-                        durationMs: Date.now() - turnStartedAt,
-                        exitCode: result.exitCode,
-                        interrupted: result.interrupted === true
-                    });
-                    traceLines.push(result.interrupted === true ? '[任务] 已停止' : '[任务] 已完成');
-                    patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
-                        pending: false,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded
-                    });
-                    patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
-                        content: traceLines.join('\n'),
-                        traceEvents,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: result.interrupted === true,
-                        pending: false
-                    });
-                    if (streamingReplyMessageId) {
-                        removeWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId);
-                    }
-                    const replyMessage = finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        resumeError,
-                        engineSessionId
-                    }, result);
-                    emitStreamEvent({
-                        type: 'result',
-                        exitCode: result.exitCode,
-                        output: result.output,
-                        // 最终 assistant 消息的持久化 id：前端把 __streaming__ 占位换成它，
-                        // 发送后的首次对账才不会重建整个消息列表 DOM（滚动位置/选区保持）
-                        replyMessageId: replyMessage && replyMessage.id,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: result.interrupted === true
-                    }, result.interrupted === true ? 'process.interrupted' : 'process.exited', { exitCode: result.exitCode });
-                } catch (e) {
-                    ctx.logger.error('agent turn failed', {
-                        session: turnSessionKey,
-                        durationMs: Date.now() - turnStartedAt,
-                        message: e && e.message ? e.message : 'Agent 执行失败'
-                    });
-                    traceLines.push(`[错误] ${e && e.message ? e.message : 'Agent 执行失败'}`);
-                    patchWebSessionMessage(state.webHistoryDir, sessionRef, userMessage && userMessage.id, {
-                        pending: false,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded
-                    });
-                    patchWebSessionMessage(state.webHistoryDir, sessionRef, traceMessage && traceMessage.id, {
-                        content: traceLines.join('\n'),
-                        traceEvents,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: true,
-                        pending: false
-                    });
-                    if (streamingReplyMessageId) {
-                        removeWebSessionMessage(state.webHistoryDir, sessionRef, streamingReplyMessageId);
+                if (rejectDuplicateClientMessage(res, state.webHistoryDir, sessionRef, queueClientId.value)) {
+                    return;
+                }
+                const runState = state.agentRuns.get(sessionRef.containerName);
+                if (runState && runState.sessionKey !== buildWebSessionKey(sessionRef.containerName, sessionRef.agentId)) {
+                    sendJson(res, 409, { error: '当前容器已有其他会话的 agent 任务在运行，请等它结束或先停止' });
+                    return;
+                }
+                // 入队与下面的调度之间没有 await：队列落盘和打断判断对同一会话是原子的
+                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true, includeArchived: true });
+                const added = agentQueue.enqueue(agentSession, { clientMessageId: queueClientId.value, text, when });
+                if (!added.ok) {
+                    sendJson(res, 409, { error: '排队已满（最多 10 条），请先取消几条或等它们发出', full: true });
+                    return;
+                }
+                if (!added.duplicate) {
+                    saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
+                    if (!runState) {
+                        dispatchNextQueued(ctx, state, sessionRef);
+                    } else if (when === 'now') {
+                        steerWebAgentRun(ctx, runState, 'now', state);
+                    } else if (when === 'step') {
+                        armStepSteer(ctx, state, runState);
                     }
-                    emitStreamEvent({
-                        type: 'error',
-                        error: e && e.message ? e.message : 'Agent 执行失败'
-                    }, 'agent.turn.failed', { error: e && e.message ? e.message : 'Agent 执行失败' });
-                } finally {
-                    clearInterval(heartbeatTimer);
-                    res.end();
                 }
+                sendJson(res, 200, { item: added.item, duplicate: added.duplicate, queue: agentQueue.publicQueue(agentSession) });
+            }
+        },
+        {
+            method: 'DELETE',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/queue\/([A-Za-z0-9_-]+)$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                const agentSession = getWebAgentSession(history, sessionRef.agentId, { includeArchived: true });
+                const removed = agentSession ? agentQueue.removeFromQueue(agentSession, match[2]) : null;
+                if (!removed) {
+                    // 已经发出去了或早被取消：前端据此刷新，不当错误
+                    sendJson(res, 404, { error: '这条排队的提示词已经发出或已取消' });
+                    return;
+                }
+                saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
+                // 取消的是最后一个 now / step：撤掉还在等的“步骤结束后打断”
+                const activeRun = state.agentRuns.get(sessionRef.containerName);
+                if (activeRun && activeRun.stepPending && !queueHasSteerItems(state, sessionRef)) {
+                    clearTimeout(activeRun.stepTimer);
+                    activeRun.stepPending = false;
+                }
+                sendJson(res, 200, { removed: removed.id, queue: agentQueue.publicQueue(agentSession) });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/queue\/continue$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                if (state.agentRuns.has(sessionRef.containerName)) {
+                    sendJson(res, 409, { error: '当前容器已有运行中的 agent 任务' });
+                    return;
+                }
+                const started = dispatchNextQueued(ctx, state, sessionRef, { force: true });
+                sendJson(res, 200, { started });
             }
         },
         {
@@ -6978,7 +7363,7 @@ async function handleWebApi(req, res, pathname, ctx, state) {
                 if (!sessionRef) {
                     return;
                 }
-                const stopped = stopWebAgentRun(state, sessionRef.containerName);
+                const stopped = stopWebAgentRun(state, sessionRef.containerName, ctx);
                 if (!stopped) {
                     // 运行登记不存在（serve 重启后常见的孤儿任务）：把残留的
                     // pending 消息标记为已中断，否则前端会因 pending 永久禁用输入
@@ -7143,6 +7528,14 @@ async function startWebServer(options) {
         agentStreamHeartbeatMs: Number.isFinite(options.agentStreamHeartbeatMs) && options.agentStreamHeartbeatMs > 0
             ? options.agentStreamHeartbeatMs
             : DEFAULT_AGENT_STREAM_HEARTBEAT_MS,
+        // 停止 / 打断时每一级信号（INT → TERM → KILL）等进程退出的时间
+        agentStopGraceMs: Number.isFinite(options.agentStopGraceMs) && options.agentStopGraceMs > 0
+            ? options.agentStopGraceMs
+            : agentRunControl.DEFAULT_GRACE_MS,
+        // 追加提示词“当前步骤结束后插入”等不到步骤边界时，退化成立即打断的等待时间
+        agentStepFallbackMs: Number.isFinite(options.agentStepFallbackMs) && options.agentStepFallbackMs > 0
+            ? options.agentStepFallbackMs
+            : agentQueue.STEP_FALLBACK_MS,
         colors: options.colors || {
             GREEN: '',
             CYAN: '',
@@ -7426,6 +7819,10 @@ module.exports = {
     buildEnvModelOptions,
     // 仅供测试：直接驱动历史读写层
     __testing: {
+        prepareStructuredTraceEvents,
+        buildClaudeAgentExecCommand,
+        extractContentDeltaFromPayload,
+        extractAgentMessageFromStructuredOutput,
         appendWebSessionMessage,
         appendWebSessionControlEvent,
         removeWebSessionMessage,