@walkhi/code-relax 0.1.0-beta.1

package/dist/src/server.mjs

@@ -0,0 +1,2086 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import vm from 'node:vm';
+import { attachLanSocket } from './lan-socket-server.mjs';
+import { validateInlineImage, persistLegacyImage } from './message-images.mjs';
+import { ThreadWriterConflictError } from './shared-app-server.mjs';
+import { ManagedAppServer, managedAppServerUrl } from './managed-app-server.mjs';
+import { streamSharedThread } from './shared-thread-stream.mjs';
+import { AppServerClient } from './app-server-client.mjs';
+import { AppServerTaskStore, AppServerTaskTransport } from './app-server-tasks.mjs';
+import { supplementThreadCatalog } from './thread-catalog.mjs';
+import appServerEvents from '../shared/app-server-events.cjs';
+import { runtimePaths } from './platform/windows/runtime-paths.mjs';
+import { openControl } from './service-control.mjs';
+import { writeRecord, readRecord } from './service-lifecycle.mjs';
+import { ExecutionHealth } from './execution-health.mjs';
+import { activeDebugPort, serveDebugResource } from './debug-ui.mjs';
+import { authorizeLanDevice } from './self-relay/lan-authorizations.mjs';
+import { generateAndSetThreadTitle } from './thread-title-generation.mjs';
+import { DesktopMonitor } from './platform/windows/desktop-monitor.mjs';
+import { desktopHost } from './platform/windows/desktop-host.mjs';
+import { SharedCatalog } from './shared-catalog.mjs';
+import { requestRecovery, recoveryStatus } from './shared-recovery.mjs';
+import { requestServiceRestart } from './service-restart.mjs';
+
+const MAX_FRAME_BYTES = 32 * 1024 * 1024;
+const MAX_ATTACHMENT_BYTES = 16 * 1024 * 1024;
+const MAX_CACHED_ATTACHMENTS = 32;
+const MAX_CACHED_FILES = 64;
+const MAX_CONTEXT_TAIL_BYTES = 4 * 1024 * 1024;
+const MAX_LIVE_ACTIVITY_TAIL_BYTES = 1024 * 1024;
+const MAX_SETTINGS_SCAN_BYTES = 64 * 1024 * 1024;
+const ALLOWED_MODELS = new Set([
+  'gpt-6-astra',
+  'gpt-5.6-sol',
+  'gpt-5.6-terra',
+  'gpt-5.6-luna',
+  'gpt-5.5',
+  'gpt-5.3-codex-spark',
+]);
+const ALLOWED_THINKING = new Set(['low', 'medium', 'high', 'xhigh', 'max', 'ultra']);
+const ALLOWED_TOOLS = new Set([
+  'create_thread',
+  'get_usage_limits',
+  'list_projects',
+  'list_threads',
+  'navigate_to_codex_page',
+  'read_thread',
+  'send_message_to_thread',
+  'wait_threads',
+]);
+
+const options = parseOptions(process.argv.slice(2));
+const pipePath = process.env.CODEX_APP_TOOLS_PIPE_PATH?.trim();
+let sourceThreadId = (process.env.CODEX_THREAD_ID || process.env.CODEX_SESSION_ID)?.trim();
+
+const webRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'web');
+const repositoryRoot = path.resolve(webRoot, '..', '..');
+const projectRoot = os.homedir();
+const { codexDataRoot, stateRoot, sessionsRoot, uploadsRoot } = runtimePaths();
+const markdownItScript = fs.readFileSync(path.join(webRoot, 'vendor', 'markdown-it.umd.min.js'));
+const markdownSandbox = { atob };
+vm.runInNewContext(markdownItScript.toString(), markdownSandbox);
+const imageMarkdown = markdownSandbox.markdownit({ html: false });
+let nextRequestId = 0;
+const attachmentCache = new Map();
+const fileCache = new Map();
+const fileCapabilitySecret = crypto.randomBytes(32);
+const legacyUploadsRoot = path.resolve(webRoot, '..', 'uploads');
+const allowedUploadsRoots = [uploadsRoot, legacyUploadsRoot,
+  ...JSON.parse(process.env.CODEX_REMOTE_LEGACY_UPLOADS_ROOTS || '[]')];
+const sessionPathCache = new Map();
+const sessionSettingsCache = new Map();
+const liveActivityCache = new Map();
+const messageQueues = new Map();
+let sharedServer = null;
+const desktopMonitor = new DesktopMonitor({
+  read: (tool, args, pipe) => callTool(tool, args, 5000, pipe),
+});
+const managedAppServer = new ManagedAppServer({ stateRoot, host: desktopHost });
+let sharedCatalog = null, executionMode = 'ordinary';
+function selectSharedExecution(enabled) {
+  const next = enabled ? managedAppServer.client : null;
+  if (sharedServer === next) return;
+  sharedServer = next;
+  sharedCatalog = sharedServer ? new SharedCatalog(sharedServer, desktopMonitor) : null;
+}
+const executionHealth = new ExecutionHealth(async () => {
+  await managedAppServer.ensure();
+  const [desktop, attachedUrl] = await Promise.all([desktopHost.inspect(), desktopHost.sharedServiceUrl()]);
+  const attached = Boolean(desktop.running && attachedUrl === managedAppServerUrl);
+  const managed = managedAppServer.snapshot();
+  // The managed app-server owns execution. Desktop is another client of the
+  // same service, so closing Desktop must not disable phone writes.
+  selectSharedExecution(managed.ready);
+  executionMode = sharedServer ? 'shared' : 'ordinary';
+  const basicReady = Boolean(desktop.running && sourceThreadId && desktopMonitor.pipe);
+  const managedRestarting = managed.state === 'restarting';
+  const ready = !managedRestarting && (sharedServer ? sharedServer.ready === true : basicReady);
+  const state = managedRestarting ? 'restarting'
+    : ready ? (sharedServer ? 'full' : 'basic') : !desktop.running ? 'offline' : 'unavailable';
+  return { state, ready, canWrite: ready, mode: executionMode,
+    desktop: { state: !desktop.running ? 'stopped' : attached ? 'managed' : 'ordinary', attachedToManagedServer: attached } };
+});
+async function refreshExecution() {
+  sourceThreadId = readRecord(path.join(stateRoot, 'bridge-startup-context.json'))?.sourceThreadId || sourceThreadId;
+  await executionHealth.refresh();
+  return { mode: executionMode };
+}
+async function requireExecutionWritable(threadId) {
+  const recovery = readRecord(path.join(stateRoot, 'shared-recovery.json'));
+  if (['scheduled', 'running'].includes(recovery?.status)) {
+    throw new RequestError(409, 'Codex 正在重新启动，当前不能提交写操作。', { code: 'desktop_recovering' });
+  }
+  const execution = await executionHealth.refresh();
+  if (!execution.canWrite) {
+    const message = execution.mode === 'shared'
+      ? 'Codex 内核尚未建立可写连接，请稍后重新检测。'
+      : 'Codex Desktop 尚未建立基础控制连接，请稍后重新检测。';
+    throw new RequestError(409, message, { code: 'execution_not_writable', execution });
+  }
+  if (threadId && sharedServer) sharedServer.requireWritable(threadId);
+  return execution;
+}
+managedAppServer.client.on('subscription-error', error => console.error('完整控制任务取消订阅失败：', error.message));
+const queueWorkers = new Map();
+const appServer = new AppServerClient({ cwd: projectRoot });
+const appServerTasks = new AppServerTaskTransport({
+  client: appServer,
+  store: new AppServerTaskStore(path.join(stateRoot, 'app-server-tasks.json')),
+});
+appServer.on('protocol-error', error => console.error(`app-server 协议错误：${error.message}`));
+appServer.on('server-request', request => {
+  console.log(`app-server 等待客户端处理反向请求：${request.method} (${request.id})`);
+});
+
+async function handleRequest(request, response) {
+  try {
+    const url = new URL(request.url || '/', `http://${request.headers.host || 'localhost'}`);
+
+    if (!request.socketRequest) {
+      if (serveDebugResource(request, response, stateRoot, options.port)) return;
+      sendJson(response, 404, { error: 'Bridge 调试页面未开启，或请求的资源不存在。' });
+      return;
+    }
+
+    // These routes never wait on Desktop tools or a stuck thread. They remain
+    // available to authenticated paired controllers during an app-server stall.
+    if (request.method === 'GET' && url.pathname === '/api/shared-recovery/events') {
+      response.startEvents();
+      let stopped = false, timer, previous = '';
+      response.once('close', () => { stopped = true; clearTimeout(timer); });
+      const publish = async () => {
+        try {
+          const state = await recoveryStatus(stateRoot);
+          const serialized = JSON.stringify(state);
+          if (!stopped && serialized !== previous) { previous = serialized; response.event('progress', state); }
+        } catch (error) { if (!stopped) response.event('progress-error', { error: error.message }); }
+        if (!stopped) timer = setTimeout(publish, 1000);
+      };
+      void publish(); return;
+    }
+    if (request.method === 'GET' && url.pathname === '/api/shared-recovery') {
+      sendJson(response, 200, await recoveryStatus(stateRoot)); return;
+    }
+    if (request.method === 'POST' && url.pathname === '/api/shared-recovery') {
+      const body = await readJsonBody(request);
+      if (body.confirmed !== true || typeof body.operationId !== 'string') throw new RequestError(400, '请确认重新打开当前 Codex 并启用完整控制后再继续。');
+      sendJson(response, 202, await requestRecovery(stateRoot, body)); return;
+    }
+    if (request.method === 'POST' && url.pathname === '/api/service/restart') {
+      const body = await readJsonBody(request);
+      if (body.confirmed !== true) throw new RequestError(400, '请确认重启工作站服务后再继续。');
+      sendJson(response, 202, await requestServiceRestart(stateRoot)); return;
+    }
+    if (request.method === 'POST' && url.pathname === '/api/managed-app-server/restart') {
+      const body = await readJsonBody(request);
+      if (body.confirmed !== true || typeof body.operationId !== 'string' || !body.operationId.trim()) {
+        throw new RequestError(400, '请先确认中断风险，再重启 Codex 内核。');
+      }
+      try {
+        sendJson(response, 202, managedAppServer.restart(body.operationId.trim()));
+      } catch (error) {
+        if (error?.code === 'managed_app_server_restarting') throw new RequestError(409, error.message);
+        throw error;
+      }
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/health') {
+      // Status readers consume the workstation's cached sample. A phone query
+      // must not trigger PowerShell, process-identity, or app-server checks.
+      const recovery = readRecord(path.join(stateRoot, 'shared-recovery.json'));
+      const recovering = ['scheduled', 'running'].includes(recovery?.status);
+      sendJson(response, 200, {
+        status: 'ok', resident: true,
+        execution: { ...executionHealth.state, ready: executionHealth.state.ready && (!sharedServer || sharedServer.ready),
+          ...(recovering ? { state: 'recovering' } : {}), mode: executionMode },
+        managedAppServer: managedAppServer.snapshot(),
+        desktop: executionHealth.state.desktop || { state: 'stopped', attachedToManagedServer: false },
+        desktopRestartRecommended: executionHealth.state.desktop?.state === 'ordinary' && managedAppServer.snapshot().ready,
+        recovery: recovery ? { operationId: recovery.operationId, status: recovery.status, stage: recovery.stage, error: recovery.error } : null,
+        debugUiPort: await activeDebugPort(stateRoot, options.port),
+        desktopConnected: Boolean(desktopMonitor.pipe),
+        sharedAppServerConnected: sharedServer?.ready === true,
+        sharedRecoveryAvailable: true,
+        desktopOrderingReady: Boolean(desktopMonitor.snapshot),
+        toolCount: 0,
+        mode: options.lan ? 'lan' : 'loopback',
+        tokenRequired: Boolean(options.token),
+        nativeImageTransport: sharedServer ? 'shared-app-server' : null,
+        transportMode: sharedServer ? 'lan-shared' : 'lan-legacy',
+        appServer: {
+          state: appServer.state,
+          cliVersion: appServer.cliVersion,
+          taskCount: appServerTasks.store.list().length,
+        },
+      });
+      return;
+    }
+
+
+    const imageMatch = /^\/api\/images\/([a-f0-9]{64})$/.exec(url.pathname);
+    if (request.method === 'GET' && imageMatch) {
+      const image = attachmentCache.get(imageMatch[1]);
+      if (!image) throw new RequestError(404, '图片缓存已失效，请重新读取对话。');
+      sendJson(response, 200, { url: `data:${image.mimeType};base64,${image.buffer.toString('base64')}` });
+      return;
+    }
+
+    const fileMatch = /^\/api\/files\/([a-f0-9]{64})$/.exec(url.pathname);
+    if (request.method === 'GET' && fileMatch) {
+      const file = fileCache.get(fileMatch[1]);
+      if (!file) throw new RequestError(404, '文件授权已失效，请重新读取对话。');
+      let stat;
+      try { stat = fs.statSync(file.path); } catch { throw new RequestError(404, '电脑上的文件已不存在。'); }
+      if (!stat.isFile() || stat.size !== file.size || stat.mtimeMs !== file.mtimeMs) {
+        fileCache.delete(fileMatch[1]);
+        throw new RequestError(409, '电脑上的文件已发生变化，请重新读取对话。');
+      }
+      if (stat.size > MAX_ATTACHMENT_BYTES) throw new RequestError(413, '暂只支持下载不超过 16 MiB 的文件。');
+      sendJson(response, 200, { name: file.name, size: file.size, dataBase64: fs.readFileSync(file.path).toString('base64') });
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/models') {
+      if (!usesSharedTask({ hostId: url.searchParams.get('hostId') })) throw new RequestError(400, '当前连接不支持即时模型设置。');
+      sendJson(response, 200, await sharedServer.models());
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/threads') {
+      const limit = boundedInteger(url.searchParams.get('limit'), 20, 1, 200);
+      const archived = url.searchParams.get('archived') === 'true';
+      const catalog = sharedCatalog;
+      const sharedSnapshot = Boolean(catalog);
+      let desktopCatalog;
+      if (catalog) desktopCatalog = await catalog.threads(limit, archived);
+      else {
+        if (archived) throw new RequestError(400, '当前连接不支持归档对话。请启用完整控制。');
+        const listing = await callTool('list_threads', { limit: Math.min(limit, 50) });
+        if (!listing.success) { sendToolResult(response, listing); return; }
+        const projects = await callTool('list_projects', {});
+        if (!projects.success) { sendToolResult(response, projects); return; }
+        const catalogProjects = projects.data.projects || [];
+        desktopCatalog = { ...supplementThreadCatalog(listing.data, catalogProjects, codexDataRoot, limit),
+          projects: catalogProjects };
+      }
+      let appServerThreads = archived ? [] : appServerTasks.store.list().map(record => ({
+        id: record.id,
+        kind: 'codex',
+        hostId: 'app-server',
+        title: record.title,
+        cwd: record.cwd,
+        projectId: record.projectId,
+        updatedAt: record.updatedAt,
+        status: 'unknown',
+        transport: 'app-server',
+      }));
+      if (appServerThreads.length) {
+        try { appServerThreads = await appServerTasks.listTasks(); } catch {}
+      }
+      sendJson(response, 200, mergeThreadCatalog(desktopCatalog, appServerThreads, limit, sharedSnapshot));
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/projects') {
+      if (sharedCatalog) {
+        sendJson(response, 200, { projects: (await sharedCatalog.projects()).projects });
+        return;
+      }
+      const result = await callTool('list_projects', {});
+      sendToolResult(response, result);
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/usage-limits') {
+      if (sharedServer) sendJson(response, 200, await sharedServer.usage());
+      else sendToolResult(response, await callTool('get_usage_limits', {}));
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/usage-events' && sharedServer) {
+      const execution = sharedServer;
+      response.startEvents();
+      const emit = value => { if (!response.destroyed) response.event('usage', value); };
+      const failed = error => { if (!response.destroyed) response.event('usage-error', { error: error.message }); };
+      const disconnected = () => response.end();
+      execution.on('usage', emit); execution.on('usage-error', failed); execution.on('disconnected', disconnected);
+      response.once('close', () => { execution.off('usage', emit); execution.off('usage-error', failed); execution.off('disconnected', disconnected); });
+      try { emit(await execution.usage()); } catch (error) { failed(error); }
+      return;
+    }
+
+    if (request.method === 'GET' && url.pathname === '/api/app-server/status') {
+      sendJson(response, 200, appServerBridgeStatus());
+      return;
+    }
+
+    if (request.method === 'POST' && url.pathname === '/api/app-server/start') {
+      await requireExecutionWritable();
+      await appServer.start();
+      sendJson(response, 200, appServerBridgeStatus());
+      return;
+    }
+
+    const createThreadMatch = /^\/api\/projects\/([^/]+)\/threads$/.exec(url.pathname);
+    if (request.method === 'POST' && createThreadMatch) {
+      await requireExecutionWritable();
+      const projectId = decodeURIComponent(createThreadMatch[1]);
+      const body = createThreadBody(await readJsonBody(request));
+      let projects = [];
+      if (body.transport !== 'app-server' || projectId !== '__unassigned__') {
+        const projectsResult = sharedCatalog
+          ? { success: true, data: { projects: (await sharedCatalog.projects()).projects } }
+          : await callTool('list_projects', {});
+        if (!projectsResult.success) {
+          sendJson(response, 502, { error: '无法读取 Codex Desktop 项目。', details: projectsResult.data });
+          return;
+        }
+        projects = Array.isArray(projectsResult.data?.projects) ? projectsResult.data.projects : [];
+      }
+      if (body.transport === 'app-server') {
+        const target = appServerProjectTarget(projectId, projects);
+        const result = await appServerTasks.createTask({
+          cwd: target.cwd,
+          projectId: target.projectId,
+          input: appServerTurnArguments('', body).input,
+        });
+        sendJson(response, 201, {
+          threadId: result.record.id,
+          hostId: 'app-server',
+          transport: 'app-server',
+          turnId: result.turn.id,
+        });
+        return;
+      }
+      const project = projects.find(item => item.projectId === projectId);
+      if (usesSharedTask({ hostId:project?.hostId || body.hostId })) {
+        if (projectId !== '__unassigned__' && !project) throw new RequestError(404, '没有找到对应项目。');
+        const execution = sharedServer;
+        await execution.connect();
+        const rpc = (method, params) => execution.request(method, params);
+        let target = appServerEvents.projectlessThreadTarget(projectRoot);
+        if (project) {
+          const nativeProjects = await appServerEvents.readProjects(rpc);
+          const nativeId = nativeProjects.find(item => item.id === project.projectId)?.id;
+          if (!nativeId) throw new RequestError(404, '完整控制中没有找到对应项目，请刷新项目列表。');
+          target = { projectId:nativeId, cwd:project.path };
+        }
+        const { input } = appServerTurnArguments('', body);
+        const created = await appServerEvents.createThread(rpc, target, input, body);
+        const prompt = input.filter(part => part.type === 'text').map(part => part.text).join('\n');
+        void generateAndSetThreadTitle({
+          request: rpc,
+          subscribe: listener => {
+            execution.on('notification', listener);
+            return () => execution.off('notification', listener);
+          },
+          threadId: created.threadId,
+          prompt,
+          cwd: target.cwd || null,
+        }).catch(error => console.error(`生成对话标题失败：${error.message}`));
+        sendJson(response, 201, { ...created, hostId:'local' });
+        return;
+      }
+      const argumentsValue = await createThreadArguments(projectId, body, projects);
+      sendToolResult(response, await callTool('create_thread', argumentsValue, 90_000));
+      return;
+    }
+
+    const timelineMatch = /^\/api\/threads\/([^/]+)\/timeline$/.exec(url.pathname);
+    if (request.method === 'GET' && timelineMatch) {
+      const threadId = decodeURIComponent(timelineMatch[1]);
+      if (!appServerTasks.owns(threadId) && usesSharedTask({ hostId: url.searchParams.get('hostId') })) {
+        const timeline = normalizeSharedTimeline(await sharedServer.timeline(threadId));
+        const knownUpdatedAt = Number(url.searchParams.get('knownUpdatedAt'));
+        const knownTurnId = url.searchParams.get('knownTurnId') || '';
+        const knownTurnStatus = url.searchParams.get('knownTurnStatus') || '';
+        const latest = timeline.turns.at(-1);
+        const knownIndex = knownTurnId ? timeline.turns.findIndex(turn => turn.id === knownTurnId) : -1;
+        const unchanged = knownIndex === timeline.turns.length - 1
+          && timeline.thread.status === 'idle' && latest?.status !== 'inProgress'
+          && knownTurnStatus && knownTurnStatus !== 'inProgress'
+          && (!Number.isFinite(knownUpdatedAt) || knownUpdatedAt <= 0 || timeline.thread.updatedAt === knownUpdatedAt);
+        const partial = !unchanged && knownIndex >= 0
+          ? { ...timeline, turns: timeline.turns.slice(knownIndex), partialFromTurnId: knownTurnId }
+          : timeline;
+        sendJson(response, 200, unchanged ? { ...timeline, turns: [], notModified: true } : partial);
+        return;
+      }
+      if (appServerTasks.owns(threadId)) {
+        const thread = await appServerTasks.readTask(threadId, {
+          includeTurns: true,
+          turnLimit: boundedInteger(url.searchParams.get('turnLimit'), 10, 1, 10),
+        });
+        sendJson(response, 200, normalizeAppServerTimeline(thread));
+        return;
+      }
+      const argumentsValue = readThreadArguments(url, threadId, 10);
+      const result = await callTool('read_thread', argumentsValue);
+      if (result.success) {
+        const timeline = normalizeTimeline(result.data);
+        enrichTimelineWithLocalActivity(timeline, threadId);
+        sendJson(response, 200, timeline);
+      } else {
+        sendJson(response, 502, { error: 'Codex Desktop 工具返回失败。', details: result.data });
+      }
+      return;
+    }
+
+    const approvalMatch = /^\/api\/threads\/([^/]+)\/approvals$/.exec(url.pathname);
+    if (request.method === 'POST' && approvalMatch) {
+      const threadId = decodeURIComponent(approvalMatch[1]);
+      await requireExecutionWritable(threadId);
+      if (!usesSharedTask({ hostId: url.searchParams.get('hostId') }) || appServerTasks.owns(threadId)) {
+        sendJson(response, 409, { error: '当前执行模式不支持手机审批，请在工作站处理。' }); return;
+      }
+      const body = await readJsonBody(request);
+      sendJson(response, 200, await sharedServer.respondApproval(threadId, body)); return;
+    }
+
+    const eventsMatch = /^\/api\/threads\/([^/]+)\/events$/.exec(url.pathname);
+    if (request.method === 'GET' && eventsMatch) {
+      const threadId = decodeURIComponent(eventsMatch[1]);
+      if (!appServerTasks.owns(threadId) && usesSharedTask({ hostId: url.searchParams.get('hostId') })) {
+        const after = Number(url.searchParams.get('afterSeq'));
+        const requestedSync = url.searchParams.get('syncId') && url.searchParams.get('syncEpoch') && Number.isSafeInteger(after) && after >= 0
+          ? { id: url.searchParams.get('syncId'), epoch: url.searchParams.get('syncEpoch'), after } : undefined;
+        const knownUpdatedAt = Number(url.searchParams.get('knownUpdatedAt'));
+        const known = url.searchParams.get('knownTurnId') ? {
+          updatedAt: Number.isFinite(knownUpdatedAt) ? knownUpdatedAt : 0,
+          turnId: url.searchParams.get('knownTurnId'),
+          turnStatus: url.searchParams.get('knownTurnStatus') || '',
+        } : undefined;
+        await streamSharedThread(response, threadId, sharedServer, normalizeSharedTimeline, requestedSync, known);
+        return;
+      }
+      if (appServerTasks.owns(threadId)) {
+        await streamAppServerThreadEvents(request, response, threadId);
+        return;
+      }
+      await streamThreadEvents(
+        request,
+        response,
+        threadId,
+        url.searchParams.get('hostId')?.trim(),
+      );
+      return;
+    }
+
+    const navigateMatch = /^\/api\/threads\/([^/]+)\/navigate$/.exec(url.pathname);
+    if (request.method === 'POST' && navigateMatch) {
+      const threadId = decodeURIComponent(navigateMatch[1]);
+      if (sharedServer && !desktopMonitor.pipe) {
+        sendJson(response, 200, { opened: false, reason: 'Desktop 工具通道尚未就绪' });
+        return;
+      }
+      if (appServerTasks.owns(threadId)) {
+        sendJson(response, 200, { opened: false, transport: 'app-server' });
+        return;
+      }
+      sendToolResult(response, await callTool('navigate_to_codex_page', {
+        threadId,
+      }, 15_000));
+      return;
+    }
+
+    const contextMatch = /^\/api\/threads\/([^/]+)\/context$/.exec(url.pathname);
+    if (request.method === 'GET' && contextMatch) {
+      const threadId = decodeURIComponent(contextMatch[1]);
+      const current = readContextUsage(threadId);
+      const native = usesSharedTask({ hostId: url.searchParams.get('hostId') }) ? await sharedServer.readContext(threadId) : {};
+      sendJson(response, 200, { ...current, ...(native.model ? { model: native.model, thinking: native.thinking, serviceTier: native.serviceTier,
+        permissionMode: native.permissionMode, permissionModes: native.permissionModes } : {}), ...(native.available ? native : {}) });
+      return;
+    }
+
+    const sharedAction = /^\/api\/threads\/([^/]+)\/(history|settings|permissions)$/.exec(url.pathname);
+    if (sharedAction) {
+      const id = decodeURIComponent(sharedAction[1]);
+      if (!usesSharedTask({ hostId: url.searchParams.get('hostId') }) || appServerTasks.owns(id)) throw new RequestError(400, '此连接不支持该操作。');
+      if (request.method === 'GET' && sharedAction[2] === 'history') {
+        sendJson(response, 200, normalizeSharedTimeline(await sharedServer.history(id, url.searchParams.get('cursor'))));
+        return;
+      }
+      if (request.method === 'POST' && sharedAction[2] === 'settings') {
+        await requireExecutionWritable(id);
+        const body = await readJsonBody(request);
+        sendJson(response, 200, await sharedServer.settings(id, body.model, body.thinking, body.serviceTier));
+        return;
+      }
+      if (request.method === 'POST' && sharedAction[2] === 'permissions') {
+        await requireExecutionWritable(id);
+        const body = await readJsonBody(request);
+        sendJson(response, 200, await sharedServer.permissions(id, body.mode));
+        return;
+      }
+    }
+
+    const archiveMatch = /^\/api\/threads\/([^/]+)\/(archive|unarchive)$/.exec(url.pathname);
+    if (request.method === 'POST' && archiveMatch) {
+      const threadId = decodeURIComponent(archiveMatch[1]);
+      await requireExecutionWritable(threadId);
+      if (!usesSharedTask({ hostId: url.searchParams.get('hostId') }) || appServerTasks.owns(threadId)) {
+        throw new RequestError(400, '当前连接不支持归档对话。请启用完整控制。');
+      }
+      await sharedServer.request(`thread/${archiveMatch[2]}`, { threadId });
+      sendJson(response, 200, { threadId, archived: archiveMatch[2] === 'archive' });
+      return;
+    }
+
+    const readMatch = /^\/api\/threads\/([^/]+)$/.exec(url.pathname);
+    if (request.method === 'DELETE' && readMatch) {
+      const threadId = decodeURIComponent(readMatch[1]);
+      await requireExecutionWritable(threadId);
+      if (!appServerTasks.owns(threadId)) {
+        throw new RequestError(400, '仅支持删除由独立 app-server 通道创建的任务。');
+      }
+      await appServerTasks.deleteTask(threadId);
+      messageQueues.delete(threadId);
+      sendJson(response, 200, { deleted: true, threadId, transport: 'app-server' });
+      return;
+    }
+    if (request.method === 'GET' && readMatch) {
+      const threadId = decodeURIComponent(readMatch[1]);
+      if (appServerTasks.owns(threadId)) {
+        sendJson(response, 200, { thread: await appServerTasks.readTask(threadId, {
+          includeTurns: true,
+          turnLimit: boundedInteger(url.searchParams.get('turnLimit'), 10, 1, 10),
+        }) });
+        return;
+      }
+      const argumentsValue = readThreadArguments(url, threadId, 10, 12_000);
+      sendToolResult(response, await callTool('read_thread', argumentsValue));
+      return;
+    }
+
+    const queueMatch = /^\/api\/threads\/([^/]+)\/queue$/.exec(url.pathname);
+    if (queueMatch) {
+      const threadId = decodeURIComponent(queueMatch[1]);
+      if (!appServerTasks.owns(threadId) && usesSharedTask({ hostId: url.searchParams.get('hostId') })) {
+        await sharedServer.connect();
+        const rpc = (method, params) => sharedServer.request(method, params);
+        if (request.method === 'GET') { sendJson(response, 200, await appServerEvents.readQueue(rpc, threadId)); return; }
+        if (request.method === 'POST') {
+          await requireExecutionWritable(threadId);
+          const args = appServerTurnArguments(threadId, await readJsonBody(request));
+          sendJson(response, 202, await appServerEvents.addQueue(rpc, threadId, args.input, crypto.randomUUID())); return;
+        }
+      }
+      if (request.method === 'GET') {
+        sendJson(response, 200, { items: publicQueue(threadId) });
+        return;
+      }
+      if (request.method === 'POST') {
+        await requireExecutionWritable(threadId);
+        const body = await readJsonBody(request);
+        const argumentsValue = appServerTasks.owns(threadId)
+          ? appServerTurnArguments(threadId, body)
+          : await messageArguments(threadId, body);
+        const item = {
+          id: crypto.randomUUID(),
+          ...argumentsValue,
+          transport: appServerTasks.owns(threadId) ? 'app-server' : 'desktop-tools',
+          displayPrompt: messageDisplayText(body),
+          text: typeof body.prompt === 'string' ? body.prompt.trim() : '',
+          attachments: (body.images || []).map(id => ({ type:'image', available:true, url:id.startsWith('data:') ? id : `/api/attachments/${id}`, thumbnailUrl:id.startsWith('data:') ? id : `/api/attachments/${id}/thumbnail` })),
+          createdAt: new Date().toISOString(),
+          error: '',
+        };
+        const queue = messageQueues.get(threadId) || [];
+        queue.push(item);
+        messageQueues.set(threadId, queue);
+        ensureQueueWorker(threadId);
+        sendJson(response, 202, { items: publicQueue(threadId) });
+        return;
+      }
+    }
+
+    const queueItemMatch = /^\/api\/threads\/([^/]+)\/queue\/([a-f0-9-]+)(?:\/(steer))?$/.exec(url.pathname);
+    if (queueItemMatch) {
+      const threadId = decodeURIComponent(queueItemMatch[1]);
+      const itemId = queueItemMatch[2];
+      if (!appServerTasks.owns(threadId) && usesSharedTask({ hostId: url.searchParams.get('hostId') })) {
+        await sharedServer.connect();
+        const action = request.method === 'DELETE' ? 'delete' : queueItemMatch[3] === 'steer' ? 'steer' : null;
+        if (!action) throw new RequestError(405, '不支持的队列操作');
+        await requireExecutionWritable(threadId);
+        sendJson(response, 200, await appServerEvents.changeQueue((method, params) => sharedServer.request(method, params), threadId, itemId, action)); return;
+      }
+      const queue = messageQueues.get(threadId) || [];
+      const index = queue.findIndex(item => item.id === itemId);
+      if (index < 0) {
+        sendJson(response, 404, { error: '没有找到该排队消息。' });
+        return;
+      }
+      if (request.method === 'DELETE' && !queueItemMatch[3]) {
+        await requireExecutionWritable(threadId);
+        queue.splice(index, 1);
+        sendJson(response, 200, { items: publicQueue(threadId) });
+        return;
+      }
+      if (request.method === 'POST' && queueItemMatch[3] === 'steer') {
+        await requireExecutionWritable(threadId);
+        const [item] = queue.splice(index, 1);
+        const result = await steerQueuedItem(threadId, item);
+        if (!result.success) {
+          queue.splice(index, 0, item);
+          sendJson(response, 502, { error: '插队发送失败。', details: result.data });
+          return;
+        }
+        sendJson(response, 200, { items: publicQueue(threadId) });
+        return;
+      }
+    }
+
+    const takeoverMatch = /^\/api\/threads\/([^/]+)\/takeover$/.exec(url.pathname);
+    if (request.method === 'POST' && takeoverMatch) {
+      const threadId = decodeURIComponent(takeoverMatch[1]);
+      await requireExecutionWritable(threadId);
+      if (appServerTasks.owns(threadId)) {
+        sendJson(response, 200, { thread: (await appServerTasks.listTasks()).find(t => t.id === threadId) });
+        return;
+      }
+      if (messageQueues.get(threadId)?.length || queueWorkers.has(threadId)) throw new RequestError(409, '请先处理此聊天的排队消息。');
+      const result = await callTool('read_thread', { threadId, turnLimit: 1, includeOutputs: false });
+      if (!result.success) throw new RequestError(502, '无法确认 Desktop 聊天状态。');
+      const timeline = normalizeTimeline(result.data);
+      const thread = timeline.thread;
+      if (thread.hostId && thread.hostId !== 'local') throw new RequestError(400, '只支持本机聊天。');
+      if (!['idle', 'notLoaded'].includes(thread.status) || timeline.turns.some(t => t.status === 'inProgress')) throw new RequestError(409, '只允许接管已空闲的聊天，请等当前轮次结束。');
+      if (!findSessionPath(threadId)) throw new RequestError(400, '未找到此聊天的本机历史。');
+      sendJson(response, 200, { thread: await appServerTasks.adoptTask({ ...thread, id: threadId }) });
+      return;
+    }
+
+    const interruptMatch = /^\/api\/threads\/([^/]+)\/interrupt$/.exec(url.pathname);
+    if (request.method === 'POST' && interruptMatch) {
+      const threadId = decodeURIComponent(interruptMatch[1]);
+      await requireExecutionWritable(threadId);
+      if (!appServerTasks.owns(threadId) && usesSharedTask({ hostId: url.searchParams.get('hostId') })) {
+        const body = await readJsonBody(request);
+        if (!body.turnId) throw new RequestError(400, '缺少活动轮次 ID。');
+        await sharedServer.interrupt(threadId, body.turnId);
+        sendJson(response, 200, { requested: true });
+        return;
+      }
+      if (!appServerTasks.owns(threadId)) throw new RequestError(409, '请先接管空闲聊天。');
+      const body = await readJsonBody(request);
+      const thread = await appServerTasks.readTask(threadId, { turnLimit: 1 });
+      const active = thread.turns?.at(-1);
+      if (!body.turnId || active?.id !== body.turnId || statusText(active.status) !== 'inProgress') throw new RequestError(409, '此轮次已经结束或发生变化。');
+      // Stop also clears pending messages so the queue cannot restart work.
+      messageQueues.delete(threadId);
+      await appServerTasks.interruptTurn(threadId, body.turnId);
+      sendJson(response, 200, { requested: true });
+      return;
+    }
+
+    const messageMatch = /^\/api\/threads\/([^/]+)\/messages$/.exec(url.pathname);
+    if (request.method === 'POST' && messageMatch) {
+      const threadId = decodeURIComponent(messageMatch[1]);
+      await requireExecutionWritable(threadId);
+      const body = await readJsonBody(request);
+      if (!appServerTasks.owns(threadId) && usesSharedTask(body)) {
+        sendJson(response, 200, { success: true, data: await sharedServer.send(appServerTurnArguments(threadId, body)) });
+      } else if (appServerTasks.owns(threadId)) {
+        const args = appServerTurnArguments(threadId, body);
+        const current = await appServerTasks.readTask(threadId, { turnLimit: 1 });
+        const active = current.turns?.at(-1);
+        sendJson(response, 200, statusText(active?.status) === 'inProgress'
+          ? await appServerTasks.steerTurn(threadId, active.id, args.input)
+          : await appServerTasks.startTurn(threadId, args));
+      } else {
+        sendToolResult(response, await callTool('send_message_to_thread', await messageArguments(threadId, body)));
+      }
+      return;
+    }
+
+    if (request.method === 'POST' && url.pathname === '/api/wait') {
+      const body = await readJsonBody(request);
+      sendToolResult(response, await callTool('wait_threads', body, 130_000));
+      return;
+    }
+
+    sendJson(response, 404, { error: '未找到请求的资源。' });
+  } catch (error) {
+    if (response.headersSent) {
+      if (!response.writableEnded) response.end();
+      return;
+    }
+    const status = error instanceof RequestError || error instanceof ThreadWriterConflictError ? (error.statusCode || 409) : 502;
+    sendJson(response, status, {
+      error: error instanceof Error ? error.message : String(error),
+      code: error?.code,
+      threadId: error?.threadId,
+      readOnly: error?.readOnly,
+      details: error?.details,
+    });
+  }
+}
+
+const server = http.createServer(handleRequest);
+const lanSocket = attachLanSocket(server, { token: options.token, dispatch: handleRequest,
+  authorizeDevice: (clientId, credential) => authorizeLanDevice(stateRoot, clientId, credential),
+});
+
+if (options.appServer) {
+  try {
+    await appServer.start();
+  } catch (error) {
+    console.error(`app-server 启动失败：${error instanceof Error ? error.message : String(error)}`);
+    process.exit(2);
+  }
+}
+
+let control;
+desktopMonitor.start();
+void managedAppServer.start();
+executionHealth.start();
+server.on('error', error => {
+  console.error('Bridge 监听失败：', error.message);
+  process.exit(1);
+});
+server.listen(options.port, options.lan ? '0.0.0.0' : '127.0.0.1', async () => {
+  try {
+    if (process.env.CODEX_REMOTE_INSTANCE && process.env.CODEX_REMOTE_CONTROL_SECRET && process.env.CODEX_REMOTE_READY_PATH) {
+      control = await openControl({ instanceId: process.env.CODEX_REMOTE_INSTANCE,
+        secret: process.env.CODEX_REMOTE_CONTROL_SECRET, shutdown: shutDown, actions: { 'refresh-execution': refreshExecution } });
+      writeRecord(process.env.CODEX_REMOTE_READY_PATH, { instanceId: process.env.CODEX_REMOTE_INSTANCE,
+        pid: process.pid, controlPort: control.port });
+    }
+  } catch (error) {
+    console.error('Bridge 管理通道启动失败：', error.message);
+    process.exit(1);
+  }
+  console.log(`Code Relax Bridge 已启动：http://127.0.0.1:${options.port}/`);
+  if (options.lan) {
+    console.log('LAN 模式使用鉴权 WebSocket，仅适合受信任局域网测试，不要暴露到公网。');
+  }
+});
+
+let shuttingDown = false;
+async function shutDown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  lanSocket.close();
+  server.close();
+  desktopMonitor?.stop();
+  executionHealth?.stop();
+  managedAppServer.close();
+  await appServer.close();
+  await control?.close();
+  process.exit(0);
+}
+process.on('SIGTERM', shutDown);
+process.on('SIGINT', shutDown);
+
+async function callTool(tool, argumentsValue, timeoutMs = 60_000, targetPipe) {
+  if (!sourceThreadId) throw new RequestError(503, '基础控制尚未绑定调用上下文；请在 Codex 对话启动一次 Code Relax。电脑管理连接仍可使用。');
+  if (!ALLOWED_TOOLS.has(tool)) {
+    throw new RequestError(403, `工具 ${tool} 不在 Bridge 允许列表中。`);
+  }
+
+  const invocationId = crypto.randomUUID();
+  const rpc = await callDesktop('tools/call', {
+    arguments: argumentsValue,
+    callId: `codex-remote-${invocationId}`,
+    namespace: 'codex_app',
+    threadId: sourceThreadId,
+    tool,
+    turnId: `codex-remote-turn-${invocationId}`,
+  }, timeoutMs, targetPipe);
+
+  const result = rpc.result;
+  if (!result || typeof result.success !== 'boolean') {
+    throw new BridgeError('Codex Desktop 没有返回有效的工具结果。', rpc);
+  }
+
+  const items = Array.isArray(result.contentItems) ? result.contentItems : [];
+  let data = items;
+  if (items.length === 1 && items[0]?.type === 'inputText' && typeof items[0].text === 'string') {
+    try {
+      data = JSON.parse(items[0].text);
+    } catch {
+      data = items[0].text;
+    }
+  }
+
+  return { success: result.success, data };
+}
+
+function callDesktop(method, params, timeoutMs, targetPipe = desktopMonitor?.pipe || pipePath) {
+  if (!targetPipe) return Promise.reject(new RequestError(503, 'Desktop 工具通道尚未就绪。'));
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(targetPipe);
+    const requestId = ++nextRequestId;
+    const payload = Buffer.from(JSON.stringify({ jsonrpc: '2.0', id: requestId, method, params }), 'utf8');
+    const header = Buffer.allocUnsafe(4);
+    header.writeUInt32LE(payload.length, 0);
+    let pending = Buffer.alloc(0);
+    let expectedLength = null;
+    let settled = false;
+
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      callback(value);
+    };
+
+    const timer = setTimeout(() => {
+      finish(reject, new BridgeError('等待 Codex Desktop 响应超时。'));
+    }, timeoutMs);
+
+    socket.once('connect', () => socket.write(Buffer.concat([header, payload])));
+    socket.on('data', chunk => {
+      pending = Buffer.concat([pending, chunk]);
+      if (expectedLength === null && pending.length >= 4) {
+        expectedLength = pending.readUInt32LE(0);
+        pending = pending.subarray(4);
+        if (expectedLength <= 0 || expectedLength > MAX_FRAME_BYTES) {
+          finish(reject, new BridgeError(`Codex Desktop 返回了无效帧长度：${expectedLength}。`));
+          return;
+        }
+      }
+
+      if (expectedLength !== null && pending.length >= expectedLength) {
+        try {
+          const responseValue = JSON.parse(pending.subarray(0, expectedLength).toString('utf8'));
+          if (responseValue.error) {
+            finish(reject, new BridgeError('Codex Desktop 工具调用失败。', responseValue.error));
+          } else if (responseValue.id !== requestId) {
+            finish(reject, new BridgeError('Codex Desktop 返回了不匹配的请求 ID。'));
+          } else {
+            finish(resolve, responseValue);
+          }
+        } catch (error) {
+          finish(reject, new BridgeError('无法解析 Codex Desktop 响应。', undefined, error));
+        }
+      }
+    });
+    socket.once('error', error => finish(reject, new BridgeError(
+      '无法连接 Codex Desktop Pipe。桌面版可能已重启，请重新启动 Bridge。',
+      undefined,
+      error,
+    )));
+    socket.once('close', () => {
+      if (!settled) finish(reject, new BridgeError('Codex Desktop Pipe 在返回结果前关闭。'));
+    });
+  });
+}
+
+function sendToolResult(response, result) {
+  if (result.success) {
+    sendJson(response, 200, result.data);
+  } else {
+    sendJson(response, 502, { error: 'Codex Desktop 工具返回失败。', details: result.data });
+  }
+}
+
+function appServerBridgeStatus() {
+  return {
+    ...appServer.snapshot(),
+    platformFamily: appServer.initializeResult?.platformFamily || null,
+    platformOs: appServer.initializeResult?.platformOs || null,
+    taskCount: appServerTasks.store.list().length,
+    ownershipError: appServerTasks.store.loadError?.message || null,
+  };
+}
+
+function readThreadArguments(url, threadId, defaultTurnLimit, defaultOutputLimit = 4_000) {
+  const argumentsValue = {
+    threadId,
+    turnLimit: boundedInteger(url.searchParams.get('turnLimit'), defaultTurnLimit, 1, 10),
+    includeOutputs: booleanValue(url.searchParams.get('includeOutputs'), true),
+    maxOutputCharsPerItem: boundedInteger(
+      url.searchParams.get('maxOutputCharsPerItem'),
+      defaultOutputLimit,
+      500,
+      100_000,
+    ),
+  };
+  const hostId = url.searchParams.get('hostId')?.trim();
+  if (hostId) argumentsValue.hostId = hostId;
+  return argumentsValue;
+}
+
+function readContextUsage(threadId) {
+  if (!/^[0-9a-f]{8}-[0-9a-f-]{20,55}$/i.test(threadId)) {
+    return { available: false };
+  }
+  const sessionPath = findSessionPath(threadId);
+  if (!sessionPath) return { available: false };
+
+  let handle;
+  try {
+    const stat = fs.statSync(sessionPath);
+    const readLength = Math.min(stat.size, MAX_CONTEXT_TAIL_BYTES);
+    const buffer = Buffer.allocUnsafe(readLength);
+    handle = fs.openSync(sessionPath, 'r');
+    fs.readSync(handle, buffer, 0, readLength, stat.size - readLength);
+    const lines = buffer.toString('utf8').split(/\r?\n/);
+    let usage = null;
+    let settings = null;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      let event;
+      if (!usage && lines[index].includes('"token_count"')) {
+        try { event = JSON.parse(lines[index]); } catch { event = null; }
+        if (event?.type === 'event_msg' && event?.payload?.type === 'token_count') {
+          const usedTokens = Number(event.payload.info?.last_token_usage?.total_tokens);
+          const contextWindow = Number(event.payload.info?.model_context_window);
+          if (Number.isFinite(usedTokens) && Number.isFinite(contextWindow) && contextWindow > 0) {
+            usage = {
+              available: true,
+              usedTokens,
+              contextWindow,
+              remainingTokens: Math.max(0, contextWindow - usedTokens),
+              usedPercent: Math.min(100, Math.max(0, usedTokens / contextWindow * 100)),
+              updatedAt: event.timestamp || null,
+            };
+          }
+        }
+      }
+      if (!settings && lines[index].includes('"type":"turn_context"')) {
+        try { event = JSON.parse(lines[index]); } catch { event = null; }
+        settings = turnSettings(event);
+      }
+      if (usage && settings) break;
+    }
+    settings ||= sessionSettingsCache.get(sessionPath) || readLatestTurnSettings(sessionPath);
+    if (settings) sessionSettingsCache.set(sessionPath, settings);
+    if (usage) return { ...usage, ...settings };
+    if (settings) return { available: false, ...settings };
+  } catch {
+    sessionPathCache.delete(threadId);
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+  return { available: false };
+}
+
+function readLatestTurnSettings(sessionPath) {
+  let handle;
+  try {
+    const stat = fs.statSync(sessionPath);
+    const readLength = Math.min(stat.size, MAX_SETTINGS_SCAN_BYTES);
+    const buffer = Buffer.allocUnsafe(readLength);
+    handle = fs.openSync(sessionPath, 'r');
+    fs.readSync(handle, buffer, 0, readLength, stat.size - readLength);
+    const text = buffer.toString('utf8');
+    let searchFrom = text.length;
+    while (searchFrom > 0) {
+      const marker = text.lastIndexOf('"type":"turn_context"', searchFrom);
+      if (marker < 0) break;
+      const lineStart = text.lastIndexOf('\n', marker) + 1;
+      const nextLine = text.indexOf('\n', marker);
+      const lineEnd = nextLine < 0 ? text.length : nextLine;
+      let event;
+      try { event = JSON.parse(text.slice(lineStart, lineEnd)); } catch { event = null; }
+      const settings = turnSettings(event);
+      if (settings) return settings;
+      searchFrom = Math.max(0, lineStart - 1);
+    }
+  } catch {
+    return null;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+  return null;
+}
+
+function turnSettings(event) {
+  if (event?.type !== 'turn_context') return null;
+  const model = typeof event.payload?.model === 'string' && /^[a-z0-9.-]{1,80}$/i.test(event.payload.model)
+    ? event.payload.model
+    : '';
+  const thinking = typeof event.payload?.effort === 'string' && /^[a-z0-9_-]{1,32}$/i.test(event.payload.effort)
+    ? event.payload.effort
+    : '';
+  return model || thinking ? { model, thinking } : null;
+}
+
+function findSessionPath(threadId) {
+  const cached = sessionPathCache.get(threadId);
+  if (cached && fs.existsSync(cached)) return cached;
+  if (!fs.existsSync(sessionsRoot)) return null;
+
+  const suffix = `-${threadId}.jsonl`.toLowerCase();
+  const directories = [sessionsRoot];
+  while (directories.length) {
+    const directory = directories.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) directories.push(fullPath);
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(suffix)) {
+        sessionPathCache.set(threadId, fullPath);
+        return fullPath;
+      }
+    }
+  }
+  return null;
+}
+
+function enrichTimelineWithLocalActivity(timeline, threadId) {
+  const turn = timeline.turns.at(-1);
+  if (!turn || turn.status !== 'inProgress') return;
+  if (turn.entries.some(entry => entry?.type === 'activity' && entry.status === 'inProgress')) return;
+  const pending = readPendingLocalActivity(threadId);
+  if (!pending || (pending.turnId && pending.turnId !== turn.id)) return;
+  turn.entries.push(pending.entry);
+}
+
+function readPendingLocalActivity(threadId) {
+  const sessionPath = findSessionPath(threadId);
+  if (!sessionPath) return null;
+  let handle;
+  try {
+    const stat = fs.statSync(sessionPath);
+    const cacheKey = `${stat.size}:${stat.mtimeMs}`;
+    const cached = liveActivityCache.get(sessionPath);
+    if (cached?.key === cacheKey) return cached.value;
+    const readLength = Math.min(stat.size, MAX_LIVE_ACTIVITY_TAIL_BYTES);
+    const buffer = Buffer.allocUnsafe(readLength);
+    handle = fs.openSync(sessionPath, 'r');
+    fs.readSync(handle, buffer, 0, readLength, stat.size - readLength);
+    const lines = buffer.toString('utf8').split(/\r?\n/);
+    if (readLength < stat.size) lines.shift();
+    const pending = new Map();
+    for (const line of lines) {
+      if (!line.includes('"custom_tool_call')) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      if (event?.type !== 'response_item') continue;
+      const payload = event.payload;
+      const callId = payload?.call_id;
+      if (!callId) continue;
+      if (payload.type === 'custom_tool_call') pending.set(callId, payload);
+      if (payload.type === 'custom_tool_call_output') pending.delete(callId);
+    }
+    const payload = [...pending.values()].at(-1);
+    const value = payload ? pendingActivity(payload) : null;
+    liveActivityCache.set(sessionPath, { key: cacheKey, value });
+    return value;
+  } catch {
+    liveActivityCache.delete(sessionPath);
+    return null;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+}
+
+function pendingActivity(payload) {
+  const input = typeof payload.input === 'string' ? payload.input : '';
+  const nestedTool = input.match(/tools\.([A-Za-z0-9_]+)\s*\(/)?.[1] || payload.name || 'tool';
+  const id = `live:${payload.call_id}`;
+  const common = { type: 'activity', id, status: 'inProgress', transient: true };
+  const turnId = payload.internal_chat_message_metadata_passthrough?.turn_id || '';
+  if (nestedTool === 'exec_command') {
+    return {
+      turnId,
+      entry: {
+        ...common,
+        kind: 'command',
+        title: '命令',
+        command: jsonStringField(input, 'cmd'),
+        cwd: jsonStringField(input, 'workdir'),
+      },
+    };
+  }
+  if (nestedTool === 'apply_patch') {
+    return { turnId, entry: { ...common, kind: 'fileChange', title: '文件修改', changes: [] } };
+  }
+  if (nestedTool === 'web__run') {
+    return {
+      turnId,
+      entry: { ...common, kind: 'webSearch', title: '网页搜索', query: jsonStringField(input, 'q') },
+    };
+  }
+  if (nestedTool === 'view_image') {
+    return {
+      turnId,
+      entry: { ...common, kind: 'imageView', title: '查看图片', path: jsonStringField(input, 'path') },
+    };
+  }
+  const parts = nestedTool.replace(/^mcp__/, '').split('__');
+  return {
+    turnId,
+    entry: {
+      ...common,
+      kind: 'tool',
+      title: '工具',
+      server: parts.length > 1 ? parts.shift() : 'functions',
+      tool: parts.join('/') || nestedTool,
+      arguments: {},
+    },
+  };
+}
+
+function jsonStringField(source, field) {
+  const pattern = new RegExp(`(?:["']${field}["']|${field})\\s*:\\s*("(?:\\\\.|[^"\\\\])*")`);
+  const match = pattern.exec(source);
+  if (!match) return '';
+  try { return JSON.parse(match[1]); } catch { return ''; }
+}
+
+function messagePayload(body) {
+  const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
+  if (body.images !== undefined && (!Array.isArray(body.images) || body.images.length > 4)) {
+    throw new RequestError(400, '每条消息最多 4 张图片。');
+  }
+  const images = (body.images || []).map(id => {
+    if (typeof id === 'string' && id.startsWith('data:')) return validateInlineImage(id);
+    if (typeof id !== 'string' || !/^[a-f0-9]{64}$/.test(id)) throw new RequestError(400, '无效的图片标识。');
+    const webpFile = path.join(uploadsRoot, `${id}.webp`);
+    const file = fs.existsSync(webpFile) ? webpFile : path.join(uploadsRoot, `${id}.png`);
+    if (!fs.existsSync(file)) throw new RequestError(400, '图片不存在，请重新添加。');
+    return file;
+  });
+  if (images.filter(image => image.startsWith('data:')).reduce((size, image) => size + Buffer.byteLength(image.slice(image.indexOf(',') + 1), 'base64'), 0) > 8 * 1024 * 1024) throw new RequestError(413, '本条消息图片合计不能超过 8 MiB。');
+  if (!prompt && !images.length) throw new RequestError(400, 'prompt 不能为空。');
+  if (prompt.length > 32_000) throw new RequestError(400, 'prompt 不能超过 32000 个字符。');
+
+  const payload = { prompt, images };
+  if (typeof body.hostId === 'string' && body.hostId.trim()) payload.hostId = body.hostId.trim();
+  if (typeof body.model === 'string' && body.model.trim()) {
+    const model = body.model.trim();
+    if (!ALLOWED_MODELS.has(model)) throw new RequestError(400, '不支持的模型。');
+    payload.model = model;
+  }
+  if (typeof body.thinking === 'string' && body.thinking.trim()) {
+    const thinking = body.thinking.trim();
+    if (!ALLOWED_THINKING.has(thinking)) throw new RequestError(400, '不支持的推理强度。');
+    if ((payload.model === 'gpt-5.5' || payload.model === 'gpt-5.3-codex-spark')
+      && (thinking === 'max' || thinking === 'ultra')) {
+      throw new RequestError(400, '所选模型不支持该推理强度。');
+    }
+    payload.thinking = thinking;
+  }
+  return payload;
+}
+
+async function messageArguments(threadId, body) {
+  const payload = messagePayload(body);
+  payload.images = await Promise.all(payload.images.map(image => image.startsWith('data:') ? persistLegacyImage(image, uploadsRoot) : image));
+  let prompt = payload.prompt;
+  if (payload.images.length) {
+    prompt += (prompt ? '\n\n' : '') + payload.images
+      .map((file, index) => `![手机图片 ${index + 1}](${file.replaceAll('\\', '/')})`)
+      .join('\n\n');
+  }
+  const argumentsValue = { threadId, prompt };
+  if (payload.hostId) argumentsValue.hostId = payload.hostId;
+  if (payload.model) argumentsValue.model = payload.model;
+  if (payload.thinking) argumentsValue.thinking = payload.thinking;
+  return argumentsValue;
+}
+
+function usesSharedTask(body) {
+  return Boolean(sharedServer && (!body.hostId || body.hostId === 'local'));
+}
+
+function appServerTurnArguments(threadId, body) {
+  const payload = messagePayload(body);
+  const input = [];
+  if (payload.prompt) input.push({ type: 'text', text: payload.prompt });
+  for (const image of payload.images) input.push(image.startsWith('data:') ? { type: 'image', url: image } : { type: 'localImage', path: image });
+  const value = { threadId, input };
+  if (typeof body.clientUserMessageId === 'string' && /^[a-f0-9]{32}$/.test(body.clientUserMessageId)) value.clientUserMessageId = body.clientUserMessageId;
+  if (payload.model) value.model = payload.model;
+  if (payload.thinking) value.effort = payload.thinking;
+  return value;
+}
+
+function messageDisplayText(body) {
+  const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
+  const imageCount = Array.isArray(body.images) ? body.images.length : 0;
+  return prompt || (imageCount ? `[${imageCount} 张图片]` : '');
+}
+
+function createThreadBody(body) {
+  const payload = messagePayload(body);
+  return { ...body, prompt: payload.prompt, transport: body.transport === 'app-server' ? 'app-server' : 'desktop-tools' };
+}
+
+function appServerProjectTarget(projectId, projects) {
+  if (projectId === '__unassigned__') return appServerEvents.projectlessThreadTarget(projectRoot);
+  const project = projects.find(item => item?.projectId === projectId);
+  if (!project) throw new RequestError(404, '没有找到对应项目。');
+  if (project.hostId && project.hostId !== 'local') {
+    throw new RequestError(400, '独立 app-server 当前只支持本机项目。');
+  }
+  if (typeof project.path !== 'string' || !path.isAbsolute(project.path)) {
+    throw new RequestError(400, '项目没有可用的本机路径。');
+  }
+  return { projectId, cwd: project.path };
+}
+
+function mergeThreadCatalog(catalog, appThreads, limit, sharedSnapshot = Boolean(sharedServer)) {
+  const owned = new Map(appThreads.map(thread => [thread.id, thread]));
+  const pinnedThreads = (catalog.pinnedThreads || []).map(thread => owned.get(thread.id) || thread);
+  const pinnedIds = new Set(pinnedThreads.map(thread => thread.id));
+  if (sharedSnapshot) {
+    const listed = new Set([...pinnedIds, ...(catalog.threads || []).map(thread => thread.id)]);
+    return { ...catalog, pinnedThreads, threads: [
+      ...(catalog.threads || []).map(thread => owned.get(thread.id) || thread),
+      ...appThreads.filter(thread => !listed.has(thread.id)),
+    ].slice(0, limit) };
+  }
+  const desktopThreads = (catalog.threads || []).filter(thread => !owned.has(thread.id));
+  const merged = [...desktopThreads, ...appThreads.filter(thread => !pinnedIds.has(thread.id))]
+    .sort((left, right) => Number(right.updatedAt || 0) - Number(left.updatedAt || 0))
+    .slice(0, limit);
+  return { ...catalog, pinnedThreads, threads: merged };
+}
+
+async function createThreadArguments(projectId, body, projects) {
+  const { threadId, hostId, ...message } = await messageArguments('', body);
+  if (projectId === '__unassigned__') return { ...message, target: { type:'projectless' } };
+  const project = projects.find(item => item?.projectId === projectId);
+  if (!project) throw new RequestError(404, '没有找到对应项目。');
+  return { ...message, target:{ type:'project', projectId, environment:{ type:'local' } } };
+}
+
+function publicQueue(threadId) {
+  return (messageQueues.get(threadId) || []).map(item => ({
+    id: item.id,
+    prompt: item.displayPrompt || item.prompt,
+    text: item.text, attachments:item.attachments || [],
+    model: item.model || '',
+    thinking: item.thinking || item.effort || '',
+    createdAt: item.createdAt,
+    error: item.error || '',
+  }));
+}
+
+function queueArguments(item) {
+  const value = { threadId: item.threadId, prompt: item.prompt };
+  if (item.hostId) value.hostId = item.hostId;
+  if (item.model) value.model = item.model;
+  if (item.thinking) value.thinking = item.thinking;
+  return value;
+}
+
+async function sendQueuedItem(threadId, item) {
+  await requireExecutionWritable(threadId);
+  if (item.transport === 'app-server') {
+    try {
+      return { success: true, data: await appServerTasks.startTurn(threadId, item) };
+    } catch (error) {
+      return { success: false, data: error instanceof Error ? error.message : String(error) };
+    }
+  }
+  return callTool('send_message_to_thread', queueArguments(item));
+}
+
+async function steerQueuedItem(threadId, item) {
+  if (item.transport !== 'app-server') return callTool('send_message_to_thread', queueArguments(item));
+  try {
+    const thread = await appServerTasks.readTask(threadId, { includeTurns: true, turnLimit: 1 });
+    const activeTurn = thread.turns?.at(-1);
+    if (!activeTurn || statusText(activeTurn.status) !== 'inProgress') {
+      throw new Error('当前没有可引导的 app-server 活动轮次。');
+    }
+    return {
+      success: true,
+      data: await appServerTasks.steerTurn(threadId, activeTurn.id, item.input),
+    };
+  } catch (error) {
+    return { success: false, data: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function ensureQueueWorker(threadId) {
+  if (queueWorkers.has(threadId)) return;
+  const worker = runQueueWorker(threadId)
+    .catch(error => {
+      const item = messageQueues.get(threadId)?.[0];
+      if (item) item.error = error instanceof Error ? error.message : String(error);
+    })
+    .finally(() => queueWorkers.delete(threadId));
+  queueWorkers.set(threadId, worker);
+}
+
+async function runQueueWorker(threadId) {
+  while (true) {
+    const queue = messageQueues.get(threadId) || [];
+    const item = queue[0];
+    if (!item || item.error) return;
+    let timeline;
+    if (item.transport === 'app-server') {
+      const thread = await appServerTasks.readTask(threadId, { includeTurns: true, turnLimit: 1 });
+      timeline = normalizeAppServerTimeline(thread);
+    } else {
+      const readArguments = {
+        threadId,
+        turnLimit: 1,
+        includeOutputs: false,
+        maxOutputCharsPerItem: 500,
+      };
+      if (item.hostId) readArguments.hostId = item.hostId;
+      const threadResult = await callTool('read_thread', readArguments, 15_000);
+      if (!threadResult.success) throw new BridgeError('读取排队任务状态失败。', threadResult.data);
+      timeline = normalizeTimeline(threadResult.data);
+    }
+    const active = timeline.thread.status === 'active' || timeline.turns.at(-1)?.status === 'inProgress';
+    if (active) {
+      await delay(2_000);
+      continue;
+    }
+    if (messageQueues.get(threadId) !== queue || queue[0]?.id !== item.id) continue;
+    const sendResult = await sendQueuedItem(threadId, item);
+    if (!sendResult.success) throw new BridgeError('发送排队消息失败。', sendResult.data);
+    if (queue[0]?.id === item.id) queue.shift();
+  }
+}
+
+async function streamAppServerThreadEvents(request, response, threadId) {
+  response.startEvents();
+
+  let closed = false;
+  let pushPending = false;
+  let pushing = false;
+  let previousHash = '';
+  let updateTimer = null;
+  let resolveClosed;
+  const closedPromise = new Promise(resolve => { resolveClosed = resolve; });
+  response.once('close', () => { closed = true; resolveClosed(); });
+
+  const pushUpdate = async () => {
+    if (closed) return;
+    if (pushing) { pushPending = true; return; }
+    pushing = true;
+    try {
+      const thread = await appServerTasks.readTask(threadId, { includeTurns: true, turnLimit: 2 });
+      const timeline = normalizeAppServerTimeline(thread);
+      const update = {
+        thread: timeline.thread,
+        turns: timeline.turns.slice(-2),
+        turn: timeline.turns.at(-1) || null,
+        queue: publicQueue(threadId),
+      };
+      const serialized = JSON.stringify(update);
+      const hash = crypto.createHash('sha256').update(serialized).digest('base64url');
+      if (hash !== previousHash) {
+        sendEvent(response, 'update', update);
+        previousHash = hash;
+      }
+    } catch (error) {
+      sendEvent(response, 'bridge-error', { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      pushing = false;
+      if (pushPending && !closed) {
+        pushPending = false;
+        void pushUpdate();
+      }
+    }
+  };
+  const scheduleUpdate = event => {
+    if (closed || event.threadId !== threadId || updateTimer) return;
+    updateTimer = setTimeout(() => {
+      updateTimer = null;
+      void pushUpdate();
+    }, 60);
+  };
+  appServerTasks.on('thread-event', scheduleUpdate);
+  await pushUpdate();
+
+  await closedPromise;
+  closed = true;
+  if (updateTimer) clearTimeout(updateTimer);
+  appServerTasks.off('thread-event', scheduleUpdate);
+  if (!response.writableEnded) response.end();
+}
+
+async function streamThreadEvents(request, response, threadId, hostId) {
+  response.startEvents();
+
+  let closed = false;
+  let previousHash = '';
+  response.once('close', () => { closed = true; });
+
+  while (!closed) {
+    let intervalMs = 2_500;
+    try {
+      const argumentsValue = {
+        threadId,
+        turnLimit: 2,
+        includeOutputs: true,
+        maxOutputCharsPerItem: 4_000,
+      };
+      if (hostId) argumentsValue.hostId = hostId;
+      const result = await callTool('read_thread', argumentsValue);
+      if (!result.success) {
+        throw new BridgeError('Codex Desktop 工具返回失败。', result.data);
+      }
+
+      const timeline = normalizeTimeline(result.data);
+      enrichTimelineWithLocalActivity(timeline, threadId);
+      const update = {
+        thread: timeline.thread,
+        turns: timeline.turns.slice(-2),
+        turn: timeline.turns.at(-1) || null,
+        queue: publicQueue(threadId),
+      };
+      const serialized = JSON.stringify(update);
+      const hash = crypto.createHash('sha256').update(serialized).digest('base64url');
+      if (hash !== previousHash) {
+        sendEvent(response, 'update', update);
+        previousHash = hash;
+      }
+      if (timeline.thread.status === 'active' || update.turn?.status === 'inProgress') {
+        intervalMs = 1_000;
+      }
+    } catch (error) {
+      sendEvent(response, 'bridge-error', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      intervalMs = 3_000;
+    }
+
+    await delay(intervalMs);
+  }
+
+  if (!response.writableEnded) response.end();
+}
+
+function sendEvent(response, eventName, value) {
+  if (response.destroyed || response.writableEnded) return;
+  response.event(eventName, value);
+}
+
+function normalizeTimeline(data, reverseTurns = true) {
+  const source = data && typeof data === 'object' ? data : {};
+  const sourceTurns = Array.isArray(source.turns) ? source.turns : source.thread?.turns;
+  const turns = Array.isArray(sourceTurns) ? sourceTurns.map(normalizeTurn) : [];
+  if (reverseTurns) turns.reverse();
+  if (reverseTurns) restoreEmptyTurnMessages(source.thread?.id, turns);
+  return {
+    schemaVersion: 1,
+    thread: normalizeThread(source.thread),
+    turns,
+  };
+}
+
+function normalizeAppServerTimeline(thread) {
+  const record = appServerTasks.store.get(thread?.id);
+  return normalizeTimeline({
+    thread: {
+      ...thread,
+      title: thread?.name || thread?.title || record?.title || '',
+      projectId: record?.projectId || '',
+      hostId: 'app-server',
+      transport: 'app-server',
+    },
+  }, false);
+}
+
+function normalizeSharedTimeline({ thread, nextCursor, sync }) {
+  return { ...normalizeTimeline({ thread: { ...thread, title: thread.name || thread.title || '', hostId: 'local', transport: 'shared-app-server' } }, false),
+    ...(nextCursor !== undefined ? { nextCursor } : {}), ...(sync ? { sync } : {}) };
+}
+
+function restoreEmptyTurnMessages(threadId, turns) {
+  const missing = new Map(turns.filter(turn => turn.entries.length === 0).map(turn => [turn.id, turn]));
+  if (!missing.size || !threadId) return;
+  const sessionPath = findSessionPath(threadId);
+  if (!sessionPath) return;
+  const handle = fs.openSync(sessionPath, 'r');
+  try {
+    const size = fs.fstatSync(handle).size;
+    const length = Math.min(size, MAX_SETTINGS_SCAN_BYTES);
+    const buffer = Buffer.allocUnsafe(length);
+    fs.readSync(handle, buffer, 0, length, size - length);
+    const lines = buffer.toString('utf8').split(/\r?\n/);
+    if (length < size) lines.shift();
+    let turnId;
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      const item = event.payload;
+      if (event.type === 'event_msg' && item?.type === 'task_started') turnId = item.turn_id;
+      if (event.type === 'turn_context') turnId = item?.turn_id;
+      const turn = missing.get(turnId);
+      if (!turn || event.type !== 'response_item') continue;
+      let entry;
+      if (item.type === 'function_call_output' && item.namespace === 'codex_app' && ['create_thread', 'send_message_to_thread'].includes(item.name)) {
+        const text = extractDelegatedInput(item.output);
+        if (text) entry = { type: 'message', id: item.id, role: 'user', source: 'remote', ...splitUploadedImages(text) };
+      } else if (item.type === 'message' && ['user', 'assistant'].includes(item.role) && item.channel !== 'analysis') {
+        const text = (item.content || []).filter(part => ['input_text', 'output_text'].includes(part.type)).map(part => part.text || '').join('\n');
+        if (text) entry = item.role === 'user'
+          ? normalizeItem({ type: 'userMessage', id: item.id, content: item.content.map(part => ({ ...part, type: part.type === 'input_text' ? 'text' : part.type })) })
+          : normalizeItem({ type: 'agentMessage', id: item.id, phase: item.phase || item.channel, text });
+      }
+      if (entry) turn.entries.push(entry);
+    }
+  } finally { fs.closeSync(handle); }
+}
+
+function normalizeThread(thread) {
+  const source = thread && typeof thread === 'object' ? thread : {};
+  return {
+    id: source.id || '',
+    title: source.name || source.title || source.preview || '',
+    status: statusText(source.status),
+    updatedAt: Number(source.updatedAt) || 0,
+    projectId: source.projectId || '',
+    cwd: source.cwd || '',
+    hostId: source.hostId || '',
+    transport: source.transport || (source.hostId === 'app-server' ? 'app-server' : 'desktop-tools'),
+    readOnly: source.readOnly === true,
+    readOnlyReason: source.readOnlyReason || '',
+  };
+}
+
+function normalizeTurn(turn) {
+  const source = turn && typeof turn === 'object' ? turn : {};
+  return {
+    id: source.id || '',
+    status: statusText(source.status),
+    startedAt: source.startedAt || null,
+    completedAt: source.completedAt || null,
+    durationMs: source.durationMs ?? null,
+    error: source.error ?? null,
+    entries: Array.isArray(source.items) ? source.items.map(normalizeItem).filter(Boolean) : [],
+  };
+}
+
+function normalizeItem(item) {
+  if (!item || typeof item !== 'object') return null;
+
+  if (item.type === 'contextCompaction') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'contextCompaction',
+      title: '已自动压缩上下文',
+    };
+  }
+
+  if (item.type === 'functionCallOutput'
+    && item.namespace === 'codex_app'
+    && ['create_thread', 'send_message_to_thread'].includes(item.name)) {
+    const text = extractDelegatedInput(delegatedOutputText(item.output));
+    if (text) {
+      return {
+        type: 'message',
+        id: item.id || '',
+        role: 'user',
+        source: 'remote',
+        ...splitUploadedImages(text),
+      };
+    }
+  }
+
+  if (item.type === 'userMessage') {
+    const text = extractUserText(item.content);
+    const attachments = normalizeAttachments(item.content);
+    if (!text && !attachments.length) return null;
+    return {
+      clientId: item.clientId,
+      type: 'message',
+      id: item.id || '',
+      role: 'user',
+      text,
+      attachments,
+    };
+  }
+
+  if (item.type === 'agentMessage') {
+    return {
+      type: 'message',
+      id: item.id || '',
+      role: 'assistant',
+      phase: item.phase || '',
+      delivery: item.delivery,
+      questions: item.questions,
+      text: item.text || '',
+      imageAssets: markdownImageAssets(item.text || ''),
+      fileAssets: markdownFileAssets(item.text || ''),
+    };
+  }
+
+  if (item.type === 'reasoning') {
+    const detail = Array.isArray(item.summary)
+      ? item.summary.map(summaryText).filter(Boolean).join('\n')
+      : summaryText(item.summary);
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'reasoning',
+      title: '思考摘要',
+      detail,
+    };
+  }
+
+  if (item.type === 'commandExecution') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'command',
+      title: '命令',
+      status: statusText(item.status),
+      command: item.command || '',
+      cwd: item.cwd || '',
+      exitCode: item.exitCode ?? null,
+      durationMs: item.durationMs ?? null,
+      output: item.aggregatedOutput || item.output?.text || '',
+    };
+  }
+
+  if (item.type === 'mcpToolCall') {
+    const result = normalizeToolResult(item.result, item.error);
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'tool',
+      title: '工具',
+      status: statusText(item.status),
+      server: item.server || '',
+      tool: item.tool || '',
+      arguments: item.arguments || {},
+      resultText: result.text,
+      errorText: result.error,
+      resources: result.resources,
+      mediaCount: result.mediaCount,
+      durationMs: item.durationMs ?? null,
+    };
+  }
+
+  if (item.type === 'fileChange') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'fileChange',
+      title: '文件修改',
+      status: statusText(item.status),
+      changes: Array.isArray(item.changes) ? item.changes : [],
+    };
+  }
+
+  if (item.type === 'webSearch') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'webSearch',
+      title: '网页搜索',
+      query: item.query || item.action?.query || '',
+    };
+  }
+
+  if (item.type === 'imageView') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'imageView',
+      title: '查看图片',
+      path: item.path || '',
+      image: typeof item.path === 'string' && item.path
+        ? normalizeAttachment({ type: 'localImage', path: item.path })
+        : null,
+    };
+  }
+
+  if (item.type === 'imageGeneration') {
+    let image = typeof item.savedPath === 'string' && item.savedPath
+      ? normalizeAttachment({ type: 'localImage', path: item.savedPath, name: '生成的图片' })
+      : null;
+    if ((!image || !image.available) && typeof item.result === 'string' && item.result.trim()) {
+      const result = item.result.trim();
+      const url = result.startsWith('data:image/') ? result : `data:image/png;base64,${result}`;
+      image = normalizeAttachment({ type: 'image', url, name: '生成的图片' });
+    }
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'imageGeneration',
+      title: '生成图片',
+      status: statusText(item.status),
+      image,
+      failure: item.failure || null,
+      transparentBackground: item.transparentBackground === true,
+    };
+  }
+
+  if (item.type === 'subAgentActivity') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'subAgent',
+      title: '子任务',
+      status: statusText(item.kind),
+      agentPath: item.agentPath || '',
+      agentThreadId: item.agentThreadId || '',
+    };
+  }
+
+  if (item.type === 'collabAgentToolCall') {
+    return {
+      type: 'activity',
+      id: item.id || '',
+      kind: 'collaboration',
+      title: '任务协作',
+      status: statusText(item.status),
+      tool: item.tool || '',
+      prompt: item.prompt || '',
+      receiverThreadIds: Array.isArray(item.receiverThreadIds) ? item.receiverThreadIds : [],
+    };
+  }
+
+  return {
+    type: 'activity',
+    id: item.id || '',
+    kind: item.type || 'event',
+    title: item.type || '事件',
+    status: statusText(item.status),
+    detail: JSON.stringify(item, null, 2),
+  };
+}
+
+function normalizeToolResult(result, fallbackError) {
+  const text = [];
+  const resources = [];
+  let mediaCount = 0;
+  const seen = new Set();
+  const addText = value => {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (normalized && !seen.has(normalized)) { seen.add(normalized); text.push(normalized); }
+  };
+  const visit = (value, depth = 0) => {
+    if (value == null || depth > 4) return;
+    if (typeof value === 'string') { addText(value); return; }
+    if (Array.isArray(value)) { for (const item of value) visit(item, depth + 1); return; }
+    if (typeof value !== 'object') return;
+    if (value.type === 'image' || value.type === 'audio') { mediaCount += 1; return; }
+    if (value.type === 'resource_link') {
+      resources.push({ name: value.title || value.name || '资源', uri: value.uri || '', description: value.description || '' });
+      return;
+    }
+    if (value.type === 'resource' && value.resource) {
+      const resource = value.resource;
+      if (typeof resource.text === 'string') addText(resource.text);
+      else if (resource.uri) resources.push({ name: resource.title || resource.name || '资源', uri: resource.uri, description: resource.description || '' });
+      return;
+    }
+    if (typeof value.text === 'string') addText(value.text);
+    if (typeof value.message === 'string') addText(value.message);
+    if (value.content) visit(value.content, depth + 1);
+    if (value.raw) visit(value.raw, depth + 1);
+  };
+  visit(result);
+  const resultError = result?.type === 'error' ? result.error : null;
+  const errorValue = fallbackError || resultError;
+  const error = typeof errorValue === 'string' ? errorValue : errorValue?.message || errorValue?.text || '';
+  return { text: text.join('\n\n'), error, resources, mediaCount };
+}
+
+function normalizeAttachments(content) {
+  if (!Array.isArray(content)) return [];
+  const items = content.filter(item => item && !['text', 'input_text'].includes(item.type)).map(item => ({ ...item }));
+  const text = content.filter(item => ['text', 'input_text'].includes(item?.type)).map(item => item.text || '').join('\n');
+  const paths = [...new Set([...text.matchAll(/<image\b[^>]*\bpath="([^"]+)"[^>]*>/g)].map(match => match[1]))];
+  const images = items.filter(item => ['image', 'input_image', 'localImage'].includes(item.type));
+  for (const [index, imagePath] of paths.entries()) {
+    if (images.some(item => item.path === imagePath)) continue;
+    if (images[index] && !images[index].path) images[index].path = imagePath;
+    else items.push({ type: 'localImage', path: imagePath });
+  }
+  const seen = new Set();
+  return items.map(normalizeAttachment).filter(item => {
+    if (!item.url) return true;
+    if (seen.has(item.url)) return false;
+    seen.add(item.url); return true;
+  });
+}
+
+function markdownImageAssets(text) {
+  const assets = Object.create(null);
+  function visit(tokens) {
+    for (const token of tokens) {
+      const value = token.type === 'image' ? token.attrGet('src')
+        : token.type === 'link_open' ? token.attrGet('href') : null;
+      if (value && !Object.hasOwn(assets, value)) {
+        let localPath;
+        try { localPath = decodeURIComponent(value); } catch { continue; }
+        // Only paths actually referenced by Desktop messages become accessible.
+        // Do not expose a client-supplied filesystem path endpoint or UNC shares.
+        if (/^\/?[a-z]:[\\/]/i.test(localPath)) {
+          localPath = localPath.replace(/^\/(?=[a-z]:)/i, '');
+          const asset = normalizeAttachment({ type: 'localImage', path: localPath });
+          if (asset.available) assets[value] = asset;
+        }
+      }
+      if (token.children) visit(token.children);
+    }
+  }
+  visit(imageMarkdown.parse(text, {}));
+  return assets;
+}
+
+function markdownFileAssets(text) {
+  const assets = Object.create(null);
+  function visit(tokens) {
+    for (const token of tokens) {
+      if (token.type === 'link_open') {
+        const value = token.attrGet('href');
+        if (value && !Object.hasOwn(assets, value)) {
+          let localPath;
+          try { localPath = decodeURIComponent(value); } catch { localPath = ''; }
+          if (/^\/?[a-z]:[\\/]/i.test(localPath)) {
+            localPath = localPath.replace(/^\/(?=[a-z]:)/i, '');
+            const asset = rememberLocalFile(localPath);
+            if (asset) assets[value] = { remotePath: asset.id, name: asset.name, size: asset.size };
+          }
+        }
+      }
+      if (token.children) visit(token.children);
+    }
+  }
+  visit(imageMarkdown.parse(text, {}));
+  return assets;
+}
+
+function rememberLocalFile(filePath) {
+  try {
+    const resolved = path.resolve(filePath);
+    const stat = fs.statSync(resolved);
+    if (!stat.isFile() || stat.size > MAX_ATTACHMENT_BYTES) return null;
+    const id = crypto.createHmac('sha256', fileCapabilitySecret)
+      .update(resolved).update('\0').update(String(stat.size)).update('\0').update(String(stat.mtimeMs)).digest('hex');
+    if (!fileCache.has(id)) {
+      while (fileCache.size >= MAX_CACHED_FILES) fileCache.delete(fileCache.keys().next().value);
+      fileCache.set(id, { id, path: resolved, name: path.basename(resolved), size: stat.size, mtimeMs: stat.mtimeMs });
+    }
+    return fileCache.get(id);
+  } catch {
+    return null;
+  }
+}
+
+function splitUploadedImages(text) {
+  const tokens = imageMarkdown.parse(text, {});
+  const lines = text.split('\n');
+  const removed = new Set();
+  const attachments = [];
+  for (let index = 0; index < tokens.length - 1; index++) {
+    const block = tokens[index];
+    const inline = tokens[index + 1];
+    if (block.type !== 'paragraph_open' || !block.map || inline.type !== 'inline') continue;
+    const children = (inline.children || []).filter(token => token.type !== 'softbreak');
+    if (!children.length || children.some(token => token.type !== 'image')) continue;
+    const paths = children.map(token => {
+      try { return path.resolve(decodeURIComponent(token.attrGet('src') || '')); } catch { return ''; }
+    });
+    if (paths.some(file => !allowedUploadsRoots.some(root => path.dirname(file).toLowerCase() === root.toLowerCase())
+      || !/^[a-f0-9]{64}\.(png|webp)$/.test(path.basename(file)))) continue;
+    for (const file of paths) attachments.push(normalizeAttachment({ type: 'localImage', path: file, name: '手机图片' }));
+    for (let line = block.map[0]; line < block.map[1]; line++) removed.add(line);
+  }
+  const visibleText = lines.filter((line, index) => !removed.has(index)).join('\n').trim();
+  return { text: visibleText, attachments, imageAssets: markdownImageAssets(visibleText) };
+}
+
+function normalizeAttachment(item) {
+  const name = item.name || item.fileName || (typeof item.path === 'string' ? path.basename(item.path) : '');
+  let cached = null;
+  const isImage = ['image', 'input_image', 'localImage'].includes(item.type);
+  if (isImage && typeof item.path === 'string') {
+    cached = cacheLocalImage(item.path, name);
+  }
+  if (!cached) {
+    const dataUrl = typeof item.url === 'string' && item.url.startsWith('data:image/')
+      ? item.url
+      : (typeof item.image_url === 'string' && item.image_url.startsWith('data:image/') ? item.image_url : '');
+    if (dataUrl) cached = cacheDataImage(dataUrl, name);
+  }
+  return {
+    type: isImage ? 'image' : item.type || 'attachment',
+    name,
+    mimeType: cached?.mimeType || item.mimeType || '',
+    available: Boolean(cached),
+    remotePath: cached ? cached.id : '',
+    url: '',
+    thumbnailUrl: '',
+  };
+}
+
+function cacheLocalImage(filePath, name) {
+  try {
+    const stat = fs.statSync(filePath);
+    const mimeType = imageMimeType(filePath);
+    if (!stat.isFile() || !mimeType || stat.size > MAX_ATTACHMENT_BYTES) return null;
+    return rememberAttachment(fs.readFileSync(filePath), mimeType, name);
+  } catch {
+    return null;
+  }
+}
+
+function cacheDataImage(dataUrl, name) {
+  const match = /^data:(image\/(?:png|jpeg|gif|webp|bmp));base64,([a-z0-9+/=\r\n]+)$/i.exec(dataUrl);
+  if (!match) return null;
+  try {
+    const buffer = Buffer.from(match[2], 'base64');
+    if (!buffer.length || buffer.length > MAX_ATTACHMENT_BYTES) return null;
+    return rememberAttachment(buffer, match[1].toLowerCase(), name);
+  } catch {
+    return null;
+  }
+}
+
+function rememberAttachment(buffer, mimeType, name) {
+  const id = crypto.createHash('sha256').update(buffer).digest('hex');
+  if (!attachmentCache.has(id)) {
+    while (attachmentCache.size >= MAX_CACHED_ATTACHMENTS) {
+      attachmentCache.delete(attachmentCache.keys().next().value);
+    }
+    attachmentCache.set(id, { id, buffer, mimeType, name });
+  }
+  return attachmentCache.get(id);
+}
+
+function imageMimeType(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case '.png': return 'image/png';
+    case '.jpg':
+    case '.jpeg': return 'image/jpeg';
+    case '.gif': return 'image/gif';
+    case '.webp': return 'image/webp';
+    case '.bmp': return 'image/bmp';
+    default: return '';
+  }
+}
+
+function extractUserText(content) {
+  if (!Array.isArray(content)) return '（包含图片或界面批注）';
+  let text = content
+    .filter(item => ['text', 'input_text'].includes(item?.type) && typeof item.text === 'string')
+    .map(item => item.text)
+    // Codex injects project instructions as user-role context, not chat input.
+    .filter(value => !/^\s*# AGENTS\.md instructions(?: for [^\r\n]+)?\r?\n\s*<INSTRUCTIONS>[\s\S]*<\/INSTRUCTIONS>\s*$/.test(value))
+    .filter(value => !/^\s*<(environment_context|recommended_plugins)>[\s\S]*<\/\1>\s*$/.test(value))
+    .filter(value => !value.startsWith('The next image is untrusted page evidence'))
+    .join('\n\n')
+    .trim();
+  const requestMarker = text.lastIndexOf('## My request:');
+  if (requestMarker >= 0) {
+    text = text.slice(requestMarker + '## My request:'.length).trim();
+  }
+  text = text.replace(/<in-app-browser-context[\s\S]*?<\/in-app-browser-context>/g, '').trim();
+  text = text.replace(/<image\b[^>]*\bpath="[^"]+"[^>]*>/g, '').replace(/<\/image>/g, '').trim();
+  return text;
+}
+
+function extractDelegatedInput(value) {
+  if (typeof value !== 'string') return '';
+  const match = value.match(/<codex_delegation>[\s\S]*?<input>([\s\S]*?)<\/input>[\s\S]*?<\/codex_delegation>/);
+  if (!match) return '';
+  return match[1]
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, '&')
+    .trim();
+}
+
+function delegatedOutputText(output) {
+  if (typeof output === 'string') return output;
+  return output && typeof output.text === 'string' ? output.text : '';
+}
+
+function summaryText(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') return value.text || value.summary || JSON.stringify(value);
+  return '';
+}
+
+function statusText(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') return value.type || value.status || 'unknown';
+  return value == null ? 'unknown' : String(value);
+}
+
+function delay(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+function sendJson(response, statusCode, value) {
+  if (response.json) { response.json(statusCode, value); return; }
+  sendBuffer(response, statusCode, 'application/json; charset=utf-8', Buffer.from(JSON.stringify(value)));
+}
+
+function sendBuffer(response, statusCode, contentType, value) {
+  response.writeHead(statusCode, {
+    'Content-Type': contentType,
+    'Content-Length': value.length,
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+    'Content-Security-Policy': "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:",
+  });
+  response.end(value);
+}
+
+async function readJsonBody(request) {
+  return request.body;
+}
+
+function parseOptions(args) {
+  let port = Number.parseInt(process.env.CODEX_REMOTE_BRIDGE_PORT || '45831', 10);
+  let lan = process.env.CODEX_REMOTE_BRIDGE_LAN === 'true';
+  let token = process.env.CODEX_REMOTE_BRIDGE_TOKEN?.trim() || '';
+  let appServer = process.env.CODEX_REMOTE_APP_SERVER === 'true';
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--lan') lan = true;
+    if (args[i] === '--app-server') appServer = true;
+    if (args[i] === '--port' && args[i + 1]) port = Number.parseInt(args[++i], 10);
+    if (args[i] === '--token' && args[i + 1]) token = args[++i];
+  }
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error('端口必须位于 1024 到 65535 之间。');
+  }
+  if (lan && !token) token = crypto.randomBytes(32).toString('base64url');
+  return { port, lan, token, appServer };
+}
+
+function boundedInteger(value, fallback, minimum, maximum) {
+  const parsed = Number.parseInt(value || '', 10);
+  return Number.isFinite(parsed) ? Math.min(maximum, Math.max(minimum, parsed)) : fallback;
+}
+
+function booleanValue(value, fallback) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return fallback;
+}
+
+class BridgeError extends Error {
+  constructor(message, details, options) {
+    super(message, options ? { cause: options } : undefined);
+    this.details = details;
+  }
+}
+
+class RequestError extends Error {
+  constructor(statusCode, message, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.code = details?.code;
+  }
+}