@gakim-digital/dexter-bridge 0.5.0

package/src/agent.js

@@ -0,0 +1,998 @@
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { postRunEvent } from './api.js';
+import { createCompanionUsageAccumulator, parseAgentOutput } from './agentOutput.js';
+import {
+  DEFAULT_BRIDGE_AGENT,
+  companionModelDefinition,
+  companionModelsForAgent,
+  normalizeAgentName,
+  normalizeCompanionModelName,
+} from './config.js';
+import {
+  buildModelTurnPrompt,
+  extractJsonObject,
+  normalizeModelTurnCompletion,
+  runSummary,
+} from './protocol.js';
+import {
+  clip,
+  createRunLogger,
+  errorMeta,
+  logLocationHint,
+  summarizePayload,
+  summarizeToolResult,
+} from './logger.js';
+import { createLocalAgentAdapter } from './providers/index.js';
+
+export const AGENT_DEFINITIONS = {
+  'claude-code': {
+    id: 'claude-code',
+    label: 'Claude Code',
+    commandEnv: 'DEXTER_BRIDGE_CLAUDE_BIN',
+    fallbackCommand: 'claude',
+    argsEnv: 'DEXTER_BRIDGE_CLAUDE_ARGS',
+    defaultArgs: '-p',
+    promptMode: 'stdin',
+    model: 'claude-code:sonnet',
+    statusStage: 'claude_start',
+  },
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    commandEnv: 'DEXTER_BRIDGE_CODEX_BIN',
+    fallbackCommand: 'codex',
+    argsEnv: 'DEXTER_BRIDGE_CODEX_ARGS',
+    defaultArgs: 'exec --sandbox read-only --skip-git-repo-check',
+    promptMode: 'stdin',
+    model: 'codex:gpt-5.5',
+    statusStage: 'codex_start',
+  },
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function createEventPoster({ apiBaseUrl, deviceToken, run, fetchImpl, trace }) {
+  return async function send(type, payload = {}) {
+    const eventId = `${type}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const started = Date.now();
+    trace?.info('event_post_start', {
+      type,
+      eventId,
+      payload: summarizePayload(payload),
+    });
+    try {
+      const response = await postRunEvent(apiBaseUrl, {
+        deviceToken,
+        runId: run.runId,
+        fetchImpl,
+        event: {
+          type,
+          eventId,
+          payload,
+        },
+      });
+      trace?.info('event_post_done', {
+        type,
+        eventId,
+        durationMs: Date.now() - started,
+        accepted: response?.accepted,
+        status: response?.status,
+        hasToolResult: Boolean(response?.toolResult),
+        toolResult: summarizeToolResult(response?.toolResult),
+      });
+      return response;
+    } catch (error) {
+      trace?.error('event_post_failed', {
+        type,
+        eventId,
+        durationMs: Date.now() - started,
+        error: errorMeta(error),
+      });
+      throw error;
+    }
+  };
+}
+
+function commandFromEnv(name, fallback, env = process.env) {
+  return env[name] || fallback;
+}
+
+function parseExtraArgs(value, fallback = '') {
+  const source = value === undefined || value === null || value === '' ? fallback : value;
+  if (!source) return [];
+  return String(source).split(/\s+/).map((item) => item.trim()).filter(Boolean);
+}
+
+function argsAlreadySelectModel(args) {
+  return args.some((arg) => arg === '--model' || arg === '-m' || arg.startsWith('--model='));
+}
+
+function argsIncludeFlag(args, flag) {
+  return args.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+}
+
+function structuredUsageEnabled(env = process.env) {
+  return String(env.DEXTER_BRIDGE_STRUCTURED_USAGE || 'true').trim().toLowerCase() !== 'false';
+}
+
+function argsWithRequiredAgentFlags(args, definition) {
+  if (definition.id !== 'codex') return args;
+  if (argsIncludeFlag(args, '--skip-git-repo-check')) return args;
+  return [...args, '--skip-git-repo-check'];
+}
+
+const CLAUDE_CLI_MODEL_IDS = {
+  fable: 'claude-fable-5',
+  opus: 'claude-opus-4-8',
+  sonnet: 'claude-sonnet-5',
+  haiku: 'claude-haiku-4-5-20251001',
+};
+
+export function mapClaudeCliModelId(value) {
+  const raw = String(value || '').trim();
+  return CLAUDE_CLI_MODEL_IDS[raw.toLowerCase()] || raw;
+}
+
+function argsWithSelectedModel(args, modelDefinition, definition) {
+  if (!modelDefinition?.invocationName || modelDefinition.invocationName === 'dry-run') return args;
+  if (argsAlreadySelectModel(args)) return args;
+  const invocationName = definition.id === 'claude-code'
+    ? mapClaudeCliModelId(modelDefinition.invocationName)
+    : modelDefinition.invocationName;
+  return [...args, '--model', invocationName];
+}
+
+function argsWithStructuredOutput(args, definition, env = process.env) {
+  if (!structuredUsageEnabled(env)) return args;
+  if (definition.id === 'claude-code') {
+    return argsIncludeFlag(args, '--output-format') ? args : [...args, '--output-format', 'json'];
+  }
+  if (definition.id === 'codex') {
+    return argsIncludeFlag(args, '--json') ? args : [...args, '--json'];
+  }
+  return args;
+}
+
+function argsWithPromptInput(args, definition) {
+  if (definition.id !== 'codex' || args.includes('-')) return args;
+  return [...args, '-'];
+}
+
+function argsWithResumedSession(args, definition, sessionId) {
+  if (!sessionId) return args;
+  if (definition.id === 'claude-code') {
+    const withoutExistingResume = [];
+    for (let index = 0; index < args.length; index += 1) {
+      if (args[index] === '--resume' || args[index] === '-r' || args[index] === '--session-id') {
+        index += 1;
+        continue;
+      }
+      withoutExistingResume.push(args[index]);
+    }
+    return [...withoutExistingResume, '--resume', sessionId];
+  }
+  if (definition.id !== 'codex') return args;
+
+  const resumeArgs = ['exec', 'resume'];
+  const optionsWithValues = new Set([
+    '--config',
+    '-c',
+    '--enable',
+    '--disable',
+    '--model',
+    '-m',
+    '--profile',
+    '-p',
+    '--output-schema',
+    '--output-last-message',
+    '-o',
+  ]);
+  const initialOnlyWithValues = new Set(['--sandbox', '-s', '--cd', '-C', '--add-dir', '--image', '-i']);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === 'exec' || arg === 'resume' || arg === '-' || arg === '--ephemeral') continue;
+    if (initialOnlyWithValues.has(arg)) {
+      index += 1;
+      continue;
+    }
+    resumeArgs.push(arg);
+    if (optionsWithValues.has(arg) && index + 1 < args.length) {
+      resumeArgs.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return [...resumeArgs, sessionId, '-'];
+}
+
+function agentSessionResumeEnabled(definition, env = process.env) {
+  if (String(env.DEXTER_BRIDGE_SESSION_RESUME || 'true').trim().toLowerCase() === 'false') return false;
+  const baseArgs = parseExtraArgs(env[definition.argsEnv], definition.defaultArgs);
+  if (definition.id === 'claude-code' && argsIncludeFlag(baseArgs, '--no-session-persistence')) return false;
+  if (definition.id === 'codex' && argsIncludeFlag(baseArgs, '--ephemeral')) return false;
+  return true;
+}
+
+export function buildAgentArgs(definition, modelDefinition, env = process.env, options = {}) {
+  const baseArgs = parseExtraArgs(env[definition.argsEnv], definition.defaultArgs);
+  const requiredArgs = argsWithRequiredAgentFlags(baseArgs, definition);
+  const modelArgs = argsWithSelectedModel(requiredArgs, modelDefinition, definition);
+  const structuredArgs = argsWithStructuredOutput(modelArgs, definition, env);
+  const resumedArgs = argsWithResumedSession(structuredArgs, definition, options.resumeSessionId);
+  return argsWithPromptInput(resumedArgs, definition);
+}
+
+export function parseEnvOutput(output) {
+  const result = {};
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const index = line.indexOf('=');
+    if (index <= 0) continue;
+    const key = line.slice(0, index);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    result[key] = line.slice(index + 1);
+  }
+  return result;
+}
+
+let cachedLoginShellEnv;
+let cachedLoginShellEnvMeta = { attempted: false, loaded: false, keys: 0 };
+
+function loginShellEnv() {
+  if (process.env.DEXTER_BRIDGE_DISABLE_LOGIN_SHELL_ENV === '1' || process.platform === 'win32') {
+    cachedLoginShellEnvMeta = { attempted: false, loaded: false, keys: 0, disabled: true };
+    return {};
+  }
+  if (cachedLoginShellEnv) return cachedLoginShellEnv;
+  cachedLoginShellEnvMeta = { attempted: true, loaded: false, keys: 0 };
+  const shell = process.env.SHELL || '/bin/zsh';
+  const shellArgVariants = [
+    ['-lic', 'env'],
+    ['-lc', 'env'],
+  ];
+  try {
+    let output = '';
+    let usedArgs = shellArgVariants[0];
+    let lastError;
+    for (const args of shellArgVariants) {
+      try {
+        output = execFileSync(shell, args, {
+          encoding: 'utf8',
+          env: process.env,
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 3000,
+        });
+        usedArgs = args;
+        lastError = undefined;
+        break;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (lastError) throw lastError;
+    cachedLoginShellEnv = parseEnvOutput(output);
+    cachedLoginShellEnvMeta = {
+      attempted: true,
+      loaded: true,
+      shell,
+      shellArgs: usedArgs.join(' '),
+      keys: Object.keys(cachedLoginShellEnv).length,
+    };
+    return cachedLoginShellEnv;
+  } catch (error) {
+    cachedLoginShellEnv = {};
+    cachedLoginShellEnvMeta = {
+      attempted: true,
+      loaded: false,
+      shell,
+      keys: 0,
+      error: error?.message || String(error || ''),
+    };
+    return cachedLoginShellEnv;
+  }
+}
+
+export function mergePathEntries(paths, platform = process.platform) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  return paths
+    .flatMap((value) => String(value || '').split(delimiter))
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .filter((item, index, list) => list.indexOf(item) === index)
+    .join(delimiter);
+}
+
+function processEnvWithCliPath(platform = process.platform) {
+  const fallbackPath = platform === 'win32'
+    ? [path.join(process.env.APPDATA || '', 'npm'), path.join(process.env.LOCALAPPDATA || '', 'Programs')]
+    : ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  const shellEnv = loginShellEnv();
+  const existingPath = String(process.env.PATH || '');
+  const mergedPath = mergePathEntries([shellEnv.PATH, existingPath, ...fallbackPath], platform);
+  return {
+    ...shellEnv,
+    ...process.env,
+    PATH: mergedPath,
+  };
+}
+
+export function resolveAgentCwd(env = process.env, currentWorkingDirectory = process.cwd(), platform = process.platform) {
+  const explicit = String(env.DEXTER_BRIDGE_AGENT_CWD || env.DEXTER_BRIDGE_WORKDIR || '').trim();
+  if (explicit) return explicit;
+  const pathApi = platform === 'win32' ? path.win32 : path.posix;
+  const root = currentWorkingDirectory ? pathApi.parse(currentWorkingDirectory).root : '';
+  if (currentWorkingDirectory && currentWorkingDirectory !== root) return currentWorkingDirectory;
+  return os.homedir() || currentWorkingDirectory || root || '/';
+}
+
+function processEnvSummary(env, platform = process.platform) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathEntries = String(env.PATH || '').split(delimiter).filter(Boolean);
+  return {
+    hasAzureOpenAiApiKey: Boolean(env.AZURE_OPENAI_API_KEY),
+    hasOpenAiApiKey: Boolean(env.OPENAI_API_KEY),
+    hasAnthropicApiKey: Boolean(env.ANTHROPIC_API_KEY),
+    hasShell: Boolean(env.SHELL),
+    pathEntryCount: pathEntries.length,
+    pathHead: pathEntries.slice(0, 8),
+    loginShellEnv: cachedLoginShellEnvMeta,
+  };
+}
+
+export function executableCandidates(command, env = process.env, platform = process.platform, existsSync = fs.existsSync) {
+  const raw = String(command || '').trim();
+  if (!raw) return [];
+  if (/[\\/]/.test(raw)) return [raw];
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const pathApi = platform === 'win32' ? path.win32 : path.posix;
+  const pathEntries = String(env.PATH || '').split(delimiter).filter(Boolean);
+  const extensions = platform === 'win32'
+    ? path.win32.extname(raw)
+      ? ['']
+      : String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+  const candidates = [];
+  for (const directory of pathEntries) {
+    for (const extension of extensions) {
+      const candidate = pathApi.join(directory, `${raw}${extension.toLowerCase()}`);
+      if (existsSync(candidate)) candidates.push(candidate);
+      if (platform === 'win32') {
+        const upperCandidate = path.win32.join(directory, `${raw}${extension.toUpperCase()}`);
+        if (upperCandidate !== candidate && existsSync(upperCandidate)) candidates.push(upperCandidate);
+      }
+    }
+  }
+  return [...new Set(candidates.length ? candidates : [raw])];
+}
+
+export function resolveExecutableCommand(command, env = process.env, platform = process.platform, existsSync = fs.existsSync) {
+  return executableCandidates(command, env, platform, existsSync)[0] || String(command || '').trim();
+}
+
+export function parseAgentVersion(output) {
+  const match = String(output || '').match(/(?:^|[^\d])v?(\d+)\.(\d+)\.(\d+)(?:[^\d]|$)/i);
+  return match ? `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}` : null;
+}
+
+function versionParts(value) {
+  const match = String(value || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+export function compareAgentVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (!a && !b) return 0;
+  if (!a) return -1;
+  if (!b) return 1;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+export function modelSupportsAgentVersion(modelDefinition, version) {
+  if (!modelDefinition?.minimumAgentVersion) return true;
+  return compareAgentVersions(version, modelDefinition.minimumAgentVersion) >= 0;
+}
+
+export function selectAgentRuntime(inspections, definition, modelDefinition) {
+  const successful = inspections.filter((inspection) => inspection?.ok);
+  if (!successful.length) {
+    const first = inspections[0];
+    return {
+      ok: false,
+      command: first?.command || definition.fallbackCommand,
+      error: first?.error || `${definition.label} is not installed or could not be started.`,
+      candidates: inspections,
+    };
+  }
+
+  const ranked = successful
+    .map((inspection, index) => ({ ...inspection, discoveryIndex: index }))
+    .sort((left, right) => compareAgentVersions(right.version, left.version) || left.discoveryIndex - right.discoveryIndex);
+  const compatible = ranked.find((inspection) => modelSupportsAgentVersion(modelDefinition, inspection.version));
+  if (compatible) {
+    return {
+      ...compatible,
+      ok: true,
+      candidates: inspections,
+    };
+  }
+
+  const found = ranked[0];
+  const requiredVersion = modelDefinition?.minimumAgentVersion;
+  const modelLabel = modelDefinition?.displayName || modelDefinition?.id || 'The selected model';
+  const foundVersion = found.version || 'an unknown version';
+  return {
+    ...found,
+    ok: false,
+    code: 'DEXTER_AGENT_MODEL_VERSION_UNSUPPORTED',
+    error: `${modelLabel} requires ${definition.label} ${requiredVersion} or newer. Dexter found ${foundVersion} at ${found.command}. Update ${definition.label} or set ${definition.commandEnv} to the full path of a compatible installation.`,
+    candidates: inspections,
+  };
+}
+
+function quoteWindowsCommandArg(value) {
+  return `"${String(value).replace(/%/g, '%%').replace(/(["^&|<>])/g, '^$1')}"`;
+}
+
+export function processInvocation(command, args, env = process.env, platform = process.platform) {
+  const resolvedCommand = resolveExecutableCommand(command, env, platform);
+  if (platform === 'win32' && /\.(cmd|bat)$/i.test(resolvedCommand)) {
+    const commandLine = [resolvedCommand, ...args].map(quoteWindowsCommandArg).join(' ');
+    return {
+      command: env.ComSpec || env.COMSPEC || 'cmd.exe',
+      args: ['/d', '/s', '/c', commandLine],
+      resolvedCommand,
+      windowsHide: true,
+    };
+  }
+  return { command: resolvedCommand, args, resolvedCommand, windowsHide: platform === 'win32' };
+}
+
+function safeCommandArgs(args) {
+  return args.map((arg) => {
+    const text = String(arg);
+    if (text.length > 300) return `[long-arg ${text.length} chars]`;
+    return text;
+  });
+}
+
+function normalizeDiagnosticLine(line) {
+  return String(line || '')
+    .trim()
+    .replace(/^ERROR:\s*/i, '')
+    .replace(/\s+/g, ' ');
+}
+
+export function agentFailureMessage(command, code, stdout = '', stderr = '') {
+  const combined = [stderr, stdout].filter(Boolean).join('\n').trim();
+  const lines = combined
+    .split(/\r?\n/)
+    .map(normalizeDiagnosticLine)
+    .filter(Boolean);
+  const diagnosticPatterns = [
+    /missing environment variable/i,
+    /not inside a trusted directory/i,
+    /api key/i,
+    /authentication/i,
+    /unauthorized/i,
+    /permission denied/i,
+    /command not found/i,
+    /not found/i,
+    /rate limit/i,
+    /timed out/i,
+    /^failed\b/i,
+  ];
+  const diagnostics = lines.filter((line) => diagnosticPatterns.some((pattern) => pattern.test(line)));
+  const detail = diagnostics.length
+    ? diagnostics.slice(-3).join(' ')
+    : clip(combined, 1000);
+  return `${command} exited with code ${code}.${detail ? ` ${clip(detail, 1000)}` : ''}`.trim();
+}
+
+function runProcess(command, args, stdin, {
+  timeoutMs = 120000,
+  trace,
+  childEnv: providedChildEnv,
+  platform = process.platform,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const childEnv = providedChildEnv || processEnvWithCliPath(platform);
+    const cwd = resolveAgentCwd(childEnv, process.cwd(), platform);
+    const invocation = processInvocation(command, args, childEnv, platform);
+    trace?.info('agent_process_spawn', {
+      command,
+      resolvedCommand: invocation.resolvedCommand,
+      args: safeCommandArgs(args),
+      cwd,
+      env: processEnvSummary(childEnv),
+      stdinChars: stdin.length,
+      timeoutMs,
+    });
+    const child = spawn(invocation.command, invocation.args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: childEnv,
+      cwd,
+      windowsHide: invocation.windowsHide,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill('SIGTERM');
+      const error = new Error(`${command} timed out after ${timeoutMs}ms.`);
+      trace?.error('agent_process_timeout', {
+        command,
+        durationMs: Date.now() - started,
+        timeoutMs,
+        stdoutChars: stdout.length,
+        stderrChars: stderr.length,
+        stdoutExcerpt: clip(stdout, 1000),
+        stderrExcerpt: clip(stderr, 1000),
+      });
+      reject(error);
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString('utf8');
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf8');
+    });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      trace?.error('agent_process_error', {
+        command,
+        durationMs: Date.now() - started,
+        error: errorMeta(error),
+      });
+      reject(error);
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const meta = {
+        command,
+        code,
+        durationMs: Date.now() - started,
+        stdoutChars: stdout.length,
+        stderrChars: stderr.length,
+        stdoutExcerpt: clip(stdout, 2000),
+        stderrExcerpt: clip(stderr, 2000),
+      };
+      if (code === 0) {
+        trace?.info('agent_process_exit', meta);
+        resolve({ stdout, stderr, code });
+        return;
+      }
+      const failureMessage = agentFailureMessage(command, code, stdout, stderr);
+      trace?.error('agent_process_exit_nonzero', { ...meta, failureMessage });
+      const error = new Error(failureMessage);
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.exitCode = code;
+      reject(error);
+    });
+
+    child.stdin.end(stdin);
+  });
+}
+
+function definitionForAgent(agent) {
+  return AGENT_DEFINITIONS[normalizeAgentName(agent)] || AGENT_DEFINITIONS[DEFAULT_BRIDGE_AGENT];
+}
+
+function adapterSessionId(run) {
+  return run?.turnId || run?.runId;
+}
+
+function adapterInvocationModel(run, selectedModel, agent) {
+  const explicit = run?.companion?.model?.invocationName;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  if (selectedModel?.invocationName) return selectedModel.invocationName;
+  const id = run?.companion?.model?.id || run?.model;
+  const raw = typeof id === 'string' ? id.trim() : '';
+  const prefix = `${normalizeAgentName(agent)}:`;
+  return raw.startsWith(prefix) ? raw.slice(prefix.length) : raw || undefined;
+}
+
+function controlRequestsCancellation(response) {
+  return Boolean(
+    response?.control?.cancelRequested
+    || response?.status === 'cancelled'
+    || response?.status === 'expired',
+  );
+}
+
+function boundedDurationMs(value, fallback, minimum = 10, maximum = 60 * 60 * 1000) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(minimum, Math.min(maximum, parsed));
+}
+
+function waitForControl(delayMs, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason || new Error('Control monitor stopped.'));
+      return;
+    }
+    const timer = setTimeout(resolve, delayMs);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason || new Error('Control monitor stopped.'));
+    }, { once: true });
+  });
+}
+
+class CompanionRunCancelledError extends Error {
+  constructor(message = 'The Dexter companion model turn was cancelled.') {
+    super(message);
+    this.name = 'CompanionRunCancelledError';
+    this.code = 'RUN_CANCELLED';
+  }
+}
+
+async function callProviderAdapter(adapter, input, {
+  send,
+  trace,
+  controlPollMs = 5000,
+} = {}) {
+  if (!adapter || typeof adapter.runModelTurn !== 'function') {
+    throw new Error('The selected provider adapter cannot execute model turns.');
+  }
+  const monitorAbort = new AbortController();
+  let finished = false;
+  let cancelRequested = false;
+  let cancelSent = false;
+
+  async function requestCancel() {
+    cancelRequested = true;
+    if (cancelSent) return;
+    cancelSent = true;
+    await adapter.cancel?.(input.sessionId);
+  }
+
+  async function monitorControl() {
+    while (!finished && !monitorAbort.signal.aborted) {
+      try {
+        await waitForControl(controlPollMs, monitorAbort.signal);
+        if (finished || monitorAbort.signal.aborted) return;
+        const response = await send('activity', {
+          stage: 'model_turn',
+          message: `${adapter.label || adapter.id || 'Provider'} is still generating the next Dexter action.`,
+        });
+        if (controlRequestsCancellation(response)) await requestCancel();
+      } catch (error) {
+        if (monitorAbort.signal.aborted) return;
+        trace?.warn('adapter_control_poll_failed', { error: errorMeta(error) });
+      }
+    }
+  }
+
+  const controlMonitor = monitorControl();
+  try {
+    const result = await adapter.runModelTurn(input);
+    if (cancelRequested) throw new CompanionRunCancelledError();
+    return result;
+  } catch (error) {
+    if (cancelRequested) throw new CompanionRunCancelledError();
+    throw error;
+  } finally {
+    finished = true;
+    monitorAbort.abort();
+    await controlMonitor.catch(() => undefined);
+  }
+}
+
+export async function resolveAgentRuntime(definition, modelDefinition, options = {}) {
+  const platform = options.platform || process.platform;
+  const childEnv = options.env || processEnvWithCliPath(platform);
+  const configuredCommand = commandFromEnv(definition.commandEnv, definition.fallbackCommand, childEnv);
+  const candidates = executableCandidates(
+    configuredCommand,
+    childEnv,
+    platform,
+    options.existsSync || fs.existsSync,
+  );
+  const inspect = options.inspect || (async (command) => {
+    try {
+      const result = await runProcess(command, ['--version'], '', {
+        timeoutMs: 10000,
+        childEnv,
+        platform,
+      });
+      const output = (result.stdout || result.stderr || '').trim();
+      return {
+        ok: true,
+        command,
+        output,
+        version: parseAgentVersion(output),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        command,
+        error: error?.message || String(error || ''),
+      };
+    }
+  });
+  const inspections = await Promise.all(candidates.map((candidate) => inspect(candidate)));
+  return selectAgentRuntime(inspections, definition, modelDefinition);
+}
+
+async function callLocalJsonAgent(agent, prompt, options = {}) {
+  const definition = definitionForAgent(agent);
+  const command = options.runtime?.command || commandFromEnv(definition.commandEnv, definition.fallbackCommand);
+  const modelDefinition = companionModelDefinition(options.model, definition.id);
+  const args = buildAgentArgs(definition, modelDefinition, process.env, {
+    resumeSessionId: options.resumeSessionId,
+  });
+  const timeoutMs = options.timeoutMs || Number(process.env.DEXTER_BRIDGE_AGENT_TIMEOUT_MS || 120000);
+  options.trace?.info('agent_step_invoke', {
+    agent: definition.id,
+    command,
+    model: modelDefinition?.id,
+    invocationModel: modelDefinition?.invocationName,
+    resolvedCommand: command,
+    agentVersion: options.runtime?.version,
+    promptMode: definition.promptMode,
+    promptChars: prompt.length,
+    resumeSessionId: options.resumeSessionId,
+    timeoutMs,
+  });
+  return runProcess(command, args, prompt, {
+    timeoutMs,
+    trace: options.trace,
+  });
+}
+
+async function executeModelTurnRun(run, send, agent, options = {}) {
+  if (normalizeAgentName(agent) === 'dry-run') {
+    await send('done', {
+      operationType: 'chat',
+      outcome: 'answer',
+      completion: {
+        text: 'Dry-run model turn completed.',
+        toolCalls: [],
+        finishReason: 'stop',
+        model: 'dexter-bridge-dry-run',
+      },
+      tokenUsage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+      model: 'dexter-bridge-dry-run',
+    });
+    return;
+  }
+  const definition = definitionForAgent(agent);
+  const requestedModel = run?.companion?.model?.id || run?.model || options.selectedModel;
+  const selectedModel = companionModelDefinition(requestedModel, definition.id);
+  const selectedModelId = typeof requestedModel === 'string' && requestedModel.trim()
+    ? requestedModel.trim()
+    : selectedModel?.id || definition.model;
+  const adapter = options.providerAdapter || null;
+  const prompt = buildModelTurnPrompt(run.modelTurn);
+  const statusResponse = await send('status', {
+    stage: 'model_turn',
+    message: `${definition.label} is generating the next Dexter action.`,
+  });
+  if (controlRequestsCancellation(statusResponse)) {
+    if (adapter) await adapter.cancel?.(adapterSessionId(run));
+    throw new CompanionRunCancelledError();
+  }
+  const usageAccumulator = createCompanionUsageAccumulator(definition.id);
+  let resultText;
+  if (adapter) {
+    const sessionId = adapterSessionId(run);
+    const invocationModel = adapterInvocationModel(run, selectedModel, definition.id);
+    options.trace?.info('agent_adapter_invoke', {
+      adapter: adapter.id,
+      agent: definition.id,
+      sessionId,
+      model: selectedModelId,
+      invocationModel,
+      promptChars: prompt.length,
+    });
+    const result = await callProviderAdapter(adapter, {
+      runId: run.runId,
+      sessionId,
+      prompt,
+      model: invocationModel,
+      timeoutMs: boundedDurationMs(
+        options.timeoutMs ?? options.env?.DEXTER_BRIDGE_AGENT_TIMEOUT_MS,
+        120000,
+        1000,
+      ),
+    }, {
+      send,
+      trace: options.trace,
+      controlPollMs: boundedDurationMs(
+        options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
+        5000,
+        10,
+        30000,
+      ),
+    });
+    usageAccumulator.add(result);
+    resultText = result?.text;
+  } else {
+    const runtime = await resolveAgentRuntime(definition, selectedModel, {
+      env: options.env,
+    });
+    if (!runtime.ok) {
+      throw new Error(runtime.error || `${definition.label} is not available.`);
+    }
+    const result = await callLocalJsonAgent(definition.id, prompt, {
+      ...options,
+      model: selectedModelId,
+      runtime,
+    });
+    const parsed = parseAgentOutput(definition.id, result.stdout);
+    usageAccumulator.add(parsed);
+    resultText = parsed.resultText;
+  }
+  const completion = normalizeModelTurnCompletion(
+    extractJsonObject(resultText),
+    selectedModelId,
+  );
+  await send('done', {
+    operationType: 'chat',
+    outcome: 'answer',
+    completion,
+    model: selectedModelId,
+    ...usageAccumulator.snapshot(),
+  });
+}
+
+export async function executeRun(run, {
+  apiBaseUrl,
+  deviceToken,
+  agent = process.env.DEXTER_BRIDGE_AGENT || DEFAULT_BRIDGE_AGENT,
+  fetchImpl,
+  log = console.log,
+  logDir,
+  selectedModel,
+  providerAdapter,
+  adapterOptions,
+  env = process.env,
+  controlPollMs,
+} = {}) {
+  if (!run?.runId) throw new Error('Companion run payload is missing runId.');
+  if (run?.protocol?.version !== 'dexter-companion-v4') {
+    throw new Error(`Unsupported Dexter Companion protocol ${run.protocol.version}. Update Dexter Bridge and reconnect.`);
+  }
+  if (run?.kind !== 'model_turn' || run?.protocol?.mode !== 'model_turn') {
+    throw new Error('Dexter Companion v4 only accepts server-owned model_turn runs.');
+  }
+  const writeLine = (message) => {
+    if (typeof log !== 'function') return;
+    if (log.length >= 3) log('info', 'run_message', { message });
+    else log(message);
+  };
+  const trace = createRunLogger({ runId: run.runId, logDir, mirror: log });
+  const send = createEventPoster({ apiBaseUrl, deviceToken, run, fetchImpl, trace });
+  const normalizedAgent = normalizeAgentName(run?.companion?.agent || agent);
+  const runModel = run?.companion?.model?.id || run?.model || selectedModel;
+  const usageAccumulator = createCompanionUsageAccumulator(normalizedAgent);
+  const adapterProvided = providerAdapter !== undefined;
+  const activeAdapter = adapterProvided
+    ? providerAdapter
+    : createLocalAgentAdapter(normalizedAgent, {
+      ...adapterOptions,
+      env: adapterOptions?.env || env,
+      trace,
+    });
+  const ownsAdapter = !adapterProvided && Boolean(activeAdapter);
+  if (
+    activeAdapter?.id
+    && activeAdapter.id !== normalizedAgent
+  ) {
+    if (ownsAdapter) activeAdapter.close?.();
+    throw new Error(`Provider adapter ${activeAdapter.id} cannot execute ${normalizedAgent} runs.`);
+  }
+  writeLine(`Running Dexter companion run ${run.runId} (${normalizedAgent}, ${runModel || 'default model'}).`);
+  writeLine(`Dexter Bridge run log: ${trace.filePath || logLocationHint(logDir)}`);
+  trace.info('run_start', {
+    apiBaseUrl,
+    agent: normalizedAgent,
+    model: runModel || null,
+    summary: runSummary(run),
+    logFile: trace.filePath,
+  });
+
+  try {
+    await executeModelTurnRun(run, send, normalizedAgent, {
+      model: runModel || selectedModel,
+      selectedModel: runModel || selectedModel,
+      providerAdapter: activeAdapter,
+      trace,
+      env,
+      controlPollMs,
+    });
+    trace.info('run_done', { status: 'model_turn_sent' });
+    return { cancelled: false };
+  } catch (error) {
+    if (error?.code === 'RUN_CANCELLED') {
+      trace.info('run_cancelled', { message: error.message });
+      await send('error', {
+        operationType: 'cancelled',
+        outcome: 'cancelled',
+        message: error.message,
+        code: 'RUN_CANCELLED',
+      }).catch(() => undefined);
+      return { cancelled: true };
+    }
+    trace.error('run_failed', { error: errorMeta(error) });
+    await send('error', {
+      stage: 'agent',
+      message: error?.message || 'Local Companion failed.',
+      code: error?.code,
+      ...(error?.companionUsage || usageAccumulator.snapshot()),
+    }).catch(() => undefined);
+    throw error;
+  } finally {
+    if (ownsAdapter) activeAdapter?.close?.();
+  }
+}
+
+export function checkCommand(command, args = ['--version'], timeoutMs = 10000) {
+  return runProcess(command, args, '', { timeoutMs })
+    .then((result) => ({ ok: true, command, output: (result.stdout || result.stderr || '').trim() }))
+    .catch((error) => ({ ok: false, command, error: error.message }));
+}
+
+export async function checkAgentAvailability(agent, model, options = {}) {
+  const normalizedAgent = normalizeAgentName(agent);
+  if (normalizedAgent === 'dry-run') {
+    return {
+      ok: true,
+      agent: 'dry-run',
+      label: 'Dry run',
+      command: 'dry-run',
+      output: 'debug mode',
+      models: ['dry-run:default'],
+    };
+  }
+  const definition = definitionForAgent(normalizedAgent);
+  const selectedModel = model ? companionModelDefinition(model?.id || model, normalizedAgent) : undefined;
+  const runtime = await resolveAgentRuntime(definition, selectedModel, {
+    env: options.env,
+  });
+  const supportedModels = companionModelsForAgent(normalizedAgent)
+    .filter((candidate) => modelSupportsAgentVersion(candidate, runtime.version))
+    .map((candidate) => candidate.id);
+  return {
+    ...runtime,
+    agent: definition.id,
+    label: definition.label,
+    models: supportedModels,
+  };
+}
+
+export async function checkAllAgents(options = {}) {
+  const agents = await Promise.all([
+    checkAgentAvailability('claude-code', undefined, options),
+    checkAgentAvailability('codex', undefined, options),
+  ]);
+  return {
+    agents,
+    dryRun: {
+      ok: true,
+      agent: 'dry-run',
+      label: 'Dry run',
+      command: 'dry-run',
+      output: 'debug mode',
+      models: ['dry-run:default'],
+    },
+  };
+}