@xcanwin/manyoyo 5.8.9 → 5.8.10

package/lib/web/server.js

@@ -12,24 +12,6 @@ const { buildContainerRunArgs } = require('../container-run');
 const { extractAgentMessageFromCodexJsonl } = require('../codex-output');
 const { findValueRangeByPath, applyTextReplacements } = require('../json5-text-edit');
 const { resolveRuntimeConfig } = require('../runtime-resolver');
-const {
-    normalizeAgentPromptCommandTemplate,
-    isAgentPromptCommandEnabled,
-    buildWebAgentExecCommand,
-    getAgentRuntimeMeta
-} = require('./agent-command');
-const { createStructuredOutputHelpers } = require('./structured-output');
-const { prepareStructuredTraceEvents, extractContentDeltaFromPayload } = require('./structured-trace');
-const { createWebContainerExecHelpers } = require('./container-exec');
-const { createWebRuntimeStateHelpers } = require('./runtime-state');
-const { createWebTerminalHelpers } = require('./terminal-session');
-const { createWebUpgradeHandler } = require('./upgrade-handler');
-const { createWebHttpHandlers } = require('./http-handlers');
-const { createWebServerContextHelpers } = require('./server-context');
-const { createWebServerLifecycleHelpers } = require('./server-lifecycle');
-const { createApiRouteHelpers, runMatchedRoute } = require('./api-route-helpers');
-const { createSystemApiRoutes } = require('./system-api-routes');
-const { createSessionApiRoutes } = require('./session-api-routes');
 const {
     parseEnvEntry,
     expandHomeAliasPath,
@@ -59,9 +41,6 @@ const WEB_DEFAULT_AGENT_ID = 'default';
 const WEB_DEFAULT_AGENT_NAME = 'AGENT 1';
 const WEB_CONFIG_KEEP_SECRET_PLACEHOLDER = '***HIDDEN_SECRET***';
 const FRONTEND_DIR = path.join(__dirname, 'frontend');
-const AUTH_FRONTEND_ASSETS = new Set(['login.css', 'login.js']);
-const APP_FRONTEND_ASSETS = new Set(['app.css', 'app.js', 'markdown.css', 'markdown-renderer.js']);
-const APP_VENDOR_ASSETS = new Set(['xterm.css', 'xterm.js', 'xterm-addon-fit.js', 'marked.min.js']);
 const SAFE_CONTAINER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const IMAGE_VERSION_TAG_PATTERN = /^(\d+\.\d+\.\d+)-([A-Za-z0-9][A-Za-z0-9_.-]*)$/;
 const SENSITIVE_CONFIG_KEY_PATTERN = /(pass(word)?|passwd|secret|token|api(?:_|-)?key|auth(?:_|-)?token|oauth(?:_|-)?token)$/i;
@@ -545,95 +524,273 @@ function clipText(text, maxChars = WEB_OUTPUT_MAX_CHARS) {
     return `${text.slice(0, maxChars)}\n...[truncated]`;
 }
 
-const {
-    parseJsonObjectLine,
-    collectStructuredText,
-    extractAgentMessageFromStructuredOutput
-} = createStructuredOutputHelpers({
-    pickFirstString,
-    toPlainObject,
-    extractAgentMessageFromCodexJsonl
-});
-
-const STRUCTURED_TRACE_DEPS = {
-    pickFirstString,
-    toPlainObject,
-    collectStructuredText,
-    clipText,
-    stripAnsi
-};
+function normalizeAgentPromptCommandTemplate(value, sourceLabel = 'agentPromptCommand') {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${sourceLabel} 必须是字符串`);
+    }
+    const text = value.trim();
+    if (!text) {
+        return '';
+    }
+    if (!text.includes('{prompt}')) {
+        throw new Error(`${sourceLabel} 必须包含 {prompt} 占位符`);
+    }
+    if (/^codex\s+exec(?:\s|$)/.test(text) && !text.includes('--skip-git-repo-check')) {
+        return text.replace(/^codex\s+exec\b/, 'codex exec --skip-git-repo-check');
+    }
+    return text;
+}
 
-const {
-    execCommandInWebContainer,
-    execAgentInWebContainerStream
-} = createWebContainerExecHelpers({
-    buildWebSessionKey,
-    defaultAgentId: WEB_DEFAULT_AGENT_ID,
-    extractAgentMessageFromStructuredOutput,
-    parseJsonObjectLine,
-    prepareStructuredTraceEvents,
-    extractContentDeltaFromPayload,
-    structuredTraceDeps: STRUCTURED_TRACE_DEPS,
-    clipText,
-    stripAnsi
-});
+function isAgentPromptCommandEnabled(value) {
+    return typeof value === 'string' && value.includes('{prompt}') && Boolean(value.trim());
+}
 
-const {
-    createInitialWebRuntimeState,
-    stopWebAgentRun,
-    cleanupWebRuntimeState
-} = createWebRuntimeStateHelpers();
+function quoteBashSingleValue(value) {
+    const text = String(value || '');
+    return `'${text.replace(/'/g, `'\"'\"'`)}'`;
+}
 
-const {
-    createWebServerContext,
-    createWebServerState
-} = createWebServerContextHelpers({
-    createInitialWebRuntimeState,
-    getDefaultWebConfigPath
-});
+function renderAgentPromptCommand(template, prompt) {
+    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const safePrompt = quoteBashSingleValue(prompt);
+    return templateText.replace(/\{prompt\}/g, safePrompt);
+}
 
-const {
-    normalizeTerminalSize,
-    sendWebSocketUpgradeError,
-    bindTerminalWebSocket
-} = createWebTerminalHelpers({
-    WebSocket,
-    spawn,
-    forceKillMs: WEB_TERMINAL_FORCE_KILL_MS,
-    defaultCols: WEB_TERMINAL_DEFAULT_COLS,
-    defaultRows: WEB_TERMINAL_DEFAULT_ROWS,
-    minCols: WEB_TERMINAL_MIN_COLS,
-    minRows: WEB_TERMINAL_MIN_ROWS
-});
-
-const handleWebUpgradeRequest = createWebUpgradeHandler({
-    formatUrlHost,
-    sendWebSocketUpgradeError,
-    getWebAuthSession,
-    parseWebSessionKey,
-    decodeSessionName,
-    safeContainerNamePattern: SAFE_CONTAINER_NAME_PATTERN,
-    normalizeTerminalSize,
-    ensureWebContainer,
-    maxTerminalSessions: WEB_TERMINAL_MAX_SESSIONS
-});
+function buildCodexAgentExecCommand(template, prompt) {
+    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const execMatch = templateText.match(
+        /^((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)codex\s+exec\b/
+    );
+    let codexTemplate = templateText;
+    if (execMatch) {
+        const prefix = execMatch[1] || '';
+        const suffix = templateText.slice(execMatch[0].length);
+        const hasJson = /(?:^|\s)--json(?:\s|$)/.test(suffix);
+        const injectedFlags = hasJson ? '' : ' --json';
+        codexTemplate = `${prefix}codex exec${injectedFlags}${suffix}`;
+    }
+    return codexTemplate === templateText
+        ? renderAgentPromptCommand(templateText, prompt)
+        : renderAgentPromptCommand(codexTemplate, prompt);
+}
+
+function prependAgentFlags(commandText, matchPattern, flagSpecs) {
+    const matched = String(commandText || '').match(matchPattern);
+    if (!matched) {
+        return String(commandText || '');
+    }
+    const prefix = matched[1] || '';
+    let suffix = matched[matched.length - 1] || '';
+    for (let i = flagSpecs.length - 1; i >= 0; i -= 1) {
+        const spec = flagSpecs[i];
+        if (!spec || !spec.flag || !(spec.pattern instanceof RegExp) || spec.pattern.test(suffix)) {
+            continue;
+        }
+        suffix = ` ${spec.flag}${suffix}`;
+    }
+    return `${prefix}${suffix}`;
+}
 
-const {
-    createWsServer,
-    createHttpServer,
-    listenWebServer,
-    closeWebServer
-} = createWebServerLifecycleHelpers({
-    http,
-    WebSocket,
-    formatUrlHost,
-    normalizeTerminalSize,
-    bindTerminalWebSocket,
-    handleWebUpgradeRequest,
-    sendJson,
-    sendHtml,
-    cleanupWebRuntimeState
-});
+function buildClaudeAgentExecCommand(template, prompt) {
+    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const claudeTemplate = prependAgentFlags(
+        templateText,
+        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)claude\b)(.*)$/,
+        [
+            { flag: '--verbose', pattern: /(?:^|\s)--verbose(?:\s|$)/ },
+            { flag: '--output-format stream-json', pattern: /(?:^|\s)--output-format(?:\s|$)/ }
+        ]
+    );
+    return claudeTemplate === templateText
+        ? renderAgentPromptCommand(templateText, prompt)
+        : renderAgentPromptCommand(claudeTemplate, prompt);
+}
+
+function buildGeminiAgentExecCommand(template, prompt) {
+    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const geminiTemplate = prependAgentFlags(
+        templateText,
+        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)gemini\b)(.*)$/,
+        [
+            { flag: '--output-format stream-json', pattern: /(?:^|\s)--output-format(?:\s|$)/ }
+        ]
+    );
+    return geminiTemplate === templateText
+        ? renderAgentPromptCommand(templateText, prompt)
+        : renderAgentPromptCommand(geminiTemplate, prompt);
+}
+
+function buildOpenCodeAgentExecCommand(template, prompt) {
+    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const opencodeTemplate = prependAgentFlags(
+        templateText,
+        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)opencode\s+run\b)(.*)$/,
+        [
+            { flag: '--format json', pattern: /(?:^|\s)--format(?:\s|$)/ }
+        ]
+    );
+    return opencodeTemplate === templateText
+        ? renderAgentPromptCommand(templateText, prompt)
+        : renderAgentPromptCommand(opencodeTemplate, prompt);
+}
+
+function buildWebAgentExecCommand(template, prompt, agentProgram) {
+    switch (agentProgram) {
+    case 'claude':
+        return buildClaudeAgentExecCommand(template, prompt);
+    case 'gemini':
+        return buildGeminiAgentExecCommand(template, prompt);
+    case 'codex':
+        return buildCodexAgentExecCommand(template, prompt);
+    case 'opencode':
+        return buildOpenCodeAgentExecCommand(template, prompt);
+    default:
+        break;
+    }
+    return renderAgentPromptCommand(template, prompt);
+}
+
+function parseJsonObjectLine(line) {
+    const text = String(line || '').trim();
+    if (!text) {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(text);
+        return payload && typeof payload === 'object' ? payload : null;
+    } catch (e) {
+        return null;
+    }
+}
+
+function collectStructuredText(value) {
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => collectStructuredText(item)).filter(Boolean).join('\n').trim();
+    }
+    if (!value || typeof value !== 'object') {
+        return '';
+    }
+    if (typeof value.text === 'string' && value.text.trim()) {
+        return value.text.trim();
+    }
+    if (typeof value.content === 'string' && value.content.trim()) {
+        return value.content.trim();
+    }
+    if (Array.isArray(value.content)) {
+        return value.content.map(item => collectStructuredText(item)).filter(Boolean).join('\n').trim();
+    }
+    return '';
+}
+
+function extractClaudeAgentMessage(text) {
+    let lastMessage = '';
+    for (const rawLine of String(text || '').split('\n')) {
+        const payload = parseJsonObjectLine(rawLine);
+        if (!payload || payload.type !== 'assistant') {
+            continue;
+        }
+        const message = toPlainObject(payload.message);
+        const content = Array.isArray(message.content) ? message.content : [];
+        const nextMessage = content
+            .filter(item => item && typeof item === 'object' && item.type === 'text')
+            .map(item => collectStructuredText(item))
+            .filter(Boolean)
+            .join('\n')
+            .trim();
+        if (nextMessage) {
+            lastMessage = nextMessage;
+        }
+    }
+    return lastMessage.trim();
+}
+
+function extractGeminiAgentMessage(text) {
+    let lastMessage = '';
+    let deltaMessage = '';
+    for (const rawLine of String(text || '').split('\n')) {
+        const payload = parseJsonObjectLine(rawLine);
+        if (!payload || payload.type !== 'message' || payload.role !== 'assistant') {
+            continue;
+        }
+        const content = collectStructuredText(payload.content);
+        if (!content) {
+            continue;
+        }
+        if (payload.delta === true) {
+            deltaMessage += content;
+            lastMessage = deltaMessage.trim();
+            continue;
+        }
+        deltaMessage = '';
+        lastMessage = content;
+    }
+    return lastMessage.trim();
+}
+
+function extractOpenCodeAgentMessage(text) {
+    let lastMessage = '';
+    let deltaMessage = '';
+    for (const rawLine of String(text || '').split('\n')) {
+        const payload = parseJsonObjectLine(rawLine);
+        if (!payload) {
+            continue;
+        }
+        const eventType = pickFirstString(payload.type);
+        const message = toPlainObject(payload.message);
+        const role = pickFirstString(payload.role, message.role);
+        if (eventType !== 'message' && eventType !== 'assistant' && eventType !== 'assistant_message' && eventType !== 'text') {
+            continue;
+        }
+        if (role && role !== 'assistant') {
+            continue;
+        }
+        const content = collectStructuredText(message.content || payload.content || payload.text || payload);
+        if (!content) {
+            continue;
+        }
+        if (payload.delta === true) {
+            deltaMessage += content;
+            lastMessage = deltaMessage.trim();
+            continue;
+        }
+        deltaMessage = '';
+        lastMessage = content;
+    }
+    return lastMessage.trim();
+}
+
+function extractAgentMessageFromStructuredOutput(agentProgram, text) {
+    if (agentProgram === 'codex') {
+        return extractAgentMessageFromCodexJsonl(text);
+    }
+    if (agentProgram === 'claude') {
+        return extractClaudeAgentMessage(text);
+    }
+    if (agentProgram === 'gemini') {
+        return extractGeminiAgentMessage(text);
+    }
+    if (agentProgram === 'opencode') {
+        return extractOpenCodeAgentMessage(text);
+    }
+    return '';
+}
+
+function getAgentRuntimeMeta(template) {
+    const normalizedTemplate = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
+    const agentProgram = resolveAgentProgram(normalizedTemplate);
+    const resumeCommand = buildAgentResumeCommand(agentProgram);
+    return {
+        agentProgram: agentProgram || '',
+        resumeCommand: resumeCommand || '',
+        resumeSupported: Boolean(resumeCommand)
+    };
+}
 
 function hasAgentConversationHistory(history) {
     const messages = history && Array.isArray(history.messages) ? history.messages : [];
@@ -695,6 +852,599 @@ function buildAgentPromptWithHistory(history, prompt) {
     ].join('\n');
 }
 
+function shortenTraceText(value, maxChars = 140) {
+    const raw = clipText(stripAnsi(String(value || '')).replace(/\s+/g, ' ').trim(), maxChars);
+    return raw.trim();
+}
+
+function summarizeTraceArguments(args) {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+        return '';
+    }
+    const parts = [];
+    for (const [key, value] of Object.entries(args)) {
+        if (value === undefined || value === null) continue;
+        if (typeof value === 'string') {
+            const textValue = value.trim();
+            if (!textValue) continue;
+            parts.push(`${key}=${shortenTraceText(textValue, 80)}`);
+            continue;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            parts.push(`${key}=${String(value)}`);
+        }
+    }
+    return parts.slice(0, 3).join(', ');
+}
+
+function createStructuredTraceEvent(provider, kind, eventType, textValue, extra = {}) {
+    const normalizedText = String(textValue || '').trim();
+    if (!normalizedText) {
+        return null;
+    }
+    return {
+        provider,
+        kind,
+        eventType,
+        text: normalizedText,
+        ...extra
+    };
+}
+
+function prepareClaudeTraceEvents(payload, state) {
+    const eventType = pickFirstString(payload.type);
+    const subtype = pickFirstString(payload.subtype);
+    const message = toPlainObject(payload.message);
+    const content = Array.isArray(message.content) ? message.content : [];
+    const toolNamesById = state.toolNamesById;
+    const events = [];
+
+    if (eventType === 'system' && subtype === 'init') {
+        events.push(createStructuredTraceEvent('claude', 'thread', eventType, '[会话] Claude 已开始处理', {
+            phase: 'started',
+            status: 'started',
+            subtype
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'assistant') {
+        content.forEach(item => {
+            if (!item || typeof item !== 'object') {
+                return;
+            }
+            if (item.type === 'text') {
+                const detail = collectStructuredText(item);
+                if (detail) {
+                    events.push(createStructuredTraceEvent('claude', 'agent_message', eventType, `[说明] ${detail}`, {
+                        phase: 'completed',
+                        status: 'completed',
+                        detail
+                    }));
+                }
+                return;
+            }
+            if (item.type === 'tool_use') {
+                const toolName = pickFirstString(item.name, item.id, 'tool');
+                const toolId = pickFirstString(item.id);
+                if (toolId) {
+                    toolNamesById.set(toolId, toolName);
+                }
+                const summary = summarizeTraceArguments(toPlainObject(item.input));
+                events.push(createStructuredTraceEvent(
+                    'claude',
+                    'tool',
+                    eventType,
+                    summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
+                    {
+                        phase: 'started',
+                        status: 'in_progress',
+                        toolName,
+                        toolId,
+                        arguments: toPlainObject(item.input),
+                        argumentSummary: summary
+                    }
+                ));
+            }
+        });
+        return events.filter(Boolean);
+    }
+    if (eventType === 'user') {
+        content.forEach(item => {
+            if (!item || typeof item !== 'object' || item.type !== 'tool_result') {
+                return;
+            }
+            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})`, {
+                phase: 'completed',
+                status,
+                toolName,
+                toolId,
+                result: collectStructuredText(item.content),
+                error: item.is_error === true ? collectStructuredText(item.content) : ''
+            }));
+        });
+        return events.filter(Boolean);
+    }
+    if (eventType === 'result') {
+        events.push(createStructuredTraceEvent('claude', 'turn', eventType, '[回合] 响应完成', {
+            phase: 'completed',
+            status: pickFirstString(subtype, 'completed'),
+            subtype
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'error') {
+        const detail = pickFirstString(payload.message, payload.error);
+        events.push(createStructuredTraceEvent('claude', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] Claude 返回了错误事件', {
+            status: 'error',
+            detail
+        }));
+        return events.filter(Boolean);
+    }
+    return [];
+}
+
+function prepareGeminiTraceEvents(payload, state) {
+    const eventType = pickFirstString(payload.type);
+    const toolNamesById = state.toolNamesById;
+    const events = [];
+
+    if (eventType === 'init') {
+        events.push(createStructuredTraceEvent('gemini', 'thread', eventType, '[会话] Gemini 已开始处理', {
+            phase: 'started',
+            status: 'started',
+            sessionId: pickFirstString(payload.session_id),
+            model: pickFirstString(payload.model)
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'message' && payload.role === 'assistant') {
+        if (payload.delta === true) {
+            return [];
+        }
+        const detail = collectStructuredText(payload.content);
+        if (!detail) {
+            return [];
+        }
+        events.push(createStructuredTraceEvent('gemini', 'agent_message', eventType, `[说明] ${detail}`, {
+            phase: 'completed',
+            status: 'completed',
+            detail
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'tool_use') {
+        const toolName = pickFirstString(payload.tool_name, payload.tool_id, 'tool');
+        const toolId = pickFirstString(payload.tool_id);
+        if (toolId) {
+            toolNamesById.set(toolId, toolName);
+        }
+        const summary = summarizeTraceArguments(toPlainObject(payload.parameters));
+        events.push(createStructuredTraceEvent(
+            'gemini',
+            'tool',
+            eventType,
+            summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
+            {
+                phase: 'started',
+                status: 'in_progress',
+                toolName,
+                toolId,
+                arguments: toPlainObject(payload.parameters),
+                argumentSummary: summary
+            }
+        ));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'tool_result') {
+        const toolId = pickFirstString(payload.tool_id);
+        const toolName = pickFirstString(toolNamesById.get(toolId), toolId, 'tool');
+        const status = pickFirstString(payload.status, 'completed');
+        events.push(createStructuredTraceEvent('gemini', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
+            phase: 'completed',
+            status,
+            toolName,
+            toolId,
+            result: collectStructuredText(payload.output),
+            error: toPlainObject(payload.error)
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'result') {
+        events.push(createStructuredTraceEvent('gemini', 'turn', eventType, '[回合] 响应完成', {
+            phase: 'completed',
+            status: pickFirstString(payload.status, 'completed')
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'error') {
+        const detail = pickFirstString(payload.message);
+        events.push(createStructuredTraceEvent('gemini', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] Gemini 返回了错误事件', {
+            status: pickFirstString(payload.severity, 'error'),
+            detail
+        }));
+        return events.filter(Boolean);
+    }
+    return [];
+}
+
+function prepareOpenCodeTraceEvents(payload, state) {
+    const eventType = pickFirstString(payload.type);
+    const message = toPlainObject(payload.message);
+    const role = pickFirstString(payload.role, message.role);
+    const toolNamesById = state.toolNamesById;
+    const events = [];
+
+    if (eventType === 'session.start' || eventType === 'init') {
+        events.push(createStructuredTraceEvent('opencode', 'thread', eventType, '[会话] OpenCode 已开始处理', {
+            phase: 'started',
+            status: 'started',
+            sessionId: pickFirstString(payload.session_id, payload.sessionID)
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'message' || eventType === 'assistant' || eventType === 'assistant_message' || eventType === 'text') {
+        if (role && role !== 'assistant') {
+            return [];
+        }
+        if (payload.delta === true) {
+            return [];
+        }
+        const detail = collectStructuredText(message.content || payload.content || payload.text || payload);
+        if (!detail) {
+            return [];
+        }
+        events.push(createStructuredTraceEvent('opencode', 'agent_message', eventType, `[说明] ${detail}`, {
+            phase: 'completed',
+            status: 'completed',
+            detail
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'tool_use' || eventType === 'step_start') {
+        const toolName = pickFirstString(payload.tool_name, payload.name, payload.tool, payload.step, payload.tool_id, 'tool');
+        const toolId = pickFirstString(payload.tool_id, payload.id);
+        if (toolId) {
+            toolNamesById.set(toolId, toolName);
+        }
+        const argumentsValue = toPlainObject(payload.parameters || payload.input || payload.arguments);
+        const summary = summarizeTraceArguments(argumentsValue);
+        events.push(createStructuredTraceEvent(
+            'opencode',
+            'tool',
+            eventType,
+            summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
+            {
+                phase: 'started',
+                status: pickFirstString(payload.status, 'in_progress'),
+                toolName,
+                toolId,
+                arguments: argumentsValue,
+                argumentSummary: summary
+            }
+        ));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'tool_result' || eventType === 'step_finish') {
+        const toolId = pickFirstString(payload.tool_id, payload.id);
+        const toolName = pickFirstString(toolNamesById.get(toolId), payload.tool_name, payload.name, payload.tool, toolId, 'tool');
+        const status = pickFirstString(payload.status, payload.state, 'completed');
+        events.push(createStructuredTraceEvent('opencode', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
+            phase: 'completed',
+            status,
+            toolName,
+            toolId,
+            result: collectStructuredText(payload.output || payload.result),
+            error: toPlainObject(payload.error)
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'result') {
+        events.push(createStructuredTraceEvent('opencode', 'turn', eventType, '[回合] 响应完成', {
+            phase: 'completed',
+            status: pickFirstString(payload.status, 'completed')
+        }));
+        return events.filter(Boolean);
+    }
+    if (eventType === 'error') {
+        const detail = pickFirstString(payload.message, payload.error && payload.error.message);
+        events.push(createStructuredTraceEvent('opencode', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] OpenCode 返回了错误事件', {
+            status: 'error',
+            detail
+        }));
+        return events.filter(Boolean);
+    }
+    return [];
+}
+
+function prepareStructuredTraceEvents(agentProgram, payload, state) {
+    if (!payload || typeof payload !== 'object') {
+        return [];
+    }
+    if (agentProgram === 'codex') {
+        const traceEvent = prepareCodexTraceEvent(payload);
+        return traceEvent ? [traceEvent] : [];
+    }
+    if (agentProgram === 'claude') {
+        return prepareClaudeTraceEvents(payload, state);
+    }
+    if (agentProgram === 'gemini') {
+        return prepareGeminiTraceEvents(payload, state);
+    }
+    if (agentProgram === 'opencode') {
+        return prepareOpenCodeTraceEvents(payload, state);
+    }
+    return [];
+}
+
+function extractContentDeltaFromPayload(agentProgram, payload) {
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+    if (agentProgram === 'claude') {
+        if (pickFirstString(payload.type) !== 'assistant') {
+            return null;
+        }
+        const message = toPlainObject(payload.message);
+        const content = Array.isArray(message.content) ? message.content : [];
+        const text = content
+            .filter(item => item && typeof item === 'object' && item.type === 'text')
+            .map(item => collectStructuredText(item))
+            .filter(Boolean)
+            .join('\n')
+            .trim();
+        if (!text) {
+            return null;
+        }
+        return { text, reset: true };
+    }
+    if (agentProgram === 'gemini' || agentProgram === 'opencode') {
+        const eventType = pickFirstString(payload.type);
+        if (eventType !== 'message') {
+            return null;
+        }
+        const role = pickFirstString(payload.role);
+        if (role !== 'assistant') {
+            return null;
+        }
+        const text = collectStructuredText(payload.content);
+        if (!text) {
+            return null;
+        }
+        if (payload.delta === true) {
+            return { text, reset: false };
+        }
+        return { text, reset: true };
+    }
+    return null;
+}
+
+function prepareCodexTraceEvent(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+
+    const eventType = typeof payload.type === 'string' ? payload.type : '';
+    const item = payload.item && typeof payload.item === 'object' && !Array.isArray(payload.item)
+        ? payload.item
+        : {};
+    const itemType = typeof item.type === 'string' ? item.type : '';
+    const text = pickFirstString(
+        item.title,
+        item.summary,
+        item.text,
+        item.name,
+        item.command,
+        payload.message,
+        payload.text
+    );
+    const toolName = pickFirstString(
+        item.name,
+        item.tool_name,
+        item.tool,
+        item.command
+    );
+    const commandText = pickFirstString(item.command);
+    const mcpServer = pickFirstString(item.server);
+    const mcpTool = pickFirstString(item.tool);
+    const itemStatus = pickFirstString(item.status);
+
+    function shortenText(value, maxChars = 140) {
+        const raw = clipText(stripAnsi(String(value || '')).replace(/\s+/g, ' ').trim(), maxChars);
+        return raw.trim();
+    }
+
+    function summarizeArguments(args) {
+        if (!args || typeof args !== 'object' || Array.isArray(args)) {
+            return '';
+        }
+        const parts = [];
+        for (const [key, value] of Object.entries(args)) {
+            if (value === undefined || value === null) continue;
+            if (typeof value === 'string') {
+                const textValue = value.trim();
+                if (!textValue) continue;
+                parts.push(`${key}=${shortenText(textValue, 80)}`);
+                continue;
+            }
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                parts.push(`${key}=${String(value)}`);
+            }
+        }
+        return parts.slice(0, 3).join(', ');
+    }
+
+    function pickDisplayStatus(defaultStatus) {
+        const status = String(itemStatus || defaultStatus || '').trim();
+        return status || '';
+    }
+
+    function createTraceEvent(kind, textValue, extra = {}) {
+        const normalizedText = String(textValue || '').trim();
+        if (!normalizedText) {
+            return null;
+        }
+        return {
+            provider: 'codex',
+            kind,
+            eventType,
+            itemType: itemType || '',
+            text: normalizedText,
+            ...extra
+        };
+    }
+
+    if (eventType === 'thread.started') {
+        return createTraceEvent('thread', '[会话] Codex 已开始处理', {
+            phase: 'started',
+            status: 'started'
+        });
+    }
+    if (eventType === 'thread.completed') {
+        return createTraceEvent('thread', '[会话] Codex 已完成当前任务', {
+            phase: 'completed',
+            status: 'completed'
+        });
+    }
+    if (eventType === 'turn.started') {
+        return createTraceEvent('turn', '[回合] 开始生成响应', {
+            phase: 'started',
+            status: 'started'
+        });
+    }
+    if (eventType === 'turn.completed') {
+        return createTraceEvent('turn', '[回合] 响应完成', {
+            phase: 'completed',
+            status: 'completed'
+        });
+    }
+    if (eventType === 'item.started') {
+        if (itemType === 'tool_call') {
+            return createTraceEvent('tool', `[工具开始] ${toolName || 'tool_call'}`, {
+                phase: 'started',
+                status: pickDisplayStatus('in_progress'),
+                toolName: toolName || 'tool_call'
+            });
+        }
+        if (itemType === 'command_execution') {
+            return createTraceEvent('command', `[命令开始] ${commandText || 'command_execution'}`, {
+                phase: 'started',
+                status: pickDisplayStatus('in_progress'),
+                command: commandText || 'command_execution'
+            });
+        }
+        if (itemType === 'mcp_tool_call') {
+            const summary = summarizeArguments(item.arguments);
+            return createTraceEvent(
+                'mcp',
+                summary
+                    ? `[MCP开始] ${mcpServer || 'mcp'}.${mcpTool || 'tool'} (${summary})`
+                    : `[MCP开始] ${mcpServer || 'mcp'}.${mcpTool || 'tool'}`,
+                {
+                    phase: 'started',
+                    status: pickDisplayStatus('in_progress'),
+                    server: mcpServer || 'mcp',
+                    tool: mcpTool || 'tool',
+                    arguments: item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
+                        ? item.arguments
+                        : null,
+                    argumentSummary: summary
+                }
+            );
+        }
+        if (itemType === 'reasoning') {
+            return createTraceEvent('status', text ? `[状态] ${text}` : '[状态] Codex 正在分析', {
+                phase: 'started',
+                status: pickDisplayStatus('in_progress'),
+                detail: text || 'Codex 正在分析'
+            });
+        }
+        if (itemType === 'agent_message') {
+            return createTraceEvent('agent_message', text ? `[说明] ${text}` : '[回复] 正在生成最终答复', {
+                phase: 'started',
+                status: pickDisplayStatus('in_progress'),
+                detail: text || '正在生成最终答复'
+            });
+        }
+        return createTraceEvent('event', text ? `[事件开始] ${text}` : `[事件开始] ${itemType || eventType}`, {
+            phase: 'started',
+            status: pickDisplayStatus('in_progress'),
+            detail: text || itemType || eventType
+        });
+    }
+    if (eventType === 'item.completed') {
+        if (itemType === 'tool_call') {
+            return createTraceEvent('tool', `[工具完成] ${toolName || 'tool_call'}`, {
+                phase: 'completed',
+                status: pickDisplayStatus('completed'),
+                toolName: toolName || 'tool_call'
+            });
+        }
+        if (itemType === 'command_execution') {
+            const suffix = itemStatus || (typeof item.exit_code === 'number' ? `exit=${item.exit_code}` : 'completed');
+            return createTraceEvent('command', `[命令完成] ${commandText || 'command_execution'} (${suffix})`, {
+                phase: 'completed',
+                status: pickDisplayStatus(suffix),
+                command: commandText || 'command_execution',
+                exitCode: typeof item.exit_code === 'number' ? item.exit_code : null
+            });
+        }
+        if (itemType === 'mcp_tool_call') {
+            const summary = summarizeArguments(item.arguments);
+            return createTraceEvent(
+                'mcp',
+                summary
+                    ? `[MCP完成] ${mcpServer || 'mcp'}.${mcpTool || 'tool'} (${summary})`
+                    : `[MCP完成] ${mcpServer || 'mcp'}.${mcpTool || 'tool'}`,
+                {
+                    phase: 'completed',
+                    status: pickDisplayStatus('completed'),
+                    server: mcpServer || 'mcp',
+                    tool: mcpTool || 'tool',
+                    arguments: item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
+                        ? item.arguments
+                        : null,
+                    argumentSummary: summary,
+                    result: item.result !== undefined ? item.result : null,
+                    error: item.error !== undefined ? item.error : null
+                }
+            );
+        }
+        if (itemType === 'reasoning') {
+            return createTraceEvent('status', text ? `[状态] ${text}` : '', {
+                phase: 'completed',
+                status: pickDisplayStatus('completed'),
+                detail: text || ''
+            });
+        }
+        if (itemType === 'agent_message') {
+            return createTraceEvent('agent_message', text ? `[说明] ${text}` : '[回复] 已生成', {
+                phase: 'completed',
+                status: pickDisplayStatus('completed'),
+                detail: text || '已生成'
+            });
+        }
+        return createTraceEvent('event', text ? `[事件完成] ${text}` : `[事件完成] ${itemType || eventType}`, {
+            phase: 'completed',
+            status: pickDisplayStatus('completed'),
+            detail: text || itemType || eventType
+        });
+    }
+    if (eventType === 'error') {
+        return createTraceEvent('error', text ? `[错误] ${text}` : '[错误] Codex 返回了错误事件', {
+            status: 'error',
+            detail: text || 'Codex 返回了错误事件'
+        });
+    }
+
+    return createTraceEvent('event', `[事件] ${eventType}`, {
+        status: itemStatus || '',
+        detail: eventType
+    });
+}
+
 async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
     const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
     const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true });
@@ -1415,12 +2165,12 @@ function buildCreateRuntime(ctx, state, payload) {
     const hasConfigVolumes = hasOwn(config, 'volumes');
     const hasConfigPorts = hasOwn(config, 'ports');
 
+    const requestName = pickFirstString(requestOptions.containerName, body.name);
     const requestEnvMap = hasRequestEnv ? normalizeEnvMap(requestOptions.env, 'createOptions.env') : {};
     const requestEnvList = Object.entries(requestEnvMap).map(([key, value]) => `${key}=${value}`);
     const requestEnvFileList = hasRequestEnvFile ? normalizeStringArray(requestOptions.envFile, 'createOptions.envFile') : [];
     const requestVolumeList = hasRequestVolumes ? normalizeStringArray(requestOptions.volumes, 'createOptions.volumes') : [];
     const requestPortList = hasRequestPorts ? normalizeStringArray(requestOptions.ports, 'createOptions.ports') : [];
-    const requestName = pickFirstString(requestOptions.containerName, body.name);
 
     const resolvedBase = resolveRuntimeConfig({
         cliOptions: {
@@ -1533,14 +2283,16 @@ function buildCreateRuntime(ctx, state, payload) {
     const hasRunEnv = hasOwn(runConfig, 'env');
     const hasRunEnvFile = hasOwn(runConfig, 'envFile');
     if (hasRequestEnv || hasRequestEnvFile || hasRunEnv || hasRunEnvFile || hasConfigEnv || hasConfigEnvFile) {
+        const mergedEnv = resolvedBase.env;
         const envArgs = [];
-        Object.entries(resolvedBase.env).forEach(([key, value]) => {
+        Object.entries(mergedEnv).forEach(([key, value]) => {
             const parsed = parseEnvEntry(`${key}=${value}`);
             envArgs.push('--env', `${parsed.key}=${parsed.value}`);
         });
 
+        const envFileList = resolvedBase.envFile;
         const envFileArgs = [];
-        resolvedBase.envFile.forEach(filePath => {
+        envFileList.forEach(filePath => {
             envFileArgs.push(...parseEnvFileToArgs(filePath));
         });
 
@@ -1550,8 +2302,9 @@ function buildCreateRuntime(ctx, state, payload) {
     let containerVolumes = Array.isArray(ctx.containerVolumes) ? ctx.containerVolumes.slice() : [];
     const hasRunVolumes = hasOwn(runConfig, 'volumes');
     if (hasRequestVolumes || hasRunVolumes || hasConfigVolumes) {
+        const volumeList = resolvedBase.volumes;
         containerVolumes = [];
-        resolvedBase.volumes.forEach(volume => {
+        volumeList.forEach(volume => {
             containerVolumes.push('--volume', normalizeVolume(volume));
         });
     }
@@ -1559,8 +2312,9 @@ function buildCreateRuntime(ctx, state, payload) {
     let containerPorts = Array.isArray(ctx.containerPorts) ? ctx.containerPorts.slice() : [];
     const hasRunPorts = hasOwn(runConfig, 'ports');
     if (hasRequestPorts || hasRunPorts || hasConfigPorts) {
+        const portList = resolvedBase.ports;
         containerPorts = [];
-        resolvedBase.ports.forEach(port => {
+        portList.forEach(port => {
             containerPorts.push('--publish', port);
         });
     }
@@ -1723,6 +2477,229 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
     }
 }
 
+async function execCommandInWebContainer(ctx, containerName, command, options = {}) {
+    const opts = options && typeof options === 'object' ? options : {};
+    const agentProgram = typeof opts.agentProgram === 'string' ? opts.agentProgram : '';
+    return await new Promise((resolve, reject) => {
+        const process = spawn(
+            ctx.dockerCmd,
+            ['exec', containerName, '/bin/bash', '-lc', command],
+            { stdio: ['ignore', 'pipe', 'pipe'] }
+        );
+
+        const MAX_RAW_OUTPUT_CHARS = 32 * 1024 * 1024;
+        let stdoutOutput = '';
+        let stderrOutput = '';
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+
+        function appendChunk(chunk, target) {
+            if (!chunk) return;
+            const text = chunk.toString('utf-8');
+            if (!text) return;
+            if (target.value.length >= MAX_RAW_OUTPUT_CHARS) {
+                target.truncated = true;
+                return;
+            }
+            const remain = MAX_RAW_OUTPUT_CHARS - target.value.length;
+            if (text.length > remain) {
+                target.value += text.slice(0, remain);
+                target.truncated = true;
+                return;
+            }
+            target.value += text;
+        }
+
+        process.stdout.on('data', chunk => appendChunk(chunk, {
+            get value() { return stdoutOutput; },
+            set value(nextValue) { stdoutOutput = nextValue; },
+            get truncated() { return stdoutTruncated; },
+            set truncated(nextValue) { stdoutTruncated = nextValue; }
+        }));
+        process.stderr.on('data', chunk => appendChunk(chunk, {
+            get value() { return stderrOutput; },
+            set value(nextValue) { stderrOutput = nextValue; },
+            get truncated() { return stderrTruncated; },
+            set truncated(nextValue) { stderrTruncated = nextValue; }
+        }));
+
+        process.on('error', reject);
+        process.on('close', code => {
+            const exitCode = typeof code === 'number' ? code : 1;
+            const clippedStdout = stdoutTruncated ? `${stdoutOutput}\n...[stdout-truncated]` : stdoutOutput;
+            const clippedStderr = stderrTruncated ? `${stderrOutput}\n...[stderr-truncated]` : stderrOutput;
+            const clippedRaw = `${clippedStdout}${clippedStdout && clippedStderr ? '\n' : ''}${clippedStderr}`;
+            const extractedAgentMessage = extractAgentMessageFromStructuredOutput(agentProgram, clippedStdout);
+            const cleanOutputSource = extractedAgentMessage || clippedRaw;
+            const output = clipText(stripAnsi(cleanOutputSource).trim() || '(无输出)');
+            resolve({ exitCode, output });
+        });
+    });
+}
+
+async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerName, command, options = {}) {
+    const opts = options && typeof options === 'object' ? options : {};
+    const sessionRef = typeof sessionRefOrContainerName === 'string'
+        ? { containerName: sessionRefOrContainerName, agentId: WEB_DEFAULT_AGENT_ID }
+        : sessionRefOrContainerName;
+    const sessionKey = buildWebSessionKey(sessionRef.containerName, sessionRef.agentId);
+    const agentProgram = typeof opts.agentProgram === 'string' ? opts.agentProgram : '';
+    const onEvent = typeof opts.onEvent === 'function' ? opts.onEvent : () => {};
+    const process = spawn(
+        ctx.dockerCmd,
+        ['exec', sessionRef.containerName, '/bin/bash', '-lc', command],
+        { stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+
+    const runState = {
+        containerName: sessionRef.containerName,
+        sessionKey,
+        process,
+        command,
+        startedAt: new Date().toISOString(),
+        stopping: false
+    };
+    state.agentRuns.set(sessionRef.containerName, runState);
+
+    return await new Promise((resolve, reject) => {
+        const MAX_RAW_OUTPUT_CHARS = 32 * 1024 * 1024;
+        let stdoutOutput = '';
+        let stderrOutput = '';
+        let stdoutTruncated = false;
+        let stderrTruncated = false;
+        let stdoutPending = '';
+        let stderrPending = '';
+        const structuredTraceState = {
+            toolNamesById: new Map()
+        };
+        let contentDeltaAccumulator = '';
+        function appendChunk(chunk, target) {
+            if (!chunk) return;
+            const text = chunk.toString('utf-8');
+            if (!text) return;
+            if (target.value.length >= MAX_RAW_OUTPUT_CHARS) {
+                target.truncated = true;
+                return;
+            }
+            const remain = MAX_RAW_OUTPUT_CHARS - target.value.length;
+            if (text.length > remain) {
+                target.value += text.slice(0, remain);
+                target.truncated = true;
+                return;
+            }
+            target.value += text;
+        }
+
+        function emitStdoutTraceLine(line) {
+            const rawLine = String(line || '').trim();
+            if (!rawLine) {
+                return;
+            }
+            if (agentProgram === 'claude' || agentProgram === 'gemini' || agentProgram === 'codex' || agentProgram === 'opencode') {
+                const payload = parseJsonObjectLine(rawLine);
+                if (payload) {
+                    const traceEvents = prepareStructuredTraceEvents(agentProgram, payload, structuredTraceState);
+                    traceEvents.forEach(traceEvent => {
+                        if (!traceEvent || !traceEvent.text) {
+                            return;
+                        }
+                        onEvent({
+                            type: 'trace',
+                            stream: 'stdout',
+                            text: traceEvent.text,
+                            traceEvent
+                        });
+                    });
+                    const deltaContent = extractContentDeltaFromPayload(agentProgram, payload, structuredTraceState);
+                    if (deltaContent !== null) {
+                        if (deltaContent.reset) {
+                            contentDeltaAccumulator = deltaContent.text;
+                        } else {
+                            contentDeltaAccumulator += deltaContent.text;
+                        }
+                        onEvent({
+                            type: 'content_delta',
+                            content: contentDeltaAccumulator
+                        });
+                    }
+                    return;
+                }
+                if (agentProgram === 'codex' && (/^OpenAI Codex\b/.test(rawLine) || /^tokens used\b/i.test(rawLine))) {
+                    return;
+                }
+            }
+            onEvent({ type: 'trace', stream: 'stdout', text: rawLine });
+        }
+
+        function emitStderrTraceLine(line) {
+            const rawLine = String(line || '').trim();
+            if (!rawLine) {
+                return;
+            }
+            onEvent({ type: 'trace', stream: 'stderr', text: `[stderr] ${rawLine}` });
+        }
+
+        function drainLines(text, carry, handleLine) {
+            let pending = carry + String(text || '');
+            let newlineIndex = pending.indexOf('\n');
+            while (newlineIndex !== -1) {
+                const line = pending.slice(0, newlineIndex).replace(/\r$/, '');
+                handleLine(line);
+                pending = pending.slice(newlineIndex + 1);
+                newlineIndex = pending.indexOf('\n');
+            }
+            return pending;
+        }
+
+        process.stdout.on('data', chunk => {
+            appendChunk(chunk, {
+                get value() { return stdoutOutput; },
+                set value(nextValue) { stdoutOutput = nextValue; },
+                get truncated() { return stdoutTruncated; },
+                set truncated(nextValue) { stdoutTruncated = nextValue; }
+            });
+            stdoutPending = drainLines(chunk.toString('utf-8'), stdoutPending, emitStdoutTraceLine);
+        });
+        process.stderr.on('data', chunk => {
+            appendChunk(chunk, {
+                get value() { return stderrOutput; },
+                set value(nextValue) { stderrOutput = nextValue; },
+                get truncated() { return stderrTruncated; },
+                set truncated(nextValue) { stderrTruncated = nextValue; }
+            });
+            stderrPending = drainLines(chunk.toString('utf-8'), stderrPending, emitStderrTraceLine);
+        });
+
+        process.on('error', error => {
+            state.agentRuns.delete(sessionRef.containerName);
+            reject(error);
+        });
+        process.on('close', code => {
+            state.agentRuns.delete(sessionRef.containerName);
+            if (stdoutPending) {
+                emitStdoutTraceLine(stdoutPending);
+                stdoutPending = '';
+            }
+            if (stderrPending) {
+                emitStderrTraceLine(stderrPending);
+                stderrPending = '';
+            }
+            const exitCode = typeof code === 'number' ? code : 1;
+            const clippedStdout = stdoutTruncated ? `${stdoutOutput}\n...[stdout-truncated]` : stdoutOutput;
+            const clippedStderr = stderrTruncated ? `${stderrOutput}\n...[stderr-truncated]` : stderrOutput;
+            const clippedRaw = `${clippedStdout}${clippedStdout && clippedStderr ? '\n' : ''}${clippedStderr}`;
+            const extractedAgentMessage = extractAgentMessageFromStructuredOutput(agentProgram, clippedStdout);
+            const cleanOutputSource = extractedAgentMessage || clippedRaw;
+            const output = clipText(stripAnsi(cleanOutputSource).trim() || '(无输出)');
+            resolve({
+                exitCode,
+                output,
+                interrupted: exitCode !== 0 && runState.stopping === true
+            });
+        });
+    });
+}
+
 function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         let body = '';
@@ -1763,6 +2740,20 @@ function sendNdjson(res, payload) {
     res.write(`${JSON.stringify(payload)}\n`);
 }
 
+function stopWebAgentRun(state, containerName) {
+    const runState = state.agentRuns.get(containerName);
+    if (!runState || !runState.process || runState.process.killed) {
+        return false;
+    }
+    runState.stopping = true;
+    try {
+        runState.process.kill('SIGTERM');
+    } catch (e) {
+        return false;
+    }
+    return true;
+}
+
 function sendHtml(res, statusCode, html, extraHeaders = {}) {
     res.writeHead(statusCode, {
         'Content-Type': 'text/html; charset=utf-8',
@@ -1988,6 +2979,277 @@ function loadTemplate(name) {
     return fs.readFileSync(filePath, 'utf-8');
 }
 
+function toPositiveInt(value, fallback) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}
+
+function normalizeTerminalSize(cols, rows) {
+    return {
+        cols: Math.max(WEB_TERMINAL_MIN_COLS, toPositiveInt(cols, WEB_TERMINAL_DEFAULT_COLS)),
+        rows: Math.max(WEB_TERMINAL_MIN_ROWS, toPositiveInt(rows, WEB_TERMINAL_DEFAULT_ROWS))
+    };
+}
+
+function getUpgradeStatusText(statusCode) {
+    if (statusCode === 400) return 'Bad Request';
+    if (statusCode === 401) return 'Unauthorized';
+    if (statusCode === 404) return 'Not Found';
+    if (statusCode === 429) return 'Too Many Requests';
+    if (statusCode === 500) return 'Internal Server Error';
+    return 'Error';
+}
+
+function sendWebSocketUpgradeError(socket, statusCode, message) {
+    const body = String(message || getUpgradeStatusText(statusCode));
+    const reason = getUpgradeStatusText(statusCode);
+    if (!socket.destroyed) {
+        socket.write(
+            `HTTP/1.1 ${statusCode} ${reason}\r\n` +
+            'Content-Type: text/plain; charset=utf-8\r\n' +
+            'Connection: close\r\n' +
+            `Content-Length: ${Buffer.byteLength(body, 'utf-8')}\r\n` +
+            '\r\n' +
+            body
+        );
+    }
+    socket.destroy();
+}
+
+function sendTerminalEvent(ws, type, payload = {}) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return;
+    }
+    ws.send(JSON.stringify({ type, ...payload }));
+}
+
+function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
+    const terminalBootstrap = [
+        'MANYOYO_WEB_BASHRC="$(mktemp /tmp/manyoyo-web-bashrc.XXXXXX 2>/dev/null || mktemp)"',
+        'cat > "$MANYOYO_WEB_BASHRC" <<\'EOF_MANYOYO_RC\'',
+        'if [ -f /etc/bash.bashrc ]; then',
+        '    . /etc/bash.bashrc',
+        'fi',
+        'if [ -f ~/.bashrc ]; then',
+        '    . ~/.bashrc',
+        'fi',
+        'if [ -n "${MANYOYO_TERM_COLS:-}" ] && [ -n "${MANYOYO_TERM_ROWS:-}" ]; then',
+        '    COLUMNS="$MANYOYO_TERM_COLS"',
+        '    LINES="$MANYOYO_TERM_ROWS"',
+        '    export COLUMNS LINES',
+        '    stty cols "$MANYOYO_TERM_COLS" rows "$MANYOYO_TERM_ROWS" >/dev/null 2>&1 || true',
+        'fi',
+        'EOF_MANYOYO_RC',
+        'chmod 600 "$MANYOYO_WEB_BASHRC" >/dev/null 2>&1 || true',
+        'if command -v script >/dev/null 2>&1; then',
+        '  exec script -qefc "/bin/bash --rcfile $MANYOYO_WEB_BASHRC -i" /dev/null;',
+        'fi;',
+        'if command -v python3 >/dev/null 2>&1; then',
+        '  exec python3 -c \'import os, pty; pty.spawn(["/bin/bash","--rcfile",os.environ.get("MANYOYO_WEB_BASHRC","/dev/null"),"-i"])\';',
+        'fi;',
+        'if command -v python >/dev/null 2>&1; then',
+        '  exec python -c \'import os, pty; pty.spawn(["/bin/bash","--rcfile",os.environ.get("MANYOYO_WEB_BASHRC","/dev/null"),"-i"])\';',
+        'fi;',
+        'echo "[manyoyo] 容器内未找到 script/python，终端将降级为非 TTY 模式" >&2;',
+        'exec /bin/bash --rcfile "$MANYOYO_WEB_BASHRC" -i'
+    ].join('\n');
+
+    const termValue = process.env.TERM && process.env.TERM !== 'dumb' ? process.env.TERM : 'xterm-256color';
+    const colorTermValue = process.env.COLORTERM || 'truecolor';
+    const dockerExecArgs = [
+        'exec',
+        '-i',
+        '-e', `TERM=${termValue}`,
+        '-e', `COLORTERM=${colorTermValue}`,
+        '-e', `MANYOYO_TERM_COLS=${String(cols)}`,
+        '-e', `MANYOYO_TERM_ROWS=${String(rows)}`,
+        containerName,
+        '/bin/bash',
+        '-lc',
+        terminalBootstrap
+    ];
+
+    return spawn(ctx.dockerCmd, dockerExecArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
+}
+
+function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
+    const sessionId = `${containerName}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+    const ptyProcess = spawnWebTerminalProcess(ctx, containerName, cols, rows);
+    const session = {
+        id: sessionId,
+        containerName,
+        ptyProcess,
+        closing: false
+    };
+
+    state.terminalSessions.set(sessionId, session);
+    sendTerminalEvent(ws, 'status', {
+        phase: 'ready',
+        sessionId,
+        containerName,
+        cols,
+        rows
+    });
+
+    const cleanup = () => {
+        if (session.closing) {
+            return;
+        }
+        session.closing = true;
+        state.terminalSessions.delete(sessionId);
+        if (ptyProcess && !ptyProcess.killed) {
+            ptyProcess.kill('SIGTERM');
+            setTimeout(() => {
+                if (!ptyProcess.killed) {
+                    ptyProcess.kill('SIGKILL');
+                }
+            }, WEB_TERMINAL_FORCE_KILL_MS);
+        }
+    };
+
+    ptyProcess.stdout.on('data', chunk => {
+        sendTerminalEvent(ws, 'output', { data: chunk.toString('utf-8') });
+    });
+
+    ptyProcess.stderr.on('data', chunk => {
+        sendTerminalEvent(ws, 'output', { data: chunk.toString('utf-8') });
+    });
+
+    ptyProcess.on('error', err => {
+        sendTerminalEvent(ws, 'error', {
+            error: err && err.message ? err.message : '终端进程启动失败'
+        });
+    });
+
+    ptyProcess.on('close', (code, signal) => {
+        sendTerminalEvent(ws, 'status', {
+            phase: 'closed',
+            code: typeof code === 'number' ? code : null,
+            signal: signal || null
+        });
+        cleanup();
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.close();
+        }
+    });
+
+    ws.on('message', raw => {
+        let payload = null;
+        try {
+            payload = JSON.parse(raw.toString('utf-8'));
+        } catch (e) {
+            payload = {
+                type: 'input',
+                data: raw.toString('utf-8')
+            };
+        }
+        if (!payload || typeof payload !== 'object') {
+            return;
+        }
+
+        if (payload.type === 'input' && typeof payload.data === 'string' && payload.data.length) {
+            ptyProcess.stdin.write(payload.data);
+            return;
+        }
+
+        if (payload.type === 'resize') {
+            // 当前后端不直接驱动 docker exec 的 TTY 动态 resize，保留事件以便后续扩展。
+            return;
+        }
+
+        if (payload.type === 'close') {
+            ws.close();
+        }
+    });
+
+    ws.on('close', cleanup);
+    ws.on('error', cleanup);
+}
+
+async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
+    if (req.method === 'GET' && pathname === '/favicon.ico') {
+        res.writeHead(204, { 'Cache-Control': 'no-store' });
+        res.end();
+        return true;
+    }
+
+    if (req.method === 'GET' && pathname === '/auth/login') {
+        sendHtml(res, 200, loadTemplate('login.html'));
+        return true;
+    }
+
+    const authFrontendMatch = pathname.match(/^\/auth\/frontend\/([A-Za-z0-9._-]+)$/);
+    if (req.method === 'GET' && authFrontendMatch) {
+        const assetName = authFrontendMatch[1];
+        if (!(assetName === 'login.css' || assetName === 'login.js')) {
+            sendHtml(res, 404, '<h1>404 Not Found</h1>');
+            return true;
+        }
+        sendStaticAsset(res, assetName);
+        return true;
+    }
+
+    if (req.method === 'POST' && pathname === '/auth/login') {
+        const payload = await readJsonBody(req);
+        const username = String(payload.username || '').trim();
+        const password = String(payload.password || '');
+
+        if (!username || !password) {
+            sendJson(res, 400, { error: '用户名和密码不能为空' });
+            return true;
+        }
+
+        const userOk = secureStringEqual(username, ctx.authUser);
+        const passOk = secureStringEqual(password, ctx.authPass);
+        if (!(userOk && passOk)) {
+            sendJson(res, 401, { error: '用户名或密码错误' });
+            return true;
+        }
+
+        const sessionId = createWebAuthSession(state, username);
+        sendJson(
+            res,
+            200,
+            { ok: true, username },
+            { 'Set-Cookie': getWebAuthCookie(sessionId) }
+        );
+        return true;
+    }
+
+    if (req.method === 'POST' && pathname === '/auth/logout') {
+        clearWebAuthSession(state, req);
+        sendJson(
+            res,
+            200,
+            { ok: true },
+            { 'Set-Cookie': getWebAuthClearCookie() }
+        );
+        return true;
+    }
+
+    return false;
+}
+
+function sendWebUnauthorized(res, pathname) {
+    if (pathname.startsWith('/api/') || pathname.startsWith('/auth/')) {
+        sendJson(res, 401, { error: 'UNAUTHORIZED' });
+        return;
+    }
+    if (pathname === '/' || pathname === '') {
+        sendRedirect(res, 302, '/auth/login', { 'Set-Cookie': getWebAuthClearCookie() });
+        return;
+    }
+    sendHtml(
+        res,
+        401,
+        loadTemplate('login.html'),
+        { 'Set-Cookie': getWebAuthClearCookie() }
+    );
+}
+
 async function handleWebApi(req, res, pathname, ctx, state) {
     // [P2-03] 对非只读请求校验自定义头，防止 CSRF 攻击
     // 跨站请求无法设置自定义头（浏览器同源策略），合法前端请求统一携带此头
@@ -1997,121 +3259,823 @@ async function handleWebApi(req, res, pathname, ctx, state) {
             return true;
         }
     }
-
-    const {
-        withSessionRef,
-        withJsonBody,
-        withSessionJsonBody,
-        getRequiredBodyText,
-        prepareAgentRequest
-    } = createApiRouteHelpers({
-        req,
-        res,
-        ctx,
-        state,
-        sendJson,
-        readJsonBody,
-        getValidSessionRef,
-        prepareWebAgentExecution
-    });
-
     const routes = [
-        ...createSystemApiRoutes({
-            req,
-            res,
-            ctx,
-            state,
-            fs,
-            os,
-            path,
-            withJsonBody,
-            sendJson,
-            expandHomeAliasPath,
-            readWebConfigSnapshot,
-            buildSafeWebConfigSnapshot,
-            restoreWebConfigSecrets,
-            parseAndValidateConfigRaw,
-            buildConfigDefaults
-        }),
-        ...createSessionApiRoutes({
-            req,
-            res,
-            ctx,
-            state,
-            WEB_DEFAULT_AGENT_ID,
-            withSessionRef,
-            withJsonBody,
-            withSessionJsonBody,
-            getRequiredBodyText,
-            prepareAgentRequest,
-            sendJson,
-            sendNdjson,
-            buildCreateRuntime,
-            ensureWebContainer,
-            setWebSessionAgentPromptCommand,
-            patchWebSessionHistory,
-            listWebManyoyoContainers,
-            listWebHistorySessionNames,
-            loadWebSessionHistory,
-            listWebAgentSessions,
-            buildSessionSummary,
-            createWebAgentSession,
-            saveWebSessionHistory,
-            buildWebSessionKey,
-            getWebAgentSession,
-            createEmptyWebAgentSession,
-            buildSessionDetail,
-            hasOwn,
-            setWebAgentSessionPromptCommand,
-            appendWebSessionMessage,
-            execCommandInWebContainer,
-            finalizeWebAgentExecution,
-            execAgentInWebContainerStream,
-            appendWebAgentTraceMessage,
-            stopWebAgentRun,
-            removeWebSessionHistory
-        })
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/fs/directories' ? [] : null,
+            handler: async () => {
+                const requestUrl = new URL(req.url || '/api/fs/directories', 'http://localhost');
+                const requestedPath = expandHomeAliasPath(String(requestUrl.searchParams.get('path') || '').trim() || os.homedir());
+                const requestedBasePath = expandHomeAliasPath(String(requestUrl.searchParams.get('basePath') || '').trim());
+                const realPath = fs.realpathSync(requestedPath);
+                if (!fs.statSync(realPath).isDirectory()) {
+                    sendJson(res, 400, { error: `目录不存在: ${realPath}` });
+                    return;
+                }
+
+                let realBasePath = '';
+                if (requestedBasePath) {
+                    realBasePath = fs.realpathSync(requestedBasePath);
+                    if (!fs.statSync(realBasePath).isDirectory()) {
+                        sendJson(res, 400, { error: `basePath 不是目录: ${realBasePath}` });
+                        return;
+                    }
+                    const relativeToBase = path.relative(realBasePath, realPath);
+                    if (relativeToBase.startsWith('..') || path.isAbsolute(relativeToBase)) {
+                        sendJson(res, 400, { error: '目录超出 basePath 范围' });
+                        return;
+                    }
+                }
+
+                const parentPath = realBasePath
+                    ? (realPath === realBasePath ? '' : path.dirname(realPath))
+                    : (realPath === path.parse(realPath).root ? '' : path.dirname(realPath));
+                const entries = fs.readdirSync(realPath, { withFileTypes: true })
+                    .filter(entry => entry && entry.isDirectory())
+                    .map(entry => ({
+                        name: entry.name,
+                        path: path.join(realPath, entry.name)
+                    }))
+                    .sort((a, b) => a.name.localeCompare(b.name, 'zh-CN'));
+
+                sendJson(res, 200, {
+                    currentPath: realPath,
+                    basePath: realBasePath || '',
+                    parentPath,
+                    entries
+                });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/config' ? [] : null,
+            handler: async () => {
+                const snapshot = readWebConfigSnapshot(state.webConfigPath);
+                sendJson(res, 200, buildSafeWebConfigSnapshot(snapshot, ctx));
+            }
+        },
+        {
+            method: 'PUT',
+            match: currentPath => currentPath === '/api/config' ? [] : null,
+            handler: async () => {
+                const payload = await readJsonBody(req);
+                const raw = typeof payload.raw === 'string' ? payload.raw : '';
+                if (!raw.trim()) {
+                    sendJson(res, 400, { error: '配置内容不能为空' });
+                    return;
+                }
+
+                const currentSnapshot = readWebConfigSnapshot(state.webConfigPath);
+                let finalRaw = raw;
+                let parsed = null;
+                try {
+                    finalRaw = restoreWebConfigSecrets(raw, currentSnapshot);
+                    parsed = parseAndValidateConfigRaw(finalRaw);
+                } catch (e) {
+                    sendJson(res, 400, { error: '配置格式错误', detail: e.message || '解析失败' });
+                    return;
+                }
+
+                const savePath = path.resolve(state.webConfigPath);
+                fs.mkdirSync(path.dirname(savePath), { recursive: true });
+                fs.writeFileSync(savePath, finalRaw, 'utf-8');
+
+                sendJson(res, 200, {
+                    saved: true,
+                    path: savePath,
+                    defaults: buildConfigDefaults(ctx, parsed)
+                });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath === '/api/sessions' ? [] : null,
+            handler: async () => {
+                const containerMap = listWebManyoyoContainers(ctx);
+                const names = new Set([
+                    ...Object.keys(containerMap),
+                    ...listWebHistorySessionNames(state.webHistoryDir, ctx.isValidContainerName)
+                ]);
+
+                const sessions = Array.from(names)
+                    .flatMap(name => {
+                        const history = loadWebSessionHistory(state.webHistoryDir, name);
+                        return listWebAgentSessions(history, { includeSyntheticDefault: true })
+                            .map(agentSession => buildSessionSummary(ctx, state, containerMap, {
+                                containerName: name,
+                                agentId: agentSession.agentId
+                            }))
+                            .filter(Boolean);
+                    })
+                    .sort((a, b) => {
+                        const timeA = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
+                        const timeB = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
+                        return timeB - timeA;
+                    });
+
+                sendJson(res, 200, { sessions });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath === '/api/sessions' ? [] : null,
+            handler: async () => {
+                const payload = await readJsonBody(req);
+                let runtime = null;
+                try {
+                    runtime = buildCreateRuntime(ctx, state, payload);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '创建参数错误' });
+                    return;
+                }
+
+                await ensureWebContainer(ctx, state, runtime);
+                setWebSessionAgentPromptCommand(state.webHistoryDir, runtime.containerName, runtime.agentPromptCommand);
+                patchWebSessionHistory(state.webHistoryDir, runtime.containerName, {
+                    applied: runtime.applied
+                });
+                sendJson(res, 200, { name: runtime.containerName, applied: runtime.applied });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agents$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                const agentSession = createWebAgentSession(history);
+                saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
+                sendJson(res, 200, {
+                    name: buildWebSessionKey(sessionRef.containerName, agentSession.agentId),
+                    containerName: sessionRef.containerName,
+                    agentId: agentSession.agentId,
+                    agentName: agentSession.agentName
+                });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/messages$/),
+            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)
+                    || createEmptyWebAgentSession(sessionRef.agentId);
+                sendJson(res, 200, {
+                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
+                    containerName: sessionRef.containerName,
+                    agentId: sessionRef.agentId,
+                    messages: agentSession.messages
+                });
+            }
+        },
+        {
+            method: 'GET',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/detail$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                const containerMap = listWebManyoyoContainers(ctx);
+                const detail = buildSessionDetail(ctx, state, containerMap, sessionRef);
+                sendJson(res, 200, { name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), detail });
+            }
+        },
+        {
+            method: 'PUT',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent-template$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                let payload = null;
+                try {
+                    payload = await readJsonBody(req);
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '请求参数错误' });
+                    return;
+                }
+                const normalizedPayload = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
+                const hasContainerTemplate = hasOwn(normalizedPayload, 'containerAgentPromptCommand');
+                const hasAgentOverride = hasOwn(normalizedPayload, 'agentPromptCommandOverride');
+                if (!hasContainerTemplate && !hasAgentOverride) {
+                    sendJson(res, 400, { error: '至少提供一个模板字段' });
+                    return;
+                }
+                if (hasAgentOverride && sessionRef.agentId === WEB_DEFAULT_AGENT_ID) {
+                    sendJson(res, 400, { error: '默认 AGENT 不支持单独覆盖模板，请直接修改容器模板' });
+                    return;
+                }
+
+                try {
+                    if (hasContainerTemplate) {
+                        setWebSessionAgentPromptCommand(
+                            state.webHistoryDir,
+                            sessionRef.containerName,
+                            normalizedPayload.containerAgentPromptCommand
+                        );
+                    }
+                    if (hasAgentOverride) {
+                        setWebAgentSessionPromptCommand(
+                            state.webHistoryDir,
+                            sessionRef,
+                            normalizedPayload.agentPromptCommandOverride
+                        );
+                    }
+                } catch (e) {
+                    sendJson(res, 400, { error: e.message || '保存 Agent 模板失败' });
+                    return;
+                }
+
+                const containerMap = listWebManyoyoContainers(ctx);
+                const detail = buildSessionDetail(ctx, state, containerMap, sessionRef);
+                sendJson(res, 200, {
+                    saved: true,
+                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
+                    detail
+                });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/run$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                const payload = await readJsonBody(req);
+                const command = (payload.command || '').trim();
+                if (!command) {
+                    sendJson(res, 400, { error: 'command 不能为空' });
+                    return;
+                }
+
+                await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
+                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', command);
+                const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command);
+                appendWebSessionMessage(
+                    state.webHistoryDir,
+                    sessionRef,
+                    'assistant',
+                    result.output,
+                    { exitCode: result.exitCode }
+                );
+                sendJson(res, 200, { exitCode: result.exitCode, output: result.output });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                const payload = await readJsonBody(req);
+                const prompt = (payload.prompt || '').trim();
+                if (!prompt) {
+                    sendJson(res, 400, { error: 'prompt 不能为空' });
+                    return;
+                }
+
+                let prepared = null;
+                try {
+                    prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
+                } catch (e) {
+                    sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
+                    return;
+                }
+
+                const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError } = prepared;
+                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
+                    mode: 'agent',
+                    contextMode
+                });
+                const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command, {
+                    agentProgram: agentMeta.agentProgram
+                });
+                finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
+                    contextMode,
+                    resumeAttempted,
+                    resumeSucceeded,
+                    resumeError
+                }, result);
+                sendJson(res, 200, {
+                    exitCode: result.exitCode,
+                    output: result.output,
+                    contextMode,
+                    resumeAttempted,
+                    resumeSucceeded,
+                    interrupted: result.interrupted === true
+                });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/stream$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                const payload = await readJsonBody(req);
+                const prompt = (payload.prompt || '').trim();
+                if (!prompt) {
+                    sendJson(res, 400, { error: 'prompt 不能为空' });
+                    return;
+                }
+                if (state.agentRuns.has(sessionRef.containerName)) {
+                    sendJson(res, 409, { error: '当前会话已有运行中的 agent 任务' });
+                    return;
+                }
+
+                let prepared = null;
+                try {
+                    prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
+                } catch (e) {
+                    sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
+                    return;
+                }
+
+                const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError } = prepared;
+                const traceLines = ['[执行过程]'];
+                const traceEvents = [];
+                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
+                    mode: 'agent',
+                    contextMode
+                });
+
+                res.writeHead(200, {
+                    'Content-Type': 'application/x-ndjson; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                    'X-Accel-Buffering': 'no'
+                });
+                sendNdjson(res, {
+                    type: 'meta',
+                    containerName: sessionRef.containerName,
+                    sessionName: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
+                    contextMode,
+                    resumeAttempted,
+                    resumeSucceeded,
+                    agentProgram: agentMeta.agentProgram
+                });
+                if (contextMode) {
+                    traceLines.push(`上下文模式: ${contextMode}`);
+                }
+                if (resumeAttempted) {
+                    traceLines.push(resumeSucceeded ? '会话恢复成功' : '会话恢复失败，已回退到历史注入');
+                }
+
+                try {
+                    const result = await execAgentInWebContainerStream(ctx, state, sessionRef, command, {
+                        agentProgram: agentMeta.agentProgram,
+                        onEvent: event => {
+                            if (event && event.type === 'trace' && event.text) {
+                                traceLines.push(String(event.text));
+                                if (event.traceEvent && typeof event.traceEvent === 'object') {
+                                    traceEvents.push(event.traceEvent);
+                                }
+                            }
+                            sendNdjson(res, event);
+                        }
+                    });
+                    traceLines.push(result.interrupted === true ? '[任务] 已停止' : '[任务] 已完成');
+                    appendWebAgentTraceMessage(state.webHistoryDir, sessionRef, traceLines.join('\n'), {
+                        traceEvents,
+                        contextMode,
+                        resumeAttempted,
+                        resumeSucceeded,
+                        interrupted: result.interrupted === true
+                    });
+                    finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
+                        contextMode,
+                        resumeAttempted,
+                        resumeSucceeded,
+                        resumeError
+                    }, result);
+                    sendNdjson(res, {
+                        type: 'result',
+                        exitCode: result.exitCode,
+                        output: result.output,
+                        contextMode,
+                        resumeAttempted,
+                        resumeSucceeded,
+                        interrupted: result.interrupted === true
+                    });
+                } catch (e) {
+                    traceLines.push(`[错误] ${e && e.message ? e.message : 'Agent 执行失败'}`);
+                    appendWebAgentTraceMessage(state.webHistoryDir, sessionRef, traceLines.join('\n'), {
+                        traceEvents,
+                        contextMode,
+                        resumeAttempted,
+                        resumeSucceeded,
+                        interrupted: true
+                    });
+                    sendNdjson(res, {
+                        type: 'error',
+                        error: e && e.message ? e.message : 'Agent 执行失败'
+                    });
+                } finally {
+                    res.end();
+                }
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/stop$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+                const stopped = stopWebAgentRun(state, sessionRef.containerName);
+                if (!stopped) {
+                    sendJson(res, 404, { error: '当前会话没有运行中的 agent 任务' });
+                    return;
+                }
+                sendJson(res, 200, { ok: true, stopping: true });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/remove$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                if (ctx.containerExists(sessionRef.containerName)) {
+                    ctx.removeContainer(sessionRef.containerName);
+                    appendWebSessionMessage(state.webHistoryDir, sessionRef, 'system', `容器 ${sessionRef.containerName} 已删除。`);
+                }
+
+                sendJson(res, 200, { removed: true, name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId) });
+            }
+        },
+        {
+            method: 'POST',
+            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/remove-with-history$/),
+            handler: async match => {
+                const sessionRef = getValidSessionRef(ctx, res, match[1]);
+                if (!sessionRef) {
+                    return;
+                }
+
+                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                if (history.agents && typeof history.agents === 'object') {
+                    if (sessionRef.agentId === WEB_DEFAULT_AGENT_ID) {
+                        delete history.agents[WEB_DEFAULT_AGENT_ID];
+                    } else {
+                        delete history.agents[sessionRef.agentId];
+                    }
+                }
+                if (!Object.keys(history.agents || {}).length && !ctx.containerExists(sessionRef.containerName)) {
+                    removeWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
+                } else {
+                    saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
+                }
+                sendJson(res, 200, {
+                    removedHistory: true,
+                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId)
+                });
+            }
+        }
     ];
-    return await runMatchedRoute(routes, req.method, pathname);
+
+    for (const route of routes) {
+        if (route.method !== req.method) {
+            continue;
+        }
+        const matched = route.match(pathname);
+        if (!matched) {
+            continue;
+        }
+        await route.handler(matched);
+        return true;
+    }
+
+    return false;
 }
 
 async function startWebServer(options) {
-    const ctx = createWebServerContext(options);
-    const state = createWebServerState(options);
+    const fallbackLogger = {
+        info: () => {},
+        warn: () => {},
+        error: () => {}
+    };
+    const ctx = {
+        serverHost: options.serverHost || '127.0.0.1',
+        serverPort: options.serverPort,
+        authUser: options.authUser,
+        authPass: options.authPass,
+        authPassAuto: options.authPassAuto,
+        dockerCmd: options.dockerCmd,
+        hostPath: options.hostPath,
+        containerPath: options.containerPath,
+        imageName: options.imageName,
+        imageVersion: options.imageVersion,
+        execCommandPrefix: options.execCommandPrefix,
+        execCommand: options.execCommand,
+        execCommandSuffix: options.execCommandSuffix,
+        contModeArgs: options.contModeArgs,
+        containerExtraArgs: options.containerExtraArgs,
+        containerEnvs: options.containerEnvs,
+        containerVolumes: options.containerVolumes,
+        containerPorts: options.containerPorts,
+        validateHostPath: options.validateHostPath,
+        formatDate: options.formatDate,
+        isValidContainerName: options.isValidContainerName,
+        containerExists: options.containerExists,
+        getContainerStatus: options.getContainerStatus,
+        waitForContainerReady: options.waitForContainerReady,
+        dockerExecArgs: options.dockerExecArgs,
+        showImagePullHint: options.showImagePullHint,
+        removeContainer: options.removeContainer,
+        logger: options.logger && typeof options.logger.info === 'function' ? options.logger : fallbackLogger,
+        colors: options.colors || {
+            GREEN: '',
+            CYAN: '',
+            YELLOW: '',
+            NC: ''
+        }
+    };
+
+    if (!ctx.authUser || !ctx.authPass) {
+        throw new Error('Web 认证配置缺失，请设置 serve -U / serve -P');
+    }
+
+    const state = {
+        webHistoryDir: options.webHistoryDir || path.join(os.homedir(), '.manyoyo', 'web-history'),
+        webConfigPath: options.webConfigPath || getDefaultWebConfigPath(),
+        authSessions: new Map(),
+        terminalSessions: new Map(),
+        agentRuns: new Map()
+    };
 
     ensureWebHistoryDir(state.webHistoryDir);
 
-    const wsServer = createWsServer(ctx, state);
-
-    const { handleWebHttpRequest } = createWebHttpHandlers({
-        loadTemplate,
-        sendHtml,
-        sendJson,
-        sendRedirect,
-        sendStaticAsset,
-        sendVendorAsset,
-        readJsonBody,
-        secureStringEqual,
-        createWebAuthSession,
-        clearWebAuthSession,
-        getWebAuthCookie,
-        getWebAuthClearCookie,
-        getWebAuthSession,
-        AUTH_FRONTEND_ASSETS,
-        APP_FRONTEND_ASSETS,
-        APP_VENDOR_ASSETS,
-        handleWebApi
+    const wsServer = new WebSocket.Server({
+        noServer: true,
+        maxPayload: 1024 * 1024
     });
+    wsServer.on('error', err => {
+        ctx.logger.error('ws server error', err);
+    });
+
+    wsServer.on('connection', (ws, req, meta = {}) => {
+        const containerName = meta.containerName;
+        if (!containerName || !ctx.isValidContainerName(containerName)) {
+            ws.close();
+            return;
+        }
+        const { cols, rows } = normalizeTerminalSize(meta.cols, meta.rows);
+        bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows);
+    });
+
+    const server = http.createServer(async (req, res) => {
+        try {
+            const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
+            const url = new URL(req.url, `http://${req.headers.host || fallbackHost}`);
+            const pathname = url.pathname;
 
-    const server = createHttpServer(ctx, state, wsServer, handleWebHttpRequest);
-    const listenPort = await listenWebServer(server, ctx);
+            // 全局认证入口：除登录路由外，默认全部请求都要求认证
+            if (await handleWebAuthRoutes(req, res, pathname, ctx, state)) {
+                return;
+            }
+
+            const authSession = getWebAuthSession(state, req);
+            if (!authSession) {
+                sendWebUnauthorized(res, pathname);
+                return;
+            }
+
+            if (req.method === 'GET' && pathname === '/') {
+                sendHtml(res, 200, loadTemplate('app.html'));
+                return;
+            }
+
+            const appFrontendMatch = pathname.match(/^\/app\/frontend\/([A-Za-z0-9._-]+)$/);
+            if (req.method === 'GET' && appFrontendMatch) {
+                const assetName = appFrontendMatch[1];
+                if (!(assetName === 'app.css' || assetName === 'app.js' || assetName === 'markdown.css' || assetName === 'markdown-renderer.js')) {
+                    sendHtml(res, 404, '<h1>404 Not Found</h1>');
+                    return;
+                }
+                sendStaticAsset(res, assetName);
+                return;
+            }
+
+            const appVendorMatch = pathname.match(/^\/app\/vendor\/([A-Za-z0-9._-]+)$/);
+            if (req.method === 'GET' && appVendorMatch) {
+                const assetName = appVendorMatch[1];
+                if (!(assetName === 'xterm.css' || assetName === 'xterm.js' || assetName === 'xterm-addon-fit.js' || assetName === 'marked.min.js')) {
+                    sendHtml(res, 404, '<h1>404 Not Found</h1>');
+                    return;
+                }
+                sendVendorAsset(res, assetName);
+                return;
+            }
+
+            if (pathname === '/healthz') {
+                sendJson(res, 200, { ok: true });
+                return;
+            }
+
+            if (pathname.startsWith('/api/')) {
+                const handled = await handleWebApi(req, res, pathname, ctx, state);
+                if (!handled) {
+                    sendJson(res, 404, { error: 'Not Found' });
+                }
+                return;
+            }
+
+            sendHtml(res, 404, '<h1>404 Not Found</h1>');
+        } catch (e) {
+            ctx.logger.error('http request error', {
+                method: req && req.method ? req.method : '',
+                url: req && req.url ? req.url : '',
+                message: e && e.message ? e.message : 'Server Error'
+            });
+            if ((req.url || '').startsWith('/api/')) {
+                sendJson(res, 500, { error: e.message || 'Server Error' });
+            } else {
+                sendHtml(res, 500, '<h1>500 Server Error</h1>');
+            }
+        }
+    });
+    server.on('error', err => {
+        ctx.logger.error('http server error', err);
+    });
+    server.on('close', () => {
+        ctx.logger.warn('http server closed');
+    });
+
+    server.on('upgrade', (req, socket, head) => {
+        const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
+        let url;
+        try {
+            url = new URL(req.url || '/', `http://${req.headers.host || fallbackHost}`);
+        } catch (e) {
+            sendWebSocketUpgradeError(socket, 400, 'Invalid URL');
+            return;
+        }
+
+        const terminalMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/terminal\/ws$/);
+        if (!terminalMatch) {
+            socket.destroy();
+            return;
+        }
+
+        // [P1-03] Origin 校验，防止跨站 WebSocket 劫持（CSWSH）
+        // 浏览器发起的 WebSocket 请求必须携带 Origin 头，非浏览器客户端（如 curl）不携带则放行
+        const requestOrigin = req.headers.origin;
+        if (requestOrigin) {
+            const allowedOrigins = new Set();
+            // 始终以请求的 Host 头构造允许来源，兼容 nginx 等反向代理场景
+            const hostHeader = req.headers.host || '';
+            if (hostHeader) {
+                allowedOrigins.add(`http://${hostHeader}`);
+                allowedOrigins.add(`https://${hostHeader}`);
+            }
+            if (ctx.serverHost !== '0.0.0.0') {
+                allowedOrigins.add(`http://${formatUrlHost(ctx.serverHost)}:${listenPort}`);
+                if (ctx.serverHost === '127.0.0.1') {
+                    allowedOrigins.add(`http://localhost:${listenPort}`);
+                }
+            }
+            if (allowedOrigins.size > 0 && !allowedOrigins.has(requestOrigin)) {
+                sendWebSocketUpgradeError(socket, 403, 'Forbidden');
+                return;
+            }
+        }
+
+        const authSession = getWebAuthSession(state, req);
+        if (!authSession) {
+            sendWebSocketUpgradeError(socket, 401, 'UNAUTHORIZED');
+            return;
+        }
+
+        const sessionRef = parseWebSessionKey(decodeSessionName(terminalMatch[1]));
+        if (!ctx.isValidContainerName(sessionRef.containerName)) {
+            sendWebSocketUpgradeError(socket, 400, `containerName 非法: ${sessionRef.containerName}`);
+            return;
+        }
+        if (!SAFE_CONTAINER_NAME_PATTERN.test(sessionRef.agentId)) {
+            sendWebSocketUpgradeError(socket, 400, `agentId 非法: ${sessionRef.agentId}`);
+            return;
+        }
+
+        if (state.terminalSessions.size >= WEB_TERMINAL_MAX_SESSIONS) {
+            sendWebSocketUpgradeError(socket, 429, 'TERMINAL_LIMIT_REACHED');
+            return;
+        }
+
+        const { cols, rows } = normalizeTerminalSize(
+            url.searchParams.get('cols'),
+            url.searchParams.get('rows')
+        );
+
+        ensureWebContainer(ctx, state, sessionRef.containerName)
+            .then(() => {
+                wsServer.handleUpgrade(req, socket, head, ws => {
+                    wsServer.emit('connection', ws, req, {
+                        containerName: sessionRef.containerName,
+                        cols,
+                        rows
+                    });
+                });
+            })
+            .catch(e => {
+                sendWebSocketUpgradeError(socket, 500, e && e.message ? e.message : '终端创建失败');
+            });
+    });
+
+    let listenPort = ctx.serverPort;
+
+    await new Promise((resolve, reject) => {
+        server.once('error', err => {
+            ctx.logger.error('http server listen failed', err);
+            reject(err);
+        });
+        server.listen(ctx.serverPort, ctx.serverHost, () => {
+            const address = server.address();
+            if (address && typeof address === 'object' && typeof address.port === 'number') {
+                listenPort = address.port;
+            }
+            const { GREEN, CYAN, YELLOW, NC } = ctx.colors;
+            const listenHost = formatUrlHost(ctx.serverHost);
+            console.log(`${GREEN}✅ MANYOYO Web 服务已启动: http://${listenHost}:${listenPort}${NC}`);
+            console.log(`${CYAN}提示: 左侧是 manyoyo 容器会话列表，中间是活动/终端/配置/检查工作台，右侧显示当前会话上下文。${NC}`);
+            if (ctx.serverHost === '0.0.0.0') {
+                console.log(`${CYAN}提示: 当前监听全部网卡，请用本机局域网 IP 访问。${NC}`);
+            }
+            console.log(`${CYAN}🔐 登录用户名: ${YELLOW}${ctx.authUser}${NC}`);
+            if (ctx.authPassAuto) {
+                console.log(`${CYAN}🔐 登录密码(本次随机): ${YELLOW}${ctx.authPass}${NC}`);
+            } else {
+                console.log(`${CYAN}🔐 登录密码: 使用你配置的 serve -P / serverPass / MANYOYO_SERVER_PASS${NC}`);
+            }
+            ctx.logger.info('web server started', {
+                host: ctx.serverHost,
+                port: listenPort,
+                authUser: ctx.authUser,
+                authPassAuto: Boolean(ctx.authPassAuto)
+            });
+            resolve();
+        });
+    });
 
     return {
         server,
         wsServer,
         host: ctx.serverHost,
         port: listenPort,
-        close: () => closeWebServer(server, wsServer, ctx, state)
+        close: () => new Promise(resolve => {
+            ctx.logger.info('web server closing');
+            for (const session of state.terminalSessions.values()) {
+                const ptyProcess = session && session.ptyProcess;
+                if (ptyProcess && !ptyProcess.killed) {
+                    try { ptyProcess.kill('SIGTERM'); } catch (e) {}
+                }
+            }
+            state.terminalSessions.clear();
+            for (const runState of state.agentRuns.values()) {
+                const child = runState && runState.process;
+                if (child && !child.killed) {
+                    try { child.kill('SIGTERM'); } catch (e) {}
+                }
+            }
+            state.agentRuns.clear();
+
+            const closeHttp = () => {
+                if (!server.listening) {
+                    resolve();
+                    return;
+                }
+                server.close(() => resolve());
+            };
+
+            try {
+                wsServer.close(() => closeHttp());
+            } catch (e) {
+                closeHttp();
+            }
+        })
     };
 }