@gakim-digital/dexter-bridge 0.5.6 → 0.5.7

package/package.json

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

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}`,