@gakim-digital/dexter-bridge 0.5.3 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.3",
+  "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/agent.js

@@ -45,7 +45,10 @@ function deltaModelSessionsEnabled(env = process.env) {
 }
 
 function companionSessionKey(run) {
-  return run?.modelTurn?.session?.sessionId || run?.turnId || run?.runId;
+  return run?.modelTurn?.session?.goalSessionId
+    || run?.modelTurn?.session?.sessionId
+    || run?.turnId
+    || run?.runId;
 }
 
 function rememberedCompanionSession(key) {
@@ -97,6 +100,10 @@ export const AGENT_DEFINITIONS = {
   },
 };
 
+export const AGENT_AUTHENTICATION_REQUIRED_CODE = 'DEXTER_AGENT_AUTHENTICATION_REQUIRED';
+export const CLAUDE_AUTHENTICATION_REQUIRED_MESSAGE =
+  'Claude Code sign-in has expired. Run `claude auth login` on this Mac, complete sign-in, then try again.';
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -173,7 +180,7 @@ function argsWithRequiredAgentFlags(args, definition) {
 
 const CLAUDE_CLI_MODEL_IDS = {
   fable: 'claude-fable-5',
-  opus: 'claude-opus-4-8',
+  opus: 'claude-opus-5',
   sonnet: 'claude-sonnet-5',
   haiku: 'claude-haiku-4-5-20251001',
 };
@@ -652,8 +659,18 @@ function runProcess(command, args, stdin, {
   trace,
   childEnv: providedChildEnv,
   platform = process.platform,
+  signal,
+  killGraceMs = 250,
 } = {}) {
   return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      const error = signal.reason instanceof Error
+        ? signal.reason
+        : new Error('The model process was cancelled.');
+      error.code = error.code || 'RUN_CANCELLED';
+      reject(error);
+      return;
+    }
     const started = Date.now();
     // timeoutMs is an inactivity timeout (reset whenever the child produces
     // output) so slow-but-streaming model turns are not killed mid-generation;
@@ -677,17 +694,59 @@ function runProcess(command, args, stdin, {
       env: childEnv,
       cwd,
       windowsHide: invocation.windowsHide,
+      detached: platform !== 'win32',
     });
     let stdout = '';
     let stderr = '';
     let settled = false;
     let inactivityTimer = null;
+    let forceKillTimer = null;
+    const killChildTree = (killSignal) => {
+      if (platform !== 'win32' && child.pid) {
+        try {
+          process.kill(-child.pid, killSignal);
+          return;
+        } catch {
+          // Fall back to the direct child when the process group is already gone.
+        }
+      }
+      try {
+        child.kill(killSignal);
+      } catch {
+        // The child already exited.
+      }
+    };
+    const clearTimers = () => {
+      clearTimeout(inactivityTimer);
+      clearTimeout(deadlineTimer);
+    };
+    const terminateChildTree = () => {
+      killChildTree('SIGTERM');
+      forceKillTimer = setTimeout(() => killChildTree('SIGKILL'), killGraceMs);
+      forceKillTimer.unref?.();
+    };
+    const abort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      terminateChildTree();
+      const error = signal?.reason instanceof Error
+        ? signal.reason
+        : new Error('The model process was cancelled.');
+      error.code = error.code || 'RUN_CANCELLED';
+      error.stdout = stdout;
+      error.stderr = stderr;
+      trace?.info('agent_process_cancelled', {
+        command,
+        durationMs: Date.now() - started,
+      });
+      reject(error);
+    };
     const timeOut = (message) => {
       if (settled) return;
       settled = true;
-      clearTimeout(inactivityTimer);
-      clearTimeout(deadlineTimer);
-      child.kill('SIGTERM');
+      clearTimers();
+      terminateChildTree();
       const error = new Error(message);
       error.code = 'AGENT_TIMEOUT';
       error.stdout = stdout;
@@ -714,6 +773,7 @@ function runProcess(command, args, stdin, {
     const deadlineTimer = setTimeout(() => {
       timeOut(`${command} timed out after ${hardDeadlineMs}ms.`);
     }, hardDeadlineMs);
+    signal?.addEventListener('abort', abort, { once: true });
     armInactivityTimer();
 
     child.stdout.on('data', (chunk) => {
@@ -727,8 +787,9 @@ function runProcess(command, args, stdin, {
     child.on('error', (error) => {
       if (settled) return;
       settled = true;
-      clearTimeout(inactivityTimer);
-      clearTimeout(deadlineTimer);
+      clearTimers();
+      clearTimeout(forceKillTimer);
+      signal?.removeEventListener('abort', abort);
       trace?.error('agent_process_error', {
         command,
         durationMs: Date.now() - started,
@@ -739,8 +800,9 @@ function runProcess(command, args, stdin, {
     child.on('close', (code) => {
       if (settled) return;
       settled = true;
-      clearTimeout(inactivityTimer);
-      clearTimeout(deadlineTimer);
+      clearTimers();
+      clearTimeout(forceKillTimer);
+      signal?.removeEventListener('abort', abort);
       const meta = {
         command,
         code,
@@ -825,7 +887,7 @@ class CompanionRunCancelledError extends Error {
 async function callProviderAdapter(adapter, input, {
   send,
   trace,
-  controlPollMs = 5000,
+  controlPollMs = 250,
 } = {}) {
   if (!adapter || typeof adapter.runModelTurn !== 'function') {
     throw new Error('The selected provider adapter cannot execute model turns.');
@@ -910,6 +972,83 @@ export async function resolveAgentRuntime(definition, modelDefinition, options =
   return selectAgentRuntime(inspections, definition, modelDefinition);
 }
 
+function parseClaudeAuthenticationStatus(output) {
+  const text = String(output || '').trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    return {
+      loggedIn: parsed.loggedIn === true,
+      authMethod: typeof parsed.authMethod === 'string' ? parsed.authMethod : null,
+      apiProvider: typeof parsed.apiProvider === 'string' ? parsed.apiProvider : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function inspectClaudeAuthentication(command, { childEnv, platform } = {}) {
+  try {
+    const result = await runProcess(command, ['auth', 'status', '--json'], '', {
+      timeoutMs: 10000,
+      childEnv,
+      platform,
+    });
+    return parseClaudeAuthenticationStatus(result.stdout || result.stderr);
+  } catch (error) {
+    const parsed = parseClaudeAuthenticationStatus(error?.stdout || error?.stderr);
+    if (parsed) return parsed;
+    throw error;
+  }
+}
+
+export async function checkAgentAuthentication(agent, runtime, options = {}) {
+  const normalizedAgent = normalizeAgentName(agent);
+  if (normalizedAgent !== 'claude-code') {
+    return {
+      ok: true,
+      signedIn: true,
+      status: 'ready',
+    };
+  }
+  if (!runtime?.ok || !runtime.command) {
+    return {
+      ok: false,
+      signedIn: false,
+      status: 'unavailable',
+      code: runtime?.code,
+      error: runtime?.error || 'Claude Code is not available.',
+    };
+  }
+
+  const platform = options.platform || process.platform;
+  const childEnv = options.env || processEnvWithCliPath(platform);
+  const inspect = options.inspect || inspectClaudeAuthentication;
+  try {
+    const authentication = await inspect(runtime.command, { childEnv, platform });
+    if (authentication?.loggedIn === true) {
+      return {
+        ok: true,
+        signedIn: true,
+        status: 'ready',
+        authMethod: authentication.authMethod || null,
+        apiProvider: authentication.apiProvider || null,
+      };
+    }
+  } catch {
+    // A failed or unreadable auth-status probe is not healthy enough to start a run.
+  }
+
+  return {
+    ok: false,
+    signedIn: false,
+    status: 'authentication_required',
+    code: AGENT_AUTHENTICATION_REQUIRED_CODE,
+    error: CLAUDE_AUTHENTICATION_REQUIRED_MESSAGE,
+  };
+}
+
 async function callLocalJsonAgent(agent, prompt, options = {}) {
   const definition = definitionForAgent(agent);
   const command = options.runtime?.command || commandFromEnv(definition.commandEnv, definition.fallbackCommand);
@@ -942,6 +1081,7 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
     timeoutMs,
     maxDurationMs,
     trace: options.trace,
+    signal: options.signal,
   });
 }
 
@@ -1069,9 +1209,9 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
       trace: options.trace,
       controlPollMs: boundedDurationMs(
         options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
-        5000,
-        10,
-        30000,
+        250,
+        50,
+        1000,
       ),
     };
     let result;
@@ -1098,7 +1238,7 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
     resultText = result?.text;
     providerSessionId = result?.threadId || result?.sessionId;
   } else {
-    const runtime = await resolveAgentRuntime(definition, selectedModel, {
+    const runtime = options.runtime || await resolveAgentRuntime(definition, selectedModel, {
       env: options.env,
     });
     if (!runtime.ok) {
@@ -1109,6 +1249,41 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
       && agentSessionResumeEnabled(definition, options.env)
         ? rememberedSession?.providerSessionId
         : undefined;
+    const cliAbort = new AbortController();
+    const monitorAbort = new AbortController();
+    const controlPollMs = boundedDurationMs(
+      options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
+      250,
+      50,
+      1000,
+    );
+    let cliFinished = false;
+    let cliCancelled = false;
+    const controlMonitor = (async () => {
+      while (!cliFinished && !monitorAbort.signal.aborted) {
+        try {
+          await waitForControl(controlPollMs, monitorAbort.signal);
+          if (cliFinished || monitorAbort.signal.aborted) return;
+          const response = await send('activity', {
+            stage: 'model_turn',
+            message: `${definition.label} is still generating the next Dexter action.`,
+          });
+          if (controlRequestsCancellation(response)) {
+            cliCancelled = true;
+            cliAbort.abort(Object.assign(
+              new Error('The Dexter companion model turn was cancelled.'),
+              { code: 'RUN_CANCELLED' },
+            ));
+            return;
+          }
+        } catch (error) {
+          if (monitorAbort.signal.aborted) return;
+          options.trace?.warn('cli_control_poll_failed', {
+            error: errorMeta(error),
+          });
+        }
+      }
+    })();
     let result;
     try {
       result = await callLocalJsonAgent(definition.id, prompt, {
@@ -1119,8 +1294,12 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         outputSchema: modelTurnOutputSchema(run.modelTurn),
         step: run?.modelTurn?.step,
         maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+        signal: cliAbort.signal,
       });
     } catch (error) {
+      if (cliCancelled || error?.code === 'RUN_CANCELLED') {
+        throw new CompanionRunCancelledError();
+      }
       const failure = agentErrorWithOutputUsage(definition.id, error);
       if (callContextMode !== 'delta' || !resumeFailure(failure)) throw failedModelCall(failure);
       usageAccumulator.add(failure.companionUsage || {});
@@ -1140,9 +1319,17 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         outputSchema: modelTurnOutputSchema(run.modelTurn),
         step: run?.modelTurn?.step,
         maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+        signal: cliAbort.signal,
       }).catch((error) => {
+        if (cliCancelled || error?.code === 'RUN_CANCELLED') {
+          throw new CompanionRunCancelledError();
+        }
         throw failedModelCall(agentErrorWithOutputUsage(definition.id, error));
       });
+    } finally {
+      cliFinished = true;
+      monitorAbort.abort();
+      await controlMonitor.catch(() => undefined);
     }
     const parsed = parseAgentOutput(definition.id, result.stdout);
     usageAccumulator.add(parsed);
@@ -1209,6 +1396,7 @@ export async function executeRun(run, {
   adapterOptions,
   env = process.env,
   controlPollMs,
+  inspectAgentAuthentication,
 } = {}) {
   if (!run?.runId) throw new Error('Companion run payload is missing runId.');
   if (run?.protocol?.version !== 'dexter-companion-v4') {
@@ -1266,10 +1454,33 @@ export async function executeRun(run, {
   });
 
   try {
+    let runtime;
+    if (!activeAdapter && normalizedAgent !== 'dry-run') {
+      const definition = definitionForAgent(normalizedAgent);
+      const selectedModelDefinition = companionModelDefinition(runModel, normalizedAgent);
+      runtime = await resolveAgentRuntime(definition, selectedModelDefinition, { env });
+      if (!runtime.ok) {
+        throw Object.assign(
+          new Error(runtime.error || `${definition.label} is not available.`),
+          { code: runtime.code },
+        );
+      }
+      const authentication = await checkAgentAuthentication(normalizedAgent, runtime, {
+        env,
+        inspect: inspectAgentAuthentication,
+      });
+      if (!authentication.ok) {
+        throw Object.assign(new Error(authentication.error), {
+          code: authentication.code,
+          status: authentication.status,
+        });
+      }
+    }
     await executeModelTurnRun(run, send, normalizedAgent, {
       model: runModel || selectedModel,
       selectedModel: runModel || selectedModel,
       providerAdapter: activeAdapter,
+      runtime,
       trace,
       env,
       controlPollMs,
@@ -1322,21 +1533,46 @@ export async function checkAgentAvailability(agent, model, options = {}) {
       command: 'dry-run',
       output: 'debug mode',
       models: ['dry-run:default'],
+      installed: true,
+      signedIn: true,
+      status: 'ready',
     };
   }
   const definition = definitionForAgent(normalizedAgent);
   const selectedModel = model ? companionModelDefinition(model?.id || model, normalizedAgent) : undefined;
   const runtime = await resolveAgentRuntime(definition, selectedModel, {
     env: options.env,
+    platform: options.platform,
+    existsSync: options.existsSync,
+    inspect: options.inspectRuntime,
   });
   const supportedModels = companionModelsForAgent(normalizedAgent)
     .filter((candidate) => modelSupportsAgentVersion(candidate, runtime.version))
     .map((candidate) => candidate.id);
+  if (!runtime.ok) {
+    return {
+      ...runtime,
+      agent: definition.id,
+      label: definition.label,
+      models: supportedModels,
+      installed: false,
+      signedIn: false,
+      status: 'unavailable',
+    };
+  }
+  const authentication = await checkAgentAuthentication(normalizedAgent, runtime, {
+    env: options.env,
+    platform: options.platform,
+    inspect: options.inspectAuthentication,
+  });
   return {
     ...runtime,
+    ...authentication,
+    ok: runtime.ok && authentication.ok,
     agent: definition.id,
     label: definition.label,
     models: supportedModels,
+    installed: true,
   };
 }
 

package/src/cli.js

@@ -1,7 +1,9 @@
 import os from 'node:os';
 import readline from 'node:readline/promises';
 import {
+  BRIDGE_BUILD_FINGERPRINT,
   BRIDGE_CAPABILITIES,
+  BRIDGE_VERSION,
   clearConfig,
   defaultConfigDir,
   normalizeAgentName,
@@ -12,7 +14,12 @@ import {
   saveConfigPatch,
 } from './config.js';
 import { checkAllAgents, executeRun } from './agent.js';
-import { claimPairing, heartbeat, pollRun } from './api.js';
+import {
+  claimPairing,
+  DexterBridgeApiError,
+  heartbeat,
+  pollRun,
+} from './api.js';
 import {
   createRunLogger,
   errorMeta,
@@ -106,6 +113,30 @@ function wait(delayMs) {
   return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
 
+function isInvalidPairingError(error) {
+  return error instanceof DexterBridgeApiError
+    && error.status === 401
+    && (
+      error.body?.code === 'FRAMER_COMPANION_NOT_PAIRED'
+      || /not paired|pair again/i.test(error.message)
+    );
+}
+
+function clearInvalidPairing(configDir, cause) {
+  saveConfigPatch({
+    deviceToken: null,
+    device: null,
+    pairedAt: null,
+  }, configDir);
+  const error = new Error(
+    'This Dexter Bridge pairing was disconnected. Reopen Dexter and run the new pairing command.',
+    { cause },
+  );
+  error.code = 'FRAMER_COMPANION_NOT_PAIRED';
+  error.exitCode = 2;
+  return error;
+}
+
 function agentEnvironment(config = {}, baseEnv = process.env) {
   const env = { ...baseEnv };
   const commands = config.agentCommands && typeof config.agentCommands === 'object'
@@ -130,6 +161,8 @@ async function inspectAvailability(config = {}) {
         availableModels: available.flatMap((check) => check.models || []).join(','),
         agentVersions: available.map((check) => `${check.agent}=${check.version || 'unknown'}`).join(','),
         bridgeCapabilities: BRIDGE_CAPABILITIES.join(','),
+        bridgeVersion: BRIDGE_VERSION,
+        bridgeBuildFingerprint: BRIDGE_BUILD_FINGERPRINT,
       },
       agentCommands: Object.fromEntries(
         available
@@ -139,7 +172,11 @@ async function inspectAvailability(config = {}) {
     };
   } catch {
     return {
-      metadata: { bridgeCapabilities: BRIDGE_CAPABILITIES.join(',') },
+      metadata: {
+        bridgeCapabilities: BRIDGE_CAPABILITIES.join(','),
+        bridgeVersion: BRIDGE_VERSION,
+        bridgeBuildFingerprint: BRIDGE_BUILD_FINGERPRINT,
+      },
       agentCommands: {},
     };
   }
@@ -178,17 +215,23 @@ async function pairCommand({ apiBaseUrl, args, flags, configDir }) {
   console.log(`API: ${apiBaseUrl}`);
 }
 
-async function statusCommand({ apiBaseUrl, config }) {
+async function statusCommand({ apiBaseUrl, config, configDir }) {
   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),
-  });
+  let result;
+  try {
+    result = await heartbeat(apiBaseUrl, {
+      deviceToken,
+      status: 'ready',
+      agent,
+      model,
+      metadata: await availabilityMetadata(config),
+    });
+  } catch (error) {
+    if (isInvalidPairingError(error)) throw clearInvalidPairing(configDir, error);
+    throw error;
+  }
   console.log(`Status: ${result.device?.online ? 'online' : 'paired'}`);
   console.log(`Device: ${result.device?.name || 'Dexter Bridge'}`);
   console.log(`Model: ${result.device?.model?.displayName || model}`);
@@ -240,6 +283,13 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
         poll = await pollRun(apiBaseUrl, { deviceToken, waitMs, agent, model, metadata });
         pollFailureCount = 0;
       } catch (error) {
+        if (isInvalidPairingError(error)) {
+          pollLogger.warn('pairing_invalidated', {
+            status: error.status,
+            code: error.body?.code || null,
+          });
+          throw clearInvalidPairing(configDir, error);
+        }
         if (once) throw error;
         pollFailureCount += 1;
         const retryInMs = pollBackoffMs(pollFailureCount);
@@ -320,7 +370,7 @@ export async function runCli(argv) {
       await startCommand({ apiBaseUrl, config: { ...config, apiBaseUrl }, flags: parsed.flags, configDir });
       return;
     case 'status':
-      await statusCommand({ apiBaseUrl, config });
+      await statusCommand({ apiBaseUrl, config, configDir });
       return;
     case 'doctor':
       await doctorCommand();
@@ -334,4 +384,11 @@ export async function runCli(argv) {
   }
 }
 
-export const __private__ = { agentEnvironment, parseArgv, pollBackoffMs, usage };
+export const __private__ = {
+  agentEnvironment,
+  clearInvalidPairing,
+  isInvalidPairingError,
+  parseArgv,
+  pollBackoffMs,
+  usage,
+};

package/src/config.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import crypto from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -6,8 +7,25 @@ export const DEFAULT_API_BASE_URL = 'http://localhost:3800/iwm-api/0.0.1';
 export const BRIDGE_VERSION = JSON.parse(
   fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
 ).version;
+export const BRIDGE_BUILD_FINGERPRINT = crypto
+  .createHash('sha256')
+  .update([
+    '../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')}`;
+  }).join('\u0000'))
+  .digest('hex');
 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
@@ -30,10 +48,10 @@ export const COMPANION_MODEL_DEFINITIONS = [
     id: 'claude-code:opus',
     agent: 'claude-code',
     provider: 'anthropic',
-    displayName: 'Claude Opus 4.8',
-    invocationName: 'claude-opus-4-8',
+    displayName: 'Claude Opus 5',
+    invocationName: 'claude-opus-5',
     costTier: '$$$',
-    description: 'Latest Opus-class model via Claude Code.',
+    description: 'Powerful reasoning and long-horizon coding via Claude Code.',
   },
   {
     id: 'claude-code:sonnet',

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);
 }
@@ -82,23 +128,48 @@ function compactMessages(messages = [], limit = 64) {
     : [];
 }
 
-function modelTurnInstructions() {
+function normalizedToolChoice(modelTurn = {}) {
+  const toolChoice = modelTurn?.toolChoice;
+  if (toolChoice === 'required') {
+    return { required: true, toolName: null };
+  }
+  if (
+    toolChoice
+    && typeof toolChoice === 'object'
+    && typeof toolChoice.name === 'string'
+    && toolChoice.name.trim()
+  ) {
+    return {
+      required: true,
+      toolName: toolChoice.name.trim(),
+    };
+  }
+  return { required: false, toolName: null };
+}
+
+function modelTurnInstructions(modelTurn = {}) {
+  const toolChoice = normalizedToolChoice(modelTurn);
   return [
     '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.',
-    'When the task is complete, return toolCalls:[] and finishReason:"stop".',
+    toolChoice.required
+      ? toolChoice.toolName
+        ? `This turn must call the "${toolChoice.toolName}" tool. Return at least one tool call and finishReason:"tool_calls".`
+        : 'This turn requires a structured tool decision. Return at least one tool call and finishReason:"tool_calls"; do not return plain text only.'
+      : 'When the task is complete, return toolCalls:[] and finishReason:"stop".',
   ];
 }
 
 export function buildModelTurnPrompt(modelTurn = {}) {
+  assertToolCatalogParity(modelTurn);
   const messages = compactMessages(modelTurn.messages, 64);
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
   return [
-    ...modelTurnInstructions(),
+    ...modelTurnInstructions(modelTurn),
     '',
     `Tools:\n${JSON.stringify(tools)}`,
     '',
@@ -107,15 +178,24 @@ 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
     ? compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : [])
     : [];
+  const toolChoice = normalizedToolChoice(modelTurn);
   return [
     'Continue the existing Dexter model session. The server has already supplied the doctrine, goal, prior messages, and tool catalog.',
     'Apply only the new canonical messages/state changes below.',
     'Return exactly one JSON object using the previously established response contract.',
+    ...(toolChoice.required
+      ? [
+          toolChoice.toolName
+            ? `This turn must call the "${toolChoice.toolName}" tool and finish with "tool_calls".`
+            : 'This turn requires at least one structured tool call and must finish with "tool_calls".',
+        ]
+      : []),
     ...(includeTools ? ['', `Updated tools:\n${JSON.stringify(tools)}`] : []),
     '',
     `New messages:\n${JSON.stringify(messages)}`,
@@ -135,40 +215,69 @@ export function buildModelTurnFallbackPrompt(modelTurn = {}) {
 }
 
 export function modelTurnOutputSchema(modelTurn = {}) {
+  assertToolCatalogParity(modelTurn);
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
-  const toolNames = tools.map((tool) => tool.name);
-  return {
+  const toolChoice = normalizedToolChoice(modelTurn);
+  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',
-        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,
-        },
+        ...(toolChoice.required ? { minItems: 1 } : {}),
+        maxItems: selectedTools.length ? 12 : 0,
+        items:
+          toolCallVariants.length === 1
+            ? toolCallVariants[0]
+            : toolCallVariants.length > 1
+              ? { anyOf: toolCallVariants }
+              : emptyToolCall,
       },
       finishReason: {
         type: 'string',
-        enum: ['tool_calls', 'stop', 'length'],
+        enum: toolChoice.required
+          ? ['tool_calls']
+          : ['tool_calls', 'stop', 'length'],
       },
     },
     required: ['text', 'toolCalls', 'finishReason'],
     additionalProperties: false,
   };
+  if (Object.keys(definitions).length) output.$defs = definitions;
+  return output;
 }
 
 export function normalizeModelTurnCompletion(raw, fallbackModel = 'local-companion') {
@@ -181,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}`,