@livedesk/hub 0.1.3 → 0.1.5

package/src/agents/codex-agent-runtime.js

@@ -0,0 +1,720 @@
+import crypto from 'node:crypto';
+import { access, link, mkdir, stat, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { AgentProviderError } from './provider-errors.js';
+import { AGENT_PROVIDER_CODEX } from './agent-settings.js';
+import { AGENT_TOOL_NAMES } from './agent-tool-registry.js';
+import { createAgentPermissionPolicy, hashAgentPermissionPolicy } from './agent-permissions.js';
+
+const require = createRequire(import.meta.url);
+const MAX_EVENTS = 240;
+const MAX_RUNS = 500;
+const RUN_TTL_MS = 60 * 60 * 1000;
+const SAFE_ENV_KEYS = [
+  'Path',
+  'PATH',
+  'SystemRoot',
+  'SYSTEMROOT',
+  'ComSpec',
+  'TEMP',
+  'TMP',
+  'WINDIR',
+  'LANG',
+  'LC_ALL',
+  'TMPDIR'
+];
+const LIVEDESK_MCP_TOOLS = AGENT_TOOL_NAMES;
+
+function safeText(value, max = 2400) {
+  return String(value || '').replace(/[\0\r]/g, ' ').trim().slice(0, max);
+}
+
+function publicEvent(event) {
+  const item = event?.item;
+  return {
+    type: String(event?.type || '').slice(0, 80),
+    threadId: safeText(event?.thread_id, 120),
+    item: item ? {
+      id: safeText(item.id, 120),
+      type: safeText(item.type, 80),
+      server: safeText(item.server, 80),
+      tool: safeText(item.tool, 120),
+      status: safeText(item.status, 40),
+      text: safeText(item.text, 600),
+      error: safeText(item.error?.message, 400)
+    } : undefined,
+    message: safeText(event?.message || event?.error?.message, 500)
+  };
+}
+
+function isAbortError(error) {
+  return error?.name === 'AbortError'
+    || error?.code === 'ABORT_ERR'
+    || /aborted|abort/i.test(String(error?.message || ''));
+}
+
+function normalizeCodexError(error) {
+  const message = safeText(error?.message, 800) || 'Codex run failed.';
+  if (error instanceof AgentProviderError && error.code !== 'codex-run-failed') return error;
+  if (/out of credits|usage limit|rate limit|too many requests/i.test(message)) return new AgentProviderError('codex-usage-limit-reached', 'The Codex workspace has no remaining usage.', { status: 402, retryable: true });
+  if (/refresh[_ -]?token[_ -]?(?:already[_ -]?)?used|token refresh|refresh credential/i.test(message)) return new AgentProviderError('codex-auth-stale', 'The saved Codex sign-in is stale. LiveDesk refreshed its Codex authentication bridge and will retry.', { status: 401, retryable: true });
+  if (/not authenticated|not logged in|authentication|unauthorized|login required/i.test(message)) return new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+  if (/user cancelled MCP tool call/i.test(message)) return new AgentProviderError('codex-mcp-tool-rejected', 'Codex rejected the LiveDesk MCP tool before it reached the Hub.', { status: 502 });
+  return new AgentProviderError('codex-run-failed', message, { status: 502, retryable: true });
+}
+
+function codexThreadOptions(settings, workspace) {
+  return {
+    model: settings.codexModelId || undefined,
+    sandboxMode: 'read-only',
+    approvalPolicy: 'never',
+    workingDirectory: workspace,
+    skipGitRepoCheck: true,
+    modelReasoningEffort: settings.codexReasoningEffort,
+    networkAccessEnabled: false,
+    webSearchMode: 'disabled',
+    webSearchEnabled: false,
+    additionalDirectories: []
+  };
+}
+
+function baseCodexConfig() {
+  return {
+    approval_policy: 'never',
+    sandbox_mode: 'read-only',
+    web_search: 'disabled',
+    features: {
+      shell_tool: false,
+      unified_exec: false,
+      shell_snapshot: false,
+      apps: false,
+      multi_agent: false,
+      web_search: false,
+      skill_mcp_dependency_install: false,
+      memories: false,
+      plugins: false,
+      remote_plugin: false
+    },
+    tools: {
+      web_search: false,
+      view_image: false
+    },
+    apps: {
+      _default: { enabled: false }
+    },
+    plugins: {},
+    mcp_servers: {}
+  };
+}
+
+function codexConfig({ mcpServerPath, mcpUrl, token, workspace }) {
+  const config = baseCodexConfig();
+  config.mcp_servers = {
+    livedesk: {
+      command: process.execPath,
+      args: [mcpServerPath],
+      cwd: workspace,
+      env: {
+        LIVEDESK_AGENT_MCP_URL: mcpUrl,
+        LIVEDESK_AGENT_MCP_TOKEN: token
+      },
+      enabled: true,
+      required: true,
+      enabled_tools: LIVEDESK_MCP_TOOLS,
+      startup_timeout_sec: 10,
+      tool_timeout_sec: 150
+    }
+  };
+  return config;
+}
+
+function safeCodexEnv(codexHome) {
+  const env = {
+    CODEX_HOME: codexHome,
+    HOME: codexHome,
+    USERPROFILE: codexHome,
+    APPDATA: path.join(codexHome, 'AppData', 'Roaming'),
+    LOCALAPPDATA: path.join(codexHome, 'AppData', 'Local')
+  };
+  for (const key of SAFE_ENV_KEYS) {
+    const value = process.env[key];
+    if (value !== undefined && value !== '') env[key] = value;
+  }
+  if (!env.Path && env.PATH) env.Path = env.PATH;
+  if (!env.PATH && env.Path) env.PATH = env.Path;
+  return env;
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function replaceAuthHardLink(sourceAuthPath, targetAuthPath) {
+  await unlink(targetAuthPath).catch(error => {
+    if (error?.code !== 'ENOENT') throw error;
+  });
+  try {
+    await link(sourceAuthPath, targetAuthPath);
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+}
+
+async function ensureCodexHome(codexHome, globalCodexHome, { preferGlobalAuth = false } = {}) {
+  const resolvedHome = path.resolve(codexHome);
+  const globalHome = path.resolve(globalCodexHome);
+  if (!resolvedHome || resolvedHome === globalHome) {
+    throw new AgentProviderError('codex-isolation-unavailable', 'Codex requires a dedicated LiveDesk home.', { status: 503 });
+  }
+  try {
+    await mkdir(resolvedHome, { recursive: true, mode: 0o700 });
+    if (await access(path.join(resolvedHome, 'config.toml')).then(() => true, () => false)) {
+      throw new AgentProviderError('codex-environment-isolation-failed', 'The dedicated Codex home contains an unmanaged config.toml.', { status: 503 });
+    }
+  } catch (error) {
+    if (error instanceof AgentProviderError) throw error;
+    const wrapped = new AgentProviderError('codex-environment-isolation-failed', 'The dedicated Codex home could not be prepared.', { status: 503 });
+    wrapped.cause = error;
+    throw wrapped;
+  }
+  const targetAuthPath = path.join(resolvedHome, 'auth.json');
+  const sourceAuthPath = path.join(globalHome, 'auth.json');
+  if (!(await access(sourceAuthPath).then(() => true, () => false))) return;
+  try {
+    const sourceStatus = await stat(sourceAuthPath);
+    const targetStatus = await stat(targetAuthPath).catch(error => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (!targetStatus) {
+      await link(sourceAuthPath, targetAuthPath);
+      return;
+    }
+    if (sameFile(sourceStatus, targetStatus)) return;
+
+    // Codex may atomically replace auth.json while refreshing a token. That
+    // breaks a hard link even though both paths still exist. Follow the newer
+    // credential owner, or explicitly recover from a stale-refresh failure,
+    // without ever reading or copying credential contents.
+    if (preferGlobalAuth || sourceStatus.mtimeMs > targetStatus.mtimeMs || targetStatus.size === 0) {
+      await replaceAuthHardLink(sourceAuthPath, targetAuthPath);
+    }
+  } catch (error) {
+    const wrapped = new AgentProviderError('codex-environment-isolation-failed', 'The Codex authentication bridge could not be prepared.', { status: 503 });
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+function runCli(cliPath, args, timeoutMs = 5000, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      env,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(Object.assign(new Error('Codex CLI status check timed out.'), { code: 'codex-status-timeout' }));
+    }, timeoutMs);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.once('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once('close', code => {
+      clearTimeout(timer);
+      resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() });
+    });
+  });
+}
+
+function isTerminalStatus(status) {
+  return ['completed', 'failed', 'cancelled'].includes(status);
+}
+
+function runAgeMs(run) {
+  return Math.max(0, Date.now() - Date.parse(run.updatedAt || run.createdAt || 0));
+}
+
+function codexAbortError(code, message) {
+  return new AgentProviderError(code, message, { status: code === 'codex-run-timeout' ? 504 : 409, retryable: code === 'codex-run-timeout' });
+}
+
+function safeAgentDeviceIds(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map(item => String(item || '').trim())
+    .filter(Boolean))].slice(0, 500);
+}
+
+function freezeAgentPermissionPolicy(policy) {
+  const cloned = policy && typeof policy === 'object'
+    ? JSON.parse(JSON.stringify(policy))
+    : createAgentPermissionPolicy({ mode: 'ask' });
+  if (cloned.categories && typeof cloned.categories === 'object') Object.freeze(cloned.categories);
+  return Object.freeze(cloned);
+}
+
+export function createCodexAgentRuntime({
+  settingsStore,
+  dataDir = path.join(os.homedir(), '.livedesk'),
+  mcpServerPath,
+  createMcpSession,
+  destroyMcpSession,
+  createCodexClient: injectedCodexClient,
+  getCodexStatus: injectedCodexStatus,
+  onProgress,
+  globalCodexHome = path.join(os.homedir(), '.codex')
+} = {}) {
+  const runs = new Map();
+  let activeCount = 0;
+  let codexModulePromise;
+  let securityVerificationState = 'configured';
+  const workspace = path.resolve(dataDir, 'agent-workspace');
+  const codexHome = path.resolve(dataDir, 'codex-home');
+  const resolvedGlobalCodexHome = path.resolve(globalCodexHome);
+  let codexHomePreparation = Promise.resolve();
+
+  function reportProgress(run, stage, message, extra = {}) {
+    run.stage = safeText(stage, 80);
+    run.progressMessage = safeText(message, 500);
+    if (typeof onProgress !== 'function') return;
+    try {
+      onProgress({
+        runId: run.runId,
+        deviceIds: [...run.deviceIds],
+        stage: safeText(stage, 80),
+        message: safeText(message, 500),
+        status: run.status,
+        ...extra
+      });
+    } catch {
+      // Client-side developer progress is best effort and must never affect a
+      // Codex run or its enforced permission boundary.
+    }
+  }
+
+  function securityStatus() {
+    const configured = codexHome !== path.resolve(os.homedir(), '.codex')
+      && typeof createMcpSession === 'function'
+      && Boolean(mcpServerPath);
+    return {
+      isolatedCodexHome: codexHome !== path.resolve(os.homedir(), '.codex'),
+      restrictedEnvironment: true,
+      livedeskMcpOnly: typeof createMcpSession === 'function' && Boolean(mcpServerPath),
+      selectedDeviceScopeEnforced: typeof createMcpSession === 'function',
+      failClosed: true,
+      verified: configured && securityVerificationState === 'verified',
+      state: configured ? securityVerificationState : 'unavailable'
+    };
+  }
+
+  async function prepareCodexHome(options = {}) {
+    const operation = codexHomePreparation.then(async () => {
+      try {
+        await ensureCodexHome(codexHome, resolvedGlobalCodexHome, options);
+        securityVerificationState = 'verified';
+      } catch (error) {
+        securityVerificationState = 'unavailable';
+        throw error;
+      }
+    });
+    codexHomePreparation = operation.catch(() => undefined);
+    return operation;
+  }
+
+  function assertSecurityConfiguration() {
+    const status = securityStatus();
+    if (!status.isolatedCodexHome || !status.restrictedEnvironment || !status.livedeskMcpOnly || !status.selectedDeviceScopeEnforced) {
+      throw new AgentProviderError('codex-unsupported-security-config', 'Codex security isolation is not available.', { status: 503 });
+    }
+  }
+
+  async function createCodexClient(options) {
+    if (typeof injectedCodexClient === 'function') return injectedCodexClient(options);
+    const { Codex } = await loadCodex();
+    return new Codex(options);
+  }
+
+  function scheduleRunCleanup(run) {
+    const timer = setTimeout(() => {
+      if (runs.get(run.runId) === run && isTerminalStatus(run.status) && runAgeMs(run) >= RUN_TTL_MS) {
+        runs.delete(run.runId);
+      }
+    }, RUN_TTL_MS + 1000);
+    timer.unref?.();
+  }
+
+  function pruneRuns() {
+    for (const [runId, run] of runs) {
+      if (isTerminalStatus(run.status) && runAgeMs(run) >= RUN_TTL_MS) runs.delete(runId);
+    }
+    if (runs.size < MAX_RUNS) return;
+    for (const [runId, run] of runs) {
+      if (!isTerminalStatus(run.status)) continue;
+      runs.delete(runId);
+      if (runs.size < MAX_RUNS) break;
+    }
+  }
+
+  async function loadCodex() {
+    if (!codexModulePromise) codexModulePromise = import('@openai/codex-sdk').catch(error => {
+      const wrapped = new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed in this LiveDesk package.', { status: 503 });
+      wrapped.cause = error;
+      throw wrapped;
+    });
+    return codexModulePromise;
+  }
+
+  function cliPath() {
+    try {
+      return require.resolve('@openai/codex/bin/codex.js');
+    } catch {
+      return '';
+    }
+  }
+
+  async function getStatus() {
+    if (typeof injectedCodexStatus === 'function') return injectedCodexStatus();
+    const pathToCli = cliPath();
+    if (!pathToCli) {
+      return { installed: false, authenticated: 'unknown', status: 'not-installed', codexPath: '' };
+    }
+    let authenticated = 'unknown';
+    let detail = '';
+    try {
+      await prepareCodexHome();
+      const result = await runCli(pathToCli, ['login', 'status'], 5000, safeCodexEnv(codexHome));
+      detail = safeText(result.stdout || result.stderr, 300);
+      authenticated = /logged in|authenticated|chatgpt/i.test(`${result.stdout}\n${result.stderr}`)
+        ? 'signed-in'
+        : 'not-signed-in';
+    } catch (error) {
+      if (error instanceof AgentProviderError) throw error;
+      detail = safeText(error?.message, 300);
+    }
+    return { installed: true, authenticated, status: authenticated === 'signed-in' ? 'ready' : 'auth-required', codexPath: pathToCli, detail };
+  }
+
+  async function testConnection() {
+    assertSecurityConfiguration();
+    const startedAt = Date.now();
+    const status = await getStatus();
+    if (!status.installed) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+    if (status.authenticated !== 'signed-in') throw new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+    const settings = await settingsStore.get();
+    await mkdir(workspace, { recursive: true });
+    await prepareCodexHome();
+    const codex = await createCodexClient({ env: safeCodexEnv(codexHome), config: baseCodexConfig() });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.min(30000, settings.codexTaskTimeoutMs));
+    try {
+      const thread = codex.startThread(codexThreadOptions(settings, workspace));
+      const turn = await thread.run('Reply with the single word READY. Do not use tools.', { signal: controller.signal });
+      if (!String(turn.finalResponse || '').trim()) throw new AgentProviderError('codex-empty-response', 'Codex returned an empty response.', { status: 502 });
+      return { ok: true, modelId: settings.codexModelId || 'Codex default', modelName: settings.codexModelId || 'Codex default', latencyMs: Date.now() - startedAt, threadId: thread.id || '' };
+    } catch (error) {
+      throw normalizeCodexError(error);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function publicRun(run) {
+    return {
+      runId: run.runId,
+      status: run.status,
+      provider: AGENT_PROVIDER_CODEX,
+      instruction: run.instruction,
+      threadId: run.threadId,
+      finalResponse: run.finalResponse,
+      error: run.error,
+      errorMessage: run.errorMessage,
+      errorStage: run.errorStage,
+      stage: run.stage,
+      progressMessage: run.progressMessage,
+      createdAt: run.createdAt,
+      updatedAt: run.updatedAt,
+      toolCallCount: run.toolCallCount,
+      permissionMode: run.permissionPolicy?.mode || 'ask',
+      permissionPolicy: run.permissionPolicy,
+      permissionPolicyHash: run.permissionPolicyHash,
+      batchIds: [...run.batchIds],
+      events: run.events.slice(-MAX_EVENTS)
+    };
+  }
+
+  function emit(run, event) {
+    run.events.push(publicEvent(event));
+    if (run.events.length > MAX_EVENTS) run.events.splice(0, run.events.length - MAX_EVENTS);
+    run.updatedAt = new Date().toISOString();
+    if (event?.type === 'thread.started') run.threadId = safeText(event.thread_id, 120);
+    if (event?.type === 'item.started' || event?.type === 'item.updated' || event?.type === 'item.completed') {
+      if (event.item?.type === 'mcp_tool_call') {
+        run.toolCallCount += event.type === 'item.started' ? 1 : 0;
+        if (event.item?.result?.structured_content?.batchId) run.batchIds.add(event.item.result.structured_content.batchId);
+      }
+    }
+  }
+
+  function promptFor({ instruction, deviceIds, permissionPolicy }) {
+    return [
+      'You are the LiveDesk Agent orchestrator.',
+      'Use only the registered livedesk.* MCP tools exposed by the LiveDesk server.',
+      'Never use arbitrary MCP servers, change permissions, forge approvals, request credentials, or invent a tool result.',
+      `The Hub has fixed this run to permission mode ${permissionPolicy?.mode || 'ask'} and enforces the policy independently of your instructions.`,
+      'Use only the selected connected device IDs below. If the Hub asks for user approval, wait for that approval result and do not work around it.',
+      'You may perform multiple safe read-only checks when the request requires a sequence. For example, find workstations without ComfyUI, then check the service status only on those workstations.',
+      `Selected device IDs: ${JSON.stringify(deviceIds)}`,
+      'Return a concise Korean or English summary grounded only in tool results. Do not invent results.',
+      `User request: ${safeText(instruction, 4000)}`
+    ].join('\n');
+  }
+
+  async function execute(run, input) {
+    activeCount += 1;
+    let session;
+    let timeoutTimer;
+    try {
+      reportProgress(run, 'checking-codex', 'Checking Codex SDK installation and sign-in.');
+      assertSecurityConfiguration();
+      const settings = await settingsStore.get();
+      const timeoutMs = Math.max(1000, Number(settings.codexTaskTimeoutMs) || 600000);
+      timeoutTimer = setTimeout(() => {
+        run.abortReason = 'timeout';
+        run.abortController.abort();
+        try { session?.cancel(); } catch { /* best effort */ }
+      }, timeoutMs);
+      timeoutTimer.unref?.();
+      await mkdir(workspace, { recursive: true });
+      if (activeCount > settings.maxConcurrentRequests) {
+        throw new AgentProviderError('agent-concurrency-limit', 'The LiveDesk Agent concurrency limit is reached.', { status: 429, retryable: true });
+      }
+      if (run.abortController.signal.aborted) {
+        if (run.abortReason === 'timeout') throw codexAbortError('codex-run-timeout', 'The Codex task exceeded its timeout.');
+        throw Object.assign(new Error('The Codex task was cancelled.'), { name: 'AbortError' });
+      }
+      const status = await getStatus();
+      if (!status.installed) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+      if (status.authenticated !== 'signed-in') throw new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+      reportProgress(run, 'preparing-tools', 'Codex is ready. Preparing the LiveDesk tools for this workstation.');
+      session = createMcpSession({
+        runId: run.runId,
+        signal: run.abortController.signal,
+        allowedDeviceIds: input.deviceIds,
+        maxToolCalls: run.permissionPolicy.maxToolCalls,
+        permissionPolicy: run.permissionPolicy,
+        onApprovalRequired: () => {
+          if (run.status === 'running') {
+            run.status = 'waiting-approval';
+            run.updatedAt = new Date().toISOString();
+          }
+        },
+        onApprovalResolved: () => {
+          if (run.status === 'waiting-approval') {
+            run.status = 'running';
+            run.updatedAt = new Date().toISOString();
+          }
+        }
+      });
+      run.mcpToken = session.token;
+      if (run.abortController.signal.aborted) {
+        session.cancel();
+        if (run.abortReason === 'timeout') throw codexAbortError('codex-run-timeout', 'The Codex task exceeded its timeout.');
+        throw Object.assign(new Error('The Codex task was cancelled.'), { name: 'AbortError' });
+      }
+      const threadOptions = codexThreadOptions(settings, workspace);
+      run.status = 'running';
+      run.updatedAt = new Date().toISOString();
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+          await prepareCodexHome({ preferGlobalAuth: attempt > 0 && run.authRecoveryRequested === true });
+          reportProgress(run, 'thinking', attempt === 0 ? 'Codex is analyzing the request.' : 'Codex is retrying the request with a refreshed runtime.');
+          const codex = await createCodexClient({ env: safeCodexEnv(codexHome), config: codexConfig({ mcpServerPath, mcpUrl: session.url, token: session.token, workspace }) });
+          const thread = attempt === 0 && input.resumeThreadId && settings.codexResumeSessions
+            ? codex.resumeThread(String(input.resumeThreadId), threadOptions)
+            : codex.startThread(threadOptions);
+          const streamed = await thread.runStreamed(promptFor({ instruction: run.instruction, deviceIds: input.deviceIds, permissionPolicy: run.permissionPolicy }), { signal: run.abortController.signal });
+          for await (const event of streamed.events) {
+            emit(run, event);
+            if (event.type === 'item.started' && event.item?.type === 'mcp_tool_call') {
+              reportProgress(run, 'tool-running', `Running ${safeText(event.item.tool, 120) || 'a LiveDesk tool'}.`, {
+                toolName: safeText(event.item.tool, 120)
+              });
+            }
+            if (event.type === 'turn.started') {
+              run.turnCount += 1;
+              if (run.turnCount > settings.codexMaxTurns) {
+                run.abortReason = 'turn-limit';
+                run.abortController.abort();
+                session.cancel();
+                throw new AgentProviderError('codex-turn-limit-reached', 'Codex exceeded the LiveDesk turn limit.', { status: 409 });
+              }
+            }
+            if (run.toolCallCount > run.permissionPolicy.maxToolCalls) {
+              run.abortReason = 'tool-limit';
+              run.abortController.abort();
+              session.cancel();
+              throw new AgentProviderError('codex-tool-limit-reached', 'Codex exceeded the LiveDesk tool-call limit.', { status: 409 });
+            }
+            if (event.type === 'item.completed' && event.item?.type === 'mcp_tool_call' && event.item?.status === 'failed') {
+              throw new Error(safeText(event.item?.error?.message, 800) || `LiveDesk tool ${safeText(event.item?.tool, 120) || 'call'} failed.`);
+            }
+            if (event.type === 'item.completed' && event.item?.type === 'agent_message') run.finalResponse = safeText(event.item.text, 4000);
+            if (event.type === 'turn.completed') run.status = 'completed';
+            if (event.type === 'turn.failed') throw new Error(safeText(event.error?.message, 800) || 'Codex run failed.');
+            if (event.type === 'error') throw new Error(safeText(event.message, 800) || 'Codex run failed.');
+          }
+          break;
+        } catch (error) {
+          const normalized = normalizeCodexError(error);
+          const retryBeforeTools = attempt === 0
+            && run.toolCallCount === 0
+            && run.abortController.signal.aborted !== true
+            && normalized.retryable === true;
+          if (!retryBeforeTools) throw normalized;
+          run.authRecoveryRequested = ['codex-auth-stale', 'codex-auth-required'].includes(normalized.code);
+          run.finalResponse = '';
+          run.status = 'running';
+          reportProgress(
+            run,
+            'recovering',
+            `Codex did not start cleanly (${normalized.code}). Refreshing the runtime and retrying once.`,
+            { errorCode: normalized.code, errorMessage: safeText(normalized.message, 500), attempt: 2 }
+          );
+          await new Promise(resolve => setTimeout(resolve, 250));
+        }
+      }
+      if (run.status === 'running') run.status = 'completed';
+    } catch (error) {
+      if (run.abortReason === 'timeout') {
+        run.status = 'failed';
+        run.error = 'codex-run-timeout';
+        run.errorMessage = 'The Codex task exceeded its timeout.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (run.abortReason === 'tool-limit') {
+        run.status = 'failed';
+        run.error = 'codex-tool-limit-reached';
+        run.errorMessage = 'Codex exceeded the LiveDesk tool-call limit.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (run.abortReason === 'turn-limit') {
+        run.status = 'failed';
+        run.error = 'codex-turn-limit-reached';
+        run.errorMessage = 'Codex exceeded the LiveDesk turn limit.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (isAbortError(error) || run.abortController.signal.aborted) {
+        run.status = 'cancelled';
+        run.error = 'cancelled-by-user';
+        run.errorMessage = 'The Codex request was cancelled.';
+        run.errorStage = run.stage || 'unknown';
+      } else {
+        const normalized = normalizeCodexError(error);
+        run.status = 'failed';
+        run.error = safeText(normalized.code, 240) || 'codex-run-failed';
+        run.errorMessage = safeText(normalized.message, 800) || 'Codex run failed.';
+        run.errorStage = run.stage || 'unknown';
+      }
+    } finally {
+      activeCount = Math.max(0, activeCount - 1);
+      if (session) {
+        try { session.cancel(); } catch { /* best effort */ }
+        destroyMcpSession(session.token);
+      }
+      clearTimeout(timeoutTimer);
+      run.updatedAt = new Date().toISOString();
+      reportProgress(
+        run,
+        run.status,
+        run.status === 'completed'
+          ? 'Codex completed the request.'
+          : run.status === 'cancelled'
+            ? 'The Codex request was cancelled.'
+            : `Codex stopped (${run.error || 'codex-run-failed'}): ${run.errorMessage || 'Codex run failed.'}`
+      );
+      if (isTerminalStatus(run.status)) scheduleRunCleanup(run);
+    }
+  }
+
+  async function start(input = {}) {
+    const instruction = safeText(input.instruction, 4000);
+    if (!instruction) throw new AgentProviderError('agent-invalid-instruction', 'Instruction is required.', { status: 400 });
+    const deviceIds = safeAgentDeviceIds(input.deviceIds);
+    if (deviceIds.length === 0) throw new AgentProviderError('agent-no-target-devices', 'Select at least one connected device.', { status: 400 });
+    const settings = await settingsStore.get();
+    if (!settings.enabled) throw new AgentProviderError('agent-ai-disabled', 'Agent AI is disabled in Settings.', { status: 409 });
+    assertSecurityConfiguration();
+    pruneRuns();
+    if (runs.size >= MAX_RUNS) throw new AgentProviderError('agent-run-limit', 'The LiveDesk Agent run history is full.', { status: 429, retryable: true });
+    const permissionPolicy = freezeAgentPermissionPolicy(input.permissionPolicy && typeof input.permissionPolicy === 'object'
+      ? input.permissionPolicy
+      : createAgentPermissionPolicy({ mode: input.permissionMode || 'safe-auto', deviceIds, maxToolCalls: settings.codexMaxToolCalls }));
+    const run = {
+      runId: crypto.randomUUID(),
+      status: 'queued',
+      provider: AGENT_PROVIDER_CODEX,
+      instruction,
+      deviceIds,
+      threadId: '',
+      finalResponse: '',
+      error: '',
+      errorMessage: '',
+      errorStage: '',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      toolCallCount: 0,
+      turnCount: 0,
+      permissionPolicy,
+      permissionPolicyHash: hashAgentPermissionPolicy(permissionPolicy),
+      batchIds: new Set(),
+      events: [],
+      abortController: new AbortController(),
+      abortReason: '',
+      authRecoveryRequested: false,
+      stage: 'queued',
+      progressMessage: '',
+      mcpToken: ''
+    };
+    runs.set(run.runId, run);
+    reportProgress(run, 'queued', 'Codex request queued on the Hub.');
+    void execute(run, { deviceIds, resumeThreadId: input.resumeThreadId });
+    return publicRun(run);
+  }
+
+  function get(runId) {
+    const run = runs.get(String(runId || ''));
+    return run ? publicRun(run) : null;
+  }
+
+  function cancel(runId) {
+    const run = runs.get(String(runId || ''));
+    if (!run) return null;
+    if (isTerminalStatus(run.status)) return publicRun(run);
+    run.abortReason = 'user';
+    run.abortController.abort();
+    run.status = 'cancelled';
+    run.error = 'cancelled-by-user';
+    run.updatedAt = new Date().toISOString();
+    return publicRun(run);
+  }
+
+  function cancelAll() {
+    let cancelled = 0;
+    for (const run of runs.values()) {
+      if (!isTerminalStatus(run.status)) {
+        cancel(run.runId);
+        cancelled += 1;
+      }
+    }
+    return cancelled;
+  }
+
+  return { getStatus, testConnection, start, get, cancel, cancelAll, workspace, codexHome, getSecurityStatus: securityStatus };
+}