@gakim-digital/dexter-bridge 0.5.0

package/src/providers/codexAppServer.js

@@ -0,0 +1,457 @@
+import { createJsonRpcClient } from './jsonRpcClient.js';
+import { normalizeCompanionTokenUsage } from '../agentOutput.js';
+
+/**
+ * Codex App Server adapter — the primary local-agent path.
+ *
+ * Instead of re-invoking `codex exec` per turn, this holds one long-lived
+ * `codex app-server` process and drives it over newline-delimited JSON-RPC.
+ * That gives us persistent threads, device-code login, and real plan/rate-limit
+ * data straight from Codex.
+ *
+ * Protocol verified against codex-cli 0.144.4 (`codex app-server
+ * generate-json-schema`): `initialize`, `model/list`, `account/read`,
+ * `account/login/start` (with `{type:'chatgptDeviceCode'}` →
+ * `{loginId,userCode,verificationUrl}`), `thread/start`, `turn/start`,
+ * `turn/interrupt`, `account/logout`; server pushes `item/completed`,
+ * `turn/completed`, `account/login/completed`, `error`.
+ */
+
+const CLIENT_INFO = {
+  name: 'dexter_bridge',
+  title: 'Dexter Bridge',
+  version: '0.5.0',
+};
+
+export const CODEX_APP_SERVER_METHODS = {
+  initialize: 'initialize',
+  modelList: 'model/list',
+  accountRead: 'account/read',
+  accountUsage: 'account/usage/read',
+  rateLimits: 'account/rateLimits/read',
+  loginStart: 'account/login/start',
+  loginCancel: 'account/login/cancel',
+  logout: 'account/logout',
+  threadStart: 'thread/start',
+  threadResume: 'thread/resume',
+  threadUnsubscribe: 'thread/unsubscribe',
+  turnStart: 'turn/start',
+  turnInterrupt: 'turn/interrupt',
+};
+
+export const CODEX_APP_SERVER_NOTIFICATIONS = {
+  loginCompleted: 'account/login/completed',
+  itemCompleted: 'item/completed',
+  turnCompleted: 'turn/completed',
+  threadStarted: 'thread/started',
+  error: 'error',
+};
+
+/** Pull assistant text out of a completed thread item, whatever its shape. */
+export function agentMessageText(item) {
+  if (!item || typeof item !== 'object') return '';
+  if (item.type && item.type !== 'agentMessage' && item.item_type !== 'agentMessage') return '';
+  if (typeof item.text === 'string') return item.text;
+  const content = Array.isArray(item.content) ? item.content : [];
+  return content
+    .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+    .filter(Boolean)
+    .join('');
+}
+
+/** Normalize model/list rows into the shape the bridge already speaks. */
+export function normalizeCodexModels(response) {
+  const rows = Array.isArray(response?.data) ? response.data : [];
+  return rows
+    .filter((row) => row && typeof row.id === 'string' && !row.hidden)
+    .map((row) => ({
+      id: `codex:${row.id}`,
+      agent: 'codex',
+      provider: 'openai',
+      displayName: row.displayName || row.model || row.id,
+      invocationName: row.model || row.id,
+      costTier: '$$',
+      description: row.description || 'Codex model.',
+      isDefault: Boolean(row.isDefault),
+    }));
+}
+
+export function normalizeUsage(turn) {
+  const usage = turn?.usage || turn?.tokenUsage || {};
+  const tokenUsage = normalizeCompanionTokenUsage(usage);
+  return {
+    tokenUsage,
+    usageAvailable: tokenUsage.totalTokens > 0,
+    usageSource: 'codex',
+    usageAccuracy: tokenUsage.totalTokens > 0 ? 'reported' : 'unavailable',
+  };
+}
+
+export function codexTurnErrorMessage(value, fallback = 'Codex reported an error.') {
+  const candidates = [
+    value?.message,
+    value?.error?.message,
+    value?.turn?.error?.message,
+    value?.additionalDetails,
+    value?.error?.additionalDetails,
+    value?.turn?.error?.additionalDetails,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) {
+      return candidate.trim().slice(0, 2000);
+    }
+  }
+  return fallback;
+}
+
+export function createCodexAppServerAdapter({
+  command = process.env.DEXTER_BRIDGE_CODEX_BIN || 'codex',
+  args = ['app-server'],
+  env = process.env,
+  cwd,
+  clientInfo = CLIENT_INFO,
+  trace,
+  createClient = createJsonRpcClient,
+  maxTrackedThreads = Number(env.DEXTER_BRIDGE_CODEX_MAX_THREADS || 32),
+} = {}) {
+  let client = null;
+  let initialized = null;
+  const threadLimit = Math.max(1, Math.min(200, Number(maxTrackedThreads) || 32));
+  /** threadId per Dexter turn, so relay runs in one turn share Codex context. */
+  const threadsByRun = new Map();
+  const listeners = new Set();
+
+  function emit(event) {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // A listener must never break the transport.
+      }
+    }
+  }
+
+  function ensureClient() {
+    if (client && !client.closed) return client;
+    client = createClient({
+      command,
+      args,
+      env,
+      cwd,
+      onNotification: (message) => {
+        trace?.info('codex_app_server_notification', { method: message.method });
+        emit({ type: 'notification', method: message.method, params: message.params });
+      },
+      // The app server asks for approvals; Dexter runs read-only against Codex,
+      // so anything that wants to touch the machine is denied rather than hung.
+      onServerRequest: (message) => {
+        trace?.info('codex_app_server_request', { method: message.method });
+        const method = String(message.method || '');
+        if (
+          method === 'item/commandExecution/requestApproval'
+          || method === 'item/fileChange/requestApproval'
+        ) return 'decline';
+        if (method === 'item/permissions/requestApproval') return { permissions: {} };
+        if (method === 'mcpServer/elicitation/request') return { action: 'decline', content: null };
+        return {};
+      },
+      onExit: (info) => {
+        initialized = null;
+        threadsByRun.clear();
+        trace?.info('codex_app_server_exit', info || {});
+        emit({ type: 'exit', ...info });
+      },
+    });
+    initialized = null;
+    return client;
+  }
+
+  async function initialize() {
+    const active = ensureClient();
+    if (!initialized) {
+      initialized = active
+        .request(CODEX_APP_SERVER_METHODS.initialize, { clientInfo }, { timeoutMs: 20000 })
+        .then((result) => {
+          active.notify('initialized', {});
+          return result;
+        });
+    }
+    return initialized;
+  }
+
+  async function detect() {
+    try {
+      const info = await initialize();
+      let account = null;
+      try {
+        account = await ensureClient().request(CODEX_APP_SERVER_METHODS.accountRead, {}, { timeoutMs: 15000 });
+      } catch {
+        // Not signed in yet — still "installed", just not authenticated.
+      }
+      // Observed live (codex-cli 0.144.4): a signed-out install answers
+      // `{account: null, requiresOpenaiAuth: false}` rather than failing, so an
+      // explicit null account is the signal — not the absence of a response.
+      const signedIn = Boolean(account?.account || account?.email || account?.planType || account?.plan);
+      return {
+        ok: true,
+        installed: true,
+        signedIn,
+        agent: 'codex',
+        codexHome: info?.codexHome || null,
+        userAgent: info?.userAgent || null,
+        plan: account?.planType || account?.plan || account?.account?.planType || null,
+        requiresOpenaiAuth: Boolean(account?.requiresOpenaiAuth),
+        account: account?.account || account || null,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        installed: false,
+        signedIn: false,
+        agent: 'codex',
+        error: error?.message || String(error || ''),
+      };
+    }
+  }
+
+  /**
+   * Device-code login: returns the code and URL for the plugin to show, plus a
+   * promise that settles when the user finishes (or the attempt fails).
+   */
+  async function authenticate({ timeoutMs = 10 * 60 * 1000 } = {}) {
+    await initialize();
+    const active = ensureClient();
+    const started = await active.request(
+      CODEX_APP_SERVER_METHODS.loginStart,
+      { type: 'chatgptDeviceCode' },
+      { timeoutMs: 30000 },
+    );
+
+    const completed = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        listeners.delete(listener);
+        reject(new Error('Codex sign-in timed out.'));
+      }, timeoutMs);
+      function listener(event) {
+        if (event.type === 'exit') {
+          clearTimeout(timer);
+          listeners.delete(listener);
+          reject(new Error('Codex app server stopped during sign-in.'));
+          return;
+        }
+        if (event.type !== 'notification' || event.method !== CODEX_APP_SERVER_NOTIFICATIONS.loginCompleted) return;
+        if (started.loginId && event.params?.loginId && event.params.loginId !== started.loginId) return;
+        clearTimeout(timer);
+        listeners.delete(listener);
+        if (event.params?.success) resolve({ ok: true });
+        else reject(new Error(event.params?.error || 'Codex sign-in failed.'));
+      }
+      listeners.add(listener);
+    });
+
+    return {
+      kind: started.type === 'chatgptDeviceCode' ? 'device_code' : started.type || 'unknown',
+      loginId: started.loginId || null,
+      userCode: started.userCode || null,
+      verificationUrl: started.verificationUrl || started.authUrl || null,
+      completed,
+    };
+  }
+
+  async function cancelAuthentication(loginId) {
+    if (!loginId) return;
+    try {
+      await ensureClient().request(CODEX_APP_SERVER_METHODS.loginCancel, { loginId }, { timeoutMs: 10000 });
+    } catch {
+      // Cancelling a login that already resolved is not an error worth raising.
+    }
+  }
+
+  async function models() {
+    await initialize();
+    const response = await ensureClient().request(CODEX_APP_SERVER_METHODS.modelList, {}, { timeoutMs: 20000 });
+    return normalizeCodexModels(response);
+  }
+
+  async function usage() {
+    await initialize();
+    const active = ensureClient();
+    const [rateLimits, accountUsage] = await Promise.allSettled([
+      active.request(CODEX_APP_SERVER_METHODS.rateLimits, {}, { timeoutMs: 15000 }),
+      active.request(CODEX_APP_SERVER_METHODS.accountUsage, {}, { timeoutMs: 15000 }),
+    ]);
+    return {
+      rateLimits: rateLimits.status === 'fulfilled' ? rateLimits.value : null,
+      usage: accountUsage.status === 'fulfilled' ? accountUsage.value : null,
+    };
+  }
+
+  async function ensureThread(runId, { model, cwd: threadCwd } = {}) {
+    const existing = threadsByRun.get(runId);
+    if (existing) {
+      threadsByRun.delete(runId);
+      threadsByRun.set(runId, existing);
+      return existing;
+    }
+    const active = ensureClient();
+    if (threadsByRun.size >= threadLimit) {
+      const oldest = threadsByRun.entries().next().value;
+      if (oldest) {
+        const [oldestRunId, oldestThreadId] = oldest;
+        threadsByRun.delete(oldestRunId);
+        active.request(
+          CODEX_APP_SERVER_METHODS.threadUnsubscribe,
+          { threadId: oldestThreadId },
+          { timeoutMs: 10000 },
+        ).catch(() => undefined);
+      }
+    }
+    const params = {
+      // Dexter's canvas work never touches the filesystem, so the agent runs
+      // sandboxed read-only and never asks the user to approve anything.
+      sandbox: 'read-only',
+      approvalPolicy: 'never',
+      ...(threadCwd ? { cwd: threadCwd } : {}),
+      ...(model ? { model } : {}),
+    };
+    const response = await active.request(CODEX_APP_SERVER_METHODS.threadStart, params, { timeoutMs: 30000 });
+    const threadId = response?.thread?.id || response?.threadId || response?.id;
+    if (!threadId) throw new Error('Codex app server did not return a thread id.');
+    threadsByRun.set(runId, threadId);
+    return threadId;
+  }
+
+  /**
+   * Run one Dexter model turn on the persistent thread and return the assistant's
+   * final text. The server-owned loop still decides what that text means — this
+   * adapter only changes how it is produced.
+   */
+  async function runModelTurn({
+    runId,
+    sessionId,
+    prompt,
+    model,
+    outputSchema,
+    timeoutMs = 180000,
+  } = {}) {
+    await initialize();
+    const active = ensureClient();
+    const threadKey = sessionId || runId;
+    if (!threadKey) throw new Error('Codex model turn requires a session id.');
+    const threadId = await ensureThread(threadKey, { model, cwd });
+
+    return new Promise((resolve, reject) => {
+      let lastMessage = '';
+      const timer = setTimeout(() => {
+        listeners.delete(listener);
+        active.request(
+          CODEX_APP_SERVER_METHODS.turnInterrupt,
+          { threadId },
+          { timeoutMs: 10000 },
+        ).catch(() => undefined);
+        reject(new Error(`Codex turn timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+
+      function finish(fn, value) {
+        clearTimeout(timer);
+        listeners.delete(listener);
+        fn(value);
+      }
+
+      function listener(event) {
+        if (event.type === 'exit') {
+          finish(reject, new Error('Codex app server stopped mid-turn.'));
+          return;
+        }
+        if (event.type !== 'notification') return;
+        if (event.params?.threadId && event.params.threadId !== threadId) return;
+
+        if (event.method === CODEX_APP_SERVER_NOTIFICATIONS.itemCompleted) {
+          const text = agentMessageText(event.params?.item);
+          if (text) lastMessage = text;
+          return;
+        }
+        if (event.method === CODEX_APP_SERVER_NOTIFICATIONS.error) {
+          // App Server reports retryable transport/provider errors before the
+          // final turn outcome. Let its internal retry finish; the terminal
+          // turn/completed event remains authoritative.
+          if (event.params?.willRetry === true) return;
+          finish(reject, new Error(codexTurnErrorMessage(event.params)));
+          return;
+        }
+        if (event.method === CODEX_APP_SERVER_NOTIFICATIONS.turnCompleted) {
+          const turn = event.params?.turn || {};
+          if (turn.status === 'failed') {
+            finish(reject, new Error(codexTurnErrorMessage(
+              turn,
+              'Codex turn failed without an error message.',
+            )));
+            return;
+          }
+          finish(resolve, {
+            text: lastMessage,
+            threadId,
+            turnId: turn.id || null,
+            ...normalizeUsage(turn),
+          });
+        }
+      }
+
+      listeners.add(listener);
+
+      active
+        .request(
+          CODEX_APP_SERVER_METHODS.turnStart,
+          {
+            threadId,
+            input: [{ type: 'text', text: prompt }],
+            ...(model ? { model } : {}),
+            ...(outputSchema ? { outputSchema } : {}),
+          },
+          { timeoutMs: 30000 },
+        )
+        .catch((error) => finish(reject, error));
+    });
+  }
+
+  async function cancel(sessionId) {
+    const threadId = threadsByRun.get(sessionId);
+    if (!threadId || !client || client.closed) return;
+    try {
+      await client.request(CODEX_APP_SERVER_METHODS.turnInterrupt, { threadId }, { timeoutMs: 10000 });
+    } catch {
+      // Interrupting a finished turn is a no-op, not a failure.
+    }
+  }
+
+  async function logout() {
+    if (!client || client.closed) return;
+    try {
+      await client.request(CODEX_APP_SERVER_METHODS.logout, {}, { timeoutMs: 15000 });
+    } finally {
+      threadsByRun.clear();
+    }
+  }
+
+  function close() {
+    threadsByRun.clear();
+    listeners.clear();
+    client?.close();
+    client = null;
+    initialized = null;
+  }
+
+  return {
+    id: 'codex',
+    label: 'Codex',
+    detect,
+    authenticate,
+    cancelAuthentication,
+    models,
+    usage,
+    runModelTurn,
+    cancel,
+    logout,
+    close,
+  };
+}

package/src/providers/index.js

@@ -0,0 +1,55 @@
+import { createCodexAppServerAdapter } from './codexAppServer.js';
+
+/**
+ * Local agent adapters.
+ *
+ * The server-owned agent loop and the `model_turn` relay protocol are unchanged;
+ * an adapter only decides *how* one local model turn is executed. Today's shipping
+ * Codex App Server is the default Codex path. Set
+ * DEXTER_BRIDGE_CODEX_APP_SERVER=false to force the legacy `codex exec` path
+ * during rollback or compatibility testing.
+ *
+ * @typedef {Object} ProviderStatus
+ * @property {boolean} ok
+ * @property {boolean} installed
+ * @property {boolean} signedIn
+ * @property {string}  agent
+ * @property {string=} error
+ *
+ * @typedef {Object} AuthChallenge
+ * @property {'device_code'|'browser'|'api_key'|'unknown'} kind
+ * @property {string|null} userCode          Code the user types into the browser.
+ * @property {string|null} verificationUrl   Page the user opens.
+ * @property {Promise<{ok:boolean}>} completed Resolves when sign-in finishes.
+ *
+ * @typedef {Object} LocalAgentAdapter
+ * @property {'codex'|'cursor'|'claude-api'} id
+ * @property {() => Promise<ProviderStatus>} detect
+ * @property {(() => Promise<AuthChallenge>)=} authenticate
+ * @property {() => Promise<Array<object>>} models
+ * @property {(input: object) => Promise<{text: string, tokenUsage?: object}>} runModelTurn
+ * @property {(sessionId: string) => Promise<void>} cancel
+ * @property {(() => Promise<void>)=} logout
+ */
+
+export const ADAPTER_FACTORIES = {
+  codex: createCodexAppServerAdapter,
+};
+
+export function isCodexAppServerEnabled(env = process.env) {
+  const raw = String(env.DEXTER_BRIDGE_CODEX_APP_SERVER ?? '').trim().toLowerCase();
+  if (!raw) return true;
+  return !['0', 'false', 'no', 'off', 'disabled'].includes(raw);
+}
+
+/**
+ * Returns an adapter for the agent, or null when the agent has no adapter yet
+ * or the caller explicitly disabled the adapter and should use the CLI path.
+ */
+export function createLocalAgentAdapter(agent, options = {}) {
+  const env = options.env || process.env;
+  if (agent === 'codex' && isCodexAppServerEnabled(env)) {
+    return createCodexAppServerAdapter(options);
+  }
+  return null;
+}

package/src/providers/jsonRpcClient.js

@@ -0,0 +1,172 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Newline-delimited JSON-RPC 2.0 client over a child process's stdio.
+ *
+ * Framing verified against `codex app-server` (codex-cli 0.144.4): each message
+ * is one JSON object on its own line, in both directions. There is no
+ * Content-Length header.
+ */
+export function createJsonRpcClient({
+  command,
+  args = [],
+  env = process.env,
+  cwd,
+  onNotification,
+  onServerRequest,
+  onExit,
+  spawnImpl = spawn,
+} = {}) {
+  const child = spawnImpl(command, args, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env,
+    cwd,
+  });
+
+  const pending = new Map();
+  let nextId = 1;
+  let buffer = '';
+  let stderrTail = '';
+  let closed = false;
+  let closeError = null;
+
+  function settleAllPending(error) {
+    for (const [, entry] of pending) entry.reject(error);
+    pending.clear();
+  }
+
+  function handleMessage(message) {
+    // Response to something we sent.
+    if (message.id !== undefined && (message.result !== undefined || message.error !== undefined)) {
+      const entry = pending.get(message.id);
+      if (!entry) return;
+      pending.delete(message.id);
+      if (message.error) {
+        const error = new Error(message.error.message || 'JSON-RPC error');
+        error.code = message.error.code;
+        error.data = message.error.data;
+        entry.reject(error);
+        return;
+      }
+      entry.resolve(message.result);
+      return;
+    }
+
+    // Server-initiated request — needs a reply or the server blocks.
+    if (message.id !== undefined && message.method) {
+      Promise.resolve(onServerRequest?.(message))
+        .then((result) => send({ jsonrpc: '2.0', id: message.id, result: result ?? {} }))
+        .catch((error) => send({
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32000, message: error?.message || String(error) },
+        }));
+      return;
+    }
+
+    if (message.method) onNotification?.(message);
+  }
+
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    let newlineIndex = buffer.indexOf('\n');
+    while (newlineIndex !== -1) {
+      const line = buffer.slice(0, newlineIndex).trim();
+      buffer = buffer.slice(newlineIndex + 1);
+      if (line) {
+        try {
+          handleMessage(JSON.parse(line));
+        } catch {
+          // A non-JSON line is noise from the child, not a protocol failure.
+        }
+      }
+      newlineIndex = buffer.indexOf('\n');
+    }
+  });
+
+  child.stderr.on('data', (chunk) => {
+    stderrTail = `${stderrTail}${chunk.toString('utf8')}`.slice(-4000);
+  });
+
+  child.on('error', (error) => {
+    closed = true;
+    closeError = error;
+    settleAllPending(error);
+    onExit?.({ error });
+  });
+
+  child.on('close', (code) => {
+    closed = true;
+    closeError =
+      closeError ||
+      new Error(`${command} exited with code ${code}.${stderrTail ? ` ${stderrTail.trim().slice(-500)}` : ''}`);
+    settleAllPending(closeError);
+    onExit?.({ code, stderr: stderrTail });
+  });
+
+  function send(message) {
+    if (closed) throw closeError || new Error(`${command} is not running.`);
+    child.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  function request(method, params = {}, { timeoutMs = 60000 } = {}) {
+    return new Promise((resolve, reject) => {
+      if (closed) {
+        reject(closeError || new Error(`${command} is not running.`));
+        return;
+      }
+      const id = nextId++;
+      const timer = timeoutMs
+        ? setTimeout(() => {
+            pending.delete(id);
+            reject(new Error(`${method} timed out after ${timeoutMs}ms.`));
+          }, timeoutMs)
+        : null;
+      pending.set(id, {
+        resolve: (value) => {
+          if (timer) clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          if (timer) clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        send({ jsonrpc: '2.0', id, method, params });
+      } catch (error) {
+        pending.delete(id);
+        if (timer) clearTimeout(timer);
+        reject(error);
+      }
+    });
+  }
+
+  function notify(method, params = {}) {
+    send({ jsonrpc: '2.0', method, params });
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    settleAllPending(new Error(`${command} client closed.`));
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      // Already gone.
+    }
+  }
+
+  return {
+    request,
+    notify,
+    close,
+    get closed() {
+      return closed;
+    },
+    get stderr() {
+      return stderrTail;
+    },
+    child,
+  };
+}