@gakim-digital/dexter-bridge 0.5.15 → 0.5.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.15",
+  "version": "0.5.19",
   "description": "Local Companion bridge for the Dexter Framer plugin — runs Codex or Claude Code on your machine.",
   "type": "module",
   "bin": {

package/src/providers/claudeAgentSdk.js

@@ -286,7 +286,7 @@ export function createClaudeAgentSdkAdapter({
     return {
       ...inherited,
       CLAUDE_CONFIG_DIR: configDir,
-      CLAUDE_AGENT_SDK_CLIENT_APP: 'dexter-hosted-worker/0.2.3',
+      CLAUDE_AGENT_SDK_CLIENT_APP: 'dexter-hosted-worker/0.2.4',
     };
   }
 

package/src/providers/codexAppServer.js

@@ -2,6 +2,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createJsonRpcClient } from './jsonRpcClient.js';
+import {
+  codexTransportOutputSchema,
+  codexTransportPrompt,
+  decodeCodexTransportOutput,
+} from './codexStructuredOutput.js';
 import { normalizeCompanionTokenUsage } from '../agentOutput.js';
 import { BRIDGE_VERSION } from '../config.js';
 
@@ -13,12 +18,13 @@ import { BRIDGE_VERSION } from '../config.js';
  * 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
+ * Protocol verified against codex-cli 0.146.0 (`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`.
+ * `thread/tokenUsage/updated`, `turn/completed`,
+ * `account/login/completed`, `error`.
  */
 
 const CLIENT_INFO = {
@@ -129,6 +135,7 @@ export const CODEX_APP_SERVER_METHODS = {
 export const CODEX_APP_SERVER_NOTIFICATIONS = {
   loginCompleted: 'account/login/completed',
   itemCompleted: 'item/completed',
+  tokenUsageUpdated: 'thread/tokenUsage/updated',
   turnCompleted: 'turn/completed',
   threadStarted: 'thread/started',
   error: 'error',
@@ -163,9 +170,36 @@ export function normalizeCodexModels(response) {
     }));
 }
 
-export function normalizeUsage(turn) {
-  const usage = turn?.usage || turn?.tokenUsage || {};
-  const tokenUsage = normalizeCompanionTokenUsage(usage);
+export function codexUsageSince(current, baseline = {}) {
+  const currentUsage = normalizeCompanionTokenUsage(current);
+  const baselineUsage = normalizeCompanionTokenUsage(baseline);
+  const inputTokens = Math.max(0, currentUsage.inputTokens - baselineUsage.inputTokens);
+  const outputTokens = Math.max(0, currentUsage.outputTokens - baselineUsage.outputTokens);
+  const cachedInputTokens = Math.max(
+    0,
+    currentUsage.cachedInputTokens - baselineUsage.cachedInputTokens,
+  );
+  const cacheWriteInputTokens = Math.max(
+    0,
+    currentUsage.cacheWriteInputTokens - baselineUsage.cacheWriteInputTokens,
+  );
+  const reasoningOutputTokens = Math.max(
+    0,
+    currentUsage.reasoningOutputTokens - baselineUsage.reasoningOutputTokens,
+  );
+  const totalTokens = Math.max(
+    0,
+    currentUsage.totalTokens - baselineUsage.totalTokens,
+    inputTokens + outputTokens + reasoningOutputTokens,
+  );
+  const tokenUsage = {
+    inputTokens,
+    outputTokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    reasoningOutputTokens,
+    totalTokens,
+  };
   return {
     tokenUsage,
     usageAvailable: tokenUsage.totalTokens > 0,
@@ -214,6 +248,8 @@ export function createCodexAppServerAdapter({
   );
   /** threadId per Dexter turn, so relay runs in one turn share Codex context. */
   const threadsByRun = new Map();
+  /** Latest cumulative token totals reported for each persistent Codex thread. */
+  const threadUsageTotals = new Map();
   const listeners = new Set();
 
   function emit(event) {
@@ -235,6 +271,15 @@ export function createCodexAppServerAdapter({
       cwd,
       onNotification: (message) => {
         trace?.info('codex_app_server_notification', { method: message.method });
+        if (
+          message.method === CODEX_APP_SERVER_NOTIFICATIONS.tokenUsageUpdated
+          && typeof message.params?.threadId === 'string'
+        ) {
+          threadUsageTotals.set(
+            message.params.threadId,
+            normalizeCompanionTokenUsage(message.params?.tokenUsage?.total),
+          );
+        }
         emit({ type: 'notification', method: message.method, params: message.params });
       },
       // The app server asks for approvals; Dexter runs read-only against Codex,
@@ -253,6 +298,7 @@ export function createCodexAppServerAdapter({
       onExit: (info) => {
         initialized = null;
         threadsByRun.clear();
+        threadUsageTotals.clear();
         trace?.info('codex_app_server_exit', info || {});
         emit({ type: 'exit', ...info });
       },
@@ -403,6 +449,7 @@ export function createCodexAppServerAdapter({
       if (oldest) {
         const [oldestRunId, oldestThreadId] = oldest;
         threadsByRun.delete(oldestRunId);
+        threadUsageTotals.delete(oldestThreadId);
         active.request(
           CODEX_APP_SERVER_METHODS.threadUnsubscribe,
           { threadId: oldestThreadId },
@@ -430,6 +477,7 @@ export function createCodexAppServerAdapter({
     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);
+    threadUsageTotals.delete(threadId);
     return threadId;
   }
 
@@ -451,9 +499,20 @@ export function createCodexAppServerAdapter({
     const threadKey = sessionId || runId;
     if (!threadKey) throw new Error('Codex model turn requires a session id.');
     const threadId = await ensureThread(threadKey, { model });
+    const baselineUsage = threadUsageTotals.get(threadId) || normalizeCompanionTokenUsage();
+    const transportSchema = outputSchema
+      ? codexTransportOutputSchema(outputSchema)
+      : null;
+    const transportPrompt = transportSchema
+      ? codexTransportPrompt(prompt)
+      : prompt;
 
     return new Promise((resolve, reject) => {
       let lastMessage = '';
+      const usageForTurn = () => codexUsageSince(
+        threadUsageTotals.get(threadId),
+        baselineUsage,
+      );
       const timer = setTimeout(() => {
         listeners.delete(listener);
         active.request(
@@ -461,7 +520,9 @@ export function createCodexAppServerAdapter({
           { threadId },
           { timeoutMs: 10000 },
         ).catch(() => undefined);
-        reject(new Error(`Codex turn timed out after ${timeoutMs}ms.`));
+        const error = new Error(`Codex turn timed out after ${timeoutMs}ms.`);
+        error.companionUsage = usageForTurn();
+        reject(error);
       }, timeoutMs);
 
       function finish(fn, value) {
@@ -488,7 +549,9 @@ export function createCodexAppServerAdapter({
           // 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)));
+          const error = new Error(codexTurnErrorMessage(event.params));
+          error.companionUsage = usageForTurn();
+          finish(reject, error);
           return;
         }
         if (event.method === CODEX_APP_SERVER_NOTIFICATIONS.turnCompleted) {
@@ -498,15 +561,24 @@ export function createCodexAppServerAdapter({
               turn,
               'Codex turn failed without an error message.',
             ));
-            error.companionUsage = normalizeUsage(turn);
+            error.companionUsage = usageForTurn();
             finish(reject, error);
             return;
           }
+          let decodedMessage = lastMessage;
+          if (transportSchema) {
+            try {
+              decodedMessage = decodeCodexTransportOutput(lastMessage);
+            } catch (error) {
+              finish(reject, error);
+              return;
+            }
+          }
           finish(resolve, {
-            text: lastMessage,
+            text: decodedMessage,
             threadId,
             turnId: turn.id || null,
-            ...normalizeUsage(turn),
+            ...usageForTurn(),
           });
         }
       }
@@ -518,9 +590,9 @@ export function createCodexAppServerAdapter({
           CODEX_APP_SERVER_METHODS.turnStart,
           {
             threadId,
-            input: [{ type: 'text', text: prompt }],
+            input: [{ type: 'text', text: transportPrompt }],
             ...(model ? { model } : {}),
-            ...(outputSchema ? { outputSchema } : {}),
+            ...(transportSchema ? { outputSchema: transportSchema } : {}),
           },
           { timeoutMs: 30000 },
         )
@@ -542,6 +614,7 @@ export function createCodexAppServerAdapter({
     const threadId = threadsByRun.get(sessionId);
     if (!threadId) return;
     threadsByRun.delete(sessionId);
+    threadUsageTotals.delete(threadId);
     if (!client || client.closed) return;
     await client.request(
       CODEX_APP_SERVER_METHODS.threadUnsubscribe,
@@ -556,11 +629,13 @@ export function createCodexAppServerAdapter({
       await client.request(CODEX_APP_SERVER_METHODS.logout, {}, { timeoutMs: 15000 });
     } finally {
       threadsByRun.clear();
+      threadUsageTotals.clear();
     }
   }
 
   function close() {
     threadsByRun.clear();
+    threadUsageTotals.clear();
     listeners.clear();
     client?.close();
     client = null;

package/src/providers/codexStructuredOutput.js

@@ -0,0 +1,143 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function finiteInteger(value) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function toolCallVariants(outputSchema) {
+  const items = outputSchema?.properties?.toolCalls?.items;
+  if (!isRecord(items)) return [];
+  return Array.isArray(items.anyOf)
+    ? items.anyOf.filter(isRecord)
+    : [items];
+}
+
+function toolNames(outputSchema) {
+  return Array.from(new Set(
+    toolCallVariants(outputSchema).flatMap((variant) => {
+      const names = variant?.properties?.name?.enum;
+      return Array.isArray(names)
+        ? names.filter((name) => typeof name === 'string' && name)
+        : [];
+    }),
+  ));
+}
+
+/**
+ * Codex App Server sends outputSchema through OpenAI Structured Outputs, whose
+ * supported JSON Schema subset requires closed objects with every property in
+ * `required`. Dexter's canonical tool schemas intentionally contain optional
+ * and open-ended fields, so they must not be embedded directly in that schema.
+ *
+ * Keep the strict response format as a transport envelope. The full canonical
+ * tool catalog remains in the prompt and the server validates decoded arguments
+ * before execution.
+ */
+export function codexTransportOutputSchema(outputSchema) {
+  if (!isRecord(outputSchema)) {
+    throw new Error('Codex model turn requires an output schema.');
+  }
+
+  const sourceToolCalls = outputSchema?.properties?.toolCalls;
+  const sourceFinishReason = outputSchema?.properties?.finishReason;
+  if (!isRecord(sourceToolCalls) || !isRecord(sourceFinishReason)) {
+    throw new Error('Codex model turn output schema is missing its response envelope.');
+  }
+
+  const names = toolNames(outputSchema);
+  const minItems = finiteInteger(sourceToolCalls.minItems);
+  const maxItems = finiteInteger(sourceToolCalls.maxItems);
+  const finishReasonEnum = Array.isArray(sourceFinishReason.enum)
+    ? sourceFinishReason.enum.filter((value) => typeof value === 'string')
+    : ['tool_calls', 'stop', 'length'];
+
+  return {
+    type: 'object',
+    properties: {
+      text: { type: 'string' },
+      toolCalls: {
+        type: 'array',
+        ...(minItems === undefined ? {} : { minItems }),
+        ...(maxItems === undefined ? {} : { maxItems }),
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            name: {
+              type: 'string',
+              ...(names.length ? { enum: names } : {}),
+            },
+            arguments: {
+              type: 'string',
+              description:
+                'A JSON-encoded object matching the selected Dexter tool schema.',
+            },
+          },
+          required: ['id', 'name', 'arguments'],
+          additionalProperties: false,
+        },
+      },
+      finishReason: {
+        type: 'string',
+        enum: finishReasonEnum.length
+          ? finishReasonEnum
+          : ['tool_calls', 'stop', 'length'],
+      },
+    },
+    required: ['text', 'toolCalls', 'finishReason'],
+    additionalProperties: false,
+  };
+}
+
+export function codexTransportPrompt(prompt) {
+  return [
+    String(prompt || ''),
+    '',
+    'Codex structured-output transport:',
+    'In the final JSON response, encode each toolCalls[].arguments value as a JSON string.',
+    'The decoded string must be one JSON object matching the exact selected tool schema in the Tools catalog.',
+    'Do not omit the id, name, arguments, text, toolCalls, or finishReason fields.',
+  ].join('\n');
+}
+
+export function decodeCodexTransportOutput(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text || '').trim());
+  } catch {
+    throw new Error('Codex returned malformed structured output.');
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.toolCalls)) {
+    throw new Error('Codex returned an invalid model-turn response envelope.');
+  }
+
+  const toolCalls = parsed.toolCalls.map((call, index) => {
+    if (!isRecord(call) || typeof call.arguments !== 'string') {
+      throw new Error(
+        `Codex tool call ${index + 1} did not use the JSON-string arguments transport.`,
+      );
+    }
+
+    let args;
+    try {
+      args = JSON.parse(call.arguments);
+    } catch {
+      throw new Error(`Codex tool call ${index + 1} contained malformed JSON arguments.`);
+    }
+    if (!isRecord(args)) {
+      throw new Error(`Codex tool call ${index + 1} arguments must decode to an object.`);
+    }
+    return {
+      ...call,
+      arguments: args,
+    };
+  });
+
+  return JSON.stringify({
+    ...parsed,
+    toolCalls,
+  });
+}