@gakim-digital/dexter-bridge 0.5.6 → 0.5.8

package/package.json

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

package/src/agent.js

@@ -108,45 +108,81 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+const TERMINAL_EVENT_TYPES = new Set(['done', 'error']);
+const TERMINAL_EVENT_MAX_ATTEMPTS = 5;
+
+function waitForRetry(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function terminalEventRetryDelay(error, attempt) {
+  const status = Number(error?.status);
+  const retryable =
+    !Number.isFinite(status)
+    || status === 408
+    || status === 429
+    || status >= 500;
+  if (!retryable) return null;
+  if (Number.isFinite(error?.retryAfterMs) && error.retryAfterMs > 0) {
+    return Math.min(65_000, Math.max(250, error.retryAfterMs));
+  }
+  return Math.min(8_000, 500 * (2 ** (attempt - 1)));
+}
+
 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', {
+    const maxAttempts = TERMINAL_EVENT_TYPES.has(type)
+      ? TERMINAL_EVENT_MAX_ATTEMPTS
+      : 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      trace?.info('event_post_start', {
         type,
         eventId,
-        durationMs: Date.now() - started,
-        error: errorMeta(error),
+        attempt,
+        payload: summarizePayload(payload),
       });
-      throw error;
+      try {
+        const response = await postRunEvent(apiBaseUrl, {
+          deviceToken,
+          runId: run.runId,
+          fetchImpl,
+          event: {
+            type,
+            eventId,
+            payload,
+          },
+        });
+        trace?.info('event_post_done', {
+          type,
+          eventId,
+          attempt,
+          durationMs: Date.now() - started,
+          accepted: response?.accepted,
+          status: response?.status,
+          hasToolResult: Boolean(response?.toolResult),
+          toolResult: summarizeToolResult(response?.toolResult),
+        });
+        return response;
+      } catch (error) {
+        const retryDelayMs =
+          attempt < maxAttempts
+            ? terminalEventRetryDelay(error, attempt)
+            : null;
+        trace?.error('event_post_failed', {
+          type,
+          eventId,
+          attempt,
+          durationMs: Date.now() - started,
+          retryDelayMs,
+          error: errorMeta(error),
+        });
+        if (retryDelayMs === null) throw error;
+        await waitForRetry(retryDelayMs);
+      }
     }
+    throw new Error(`Unable to deliver ${type} event.`);
   };
 }
 
@@ -887,7 +923,7 @@ class CompanionRunCancelledError extends Error {
 async function callProviderAdapter(adapter, input, {
   send,
   trace,
-  controlPollMs = 250,
+  controlPollMs = 5_000,
 } = {}) {
   if (!adapter || typeof adapter.runModelTurn !== 'function') {
     throw new Error('The selected provider adapter cannot execute model turns.');
@@ -1209,9 +1245,9 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
       trace: options.trace,
       controlPollMs: boundedDurationMs(
         options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
-        250,
-        50,
-        1000,
+        5_000,
+        1_000,
+        30_000,
       ),
     };
     let result;
@@ -1253,9 +1289,9 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
     const monitorAbort = new AbortController();
     const controlPollMs = boundedDurationMs(
       options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
-      250,
-      50,
-      1000,
+      5_000,
+      1_000,
+      30_000,
     );
     let cliFinished = false;
     let cliCancelled = false;

package/src/api.js

@@ -7,11 +7,12 @@ import {
 } from './config.js';
 
 export class DexterBridgeApiError extends Error {
-  constructor(message, status, body) {
+  constructor(message, status, body, retryAfterMs) {
     super(message);
     this.name = 'DexterBridgeApiError';
     this.status = status;
     this.body = body;
+    this.retryAfterMs = retryAfterMs;
   }
 }
 
@@ -50,10 +51,18 @@ export async function requestJson(apiBaseUrl, path, {
   });
   const parsed = await response.json().catch(() => null);
   if (!response.ok || parsed?.success === false) {
+    const retryAfterHeader = Number(response.headers?.get?.('retry-after'));
+    const retryAfterSeconds = Number(parsed?.retryAfterSeconds);
+    const retryAfterMs = Number.isFinite(retryAfterHeader) && retryAfterHeader > 0
+      ? retryAfterHeader * 1000
+      : Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? retryAfterSeconds * 1000
+        : undefined;
     throw new DexterBridgeApiError(
       parsed?.error || parsed?.message || `Dexter API request failed with status ${response.status}`,
       response.status,
       parsed,
+      retryAfterMs,
     );
   }
   return parsed;

package/src/config.js

@@ -13,8 +13,10 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
     '../package.json',
     './agent.js',
     './agentOutput.js',
+    './api.js',
     './cli.js',
     './config.js',
+    './protocol.js',
   ].map((relativePath) => {
     const url = new URL(relativePath, import.meta.url);
     return `${relativePath}\u0000${fs.readFileSync(url, 'utf8')}`;
@@ -23,6 +25,7 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
 export const BRIDGE_CAPABILITIES = [
   'model-turn-v1',
   'build-fingerprint-v1',
+  'tool-schema-parity-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

package/src/protocol.js

@@ -1,27 +1,73 @@
+import { createHash } from 'node:crypto';
+
 function isRecord(value) {
   return value && typeof value === 'object' && !Array.isArray(value);
 }
 
-function shortText(value, max = 360) {
-  const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
-  return text.length > max ? `${text.slice(0, max)}...[truncated ${text.length - max} chars]` : text;
+function toolCatalogDigest(tools) {
+  return createHash('sha256')
+    .update(JSON.stringify(tools))
+    .digest('hex')
+    .slice(0, 24);
 }
 
-function compactSchema(schema, depth = 0) {
-  if (!isRecord(schema) || depth > 4) return schema;
-  const result = {};
-  for (const key of ['type', 'enum', 'required', 'additionalProperties']) {
-    if (schema[key] !== undefined) result[key] = schema[key];
+export function assertToolCatalogParity(modelTurn = {}) {
+  const tools = Array.isArray(modelTurn.tools) ? modelTurn.tools : [];
+  const expected = modelTurn?.session?.toolCatalogHash;
+  if (!expected) return toolCatalogDigest(tools);
+  const actual = toolCatalogDigest(tools);
+  if (actual !== expected) {
+    throw Object.assign(
+      new Error(
+        `Dexter tool schema parity failed: expected ${expected}, received ${actual}.`,
+      ),
+      {
+        code: 'TOOL_SCHEMA_PARITY_ERROR',
+        expectedToolCatalogHash: expected,
+        actualToolCatalogHash: actual,
+      },
+    );
   }
-  if (isRecord(schema.properties)) {
-    result.properties = Object.fromEntries(
-      Object.entries(schema.properties)
-        .slice(0, 40)
-        .map(([key, value]) => [key, compactSchema(value, depth + 1)]),
+  return actual;
+}
+
+function toolParameters(tool) {
+  return isRecord(tool?.parameters)
+    ? tool.parameters
+    : {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      };
+}
+
+function nestedToolParameters(schema, namespace, outputDefinitions) {
+  const source = JSON.parse(JSON.stringify(schema));
+  delete source.$schema;
+  const localDefinitions = {
+    ...(isRecord(source.definitions) ? source.definitions : {}),
+    ...(isRecord(source.$defs) ? source.$defs : {}),
+  };
+  delete source.definitions;
+  delete source.$defs;
+  const prefix = `${namespace}__`;
+  const rewrite = (value) => {
+    if (Array.isArray(value)) return value.map(rewrite);
+    if (!isRecord(value)) return value;
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => {
+        if (key === '$ref' && typeof nested === 'string') {
+          const match = nested.match(/^#\/(?:definitions|\$defs)\/(.+)$/);
+          if (match) return [key, `#/$defs/${prefix}${match[1]}`];
+        }
+        return [key, rewrite(nested)];
+      }),
     );
+  };
+  for (const [name, definition] of Object.entries(localDefinitions)) {
+    outputDefinitions[`${prefix}${name}`] = rewrite(definition);
   }
-  if (schema.items !== undefined) result.items = compactSchema(schema.items, depth + 1);
-  return result;
+  return rewrite(source);
 }
 
 function compactModelTurnContent(content) {
@@ -65,8 +111,8 @@ export function compactToolCatalog(tools = []) {
     .slice(0, 40)
     .map((tool) => ({
       name: typeof tool.name === 'string' ? tool.name : '',
-      description: shortText(tool.description || '', 360),
-      parameters: compactSchema(tool.parameters),
+      description: typeof tool.description === 'string' ? tool.description : '',
+      parameters: toolParameters(tool),
     }))
     .filter((tool) => tool.name);
 }
@@ -107,8 +153,8 @@ function modelTurnInstructions(modelTurn = {}) {
     'You are the model engine for Dexter. The server owns the agent loop and executes all tools.',
     'Return exactly one JSON object and no markdown.',
     'Allowed response:',
-    '{"text":"optional assistant text","toolCalls":[{"id":"stable-id","name":"toolName","arguments":"{\\"key\\":\\"value\\"}"}],"finishReason":"tool_calls|stop|length"}',
-    'Each toolCalls[].arguments value must be a JSON-encoded string whose decoded value is an object.',
+    '{"text":"optional assistant text","toolCalls":[{"id":"stable-id","name":"toolName","arguments":{"key":"value"}}],"finishReason":"tool_calls|stop|length"}',
+    'Each toolCalls[].arguments value must be an object matching the exact selected tool schema.',
     'Use only tools listed below. Do not claim a tool executed; only request it.',
     toolChoice.required
       ? toolChoice.toolName
@@ -119,6 +165,7 @@ function modelTurnInstructions(modelTurn = {}) {
 }
 
 export function buildModelTurnPrompt(modelTurn = {}) {
+  assertToolCatalogParity(modelTurn);
   const messages = compactMessages(modelTurn.messages, 64);
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
   return [
@@ -131,6 +178,7 @@ export function buildModelTurnPrompt(modelTurn = {}) {
 }
 
 export function buildModelTurnDeltaPrompt(modelTurn = {}) {
+  assertToolCatalogParity(modelTurn);
   const messages = compactMessages(modelTurn.messages, 24);
   const includeTools = modelTurn?.session?.toolCatalogChanged === true;
   const tools = includeTools
@@ -167,37 +215,56 @@ export function buildModelTurnFallbackPrompt(modelTurn = {}) {
 }
 
 export function modelTurnOutputSchema(modelTurn = {}) {
+  assertToolCatalogParity(modelTurn);
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
   const toolChoice = normalizedToolChoice(modelTurn);
-  const availableToolNames = tools.map((tool) => tool.name);
-  const toolNames =
-    toolChoice.toolName && availableToolNames.includes(toolChoice.toolName)
-      ? [toolChoice.toolName]
-      : availableToolNames;
-  return {
+  const selectedTools =
+    toolChoice.toolName
+      ? tools.filter((tool) => tool.name === toolChoice.toolName)
+      : tools;
+  const definitions = {};
+  const toolCallVariants = selectedTools.map((tool, index) => ({
+    type: 'object',
+    properties: {
+      id: { type: 'string' },
+      name: { type: 'string', enum: [tool.name] },
+      arguments: nestedToolParameters(
+        tool.parameters,
+        `tool_${index}_${tool.name.replace(/[^A-Za-z0-9_]/g, '_')}`,
+        definitions,
+      ),
+    },
+    required: ['id', 'name', 'arguments'],
+    additionalProperties: false,
+  }));
+  const emptyToolCall = {
+    type: 'object',
+    properties: {
+      id: { type: 'string' },
+      name: { type: 'string' },
+      arguments: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    },
+    required: ['id', 'name', 'arguments'],
+    additionalProperties: false,
+  };
+  const output = {
     type: 'object',
     properties: {
       text: { type: 'string' },
       toolCalls: {
         type: 'array',
         ...(toolChoice.required ? { minItems: 1 } : {}),
-        maxItems: toolNames.length ? 12 : 0,
-        items: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-            name: toolNames.length
-              ? { type: 'string', enum: toolNames }
-              : { type: 'string' },
-            // Structured Outputs requires every object schema to declare
-            // additionalProperties:false. Tool argument shapes differ per
-            // selected tool, so encode them at this boundary and validate the
-            // decoded object before returning the completion to Dexter.
-            arguments: { type: 'string' },
-          },
-          required: ['id', 'name', 'arguments'],
-          additionalProperties: false,
-        },
+        maxItems: selectedTools.length ? 12 : 0,
+        items:
+          toolCallVariants.length === 1
+            ? toolCallVariants[0]
+            : toolCallVariants.length > 1
+              ? { anyOf: toolCallVariants }
+              : emptyToolCall,
       },
       finishReason: {
         type: 'string',
@@ -209,6 +276,8 @@ export function modelTurnOutputSchema(modelTurn = {}) {
     required: ['text', 'toolCalls', 'finishReason'],
     additionalProperties: false,
   };
+  if (Object.keys(definitions).length) output.$defs = definitions;
+  return output;
 }
 
 export function normalizeModelTurnCompletion(raw, fallbackModel = 'local-companion') {
@@ -221,16 +290,9 @@ export function normalizeModelTurnCompletion(raw, fallbackModel = 'local-compani
       if (!isRecord(call) || typeof call.name !== 'string' || !call.name.trim()) {
         throw new Error(`Model turn tool call ${index + 1} is missing a name.`);
       }
-      let toolArguments = call.arguments;
-      if (typeof toolArguments === 'string') {
-        try {
-          toolArguments = JSON.parse(toolArguments);
-        } catch {
-          throw new Error(`Model turn tool call ${index + 1} arguments must contain valid JSON.`);
-        }
-      }
+      const toolArguments = call.arguments;
       if (toolArguments !== undefined && !isRecord(toolArguments)) {
-        throw new Error(`Model turn tool call ${index + 1} arguments must decode to an object.`);
+        throw new Error(`Model turn tool call ${index + 1} arguments must be an object.`);
       }
       return {
         id: typeof call.id === 'string' && call.id.trim() ? call.id.slice(0, 160) : `local_tool_${index + 1}`,