@gakim-digital/dexter-bridge 0.5.0

package/src/cli.js

@@ -0,0 +1,337 @@
+import os from 'node:os';
+import readline from 'node:readline/promises';
+import {
+  BRIDGE_CAPABILITIES,
+  clearConfig,
+  defaultConfigDir,
+  normalizeAgentName,
+  readConfig,
+  resolveAgentName,
+  resolveApiBaseUrl,
+  resolveCompanionModelName,
+  saveConfigPatch,
+} from './config.js';
+import { checkAllAgents, executeRun } from './agent.js';
+import { claimPairing, heartbeat, pollRun } from './api.js';
+import {
+  createRunLogger,
+  errorMeta,
+  logLocationHint,
+} from './logger.js';
+import { createLocalAgentAdapter } from './providers/index.js';
+
+function usage() {
+  return [
+    'Dexter Bridge',
+    '',
+    'Usage:',
+    '  dexter-bridge connect [code-or-token] [--agent claude-code|codex|dry-run] [--model <model>] [--once] [--api <url>]',
+    '  dexter-bridge pair <code-or-token> [--api <url>]',
+    '  dexter-bridge start [--agent claude-code|codex|dry-run] [--model <model>] [--once] [--api <url>]',
+    '  dexter-bridge status [--api <url>]',
+    '  dexter-bridge doctor',
+    '  dexter-bridge logout',
+    '',
+    'Environment:',
+    '  DEXTER_API_URL              API base URL, e.g. https://api.example.com/iwm-api/0.0.1',
+    '  DEXTER_BRIDGE_AGENT         claude-code, codex, or dry-run',
+    '  DEXTER_BRIDGE_MODEL         Companion model, e.g. claude-code:sonnet or codex:gpt-5.5',
+    '  DEXTER_BRIDGE_CLAUDE_BIN    Claude CLI binary name/path',
+    '  DEXTER_BRIDGE_CLAUDE_ARGS   Claude CLI args, default: -p',
+    '  DEXTER_BRIDGE_CODEX_BIN     Codex CLI binary name/path',
+    '  DEXTER_BRIDGE_CODEX_ARGS    Legacy codex exec args used only when App Server is disabled',
+    '  DEXTER_BRIDGE_CODEX_APP_SERVER  Set false to force the legacy codex exec path',
+    '  DEXTER_BRIDGE_CODEX_MAX_THREADS Maximum retained App Server threads, default: 32',
+    '  DEXTER_BRIDGE_LOG_DIR       Log directory, default: ~/.dexter-bridge/logs',
+  ].join('\n');
+}
+
+function parseArgv(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (key === 'once' || key === 'help') {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = argv[i + 1];
+    i += 1;
+  }
+  return {
+    command: positional[0] || 'start',
+    args: positional.slice(1),
+    flags,
+  };
+}
+
+function requireDeviceToken(config) {
+  if (!config.deviceToken) {
+    const error = new Error('Dexter Bridge is not paired. Run `dexter-bridge pair <code>` from Dexter Settings.');
+    error.exitCode = 2;
+    throw error;
+  }
+  return config.deviceToken;
+}
+
+async function promptForPairingCode() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question('Paste the pairing code from the Dexter plugin and press Enter: ');
+    return answer.trim();
+  } catch {
+    return '';
+  } finally {
+    rl.close();
+  }
+}
+
+function deviceName() {
+  return process.env.DEXTER_BRIDGE_DEVICE_NAME || `${os.hostname()} (${process.platform})`;
+}
+
+function pollBackoffMs(failureCount, baseMs = 1000, maxMs = 30000) {
+  const failures = Math.max(1, Number(failureCount) || 1);
+  const base = Math.max(100, Number(baseMs) || 1000);
+  const maximum = Math.max(base, Number(maxMs) || 30000);
+  return Math.min(maximum, base * (2 ** Math.min(10, failures - 1)));
+}
+
+function wait(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function agentEnvironment(config = {}, baseEnv = process.env) {
+  const env = { ...baseEnv };
+  const commands = config.agentCommands && typeof config.agentCommands === 'object'
+    ? config.agentCommands
+    : {};
+  if (!env.DEXTER_BRIDGE_CLAUDE_BIN && commands['claude-code']) {
+    env.DEXTER_BRIDGE_CLAUDE_BIN = commands['claude-code'];
+  }
+  if (!env.DEXTER_BRIDGE_CODEX_BIN && commands.codex) {
+    env.DEXTER_BRIDGE_CODEX_BIN = commands.codex;
+  }
+  return env;
+}
+
+async function inspectAvailability(config = {}) {
+  try {
+    const checks = await checkAllAgents({ env: agentEnvironment(config) });
+    const available = checks.agents.filter((check) => check.ok);
+    return {
+      metadata: {
+        availableAgents: available.map((check) => check.agent).join(','),
+        availableModels: available.flatMap((check) => check.models || []).join(','),
+        agentVersions: available.map((check) => `${check.agent}=${check.version || 'unknown'}`).join(','),
+        bridgeCapabilities: BRIDGE_CAPABILITIES.join(','),
+      },
+      agentCommands: Object.fromEntries(
+        available
+          .filter((check) => typeof check.command === 'string' && check.command.trim())
+          .map((check) => [check.agent, check.command]),
+      ),
+    };
+  } catch {
+    return {
+      metadata: { bridgeCapabilities: BRIDGE_CAPABILITIES.join(',') },
+      agentCommands: {},
+    };
+  }
+}
+
+async function availabilityMetadata(config = {}) {
+  return (await inspectAvailability(config)).metadata;
+}
+
+async function pairCommand({ apiBaseUrl, args, flags, configDir }) {
+  const codeOrToken = args[0];
+  if (!codeOrToken) throw new Error('Pairing code or token is required.');
+  const isToken = /^dcpp_/i.test(codeOrToken);
+  const config = readConfig(configDir);
+  const agent = resolveAgentName({ flagValue: flags.agent, config });
+  const model = resolveCompanionModelName({ flagValue: flags.model, config, agent });
+  const availability = await inspectAvailability(config);
+  const result = await claimPairing(apiBaseUrl, {
+    pairingCode: isToken ? undefined : codeOrToken,
+    pairingToken: isToken ? codeOrToken : undefined,
+    deviceName: flags['device-name'] || deviceName(),
+    agent,
+    model,
+    metadata: availability.metadata,
+  });
+  saveConfigPatch({
+    apiBaseUrl,
+    agent,
+    model,
+    deviceToken: result.deviceToken,
+    device: result.device,
+    agentCommands: availability.agentCommands,
+    pairedAt: new Date().toISOString(),
+  }, configDir);
+  console.log(`Paired Dexter Bridge: ${result.device?.name || 'device'}`);
+  console.log(`API: ${apiBaseUrl}`);
+}
+
+async function statusCommand({ apiBaseUrl, config }) {
+  const deviceToken = requireDeviceToken(config);
+  const agent = resolveAgentName({ config });
+  const model = resolveCompanionModelName({ config, agent });
+  const result = await heartbeat(apiBaseUrl, {
+    deviceToken,
+    status: 'ready',
+    agent,
+    model,
+    metadata: await availabilityMetadata(config),
+  });
+  console.log(`Status: ${result.device?.online ? 'online' : 'paired'}`);
+  console.log(`Device: ${result.device?.name || 'Dexter Bridge'}`);
+  console.log(`Model: ${result.device?.model?.displayName || model}`);
+  console.log(`API: ${apiBaseUrl}`);
+}
+
+async function startCommand({ apiBaseUrl, config, flags, configDir }) {
+  let deviceToken = config.deviceToken;
+  if (!deviceToken) {
+    // First run: pair interactively so `npx @gakim-digital/dexter-bridge` alone is
+    // enough — the Dexter plugin shows the code, the user pastes it here.
+    if (!process.stdin.isTTY) requireDeviceToken(config);
+    console.log('Dexter Bridge is not paired with your Dexter account yet.');
+    console.log('Open the Dexter plugin in Framer and pick Connect → Codex to get a pairing code.');
+    const code = await promptForPairingCode();
+    if (!code) requireDeviceToken(config);
+    await pairCommand({ apiBaseUrl, args: [code], flags, configDir });
+    deviceToken = readConfig(configDir).deviceToken;
+  }
+  const agent = resolveAgentName({ flagValue: flags.agent, config });
+  const model = resolveCompanionModelName({ flagValue: flags.model, config, agent });
+  const waitMs = Number(flags['wait-ms'] || 25000);
+  const once = Boolean(flags.once);
+  const bridgeEnv = agentEnvironment(config);
+  const metadata = await availabilityMetadata(config);
+  const pollLogger = createRunLogger({ runId: 'bridge-poll' });
+  const providerAdapters = new Map();
+  const providerAdapterForAgent = (runAgent) => {
+    if (providerAdapters.has(runAgent)) return providerAdapters.get(runAgent);
+    const adapter = createLocalAgentAdapter(runAgent, {
+      env: bridgeEnv,
+      trace: pollLogger,
+    });
+    providerAdapters.set(runAgent, adapter);
+    return adapter;
+  };
+  let pollFailureCount = 0;
+
+  console.log(`Dexter Bridge connected to ${apiBaseUrl}`);
+  console.log(`Agent: ${agent}`);
+  console.log(`Model: ${model}`);
+  console.log(`Logs: ${logLocationHint()}`);
+  console.log('Waiting for runs...');
+
+  try {
+    while (true) {
+      let poll;
+      try {
+        poll = await pollRun(apiBaseUrl, { deviceToken, waitMs, agent, model, metadata });
+        pollFailureCount = 0;
+      } catch (error) {
+        if (once) throw error;
+        pollFailureCount += 1;
+        const retryInMs = pollBackoffMs(pollFailureCount);
+        pollLogger.error('poll_failed', { error: errorMeta(error) });
+        if (pollFailureCount === 1 || (pollFailureCount & (pollFailureCount - 1)) === 0) {
+          console.error(`Dexter poll failed; retrying in ${Math.round(retryInMs / 1000)}s.`);
+        }
+        await wait(retryInMs);
+        continue;
+      }
+      if (poll.run) {
+        console.log(`Claimed run ${poll.run.runId}.`);
+        const runAgent = normalizeAgentName(poll.run?.companion?.agent || agent);
+        await executeRun(poll.run, {
+          apiBaseUrl,
+          deviceToken,
+          agent: runAgent,
+          selectedModel: model,
+          providerAdapter: providerAdapterForAgent(runAgent),
+          env: bridgeEnv,
+          maxSteps: flags['max-steps'],
+        });
+        if (once) return;
+        continue;
+      }
+      if (once) {
+        console.log('No pending Dexter runs.');
+        return;
+      }
+    }
+  } finally {
+    for (const adapter of providerAdapters.values()) adapter?.close?.();
+    providerAdapters.clear();
+  }
+}
+
+async function doctorCommand() {
+  const checks = await checkAllAgents();
+  for (const check of checks.agents) {
+    if (check.ok) console.log(`${check.command}: ok ${check.output || ''}`.trim());
+    else console.log(`${check.command}: unavailable (${check.error})`);
+  }
+}
+
+export async function runCli(argv) {
+  const parsed = parseArgv(argv);
+  if (parsed.flags.help) {
+    console.log(usage());
+    return;
+  }
+
+  const configDir = parsed.flags['config-dir'] || defaultConfigDir();
+  const config = readConfig(configDir);
+  const apiBaseUrl = resolveApiBaseUrl({
+    flagValue: parsed.flags.api,
+    config,
+  });
+
+  switch (parsed.command) {
+    // The one-command production path: claim the pairing code (when given or
+    // not yet paired), save config, and go straight into the polling loop.
+    case 'connect':
+      if (parsed.args[0]) {
+        await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
+      }
+      await startCommand({
+        apiBaseUrl,
+        config: { ...readConfig(configDir), apiBaseUrl },
+        flags: parsed.flags,
+        configDir,
+      });
+      return;
+    case 'pair':
+      await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
+      console.log('Run `dexter-bridge start` to go online.');
+      return;
+    case 'start':
+      await startCommand({ apiBaseUrl, config: { ...config, apiBaseUrl }, flags: parsed.flags, configDir });
+      return;
+    case 'status':
+      await statusCommand({ apiBaseUrl, config });
+      return;
+    case 'doctor':
+      await doctorCommand();
+      return;
+    case 'logout':
+      clearConfig(configDir);
+      console.log('Dexter Bridge local pairing removed.');
+      return;
+    default:
+      throw new Error(`Unknown command "${parsed.command}".\n\n${usage()}`);
+  }
+}
+
+export const __private__ = { agentEnvironment, parseArgv, pollBackoffMs, usage };

package/src/config.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const DEFAULT_API_BASE_URL = 'http://localhost:3800/iwm-api/0.0.1';
+export const BRIDGE_VERSION = '0.5.0';
+export const BRIDGE_CAPABILITIES = [
+  'model-turn-v1',
+];
+// Codex is the default local agent: driving Claude Code from a user's Claude.ai
+// subscription needs prior written approval from Anthropic for commercial use, so
+// 'claude-code' only runs when the server offers it (see policy gating in
+// framerCompanionModels.ts and docs/dexter-connect-onboarding-plan.md §0).
+export const DEFAULT_BRIDGE_AGENT = 'codex';
+export const BRIDGE_AGENTS = ['claude-code', 'codex', 'dry-run'];
+export const COMPANION_MODEL_DEFINITIONS = [
+  {
+    id: 'claude-code:fable',
+    agent: 'claude-code',
+    provider: 'anthropic',
+    displayName: 'Claude Fable 5',
+    invocationName: 'claude-fable-5',
+    minimumAgentVersion: '2.1.170',
+    costTier: '$$$',
+    description: 'Current highest-capability Claude tier via Claude Code.',
+  },
+  {
+    id: 'claude-code:opus',
+    agent: 'claude-code',
+    provider: 'anthropic',
+    displayName: 'Claude Opus 4.8',
+    invocationName: 'claude-opus-4-8',
+    costTier: '$$$',
+    description: 'Latest Opus-class model via Claude Code.',
+  },
+  {
+    id: 'claude-code:sonnet',
+    agent: 'claude-code',
+    provider: 'anthropic',
+    displayName: 'Claude Sonnet 5',
+    invocationName: 'claude-sonnet-5',
+    costTier: '$$',
+    description: 'Current balanced Claude model via Claude Code.',
+  },
+  {
+    id: 'claude-code:haiku',
+    agent: 'claude-code',
+    provider: 'anthropic',
+    displayName: 'Claude Haiku',
+    invocationName: 'claude-haiku-4-5-20251001',
+    costTier: '$',
+    description: 'Fast Claude model via Claude Code.',
+  },
+  {
+    id: 'codex:gpt-5.5',
+    agent: 'codex',
+    provider: 'openai',
+    displayName: 'GPT-5.5',
+    invocationName: 'gpt-5.5',
+    costTier: '$$$',
+    description: 'Current frontier model for Codex runs.',
+  },
+  {
+    id: 'codex:gpt-5.4',
+    agent: 'codex',
+    provider: 'openai',
+    displayName: 'GPT-5.4',
+    invocationName: 'gpt-5.4',
+    costTier: '$$',
+    description: 'Flagship general-purpose model for Codex runs.',
+  },
+  {
+    id: 'codex:gpt-5.4-mini',
+    agent: 'codex',
+    provider: 'openai',
+    displayName: 'GPT-5.4 mini',
+    invocationName: 'gpt-5.4-mini',
+    costTier: '$',
+    description: 'Fast, efficient model for Codex runs.',
+  },
+  {
+    id: 'codex:gpt-5.3-codex-spark',
+    agent: 'codex',
+    provider: 'openai',
+    displayName: 'GPT-5.3 Codex Spark',
+    invocationName: 'gpt-5.3-codex-spark',
+    costTier: '$',
+    description: 'Low-latency Codex model for quick coding iterations.',
+  },
+  {
+    id: 'dry-run:default',
+    agent: 'dry-run',
+    provider: 'companion',
+    displayName: 'Dry run',
+    invocationName: 'dry-run',
+    costTier: '$',
+    description: 'Debug mode that does not call a local AI agent.',
+  },
+];
+
+const DEFAULT_MODEL_BY_AGENT = {
+  'claude-code': 'claude-code:sonnet',
+  codex: 'codex:gpt-5.5',
+  'dry-run': 'dry-run:default',
+};
+
+export function defaultConfigDir(env = process.env) {
+  return env.DEXTER_BRIDGE_CONFIG_DIR || path.join(os.homedir(), '.dexter-bridge');
+}
+
+export function configFilePath(configDir = defaultConfigDir()) {
+  return path.join(configDir, 'config.json');
+}
+
+export function normalizeApiBaseUrl(value) {
+  const raw = String(value || DEFAULT_API_BASE_URL).trim();
+  return raw.replace(/\/+$/, '');
+}
+
+export function normalizeAgentName(value, fallback = DEFAULT_BRIDGE_AGENT) {
+  const raw = String(value || '').trim().toLowerCase();
+  if (raw === 'claude' || raw === 'claude_code' || raw === 'claude-code') return 'claude-code';
+  if (raw === 'openai-codex' || raw === 'openai_codex' || raw === 'codex') return 'codex';
+  if (raw === 'dryrun' || raw === 'dry_run' || raw === 'dry-run') return 'dry-run';
+  return BRIDGE_AGENTS.includes(fallback) ? fallback : DEFAULT_BRIDGE_AGENT;
+}
+
+export function companionModelsForAgent(agent) {
+  const normalizedAgent = normalizeAgentName(agent);
+  return COMPANION_MODEL_DEFINITIONS.filter((model) => model.agent === normalizedAgent);
+}
+
+export function companionModelDefinition(value, agent = DEFAULT_BRIDGE_AGENT) {
+  const normalizedAgent = normalizeAgentName(agent);
+  const raw = String(value || '').trim().toLowerCase();
+  const candidates = companionModelsForAgent(normalizedAgent);
+  if (!raw || raw === 'local-companion') {
+    return COMPANION_MODEL_DEFINITIONS.find((model) => model.id === DEFAULT_MODEL_BY_AGENT[normalizedAgent]);
+  }
+  return (
+    candidates.find((model) => model.id.toLowerCase() === raw) ||
+    candidates.find((model) => model.invocationName.toLowerCase() === raw) ||
+    candidates.find((model) => model.id.toLowerCase() === `${normalizedAgent}:${raw}`) ||
+    COMPANION_MODEL_DEFINITIONS.find((model) => model.id === DEFAULT_MODEL_BY_AGENT[normalizedAgent])
+  );
+}
+
+export function normalizeCompanionModelName(value, agent = DEFAULT_BRIDGE_AGENT) {
+  return companionModelDefinition(value, agent)?.id || DEFAULT_MODEL_BY_AGENT[normalizeAgentName(agent)];
+}
+
+export function companionModelMetadata(agent, model) {
+  const normalizedAgent = normalizeAgentName(agent);
+  const selectedModel = companionModelDefinition(model, normalizedAgent);
+  return {
+    model: selectedModel?.id || DEFAULT_MODEL_BY_AGENT[normalizedAgent],
+    modelLabel: selectedModel?.displayName || '',
+    models: companionModelsForAgent(normalizedAgent),
+  };
+}
+
+export function readConfig(configDir = defaultConfigDir()) {
+  const file = configFilePath(configDir);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+export function writeConfig(config, configDir = defaultConfigDir()) {
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  const file = configFilePath(configDir);
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best effort on filesystems that do not support chmod.
+  }
+  return config;
+}
+
+export function saveConfigPatch(patch, configDir = defaultConfigDir()) {
+  return writeConfig({ ...readConfig(configDir), ...patch }, configDir);
+}
+
+export function clearConfig(configDir = defaultConfigDir()) {
+  try {
+    fs.rmSync(configFilePath(configDir), { force: true });
+  } catch {
+    // Logout should be idempotent.
+  }
+}
+
+export function resolveApiBaseUrl({ flagValue, config = readConfig(), env = process.env } = {}) {
+  return normalizeApiBaseUrl(flagValue || env.DEXTER_API_URL || env.DEXTER_BRIDGE_API_URL || config.apiBaseUrl);
+}
+
+export function resolveAgentName({ flagValue, config = readConfig(), env = process.env } = {}) {
+  return normalizeAgentName(flagValue || env.DEXTER_BRIDGE_AGENT || config.agent || config.engine);
+}
+
+export function resolveCompanionModelName({ flagValue, config = readConfig(), env = process.env, agent = DEFAULT_BRIDGE_AGENT } = {}) {
+  return normalizeCompanionModelName(flagValue || env.DEXTER_BRIDGE_MODEL || config.model || config.companionModel, agent);
+}