evolclaw 3.2.0 → 3.3.0

package/dist/agents/codex-runner.js

@@ -1,12 +1,18 @@
 /**
  * Codex Agent Runner
  *
- * Integrates OpenAI Codex SDK (@openai/codex-sdk) as an agent backend.
+ * Integrates Codex app-server as an agent backend.
  * Implements the same interface surface as AgentRunner (claude-runner.ts)
  * so MessageProcessor and CommandHandler can work with it transparently.
  */
-import { resolveOpenaiConfig } from './resolve.js';
+import { checkBlacklist, checkReadonly } from '../core/permission.js';
+import { CodexAppServerClient } from './codex-app-server-client.js';
+import { resolveOpenaiConfig } from './baseagent.js';
 import { logger } from '../utils/logger.js';
+import { renderActionAsText } from '../core/interaction-router.js';
+import { buildEnvelope, sendInteractionPayload } from '../core/message/message-processor.js';
+import { compareVersions } from '../utils/npm-ops.js';
+import { resolveRoot } from '../paths.js';
 import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
@@ -18,6 +24,42 @@ const MIME_EXT = {
     'image/gif': '.gif',
     'image/webp': '.webp',
 };
+class AsyncEventQueue {
+    queue = [];
+    done = false;
+    error = null;
+    waiting = null;
+    push(item) {
+        if (this.done)
+            return;
+        this.queue.push(item);
+        this.waiting?.();
+    }
+    end() {
+        this.done = true;
+        this.waiting?.();
+    }
+    fail(error) {
+        this.error = error;
+        this.done = true;
+        this.waiting?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            while (this.queue.length > 0) {
+                yield this.queue.shift();
+            }
+            if (this.error)
+                throw this.error;
+            if (this.done)
+                return;
+            await new Promise((resolve) => {
+                this.waiting = resolve;
+            });
+            this.waiting = null;
+        }
+    }
+}
 const CODEX_CATALOG_FALLBACK = [
     { slug: 'gpt-5.5', efforts: ['low', 'medium', 'high', 'xhigh'] },
     { slug: 'gpt-5.4', efforts: ['low', 'medium', 'high', 'xhigh'] },
@@ -26,15 +68,55 @@ const CODEX_CATALOG_FALLBACK = [
     { slug: 'gpt-5.2', efforts: ['low', 'medium', 'high', 'xhigh'] },
 ];
 let codexCatalogCache = null;
-export function isCodexSdkAvailable() {
+export const MIN_CODEX_CLI_VERSION = '0.117.0';
+export function parseCodexCliVersion(output) {
+    const match = output.match(/\b(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/);
+    return match?.[1] ?? null;
+}
+export function isCodexCliVersionSupported(version) {
+    return compareVersions(version, MIN_CODEX_CLI_VERSION) >= 0;
+}
+export function getCodexCliVersion() {
     try {
-        import.meta.resolve('@openai/codex-sdk');
-        return true;
+        const output = execFileSync('codex', ['--version'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return parseCodexCliVersion(output);
     }
     catch {
-        return false;
+        return null;
+    }
+}
+export function getCodexAppServerAvailability() {
+    const version = getCodexCliVersion();
+    const upgradeHint = '请升级 Codex CLI：npm install -g @openai/codex@latest';
+    if (!version) {
+        return { available: false, reason: `未检测到可用 Codex CLI。${upgradeHint}` };
+    }
+    if (!isCodexCliVersionSupported(version)) {
+        return {
+            available: false,
+            version,
+            reason: `Codex CLI ${version} 低于最低要求 ${MIN_CODEX_CLI_VERSION}。${upgradeHint}`,
+        };
+    }
+    try {
+        execFileSync('codex', ['app-server', '--help'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return { available: true, version };
+    }
+    catch {
+        return { available: false, version, reason: `Codex CLI ${version} 不支持 app-server。${upgradeHint}` };
     }
 }
+export function isCodexAppServerAvailable() {
+    return getCodexAppServerAvailability().available;
+}
 function fetchCodexCatalog() {
     if (codexCatalogCache)
         return codexCatalogCache;
@@ -69,68 +151,116 @@ export function getCodexEfforts(model) {
 // ── Codex Runner ──
 export class CodexRunner {
     name = 'codex';
-    capabilities = { clear: false, compact: false, fork: false };
-    codexModule = null;
+    capabilities;
     model;
     effort;
     activeAbortControllers = new Map();
     activeStreams = new Map();
     activeSessions = new Map(); // sessionId → threadId
+    activeTurns = new Map();
+    appServerClient = null;
     onSessionIdUpdate;
+    onCompactStart;
+    permissionGateway;
+    sendPromptFn;
+    permissionContexts = new Map();
     resolvedConfig;
     constructor(config, callbacks) {
         this.resolvedConfig = resolveOpenaiConfig(config);
+        this.capabilities = {
+            clear: false,
+            compact: true,
+            fork: true,
+            // Requires Codex CLI feature flag: default_mode_request_user_input.
+            askUserQuestion: this.resolvedConfig.enableRequestUserInput === true,
+            // Codex app-server exposes plan streaming, but not Claude-style ExitPlanMode approval.
+            planApproval: false,
+            // Current file rewind is intentionally degraded: it restores touched files from Git HEAD.
+            fileRewind: 'git-head',
+        };
         this.model = this.resolvedConfig.model;
         if (this.resolvedConfig.effort)
             this.effort = this.resolvedConfig.effort;
         this.onSessionIdUpdate = callbacks.onSessionIdUpdate;
     }
-    async ensureCodex(sessionId) {
-        if (!this.codexModule) {
-            const { requireOptional } = await import('../utils/npm-ops.js');
-            this.codexModule = await requireOptional('@openai/codex-sdk');
-        }
-        const codex = new this.codexModule.Codex({
-            apiKey: this.resolvedConfig.apiKey,
-            baseUrl: this.resolvedConfig.baseUrl,
-            env: {
-                ...process.env,
-                EVOLCLAW_SESSION_ID: sessionId,
-            },
+    getAppServerClient() {
+        if (!this.appServerClient) {
+            this.appServerClient = new CodexAppServerClient({
+                apiKey: this.resolvedConfig.apiKey,
+                baseUrl: this.resolvedConfig.baseUrl,
+                model: this.model,
+                effort: this.effort,
+                enableRequestUserInput: this.resolvedConfig.enableRequestUserInput,
+                approvalsReviewer: this.resolvedConfig.approvalsReviewer,
+                onServerRequest: request => this.handleAppServerRequest(request),
+            });
+        }
+        return this.appServerClient;
+    }
+    resetAppServerClient() {
+        const client = this.appServerClient;
+        this.appServerClient = null;
+        client?.close().catch(error => {
+            logger.debug(`[CodexRunner] Failed to close stale app-server client: ${error}`);
         });
-        return { codex, mod: this.codexModule };
     }
     // ── ModelSwitcher ──
-    setModel(model) { this.model = model; }
+    setModel(model) { this.model = model; this.resetAppServerClient(); }
     getModel() { return this.model; }
-    listModels() { return fetchCodexCatalog().map(m => m.slug); }
+    async listModels() {
+        try {
+            const response = await this.getAppServerClient().modelList(false);
+            const ids = (response.data ?? [])
+                .map(model => model.id || model.slug || model.name || model.model)
+                .filter((id) => typeof id === 'string' && id.length > 0);
+            if (ids.length > 0)
+                return ids;
+        }
+        catch (error) {
+            logger.debug(`[CodexRunner] app-server model/list failed, using catalog fallback: ${error}`);
+        }
+        return fetchCodexCatalog().map(m => m.slug);
+    }
     // ── Effort ──
-    setEffort(effort) { this.effort = effort; }
+    setEffort(effort) { this.effort = effort; this.resetAppServerClient(); }
     getEffort() { return this.effort; }
     // ── Permission ──
     currentMode = 'auto';
     approvalPolicy = 'never';
+    sandboxMode = 'danger-full-access';
     setMode(mode) {
         const map = {
+            // Codex app-server also supports auto_review, but EvolClaw auto currently means:
+            // run local blacklist/readonly guards, then approve app-server requests without
+            // app-server reviewer escalation. Changing this requires a semantic decision.
             'auto': 'never',
             'bypass': 'never',
+            'readonly': 'on-request',
             'request': 'on-request',
             'noask': 'untrusted',
         };
-        this.approvalPolicy = map[mode] || 'never';
         this.currentMode = mode;
+        this.approvalPolicy = map[mode] || 'never';
+        this.sandboxMode = this.toSandboxMode(mode);
     }
     getMode() { return this.currentMode; }
     listModes() {
         return [
             { key: 'auto', nameZh: '自动', description: '全部自动（受 sandbox 约束）', available: true },
             { key: 'bypass', nameZh: '放行', description: '全部自动（受 sandbox 约束）', available: true },
+            { key: 'readonly', nameZh: '只读', description: '允许读取和临时目录写入，拒绝项目文件修改', available: true },
             { key: 'request', nameZh: '审批', description: '需要审批时询问', available: true },
             { key: 'noask', nameZh: '静默', description: '只执行已知安全操作', available: true },
         ];
     }
-    setSendPrompt(_fn) { }
-    setPermissionGateway(_gw) { }
+    setSendPrompt(fn) { this.sendPromptFn = fn; }
+    setPermissionContext(sessionId, context) { this.permissionContexts.set(sessionId, context); }
+    setPermissionGateway(gw) { this.permissionGateway = gw; }
+    toSandboxMode(mode) {
+        if (mode === 'request' || mode === 'readonly' || mode === 'noask')
+            return 'read-only';
+        return 'danger-full-access';
+    }
     // ── Stream management (needed by MessageProcessor) ──
     registerStream(key, stream) {
         this.activeStreams.set(key, stream);
@@ -140,64 +270,113 @@ export class CodexRunner {
         this.activeAbortControllers.delete(key);
     }
     hasActiveStream(key) {
-        return this.activeStreams.has(key);
+        return this.activeStreams.has(key) || this.activeAbortControllers.has(key) || this.activeTurns.has(key);
     }
     // ── Core: runQuery ──
-    async runQuery(sessionId, prompt, projectPath, initialAgentSessionId, images, systemPromptAppend, sessionManager) {
-        const { codex } = await this.ensureCodex(sessionId);
+    async runQuery(sessionId, prompt, projectPath, initialAgentSessionId, images, systemPromptAppend, sessionManager, modelOverride) {
         let agentSessionId = initialAgentSessionId || this.activeSessions.get(sessionId);
-        let fullPrompt = prompt;
-        // Only inject system context on the first turn; resumed Codex threads already
-        // have that context in history and repeating it will pollute the conversation.
-        if (systemPromptAppend && !agentSessionId) {
-            fullPrompt = prompt + '\n\n--- [SYSTEM_PROMPT_END] ---\n' + systemPromptAppend;
-        }
+        const callModel = modelOverride?.model || this.model;
+        const callEffort = modelOverride?.effort ?? this.effort;
+        const appServer = this.getAppServerClient();
         const threadOptions = {
-            workingDirectory: projectPath,
-            model: this.model,
-            skipGitRepoCheck: true,
-            sandboxMode: 'danger-full-access',
+            model: callModel,
+            effort: callEffort,
             approvalPolicy: this.approvalPolicy,
-            ...(this.effort ? { modelReasoningEffort: this.effort } : {}),
+            approvalsReviewer: this.resolvedConfig.approvalsReviewer,
+            sandbox: this.sandboxMode,
+            config: this.buildEvolclawShellEnvironmentConfig(sessionId),
+            ...(systemPromptAppend ? { developerInstructions: systemPromptAppend } : {}),
         };
-        const thread = agentSessionId
-            ? codex.resumeThread(agentSessionId, threadOptions)
-            : codex.startThread(threadOptions);
+        const threadResponse = agentSessionId
+            ? await appServer.threadResume(agentSessionId, projectPath, threadOptions)
+            : await appServer.threadStart(projectPath, threadOptions);
+        const threadId = threadResponse.thread?.id || agentSessionId;
+        if (!threadId)
+            throw new Error('Codex app-server did not return a thread id');
+        agentSessionId = threadId;
+        this.activeSessions.set(sessionId, threadId);
+        this.onSessionIdUpdate?.(sessionId, threadId);
         const controller = new AbortController();
         this.activeAbortControllers.set(sessionId, controller);
-        // 构建输入：将 base64 图片写入临时文件，转换为 Codex SDK 的 local_image 格式
         const tempFiles = [];
-        let input;
-        if (images?.length) {
-            const tmpDir = os.tmpdir();
-            const parts = [{ type: 'text', text: fullPrompt }];
-            for (let i = 0; i < images.length; i++) {
-                const img = images[i];
-                const ext = MIME_EXT[img.mimeType || ''] || '.jpg';
-                const tmpPath = path.join(tmpDir, `evolclaw-img-${Date.now()}-${i}${ext}`);
-                fs.writeFileSync(tmpPath, Buffer.from(img.data, 'base64'));
-                tempFiles.push(tmpPath);
-                parts.push({ type: 'local_image', path: tmpPath });
-            }
-            input = parts;
-            logger.info(`[CodexRunner] Attached ${images.length} image(s) as local_image`);
+        const input = this.buildAppServerInput(prompt, images, tempFiles);
+        const queue = new AsyncEventQueue();
+        controller.signal.addEventListener('abort', () => queue.end(), { once: true });
+        const state = {
+            threadId,
+            streamedAgentMessageIds: new Set(),
+            agentMessageDeltaText: new Map(),
+            completedItemIds: new Set(),
+            completedTurnIds: new Set(),
+        };
+        const unsubscribe = appServer.onNotification(notification => {
+            // 仅从 turn/started 锁定权威 turnId — resume 时会有上一轮 turn 的残留通知
+            // （如 thread/tokenUsage/updated）先于新 turn 到达，不能用它们 latch turnId
+            const params = notification.params || {};
+            const notifThreadId = params.threadId ?? params.thread_id;
+            if (notifThreadId !== undefined && notifThreadId !== threadId)
+                return;
+            if (notification.method === 'turn/started') {
+                const startedTurnId = this.extractTurnId(notification);
+                if (startedTurnId && !state.turnId) {
+                    state.turnId = startedTurnId;
+                    this.activeTurns.set(sessionId, { threadId, turnId: startedTurnId });
+                }
+            }
+            if (!this.isAppServerTurnNotification(notification, state))
+                return;
+            queue.push(notification);
+            // 仅在已锁定 turnId 后才允许 turn/completed 结束队列，避免残留的旧 turn/completed 误关
+            if (notification.method === 'turn/completed' && state.turnId)
+                queue.end();
+        });
+        try {
+            const turnResponse = await appServer.turnStart(threadId, input, {
+                cwd: projectPath,
+                model: callModel,
+                effort: callEffort,
+                approvalPolicy: this.approvalPolicy,
+                sandbox: this.sandboxMode,
+            });
+            const turnId = turnResponse.turn?.id;
+            if (turnId && !state.turnId) {
+                state.turnId = turnId;
+                this.activeTurns.set(sessionId, { threadId, turnId });
+            }
+            const status = turnResponse.turn?.status;
+            if (status === 'completed' || status === 'failed') {
+                queue.push({ method: 'turn/completed', params: { threadId, turn: turnResponse.turn } });
+                queue.end();
+            }
         }
-        else {
-            input = fullPrompt;
+        catch (error) {
+            unsubscribe();
+            this.activeAbortControllers.delete(sessionId);
+            this.activeTurns.delete(sessionId);
+            this.cleanupTempFiles(tempFiles);
+            throw error;
         }
-        const { events } = await thread.runStreamed(input, { signal: controller.signal });
-        // 包装为 AgentEvent 流
-        return this.transformStream(events, sessionId, thread, tempFiles);
+        return this.transformAppServerStream(queue, sessionId, state, unsubscribe, tempFiles);
     }
     // ── Interrupt ──
     async interrupt(sessionKey) {
         const controller = this.activeAbortControllers.get(sessionKey);
-        if (controller) {
+        const activeTurn = this.activeTurns.get(sessionKey);
+        const hadActiveState = !!controller || !!activeTurn || this.activeStreams.has(sessionKey);
+        const interruptTurn = activeTurn
+            ? this.getAppServerClient().turnInterrupt(activeTurn.threadId, activeTurn.turnId).catch(error => {
+                logger.debug(`[CodexRunner] app-server turn interrupt failed: ${error}`);
+            })
+            : Promise.resolve();
+        if (controller)
             controller.abort('User interrupt');
+        if (hadActiveState) {
             this.activeAbortControllers.delete(sessionKey);
             this.activeStreams.delete(sessionKey);
+            this.activeTurns.delete(sessionKey);
             logger.info(`[CodexRunner] Interrupted session: ${sessionKey}`);
         }
+        await interruptTurn;
     }
     // ── Session commands ──
     updateSessionId(sessionId, agentSessionId) {
@@ -213,6 +392,8 @@ export class CodexRunner {
         this.activeSessions.delete(sessionId);
         this.activeStreams.delete(sessionId);
         this.activeAbortControllers.delete(sessionId);
+        this.activeTurns.delete(sessionId);
+        this.permissionContexts.delete(sessionId);
     }
     resolveSessionFile(agentSessionId, _projectPath) {
         // Codex session 文件: ~/.codex/sessions/YYYY/MM/DD/rollout-*-{threadId}.jsonl
@@ -235,113 +416,855 @@ export class CodexRunner {
         };
         return search(sessionsDir);
     }
-    async clearSession(_sessionId, _agentSessionId, _projectPath) {
+    async clearSession(sessionId, _agentSessionId, _projectPath) {
         // Codex: 清空会话 = 下次 runQuery 不传 resumeId，自动创建新 thread
+        this.activeSessions.delete(sessionId);
+        this.onSessionIdUpdate?.(sessionId, '');
         return true;
     }
-    async compactSession(_sessionId, _agentSessionId, _projectPath) {
-        // Codex CLI 内部处理 compaction，外部无法触发
-        logger.info('[CodexRunner] Compact not supported, Codex handles context internally');
-        return false;
+    async compactSession(_sessionId, agentSessionId, _projectPath) {
+        try {
+            const appServer = this.getAppServerClient();
+            this.onCompactStart?.(_sessionId);
+            try {
+                return await this.startAndWaitForCompact(appServer, agentSessionId);
+            }
+            catch (error) {
+                if (!this.isThreadNotFoundError(error))
+                    throw error;
+                logger.info(`[CodexRunner] Compact thread not loaded, resuming before compact: ${agentSessionId}`);
+                await appServer.threadResume(agentSessionId, _projectPath, {
+                    model: this.model,
+                    effort: this.effort,
+                    approvalPolicy: this.approvalPolicy,
+                    approvalsReviewer: this.resolvedConfig.approvalsReviewer,
+                    sandbox: this.sandboxMode,
+                    config: this.buildEvolclawShellEnvironmentConfig(_sessionId),
+                });
+                return await this.startAndWaitForCompact(appServer, agentSessionId);
+            }
+        }
+        catch (error) {
+            logger.error('[CodexRunner] Compact failed:', error);
+            return false;
+        }
     }
-    async compact(_sessionId, _agentSessionId, _projectPath) {
-        return this.compactSession(_sessionId, _agentSessionId, _projectPath);
+    async compact(sessionId, agentSessionId, projectPath) {
+        return this.compactSession(sessionId, agentSessionId, projectPath);
     }
-    setCompactStartCallback(_callback) { }
-    // ── Event stream transformation ──
-    async *transformStream(events, sessionId, thread, tempFiles) {
+    async startAndWaitForCompact(appServer, threadId) {
+        const completion = this.waitForThreadCompacted(appServer, threadId, Date.now());
         try {
-            for await (const event of events) {
-                if (!this.activeAbortControllers.has(sessionId))
-                    break;
-                yield* this.mapEvent(event, sessionId, thread);
-            }
+            await appServer.threadCompactStart(threadId);
+            await completion.promise;
+            return true;
         }
         finally {
-            this.activeAbortControllers.delete(sessionId);
-            // 清理临时图片文件
-            if (tempFiles?.length) {
-                for (const f of tempFiles) {
+            completion.dispose();
+        }
+    }
+    waitForThreadCompacted(appServer, threadId, startedAtMs) {
+        let unsubscribe;
+        let pollTimer;
+        let settled = false;
+        const settle = (resolve, source) => {
+            if (settled)
+                return;
+            settled = true;
+            if (pollTimer)
+                clearInterval(pollTimer);
+            logger.info(`[CodexRunner] Compact completed for thread: ${threadId} (${source})`);
+            unsubscribe?.();
+            resolve();
+        };
+        const promise = new Promise(resolve => {
+            unsubscribe = appServer.onNotification(notification => {
+                if (notification.method !== 'thread/compacted')
+                    return;
+                const params = notification.params || {};
+                const notifThreadId = params.threadId ?? params.thread_id;
+                if (notifThreadId !== threadId)
+                    return;
+                settle(resolve, 'notification');
+            });
+            pollTimer = setInterval(() => {
+                if (this.hasPersistedCompactCompletion(threadId, startedAtMs)) {
+                    settle(resolve, 'session-log');
+                }
+            }, 1000);
+            pollTimer.unref?.();
+        });
+        return {
+            promise,
+            dispose: () => {
+                if (pollTimer)
+                    clearInterval(pollTimer);
+                if (!settled)
+                    unsubscribe?.();
+            },
+        };
+    }
+    hasPersistedCompactCompletion(threadId, startedAtMs) {
+        const sessionFile = this.findCodexSessionFile(threadId);
+        if (!sessionFile)
+            return false;
+        let text = '';
+        try {
+            text = fs.readFileSync(sessionFile, 'utf8');
+        }
+        catch {
+            return false;
+        }
+        const threshold = startedAtMs - 1000;
+        for (const line of text.trimEnd().split('\n').reverse()) {
+            if (!line.trim())
+                continue;
+            let entry;
+            try {
+                entry = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const ts = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : NaN;
+            if (!Number.isFinite(ts))
+                continue;
+            if (ts < threshold)
+                break;
+            const payloadType = entry.payload?.type;
+            if (entry.type === 'compacted' || payloadType === 'context_compacted')
+                return true;
+        }
+        return false;
+    }
+    findCodexSessionFile(threadId) {
+        const root = process.env.CODEX_HOME
+            ? path.join(process.env.CODEX_HOME, 'sessions')
+            : path.join(process.env.HOME || os.homedir(), '.codex', 'sessions');
+        const stack = [root];
+        let newest;
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(fullPath);
+                }
+                else if (entry.isFile() && entry.name.includes(threadId) && entry.name.endsWith('.jsonl')) {
+                    let mtimeMs = 0;
                     try {
-                        fs.unlinkSync(f);
+                        mtimeMs = fs.statSync(fullPath).mtimeMs;
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        continue;
+                    }
+                    if (!newest || mtimeMs > newest.mtimeMs)
+                        newest = { path: fullPath, mtimeMs };
                 }
             }
         }
+        return newest?.path;
     }
-    *mapEvent(event, sessionId, thread) {
-        switch (event.type) {
-            case 'thread.started': {
-                const threadId = event.thread_id;
-                this.activeSessions.set(sessionId, threadId);
-                this.onSessionIdUpdate?.(sessionId, threadId);
-                yield { type: 'session_id', sessionId: threadId };
-                break;
+    async forkSession(agentSessionId, projectPath, title) {
+        const response = await this.getAppServerClient().threadFork(agentSessionId, projectPath, title);
+        const forkedThreadId = response.thread?.id;
+        if (!forkedThreadId)
+            throw new Error('Codex fork did not return a thread id');
+        return forkedThreadId;
+    }
+    async setSessionName(agentSessionId, name) {
+        return this.getAppServerClient().threadSetName(agentSessionId, name);
+    }
+    async updateSessionMetadata(agentSessionId, metadata) {
+        const gitInfo = metadata?.gitInfo && typeof metadata.gitInfo === 'object' ? metadata.gitInfo : undefined;
+        return this.getAppServerClient().threadMetadataUpdate(agentSessionId, gitInfo);
+    }
+    async getSessionMessages(agentSessionId, projectPath) {
+        const response = await this.getAppServerClient().threadRead(agentSessionId, true);
+        return this.mapThreadToSessionMessages(response, agentSessionId);
+    }
+    async handleAppServerRequest(request) {
+        const params = (request.params || {});
+        if (request.method === 'item/tool/requestUserInput') {
+            return this.handleToolRequestUserInput(params);
+        }
+        const sessionKey = this.findSessionKeyByThread(params.threadId || params.conversationId);
+        const toolName = request.method.includes('fileChange') || request.method === 'applyPatchApproval' ? 'FileChange' : 'Bash';
+        const toolInput = this.buildPermissionInput(request.method, params);
+        const summary = this.summarizeAppServerRequest(request.method, params);
+        const reason = params.reason || params.decisionReason || undefined;
+        const projectPath = this.resolvePermissionProjectPath(params);
+        logger.info(`[CodexRunner] app-server approval request id=${request.id} method=${request.method} session=${sessionKey} mode=${this.currentMode} tool=${toolName} summary=${summary}`);
+        try {
+            const decision = await this.resolvePermissionDecision(sessionKey, toolName, toolInput, summary, reason, projectPath);
+            const response = this.toAppServerApprovalResponse(request.method, decision);
+            logger.info(`[CodexRunner] app-server approval response id=${request.id} method=${request.method} decision=${decision} response=${JSON.stringify(response)}`);
+            return response;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`[CodexRunner] app-server approval failed id=${request.id} method=${request.method}: ${message}`);
+            throw error;
+        }
+    }
+    async handleToolRequestUserInput(params) {
+        const sessionKey = this.findSessionKeyByThread(params.threadId);
+        const questions = Array.isArray(params.questions) ? params.questions : [];
+        const answers = {};
+        for (const question of questions) {
+            const questionId = typeof question.id === 'string' ? question.id : `q-${Object.keys(answers).length + 1}`;
+            answers[questionId] = {
+                answers: await this.collectUserInputAnswer(sessionKey, question),
+            };
+        }
+        return { answers };
+    }
+    async collectUserInputAnswer(sessionKey, question) {
+        const options = Array.isArray(question.options) ? question.options : [];
+        const fallback = options[0]?.label ? [String(options[0].label)] : [''];
+        const context = this.permissionContexts.get(sessionKey);
+        const canFreeText = question.isOther !== false || options.length === 0;
+        const sendPrompt = context?.adapter && context.channelId
+            ? async (text) => context.adapter.send(buildEnvelope({
+                channel: context.adapter.channelName,
+                channelId: context.channelId,
+                replyContext: context.replyContext,
+            }), { kind: 'result.text', text, isFinal: true })
+            : this.sendPromptFn;
+        if (!context?.interactionRouter || !sendPrompt) {
+            if (sendPrompt)
+                await sendPrompt(this.formatUserInputFallback(question, fallback));
+            return fallback;
+        }
+        const requestId = `codex-ask-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const buttonArgMap = {};
+        const buttons = options.length > 0
+            ? options.map((option, index) => {
+                const key = `opt-${index}`;
+                buttonArgMap[key] = String(index + 1);
+                return { key, label: String(option.label || `选项 ${index + 1}`), style: 'default' };
+            })
+            : [{ key: 'custom', label: '提交', style: 'primary' }];
+        const bodyLines = [String(question.question || '')];
+        if (options.some((option) => option.description)) {
+            bodyLines.push('', ...options.map((option, index) => `${index + 1}. ${String(option.label || `选项 ${index + 1}`)}${option.description ? ` — ${option.description}` : ''}`));
+        }
+        const interaction = {
+            type: 'interaction',
+            id: requestId,
+            channelId: context.channelId || '',
+            sessionId: sessionKey,
+            initiatorId: context.userId,
+            kind: {
+                kind: 'action',
+                title: String(question.header || '问题'),
+                body: bodyLines.join('\n'),
+                buttons,
+                allowCustomInput: canFreeText,
+            },
+            fallback: {
+                command: 'ask',
+                buttonArgMap,
+                acceptFreeText: canFreeText,
+                freeTextHint: canFreeText ? '或回复 /ask <自定义内容>' : undefined,
+            },
+        };
+        const router = context.interactionRouter;
+        router.markWaiting(sessionKey);
+        let waitMarked = true;
+        let sent = false;
+        try {
+            await context.flushPending?.();
+            if (context.adapter && context.channelId) {
+                const envelope = buildEnvelope({
+                    taskId: context.taskId,
+                    channel: context.channel ?? context.adapter.channelName,
+                    channelId: context.channelId,
+                    agentName: context.agentName,
+                    chatmode: context.chatmode,
+                    replyContext: context.replyContext,
+                });
+                sent = !!await sendInteractionPayload(context.adapter, envelope, interaction, undefined, context.replyContext);
+            }
+            if (!sent) {
+                await sendPrompt(renderActionAsText(interaction));
+                sent = true;
             }
-            case 'item.started': {
-                const item = event.item;
-                if (item.type === 'command_execution') {
-                    yield { type: 'tool_use', name: 'Shell', input: { command: item.command } };
+        }
+        catch (error) {
+            logger.warn('[CodexRunner] requestUserInput prompt send failed:', error);
+        }
+        if (!sent) {
+            router.unmarkWaiting(sessionKey);
+            return fallback;
+        }
+        return new Promise((resolve) => {
+            router.register(requestId, sessionKey, (action, values) => {
+                resolve(this.parseUserInputAction(action, values, options, fallback));
+            }, {
+                initiatorId: context.userId,
+                fallbackCommand: 'ask',
+            });
+            if (waitMarked) {
+                router.unmarkWaiting(sessionKey);
+                waitMarked = false;
+            }
+        });
+    }
+    parseUserInputAction(action, values, options, fallback) {
+        if (action === '_custom_input') {
+            const customText = typeof values?.custom_text === 'string' ? values.custom_text.trim() : '';
+            return customText ? [customText] : fallback;
+        }
+        if (action.startsWith('opt-')) {
+            const index = Number.parseInt(action.slice(4), 10);
+            const label = options[index]?.label;
+            return label ? [String(label)] : fallback;
+        }
+        const selected = action.split(',').map(part => part.trim()).filter(Boolean);
+        if (selected.length > 0 && selected.every(part => /^\d+$/.test(part))) {
+            const labels = selected
+                .map(part => options[Number.parseInt(part, 10) - 1]?.label)
+                .filter((label) => typeof label === 'string' && label.length > 0);
+            if (labels.length > 0)
+                return labels;
+        }
+        return action.trim() ? [action.trim()] : fallback;
+    }
+    formatUserInputFallback(question, fallback) {
+        const options = Array.isArray(question.options) ? question.options : [];
+        const lines = [String(question.header || '问题'), String(question.question || '')].filter(Boolean);
+        if (options.length > 0) {
+            lines.push('', ...options.map((option, index) => `${index + 1}. ${String(option.label || `选项 ${index + 1}`)}${option.description ? ` — ${option.description}` : ''}`));
+        }
+        lines.push('', `自动选择：${fallback.join(', ')}`);
+        return lines.join('\n');
+    }
+    findSessionKeyByThread(threadId) {
+        if (threadId) {
+            for (const [sessionKey, activeThreadId] of this.activeSessions.entries()) {
+                if (activeThreadId === threadId)
+                    return sessionKey;
+            }
+        }
+        return threadId || 'codex-app-server';
+    }
+    buildPermissionInput(method, params) {
+        if (method.includes('fileChange') || method === 'applyPatchApproval') {
+            return { fileChanges: params.fileChanges, grantRoot: params.grantRoot, reason: params.reason };
+        }
+        const command = Array.isArray(params.command) ? params.command.join(' ') : (params.command || '');
+        return { command, cwd: params.cwd, reason: params.reason, commandActions: params.commandActions || params.parsedCmd };
+    }
+    summarizeAppServerRequest(method, params) {
+        if (method.includes('fileChange') || method === 'applyPatchApproval') {
+            if (params.grantRoot)
+                return '允许写入：' + params.grantRoot;
+            const changes = params.fileChanges && typeof params.fileChanges === 'object' ? Object.keys(params.fileChanges) : [];
+            return changes.length ? changes.join(', ') : '文件变更审批';
+        }
+        const command = Array.isArray(params.command) ? params.command.join(' ') : params.command;
+        return command || '命令执行审批';
+    }
+    resolvePermissionProjectPath(params) {
+        const candidates = [params.cwd, params.projectPath, params.grantRoot]
+            .filter((value) => typeof value === 'string' && value.length > 0);
+        for (const candidate of candidates) {
+            if (path.isAbsolute(candidate))
+                return candidate;
+        }
+        return process.cwd();
+    }
+    checkCodexReadonly(toolName, input, projectPath) {
+        if (toolName === 'Bash')
+            return checkReadonly(toolName, input, projectPath);
+        if (toolName !== 'FileChange')
+            return { behavior: 'allow' };
+        const tmpDir = path.join(projectPath, '.evolclaw', 'tmp') + path.sep;
+        const isAllowedPath = (filePath) => {
+            const resolved = path.resolve(projectPath, filePath) + (filePath.endsWith(path.sep) ? path.sep : '');
+            return resolved.startsWith(tmpDir) || resolved === tmpDir.slice(0, -1);
+        };
+        const grantRoot = input.grantRoot;
+        if (typeof grantRoot === 'string' && grantRoot && !isAllowedPath(grantRoot)) {
+            return { behavior: 'deny', message: '🔒 只读模式：禁止修改项目文件。如需生成文件请写入 .evolclaw/tmp/ 目录' };
+        }
+        const fileChanges = input.fileChanges;
+        const paths = fileChanges && typeof fileChanges === 'object' ? Object.keys(fileChanges) : [];
+        if (paths.some(filePath => !isAllowedPath(filePath))) {
+            return { behavior: 'deny', message: '🔒 只读模式：禁止修改项目文件。如需生成文件请写入 .evolclaw/tmp/ 目录' };
+        }
+        return { behavior: 'allow' };
+    }
+    async resolvePermissionDecision(sessionKey, toolName, toolInput, summary, reason, projectPath = process.cwd()) {
+        const blacklist = await checkBlacklist(toolName, toolInput);
+        if (blacklist.behavior === 'deny')
+            return 'deny';
+        if (toolName === 'Bash' && this.isEvolclawCtlSendOrFile(blacklist.updatedInput)) {
+            return 'allow';
+        }
+        if (this.currentMode === 'readonly') {
+            const readonly = this.checkCodexReadonly(toolName, blacklist.updatedInput, projectPath);
+            if (readonly.behavior === 'deny')
+                return 'deny';
+            return 'allow';
+        }
+        if (this.currentMode === 'bypass' || this.currentMode === 'auto')
+            return 'allow';
+        if (this.currentMode === 'noask')
+            return 'deny';
+        if (!this.permissionGateway || !this.sendPromptFn)
+            return 'allow';
+        if (this.permissionGateway.isAlwaysAllowed(toolName))
+            return 'always';
+        return this.permissionGateway.requestPermission(sessionKey, toolName, toolInput, this.sendPromptFn, this.permissionContexts.get(sessionKey), summary, reason);
+    }
+    isEvolclawCtlSendOrFile(input) {
+        const command = typeof input.command === 'string' ? input.command.trim() : '';
+        if (!/^(?:ec|evolclaw)\s+ctl\s+(?:send|file)(?:\s|$)/.test(command))
+            return false;
+        // Keep the whitelist to a single CLI invocation. If text contains shell control
+        // syntax, fall back to the normal permission mode instead of silently approving.
+        return !/[;&|`]|[$][(]|\r|\n/.test(command);
+    }
+    toAppServerApprovalResponse(method, decision) {
+        if (method === 'execCommandApproval' || method === 'applyPatchApproval') {
+            return { decision: decision === 'deny' ? 'denied' : decision === 'always' ? 'approved_for_session' : 'approved' };
+        }
+        if (method === 'item/commandExecution/requestApproval') {
+            return { decision: decision === 'deny' ? 'decline' : decision === 'always' ? 'acceptForSession' : 'accept' };
+        }
+        if (method === 'item/fileChange/requestApproval') {
+            return { decision: decision === 'deny' ? 'decline' : decision === 'always' ? 'acceptForSession' : 'accept' };
+        }
+        if (method === 'item/permissions/requestApproval') {
+            if (decision === 'deny')
+                throw new Error('Permission request denied');
+            return { permissions: {}, scope: decision === 'always' ? 'session' : 'turn' };
+        }
+        throw new Error('Unsupported Codex app-server request: ' + method);
+    }
+    async rollbackSessionTurns(agentSessionId, _projectPath, numTurns) {
+        if (numTurns < 1)
+            return true;
+        const response = await this.getAppServerClient().threadRollback(agentSessionId, numTurns);
+        return !!response.thread;
+    }
+    async rewindFiles(agentSessionId, projectPath, userMessageId) {
+        const messages = await this.getSessionMessages(agentSessionId, projectPath);
+        const targetIndex = messages.findIndex(message => message.uuid === userMessageId);
+        if (targetIndex < 0)
+            return { canRewind: false, error: 'target turn not found' };
+        const changedFiles = new Set();
+        for (let i = targetIndex; i < messages.length; i++) {
+            const message = messages[i];
+            const content = Array.isArray(message.message?.content) ? message.message.content : [];
+            for (const part of content) {
+                if (part?.type === 'file_change' && typeof part.path === 'string')
+                    changedFiles.add(part.path);
+            }
+        }
+        if (changedFiles.size === 0) {
+            return { canRewind: false, error: 'no file changes recorded for target turn' };
+        }
+        const snapshotFiles = [...changedFiles];
+        for (const filePath of snapshotFiles) {
+            const absolutePath = path.isAbsolute(filePath) ? filePath : path.join(projectPath, filePath);
+            const content = this.readGitHeadFile(projectPath, filePath);
+            if (content === null) {
+                fs.rmSync(absolutePath, { force: true });
+            }
+            else {
+                fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+                fs.writeFileSync(absolutePath, content);
+            }
+        }
+        return { canRewind: true, filesChanged: snapshotFiles };
+    }
+    readGitHeadFile(projectPath, filePath) {
+        try {
+            return execFileSync('git', ['show', `HEAD:${filePath.replace(/\\/g, '/')}`], { cwd: projectPath, stdio: ['pipe', 'pipe', 'ignore'] });
+        }
+        catch {
+            return null;
+        }
+    }
+    mapThreadToSessionMessages(response, fallbackThreadId) {
+        const thread = response.thread;
+        const threadId = thread?.id || fallbackThreadId;
+        const messages = [];
+        for (const turn of thread?.turns ?? []) {
+            for (const item of this.getTurnItems(turn)) {
+                if (item.type === 'userMessage') {
+                    messages.push({
+                        type: 'user',
+                        uuid: item.id || turn.id || (threadId + '-user-' + messages.length),
+                        session_id: threadId,
+                        message: { role: 'user', content: this.mapUserInputToContent(item.content) },
+                        parent_tool_use_id: null,
+                    });
                 }
-                else if (item.type === 'mcp_tool_call') {
-                    yield { type: 'tool_use', name: `MCP:${item.server}/${item.tool}`, input: item.arguments };
+                else if (item.type === 'agentMessage') {
+                    messages.push({
+                        type: 'assistant',
+                        uuid: item.id || turn.id || (threadId + '-assistant-' + messages.length),
+                        session_id: threadId,
+                        message: { role: 'assistant', content: item.text || '' },
+                        parent_tool_use_id: null,
+                    });
                 }
                 else if (item.type === 'file_change') {
-                    const desc = item.changes.map((c) => `${c.kind} ${c.path}`).join(', ');
-                    yield { type: 'tool_use', name: 'FileChange', input: { description: desc } };
+                    messages.push({
+                        type: 'system',
+                        uuid: item.id || turn.id || (threadId + '-file-' + messages.length),
+                        session_id: threadId,
+                        message: { role: 'system', content: this.mapFileChangeToContent(item) },
+                        parent_tool_use_id: null,
+                    });
                 }
-                else if (item.type === 'web_search') {
-                    yield { type: 'tool_use', name: 'WebSearch', input: { query: item.query } };
+            }
+        }
+        return messages;
+    }
+    getTurnItems(turn) {
+        const items = Array.isArray(turn?.items) ? turn.items : [];
+        const input = Array.isArray(turn?.input) ? turn.input : [];
+        const output = Array.isArray(turn?.output) ? turn.output : [];
+        return [...items, ...input, ...output];
+    }
+    mapUserInputToContent(content) {
+        if (!Array.isArray(content))
+            return [];
+        return content.map((part) => {
+            if (part?.type === 'text')
+                return { type: 'text', text: part.text || '' };
+            if (part?.type === 'localImage')
+                return { type: 'image', path: part.path };
+            if (part?.type === 'image')
+                return { type: 'image', url: part.url };
+            return { type: 'text', text: part?.text || part?.name || '' };
+        });
+    }
+    mapFileChangeToContent(item) {
+        const changes = this.normalizeFileChanges(item.changes);
+        return changes
+            .filter((change) => typeof change?.path === 'string')
+            .map((change) => {
+            const kind = this.normalizeFileChangeKind(change.kind ?? change.type);
+            return {
+                type: 'file_change',
+                path: change.path,
+                ...(kind ? { kind } : {}),
+            };
+        });
+    }
+    normalizeFileChanges(changes) {
+        if (Array.isArray(changes))
+            return changes;
+        if (!changes || typeof changes !== 'object')
+            return [];
+        return Object.entries(changes).map(([filePath, change]) => ({
+            ...(change && typeof change === 'object' ? change : {}),
+            path: filePath,
+        }));
+    }
+    describeFileChange(change) {
+        const kind = this.normalizeFileChangeKind(change?.kind ?? change?.type);
+        const filePath = typeof change?.path === 'string' ? change.path : '';
+        return [kind || 'change', filePath].filter(Boolean).join(' ');
+    }
+    normalizeFileChangeKind(kind) {
+        if (typeof kind === 'string')
+            return kind;
+        if (!kind || typeof kind !== 'object')
+            return undefined;
+        const data = kind;
+        for (const key of ['type', 'kind', 'action', 'operation', 'op']) {
+            if (typeof data[key] === 'string')
+                return data[key];
+        }
+        return undefined;
+    }
+    isThreadNotFoundError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return /thread\/compact\/start failed: thread not found:/i.test(message)
+            || /thread not found:/i.test(message);
+    }
+    setCompactStartCallback(callback) {
+        this.onCompactStart = callback;
+    }
+    // ── Event stream transformation ──
+    buildAppServerInput(prompt, images, tempFiles) {
+        const input = [{ type: 'text', text: prompt, text_elements: [] }];
+        if (!images?.length)
+            return input;
+        const tmpDir = os.tmpdir();
+        for (let i = 0; i < images.length; i++) {
+            const img = images[i];
+            const ext = MIME_EXT[img.mimeType || ''] || '.jpg';
+            const tmpPath = path.join(tmpDir, `evolclaw-img-${Date.now()}-${i}${ext}`);
+            fs.writeFileSync(tmpPath, Buffer.from(img.data, 'base64'));
+            tempFiles.push(tmpPath);
+            input.push({ type: 'localImage', path: tmpPath });
+        }
+        logger.info(`[CodexRunner] Attached ${images.length} image(s) as localImage`);
+        return input;
+    }
+    cleanupTempFiles(tempFiles) {
+        if (!tempFiles?.length)
+            return;
+        for (const tempFile of tempFiles) {
+            try {
+                fs.unlinkSync(tempFile);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    extractTurnId(notification) {
+        const params = notification.params || {};
+        return typeof params.turnId === 'string' ? params.turnId :
+            typeof params.turn_id === 'string' ? params.turn_id :
+                typeof params.turn?.id === 'string' ? params.turn.id : undefined;
+    }
+    isAppServerTurnNotification(notification, state) {
+        const params = notification.params || {};
+        const notifThreadId = params.threadId ?? params.thread_id;
+        if (notifThreadId !== undefined && notifThreadId !== state.threadId)
+            return false;
+        const turnId = this.extractTurnId(notification);
+        if (!state.turnId) {
+            return notification.method === 'turn/started' || !turnId;
+        }
+        return !state.turnId || !turnId || turnId === state.turnId;
+    }
+    async *transformAppServerStream(notifications, sessionId, state, unsubscribe, tempFiles) {
+        try {
+            yield { type: 'session_id', sessionId: state.threadId };
+            for await (const notification of notifications) {
+                if (!this.activeAbortControllers.has(sessionId))
+                    break;
+                yield* this.mapAppServerNotification(notification, sessionId, state);
+            }
+        }
+        finally {
+            unsubscribe();
+            this.activeAbortControllers.delete(sessionId);
+            this.activeTurns.delete(sessionId);
+            this.cleanupTempFiles(tempFiles);
+        }
+    }
+    *mapAppServerNotification(notification, sessionId, state) {
+        const params = notification.params || {};
+        switch (notification.method) {
+            case 'turn/started': {
+                const turnId = this.extractTurnId(notification);
+                if (turnId) {
+                    state.turnId = turnId;
+                    this.activeTurns.set(sessionId, { threadId: state.threadId, turnId });
                 }
+                yield { type: 'state_changed', state: 'running' };
                 break;
             }
-            case 'item.completed': {
-                const item = event.item;
-                if (item.type === 'agent_message') {
-                    yield { type: 'text', text: item.text };
-                }
-                else if (item.type === 'command_execution') {
-                    yield {
-                        type: 'tool_result',
-                        name: 'Shell',
-                        result: item.aggregated_output,
-                        isError: item.exit_code !== 0,
-                    };
-                }
-                else if (item.type === 'mcp_tool_call') {
-                    yield {
-                        type: 'tool_result',
-                        name: `MCP:${item.server}/${item.tool}`,
-                        result: item.result,
-                        isError: item.status === 'failed',
-                        error: item.error?.message,
-                    };
-                }
-                else if (item.type === 'error') {
-                    yield { type: 'error', error: item.message, errorType: 'unknown' };
+            case 'item/started': {
+                yield* this.mapAppServerItemStarted(params.item);
+                break;
+            }
+            case 'item/agentMessage/delta': {
+                const itemId = typeof params.itemId === 'string' ? params.itemId : undefined;
+                if (itemId)
+                    state.streamedAgentMessageIds.add(itemId);
+                if (itemId && typeof params.delta === 'string' && params.delta) {
+                    state.agentMessageDeltaText.set(itemId, (state.agentMessageDeltaText.get(itemId) || '') + params.delta);
                 }
                 break;
             }
-            case 'turn.completed': {
-                yield {
-                    type: 'complete',
-                    result: undefined,
-                    costUsd: undefined,
-                    durationMs: undefined,
-                };
+            case 'item/completed': {
+                const item = params.item;
+                if (item?.id)
+                    state.completedItemIds.add(item.id);
+                yield* this.mapAppServerItemCompleted(item, state);
+                break;
+            }
+            case 'turn/plan/updated': {
+                const plan = Array.isArray(params.plan) ? params.plan : [];
+                const completed = plan.filter((step) => step?.status === 'completed').length;
+                const summary = plan.length ? `计划进度：${completed}/${plan.length}` : (params.explanation || '计划已更新');
+                yield { type: 'task_progress', summary };
+                break;
+            }
+            case 'thread/tokenUsage/updated': {
+                state.tokenUsage = params.tokenUsage;
+                break;
+            }
+            case 'thread/compacted': {
+                logger.info(`[CodexRunner] Compact completed for thread: ${params.threadId || state.threadId}`);
+                yield { type: 'compact', preTokens: 0 };
                 break;
             }
-            case 'turn.failed': {
-                yield { type: 'error', error: event.error.message, errorType: 'unknown' };
+            case 'turn/completed': {
+                const turn = params.turn || {};
+                const turnId = turn.id || params.turnId;
+                if (turnId && state.completedTurnIds.has(turnId))
+                    break;
+                if (turnId)
+                    state.completedTurnIds.add(turnId);
+                this.activeTurns.delete(sessionId);
+                if (turn.status === 'failed' && turn.error?.message) {
+                    yield { type: 'error', error: turn.error.message, errorType: 'unknown' };
+                }
+                yield this.mapAppServerTurnComplete(turn, state);
                 break;
             }
             case 'error': {
-                yield { type: 'error', error: event.message, errorType: 'unknown' };
+                yield { type: 'error', error: params.message || 'Codex app-server error', errorType: 'unknown' };
+                break;
+            }
+        }
+    }
+    *mapAppServerItemStarted(item) {
+        if (!item)
+            return;
+        switch (item.type) {
+            case 'commandExecution':
+                yield { type: 'tool_use', name: 'Shell', input: { command: item.command, cwd: item.cwd }, callId: item.id };
+                break;
+            case 'mcpToolCall':
+                yield { type: 'tool_use', name: `MCP:${item.server}/${item.tool}`, input: item.arguments, callId: item.id };
+                break;
+            case 'dynamicToolCall':
+                yield { type: 'tool_use', name: item.namespace ? `${item.namespace}:${item.tool}` : item.tool, input: item.arguments, callId: item.id };
+                break;
+            case 'fileChange': {
+                const desc = this.normalizeFileChanges(item.changes).map((change) => this.describeFileChange(change)).join(', ');
+                yield { type: 'tool_use', name: 'FileChange', input: { description: desc }, callId: item.id };
                 break;
             }
+            case 'webSearch':
+                yield { type: 'tool_use', name: 'WebSearch', input: { query: item.query }, callId: item.id };
+                break;
+            case 'plan':
+                yield { type: 'task_progress', summary: item.text || '计划已更新' };
+                break;
         }
     }
+    *mapAppServerItemCompleted(item, state) {
+        if (!item)
+            return;
+        switch (item.type) {
+            case 'agentMessage':
+                {
+                    const buffered = item.id ? state.agentMessageDeltaText.get(item.id) : undefined;
+                    const text = typeof item.text === 'string' && item.text ? item.text : buffered;
+                    if (text)
+                        yield { type: 'text', text };
+                    if (item.id)
+                        state.agentMessageDeltaText.delete(item.id);
+                }
+                break;
+            case 'commandExecution':
+                yield {
+                    type: 'tool_result',
+                    name: 'Shell',
+                    result: item.aggregatedOutput ?? '',
+                    isError: item.exitCode !== null && item.exitCode !== undefined ? item.exitCode !== 0 : item.status === 'failed',
+                    callId: item.id,
+                };
+                break;
+            case 'mcpToolCall':
+                yield {
+                    type: 'tool_result',
+                    name: `MCP:${item.server}/${item.tool}`,
+                    result: item.result,
+                    isError: item.status === 'failed',
+                    error: item.error?.message,
+                    callId: item.id,
+                };
+                break;
+            case 'dynamicToolCall':
+                yield {
+                    type: 'tool_result',
+                    name: item.namespace ? `${item.namespace}:${item.tool}` : item.tool,
+                    result: item.contentItems,
+                    isError: item.success === false || item.status === 'failed',
+                    callId: item.id,
+                };
+                break;
+            case 'fileChange':
+                yield { type: 'tool_result', name: 'FileChange', result: item.changes, isError: item.status === 'failed', callId: item.id };
+                break;
+        }
+    }
+    pickNumber(...values) {
+        for (const value of values) {
+            if (typeof value === 'number' && Number.isFinite(value))
+                return value;
+        }
+        return undefined;
+    }
+    mapCodexTokenUsage(raw) {
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const usage = {
+            input_tokens: this.pickNumber(raw.inputTokens, raw.input_tokens),
+            output_tokens: this.pickNumber(raw.outputTokens, raw.output_tokens),
+            cache_read_input_tokens: this.pickNumber(raw.cachedInputTokens, raw.cache_read_input_tokens, raw.cached_input_tokens),
+            cache_creation_input_tokens: this.pickNumber(raw.cacheCreationInputTokens, raw.cache_creation_input_tokens, raw.cache_creation_tokens),
+        };
+        return Object.values(usage).some(value => value !== undefined) ? usage : undefined;
+    }
+    mapCodexContextUsage(raw) {
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const totalTokens = this.pickNumber(raw.totalTokens, raw.total_tokens, raw.total);
+        const maxTokens = this.pickNumber(raw.maxTokens, raw.max_tokens, raw.max);
+        const model = typeof raw.model === 'string' ? raw.model : undefined;
+        if (totalTokens === undefined || maxTokens === undefined || !model)
+            return undefined;
+        const percentage = this.pickNumber(raw.percentage) ?? Math.round((totalTokens / maxTokens) * 100);
+        const effort = typeof raw.effort === 'string' ? raw.effort : undefined;
+        return { totalTokens, maxTokens, percentage, model, effort };
+    }
+    mapAppServerTurnComplete(turn, state) {
+        const status = turn.status || 'completed';
+        const tokenUsage = this.mapCodexTokenUsage(state.tokenUsage?.last ?? turn.tokenUsage ?? turn.usage);
+        const contextUsage = this.mapCodexContextUsage(turn.contextUsage ?? state.tokenUsage?.contextUsage ?? state.tokenUsage?.context);
+        const terminalReason = status === 'completed'
+            ? undefined
+            : status === 'interrupted'
+                ? 'aborted_streaming'
+                : status;
+        return {
+            type: 'complete',
+            subtype: status === 'completed' ? 'success' : status,
+            isError: status === 'failed',
+            errors: turn.error?.message ? [turn.error.message] : undefined,
+            terminalReason,
+            durationMs: typeof turn.durationMs === 'number' ? turn.durationMs : undefined,
+            ttftMs: this.pickNumber(turn.ttftMs, turn.ttft_ms),
+            costUsd: this.pickNumber(turn.costUsd, turn.totalCostUsd, turn.total_cost_usd),
+            sessionTitle: typeof turn.sessionTitle === 'string' ? turn.sessionTitle : typeof turn.session_title === 'string' ? turn.session_title : undefined,
+            numTurns: this.pickNumber(turn.numTurns, turn.num_turns),
+            tokenUsage,
+            contextUsage,
+        };
+    }
+    buildEvolclawShellEnvironmentConfig(sessionId) {
+        return {
+            shell_environment_policy: {
+                set: {
+                    EVOLCLAW_SESSION_ID: sessionId,
+                    EVOLCLAW_HOME: resolveRoot(),
+                },
+            },
+        };
+    }
     async dispose() {
         // Abort all active streams
         for (const [key, controller] of this.activeAbortControllers) {
@@ -350,6 +1273,10 @@ export class CodexRunner {
         this.activeAbortControllers.clear();
         this.activeStreams.clear();
         this.activeSessions.clear();
+        this.activeTurns.clear();
+        this.permissionContexts.clear();
+        await this.appServerClient?.close();
+        this.appServerClient = null;
     }
 }
 // ── Plugin ──
@@ -358,7 +1285,7 @@ export class CodexAgentPlugin {
     isEnabled(agent) {
         if (!agent.config.baseagents?.codex)
             return false;
-        if (!isCodexSdkAvailable())
+        if (!isCodexAppServerAvailable())
             return false;
         try {
             const override = agent.config.baseagents.codex;
@@ -371,8 +1298,9 @@ export class CodexAgentPlugin {
         }
     }
     createAgent(agent, callbacks) {
-        if (!isCodexSdkAvailable()) {
-            throw new Error('Missing optional dependency @openai/codex-sdk');
+        const availability = getCodexAppServerAvailability();
+        if (!availability.available) {
+            throw new Error(availability.reason || 'Missing codex CLI with app-server');
         }
         const override = agent.config.baseagents?.codex;
         const merged = {