@gakim-digital/dexter-bridge 0.5.0 → 0.5.3

package/README.md

@@ -75,14 +75,30 @@ The CLI stores the device token in `~/.dexter-bridge/config.json` with mode
 credits are not charged for companion runs; the backend records reported usage
 for visibility.
 
-Claude Code runs use `--output-format json` and Codex runs use `--json` so the
-bridge can report input, output, cache, and reasoning tokens when the local CLI
-provides them. Claude's reported `total_cost_usd` is displayed as an estimated
+Claude Code is launched as a model-only engine: local tools, slash commands,
+MCP integrations, browser access, and project-agent context are disabled. The
+bridge supplies a strict JSON schema and a system prompt that requires Dexter
+tool requests to be returned as structured output instead of being executed
+inside Claude Code.
+
+Claude Code runs use streaming JSON and Codex runs use JSONL so the bridge can
+report input, output, cache, and reasoning tokens even when a turn is
+interrupted. Claude's reported `total_cost_usd` is displayed as an estimated
 API-equivalent cost, not an amount Dexter charged. If an older or customized
 CLI does not support structured output, set `DEXTER_BRIDGE_STRUCTURED_USAGE=false`;
 the run will continue, but its token usage will be marked unavailable rather
 than estimated from text.
 
+`DEXTER_BRIDGE_AGENT_TIMEOUT_MS` is the inactivity limit and resets whenever
+the local model produces output. `DEXTER_BRIDGE_AGENT_MAX_DURATION_MS` is the
+hard wall-clock ceiling; the API may supply a smaller per-turn ceiling from the
+remaining run budget. Claude defaults to low effort for the intent-planner lane
+and follow-up/recovery turns, and medium effort for the opening design turn.
+Override these with `DEXTER_BRIDGE_CLAUDE_PLANNER_EFFORT`,
+`DEXTER_BRIDGE_CLAUDE_MAIN_EFFORT`,
+`DEXTER_BRIDGE_CLAUDE_FOLLOWUP_EFFORT`, or
+`DEXTER_BRIDGE_CLAUDE_EFFORT`.
+
 ## Debugging
 
 The Dexter Bridge terminal is the shell where `dexter-bridge start` is running.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Local Companion bridge for the Dexter Framer plugin — runs Codex or Claude Code on your machine.",
   "type": "module",
   "bin": {
-    "dexter-bridge": "./bin/dexter-bridge.js"
+    "dexter-bridge": "bin/dexter-bridge.js"
   },
   "files": [
     "bin",

package/src/agent.js

@@ -12,8 +12,11 @@ import {
   normalizeCompanionModelName,
 } from './config.js';
 import {
+  buildModelTurnDeltaPrompt,
+  buildModelTurnFallbackPrompt,
   buildModelTurnPrompt,
   extractJsonObject,
+  modelTurnOutputSchema,
   normalizeModelTurnCompletion,
   runSummary,
 } from './protocol.js';
@@ -27,6 +30,48 @@ import {
 } from './logger.js';
 import { createLocalAgentAdapter } from './providers/index.js';
 
+const companionModelSessions = new Map();
+const sharedProviderAdapters = new Map();
+const MAX_COMPANION_MODEL_SESSIONS = 64;
+
+function enabledFlag(value, fallback = false) {
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (!raw) return fallback;
+  return !['0', 'false', 'no', 'off', 'disabled'].includes(raw);
+}
+
+function deltaModelSessionsEnabled(env = process.env) {
+  return enabledFlag(env.DEXTER_DELTA_MODEL_SESSIONS, true);
+}
+
+function companionSessionKey(run) {
+  return run?.modelTurn?.session?.sessionId || run?.turnId || run?.runId;
+}
+
+function rememberedCompanionSession(key) {
+  const session = key ? companionModelSessions.get(key) : null;
+  if (!session) return null;
+  companionModelSessions.delete(key);
+  companionModelSessions.set(key, session);
+  return session;
+}
+
+function rememberCompanionSession(key, session) {
+  if (!key) return;
+  companionModelSessions.delete(key);
+  companionModelSessions.set(key, session);
+  while (companionModelSessions.size > MAX_COMPANION_MODEL_SESSIONS) {
+    const oldest = companionModelSessions.keys().next().value;
+    if (!oldest) break;
+    companionModelSessions.delete(oldest);
+  }
+}
+
+function resumeFailure(error) {
+  const message = error?.message || String(error || '');
+  return /resume|session|thread|conversation|not found|unknown id|expired/i.test(message);
+}
+
 export const AGENT_DEFINITIONS = {
   'claude-code': {
     id: 'claude-code',
@@ -133,6 +178,16 @@ const CLAUDE_CLI_MODEL_IDS = {
   haiku: 'claude-haiku-4-5-20251001',
 };
 
+const CLAUDE_MODEL_ENGINE_SYSTEM_PROMPT = [
+  'You are a model-only completion engine embedded inside Dexter.',
+  'The user prompt contains Dexter messages and a catalog of remote tools as data.',
+  'Never execute, simulate, or emit native Claude Code tool calls for those tool names.',
+  'The only allowed tool is StructuredOutput, supplied by the JSON schema.',
+  'Encode requested Dexter actions only inside StructuredOutput.toolCalls.',
+  'Do not inspect the filesystem, project, shell, plugins, skills, MCP servers, or browser.',
+  'Be concise: reason only as much as needed to choose the next remote Dexter action.',
+].join(' ');
+
 export function mapClaudeCliModelId(value) {
   const raw = String(value || '').trim();
   return CLAUDE_CLI_MODEL_IDS[raw.toLowerCase()] || raw;
@@ -150,7 +205,16 @@ function argsWithSelectedModel(args, modelDefinition, definition) {
 function argsWithStructuredOutput(args, definition, env = process.env) {
   if (!structuredUsageEnabled(env)) return args;
   if (definition.id === 'claude-code') {
-    return argsIncludeFlag(args, '--output-format') ? args : [...args, '--output-format', 'json'];
+    const streamed = [
+      ...argsWithoutFlagValue(args, '--output-format'),
+      '--output-format',
+      'stream-json',
+    ];
+    if (!argsIncludeFlag(streamed, '--include-partial-messages')) {
+      streamed.push('--include-partial-messages');
+    }
+    if (!argsIncludeFlag(streamed, '--verbose')) streamed.push('--verbose');
+    return streamed;
   }
   if (definition.id === 'codex') {
     return argsIncludeFlag(args, '--json') ? args : [...args, '--json'];
@@ -158,6 +222,89 @@ function argsWithStructuredOutput(args, definition, env = process.env) {
   return args;
 }
 
+function argsWithClaudeIsolation(args, definition) {
+  if (definition.id !== 'claude-code') return args;
+  const isolated = argsWithoutVariadicFlag(args, '--tools');
+  isolated.push('--tools', '');
+  if (!argsIncludeFlag(isolated, '--disable-slash-commands')) isolated.push('--disable-slash-commands');
+  if (!argsIncludeFlag(isolated, '--safe-mode')) isolated.push('--safe-mode');
+  if (!argsIncludeFlag(isolated, '--strict-mcp-config')) isolated.push('--strict-mcp-config');
+  if (!argsIncludeFlag(isolated, '--no-chrome')) isolated.push('--no-chrome');
+  return isolated;
+}
+
+function normalizeClaudeEffort(value, fallback = 'medium') {
+  const effort = String(value || '').trim().toLowerCase();
+  return ['low', 'medium', 'high', 'xhigh', 'max'].includes(effort)
+    ? effort
+    : fallback;
+}
+
+function claudeEffortForStep(step, env = process.env) {
+  if (env.DEXTER_BRIDGE_CLAUDE_EFFORT) {
+    return normalizeClaudeEffort(env.DEXTER_BRIDGE_CLAUDE_EFFORT);
+  }
+  if (Number(step) < 0) {
+    return normalizeClaudeEffort(env.DEXTER_BRIDGE_CLAUDE_PLANNER_EFFORT, 'low');
+  }
+  if (Number(step) > 0) {
+    return normalizeClaudeEffort(env.DEXTER_BRIDGE_CLAUDE_FOLLOWUP_EFFORT, 'low');
+  }
+  return normalizeClaudeEffort(env.DEXTER_BRIDGE_CLAUDE_MAIN_EFFORT, 'medium');
+}
+
+function argsWithClaudeModelEngine(args, definition, options = {}, env = process.env) {
+  if (definition.id !== 'claude-code') return args;
+  let isolated = argsWithoutFlagValue(args, '--system-prompt');
+  isolated = argsWithoutFlagValue(isolated, '--append-system-prompt');
+  isolated = argsWithoutFlagValue(isolated, '--agent');
+  isolated = argsWithoutFlagValue(isolated, '--effort');
+  return [
+    ...isolated,
+    '--system-prompt',
+    CLAUDE_MODEL_ENGINE_SYSTEM_PROMPT,
+    '--effort',
+    claudeEffortForStep(options.step, env),
+  ];
+}
+
+function argsWithoutFlagValue(args, flag) {
+  const filtered = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === flag) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith(`${flag}=`)) continue;
+    filtered.push(arg);
+  }
+  return filtered;
+}
+
+function argsWithoutVariadicFlag(args, flag) {
+  const filtered = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === flag) {
+      while (index + 1 < args.length && !String(args[index + 1]).startsWith('-')) index += 1;
+      continue;
+    }
+    if (arg.startsWith(`${flag}=`)) continue;
+    filtered.push(arg);
+  }
+  return filtered;
+}
+
+function argsWithOutputSchema(args, definition, outputSchema) {
+  if (definition.id !== 'claude-code' || !outputSchema) return args;
+  return [
+    ...argsWithoutFlagValue(args, '--json-schema'),
+    '--json-schema',
+    JSON.stringify(outputSchema),
+  ];
+}
+
 function argsWithPromptInput(args, definition) {
   if (definition.id !== 'codex' || args.includes('-')) return args;
   return [...args, '-'];
@@ -222,7 +369,10 @@ export function buildAgentArgs(definition, modelDefinition, env = process.env, o
   const requiredArgs = argsWithRequiredAgentFlags(baseArgs, definition);
   const modelArgs = argsWithSelectedModel(requiredArgs, modelDefinition, definition);
   const structuredArgs = argsWithStructuredOutput(modelArgs, definition, env);
-  const resumedArgs = argsWithResumedSession(structuredArgs, definition, options.resumeSessionId);
+  const isolatedArgs = argsWithClaudeIsolation(structuredArgs, definition);
+  const modelEngineArgs = argsWithClaudeModelEngine(isolatedArgs, definition, options, env);
+  const schemaArgs = argsWithOutputSchema(modelEngineArgs, definition, options.outputSchema);
+  const resumedArgs = argsWithResumedSession(schemaArgs, definition, options.resumeSessionId);
   return argsWithPromptInput(resumedArgs, definition);
 }
 
@@ -498,12 +648,17 @@ export function agentFailureMessage(command, code, stdout = '', stderr = '') {
 
 function runProcess(command, args, stdin, {
   timeoutMs = 120000,
+  maxDurationMs,
   trace,
   childEnv: providedChildEnv,
   platform = process.platform,
 } = {}) {
   return new Promise((resolve, reject) => {
     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;
+    // hardDeadlineMs bounds total wall-clock time regardless of activity.
+    const hardDeadlineMs = Math.max(maxDurationMs || timeoutMs * 5, 10);
     const childEnv = providedChildEnv || processEnvWithCliPath(platform);
     const cwd = resolveAgentCwd(childEnv, process.cwd(), platform);
     const invocation = processInvocation(command, args, childEnv, platform);
@@ -515,6 +670,7 @@ function runProcess(command, args, stdin, {
       env: processEnvSummary(childEnv),
       stdinChars: stdin.length,
       timeoutMs,
+      maxDurationMs: hardDeadlineMs,
     });
     const child = spawn(invocation.command, invocation.args, {
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -525,33 +681,54 @@ function runProcess(command, args, stdin, {
     let stdout = '';
     let stderr = '';
     let settled = false;
-    const timer = setTimeout(() => {
+    let inactivityTimer = null;
+    const timeOut = (message) => {
       if (settled) return;
       settled = true;
+      clearTimeout(inactivityTimer);
+      clearTimeout(deadlineTimer);
       child.kill('SIGTERM');
-      const error = new Error(`${command} timed out after ${timeoutMs}ms.`);
+      const error = new Error(message);
+      error.code = 'AGENT_TIMEOUT';
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.timedOut = true;
       trace?.error('agent_process_timeout', {
         command,
         durationMs: Date.now() - started,
         timeoutMs,
+        maxDurationMs: hardDeadlineMs,
         stdoutChars: stdout.length,
         stderrChars: stderr.length,
         stdoutExcerpt: clip(stdout, 1000),
         stderrExcerpt: clip(stderr, 1000),
       });
       reject(error);
-    }, timeoutMs);
+    };
+    const armInactivityTimer = () => {
+      clearTimeout(inactivityTimer);
+      inactivityTimer = setTimeout(() => {
+        timeOut(`${command} produced no output for ${timeoutMs}ms.`);
+      }, timeoutMs);
+    };
+    const deadlineTimer = setTimeout(() => {
+      timeOut(`${command} timed out after ${hardDeadlineMs}ms.`);
+    }, hardDeadlineMs);
+    armInactivityTimer();
 
     child.stdout.on('data', (chunk) => {
       stdout += chunk.toString('utf8');
+      armInactivityTimer();
     });
     child.stderr.on('data', (chunk) => {
       stderr += chunk.toString('utf8');
+      armInactivityTimer();
     });
     child.on('error', (error) => {
       if (settled) return;
       settled = true;
-      clearTimeout(timer);
+      clearTimeout(inactivityTimer);
+      clearTimeout(deadlineTimer);
       trace?.error('agent_process_error', {
         command,
         durationMs: Date.now() - started,
@@ -562,7 +739,8 @@ function runProcess(command, args, stdin, {
     child.on('close', (code) => {
       if (settled) return;
       settled = true;
-      clearTimeout(timer);
+      clearTimeout(inactivityTimer);
+      clearTimeout(deadlineTimer);
       const meta = {
         command,
         code,
@@ -738,8 +916,15 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
   const modelDefinition = companionModelDefinition(options.model, definition.id);
   const args = buildAgentArgs(definition, modelDefinition, process.env, {
     resumeSessionId: options.resumeSessionId,
+    outputSchema: options.outputSchema,
+    step: options.step,
   });
   const timeoutMs = options.timeoutMs || Number(process.env.DEXTER_BRIDGE_AGENT_TIMEOUT_MS || 120000);
+  const maxDurationMs = boundedDurationMs(
+    options.maxDurationMs ?? process.env.DEXTER_BRIDGE_AGENT_MAX_DURATION_MS,
+    Math.max(timeoutMs * 5, 600000),
+    10,
+  );
   options.trace?.info('agent_step_invoke', {
     agent: definition.id,
     command,
@@ -751,13 +936,28 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
     promptChars: prompt.length,
     resumeSessionId: options.resumeSessionId,
     timeoutMs,
+    maxDurationMs,
   });
   return runProcess(command, args, prompt, {
     timeoutMs,
+    maxDurationMs,
     trace: options.trace,
   });
 }
 
+function agentErrorWithOutputUsage(agent, error) {
+  const failure = error instanceof Error
+    ? error
+    : new Error(String(error || 'The companion model call failed.'));
+  const parsed = parseAgentOutput(agent, failure.stdout || '');
+  if (!parsed.usageAvailable) return failure;
+  const accumulator = createCompanionUsageAccumulator(agent);
+  accumulator.add(failure.companionUsage || {});
+  accumulator.add(parsed);
+  failure.companionUsage = accumulator.snapshot();
+  return failure;
+}
+
 async function executeModelTurnRun(run, send, agent, options = {}) {
   if (normalizeAgentName(agent) === 'dry-run') {
     await send('done', {
@@ -781,7 +981,20 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
     ? requestedModel.trim()
     : selectedModel?.id || definition.model;
   const adapter = options.providerAdapter || null;
-  const prompt = buildModelTurnPrompt(run.modelTurn);
+  const sessionKey = companionSessionKey(run);
+  const rememberedSession = rememberedCompanionSession(sessionKey);
+  const deltaRequested =
+    deltaModelSessionsEnabled(options.env)
+    && run?.modelTurn?.session?.contextMode === 'delta';
+  let callContextMode = deltaRequested && rememberedSession ? 'delta' : 'full';
+  let prompt = callContextMode === 'delta'
+    ? buildModelTurnDeltaPrompt(run.modelTurn)
+    : deltaRequested
+      ? buildModelTurnFallbackPrompt(run.modelTurn)
+      : buildModelTurnPrompt(run.modelTurn);
+  const callStartedAt = Date.now();
+  let providerSessionId;
+  let fallbackAfterResumeFailure = false;
   const statusResponse = await send('status', {
     stage: 'model_turn',
     message: `${definition.label} is generating the next Dexter action.`,
@@ -791,10 +1004,39 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
     throw new CompanionRunCancelledError();
   }
   const usageAccumulator = createCompanionUsageAccumulator(definition.id);
+  const failedModelCall = (error) => {
+    const failure = error instanceof Error
+      ? error
+      : new Error(String(error || 'The companion model call failed.'));
+    usageAccumulator.add(failure.companionUsage || {});
+    const snapshot = usageAccumulator.snapshot();
+    failure.companionUsage = {
+      ...snapshot,
+      modelCalls: [{
+        callId: run.runId,
+        step: Number(run?.modelTurn?.step ?? 0),
+        model: selectedModelId,
+        status: 'failed',
+        durationMs: Date.now() - callStartedAt,
+        promptChars: prompt.length,
+        requestedContextMode: deltaRequested ? 'delta' : 'full',
+        contextMode: callContextMode,
+        resumed: callContextMode === 'delta',
+        resumeSessionAvailable: Boolean(rememberedSession),
+        fallbackAfterResumeFailure,
+        ...snapshot.tokenUsage,
+        estimatedCostUSD: snapshot.estimatedCostUSD,
+      }],
+    };
+    return failure;
+  };
   let resultText;
   if (adapter) {
-    const sessionId = adapterSessionId(run);
+    const sessionId = sessionKey || adapterSessionId(run);
     const invocationModel = adapterInvocationModel(run, selectedModel, definition.id);
+    if (callContextMode === 'full' && rememberedSession) {
+      await adapter.resetSession?.(sessionId);
+    }
     options.trace?.info('agent_adapter_invoke', {
       adapter: adapter.id,
       agent: definition.id,
@@ -803,17 +1045,26 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
       invocationModel,
       promptChars: prompt.length,
     });
-    const result = await callProviderAdapter(adapter, {
+    const adapterInput = {
       runId: run.runId,
       sessionId,
       prompt,
       model: invocationModel,
+      outputSchema: modelTurnOutputSchema(run.modelTurn),
       timeoutMs: boundedDurationMs(
         options.timeoutMs ?? options.env?.DEXTER_BRIDGE_AGENT_TIMEOUT_MS,
         120000,
         1000,
       ),
-    }, {
+      maxDurationMs: boundedDurationMs(
+        run?.modelTurn?.maxDurationMs
+          ?? options.maxDurationMs
+          ?? options.env?.DEXTER_BRIDGE_AGENT_MAX_DURATION_MS,
+        600000,
+        1000,
+      ),
+    };
+    const adapterOptions = {
       send,
       trace: options.trace,
       controlPollMs: boundedDurationMs(
@@ -822,9 +1073,30 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         10,
         30000,
       ),
-    });
+    };
+    let result;
+    try {
+      result = await callProviderAdapter(adapter, adapterInput, adapterOptions);
+    } catch (error) {
+      if (callContextMode !== 'delta' || !resumeFailure(error)) throw failedModelCall(error);
+      usageAccumulator.add(error?.companionUsage || {});
+      fallbackAfterResumeFailure = true;
+      callContextMode = 'full';
+      prompt = buildModelTurnFallbackPrompt(run.modelTurn);
+      await adapter.resetSession?.(sessionId);
+      options.trace?.warn('agent_adapter_resume_fallback', {
+        sessionId,
+        error: errorMeta(error),
+        fallbackPromptChars: prompt.length,
+      });
+      result = await callProviderAdapter(adapter, { ...adapterInput, prompt }, adapterOptions)
+        .catch((error) => {
+          throw failedModelCall(error);
+        });
+    }
     usageAccumulator.add(result);
     resultText = result?.text;
+    providerSessionId = result?.threadId || result?.sessionId;
   } else {
     const runtime = await resolveAgentRuntime(definition, selectedModel, {
       env: options.env,
@@ -832,25 +1104,96 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
     if (!runtime.ok) {
       throw new Error(runtime.error || `${definition.label} is not available.`);
     }
-    const result = await callLocalJsonAgent(definition.id, prompt, {
-      ...options,
-      model: selectedModelId,
-      runtime,
-    });
+    const resumeSessionId =
+      callContextMode === 'delta'
+      && agentSessionResumeEnabled(definition, options.env)
+        ? rememberedSession?.providerSessionId
+        : undefined;
+    let result;
+    try {
+      result = await callLocalJsonAgent(definition.id, prompt, {
+        ...options,
+        model: selectedModelId,
+        runtime,
+        resumeSessionId,
+        outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+      });
+    } catch (error) {
+      const failure = agentErrorWithOutputUsage(definition.id, error);
+      if (callContextMode !== 'delta' || !resumeFailure(failure)) throw failedModelCall(failure);
+      usageAccumulator.add(failure.companionUsage || {});
+      fallbackAfterResumeFailure = true;
+      callContextMode = 'full';
+      prompt = buildModelTurnFallbackPrompt(run.modelTurn);
+      options.trace?.warn('agent_cli_resume_fallback', {
+        resumeSessionId,
+        error: errorMeta(failure),
+        fallbackPromptChars: prompt.length,
+      });
+      result = await callLocalJsonAgent(definition.id, prompt, {
+        ...options,
+        model: selectedModelId,
+        runtime,
+        resumeSessionId: undefined,
+        outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+      }).catch((error) => {
+        throw failedModelCall(agentErrorWithOutputUsage(definition.id, error));
+      });
+    }
     const parsed = parseAgentOutput(definition.id, result.stdout);
     usageAccumulator.add(parsed);
     resultText = parsed.resultText;
+    providerSessionId = parsed.sessionId;
+  }
+  if (providerSessionId || adapter) {
+    rememberCompanionSession(sessionKey, {
+      providerSessionId: providerSessionId || rememberedSession?.providerSessionId || sessionKey,
+      agent: definition.id,
+      updatedAt: Date.now(),
+    });
+  }
+  const usageSnapshot = usageAccumulator.snapshot();
+  const callTelemetry = {
+    callId: run.runId,
+    step: Number(run?.modelTurn?.step ?? 0),
+    model: selectedModelId,
+    durationMs: Date.now() - callStartedAt,
+    promptChars: prompt.length,
+    requestedContextMode: deltaRequested ? 'delta' : 'full',
+    contextMode: callContextMode,
+    resumed: callContextMode === 'delta',
+    resumeSessionAvailable: Boolean(rememberedSession),
+    fallbackAfterResumeFailure,
+    ...usageSnapshot.tokenUsage,
+    estimatedCostUSD: usageSnapshot.estimatedCostUSD,
+  };
+  const usage = {
+    ...usageSnapshot,
+    modelCalls: [{ ...callTelemetry, status: 'succeeded' }],
+  };
+  let completion;
+  try {
+    completion = normalizeModelTurnCompletion(
+      extractJsonObject(resultText),
+      selectedModelId,
+    );
+  } catch (error) {
+    error.companionUsage = {
+      ...usage,
+      modelCalls: [{ ...callTelemetry, status: 'rejected' }],
+    };
+    throw error;
   }
-  const completion = normalizeModelTurnCompletion(
-    extractJsonObject(resultText),
-    selectedModelId,
-  );
   await send('done', {
     operationType: 'chat',
     outcome: 'answer',
     completion,
     model: selectedModelId,
-    ...usageAccumulator.snapshot(),
+    ...usage,
   });
 }
 
@@ -885,14 +1228,26 @@ export async function executeRun(run, {
   const runModel = run?.companion?.model?.id || run?.model || selectedModel;
   const usageAccumulator = createCompanionUsageAccumulator(normalizedAgent);
   const adapterProvided = providerAdapter !== undefined;
-  const activeAdapter = adapterProvided
-    ? providerAdapter
-    : createLocalAgentAdapter(normalizedAgent, {
+  const shareAdapter = !adapterProvided && deltaModelSessionsEnabled(env);
+  let activeAdapter = adapterProvided ? providerAdapter : null;
+  if (!adapterProvided && shareAdapter) {
+    activeAdapter = sharedProviderAdapters.get(normalizedAgent) || null;
+    if (!activeAdapter) {
+      activeAdapter = createLocalAgentAdapter(normalizedAgent, {
+        ...adapterOptions,
+        env: adapterOptions?.env || env,
+        trace,
+      });
+      if (activeAdapter) sharedProviderAdapters.set(normalizedAgent, activeAdapter);
+    }
+  } else if (!adapterProvided) {
+    activeAdapter = createLocalAgentAdapter(normalizedAgent, {
       ...adapterOptions,
       env: adapterOptions?.env || env,
       trace,
     });
-  const ownsAdapter = !adapterProvided && Boolean(activeAdapter);
+  }
+  const ownsAdapter = !adapterProvided && !shareAdapter && Boolean(activeAdapter);
   if (
     activeAdapter?.id
     && activeAdapter.id !== normalizedAgent
@@ -945,6 +1300,12 @@ export async function executeRun(run, {
   }
 }
 
+export function __resetAgentSessionsForTests() {
+  companionModelSessions.clear();
+  for (const adapter of sharedProviderAdapters.values()) adapter?.close?.();
+  sharedProviderAdapters.clear();
+}
+
 export function checkCommand(command, args = ['--version'], timeoutMs = 10000) {
   return runProcess(command, args, '', { timeoutMs })
     .then((result) => ({ ok: true, command, output: (result.stdout || result.stderr || '').trim() }))

package/src/agentOutput.js

@@ -79,11 +79,25 @@ function parseWholeJson(stdout) {
   }
 }
 
-export function parseClaudeOutput(stdout) {
-  const parsed = parseWholeJson(stdout);
+function parseJsonLines(stdout) {
+  return String(stdout || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        const parsed = JSON.parse(line);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? [parsed] : [];
+      } catch {
+        return [];
+      }
+    });
+}
+
+function parseClaudeEnvelope(parsed, fallbackText = '') {
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     return {
-      resultText: String(stdout || '').trim(),
+      resultText: String(fallbackText || '').trim(),
       tokenUsage: normalizeCompanionTokenUsage(),
       modelUsage: [],
       usageAvailable: false,
@@ -92,10 +106,16 @@ export function parseClaudeOutput(stdout) {
     };
   }
 
-  const hasEnvelope = typeof parsed.result === 'string' || parsed.usage || parsed.total_cost_usd !== undefined || parsed.modelUsage;
+  const structuredOutput = parsed.structured_output ?? parsed.structuredOutput;
+  const hasEnvelope =
+    typeof parsed.result === 'string'
+    || structuredOutput !== undefined
+    || parsed.usage
+    || parsed.total_cost_usd !== undefined
+    || parsed.modelUsage;
   if (!hasEnvelope) {
     return {
-      resultText: String(stdout || '').trim(),
+      resultText: String(fallbackText || '').trim(),
       tokenUsage: normalizeCompanionTokenUsage(),
       modelUsage: [],
       usageAvailable: false,
@@ -108,7 +128,13 @@ export function parseClaudeOutput(stdout) {
   const modelUsage = normalizeModelUsage(parsed.modelUsage || parsed.model_usage);
   const estimatedCostUSD = optionalNonNegativeNumber(parsed.total_cost_usd ?? parsed.totalCostUsd);
   return {
-    resultText: typeof parsed.result === 'string' ? parsed.result.trim() : '',
+    resultText: structuredOutput && typeof structuredOutput === 'object'
+      ? JSON.stringify(structuredOutput)
+      : typeof structuredOutput === 'string'
+        ? structuredOutput.trim()
+        : typeof parsed.result === 'string'
+          ? parsed.result.trim()
+          : '',
     tokenUsage,
     model: typeof parsed.model === 'string' ? parsed.model : undefined,
     sessionId: typeof parsed.session_id === 'string'
@@ -124,19 +150,111 @@ export function parseClaudeOutput(stdout) {
   };
 }
 
-function parseJsonLines(stdout) {
-  return String(stdout || '')
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .flatMap((line) => {
-      try {
-        const parsed = JSON.parse(line);
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? [parsed] : [];
-      } catch {
-        return [];
+function mergeMaximumUsage(target, rawUsage) {
+  const usage = normalizeCompanionTokenUsage(rawUsage || {});
+  for (const field of TOKEN_FIELDS) target[field] = Math.max(target[field], usage[field]);
+  target.totalTokens = target.inputTokens + target.outputTokens + target.reasoningOutputTokens;
+}
+
+function parseClaudeStreamUsage(events) {
+  const turns = new Map();
+  let activeTurnKey;
+  let anonymousSequence = 0;
+  let sessionId;
+  let partialText = '';
+
+  const ensureTurn = (key, model) => {
+    const resolvedKey = key || activeTurnKey || `turn-${++anonymousSequence}`;
+    if (!turns.has(resolvedKey)) {
+      turns.set(resolvedKey, {
+        model: typeof model === 'string' && model.trim() ? model.trim() : undefined,
+        usage: normalizeCompanionTokenUsage(),
+      });
+    } else if (model && !turns.get(resolvedKey).model) {
+      turns.get(resolvedKey).model = model;
+    }
+    activeTurnKey = resolvedKey;
+    return turns.get(resolvedKey);
+  };
+
+  for (const row of events) {
+    if (
+      (row.type === 'system' || row.type === 'init')
+      && typeof (row.session_id || row.sessionId) === 'string'
+    ) {
+      sessionId = row.session_id || row.sessionId;
+    }
+
+    if (row.type === 'assistant' && row.message && typeof row.message === 'object') {
+      const message = row.message;
+      const turn = ensureTurn(message.id, message.model);
+      mergeMaximumUsage(turn.usage, message.usage);
+      for (const part of Array.isArray(message.content) ? message.content : []) {
+        if (part?.type === 'text' && typeof part.text === 'string') partialText += part.text;
       }
-    });
+    }
+
+    if (row.type !== 'stream_event' || !row.event || typeof row.event !== 'object') continue;
+    const event = row.event;
+    if (event.type === 'message_start' && event.message && typeof event.message === 'object') {
+      const turn = ensureTurn(event.message.id, event.message.model);
+      mergeMaximumUsage(turn.usage, event.message.usage);
+      continue;
+    }
+    if (event.type === 'message_delta') {
+      const turn = ensureTurn(activeTurnKey);
+      mergeMaximumUsage(turn.usage, event.usage);
+      continue;
+    }
+    if (
+      event.type === 'content_block_delta'
+      && event.delta?.type === 'text_delta'
+      && typeof event.delta.text === 'string'
+    ) {
+      partialText += event.delta.text;
+    }
+  }
+
+  const tokenUsage = normalizeCompanionTokenUsage();
+  const modelTotals = new Map();
+  for (const turn of turns.values()) {
+    for (const field of TOKEN_FIELDS) tokenUsage[field] += turn.usage[field];
+    tokenUsage.totalTokens += turn.usage.totalTokens;
+    if (!turn.model) continue;
+    const current = modelTotals.get(turn.model) || {
+      model: turn.model,
+      ...normalizeCompanionTokenUsage(),
+    };
+    for (const field of TOKEN_FIELDS) current[field] += turn.usage[field];
+    current.totalTokens += turn.usage.totalTokens;
+    modelTotals.set(turn.model, current);
+  }
+  const usageAvailable = usageHasReportedTokens(tokenUsage);
+  return {
+    resultText: partialText.trim(),
+    tokenUsage,
+    modelUsage: Array.from(modelTotals.values()),
+    sessionId,
+    usageAvailable,
+    usageSource: 'claude-code',
+    usageAccuracy: usageAvailable ? 'reported' : 'unavailable',
+  };
+}
+
+export function parseClaudeOutput(stdout) {
+  const whole = parseWholeJson(stdout);
+  if (whole && typeof whole === 'object' && !Array.isArray(whole)) {
+    return parseClaudeEnvelope(whole, stdout);
+  }
+  const events = parseJsonLines(stdout);
+  const resultEnvelope = [...events].reverse().find((event) =>
+    event.type === 'result'
+    || event.structured_output !== undefined
+    || event.structuredOutput !== undefined
+    || typeof event.result === 'string');
+  if (resultEnvelope) return parseClaudeEnvelope(resultEnvelope, stdout);
+  if (events.length) return parseClaudeStreamUsage(events);
+  return parseClaudeEnvelope(null, stdout);
 }
 
 export function parseCodexOutput(stdout) {

package/src/config.js

@@ -3,7 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 
 export const DEFAULT_API_BASE_URL = 'http://localhost:3800/iwm-api/0.0.1';
-export const BRIDGE_VERSION = '0.5.0';
+export const BRIDGE_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
 export const BRIDGE_CAPABILITIES = [
   'model-turn-v1',
 ];

package/src/protocol.js

@@ -71,16 +71,18 @@ export function compactToolCatalog(tools = []) {
     .filter((tool) => tool.name);
 }
 
-export function buildModelTurnPrompt(modelTurn = {}) {
-  const messages = Array.isArray(modelTurn.messages)
-    ? modelTurn.messages.slice(-64).map((message) => ({
+function compactMessages(messages = [], limit = 64) {
+  return Array.isArray(messages)
+    ? messages.slice(-limit).map((message) => ({
       role: message?.role,
       content: compactModelTurnContent(message?.content),
       toolCalls: message?.toolCalls,
       toolCallId: message?.toolCallId,
     }))
     : [];
-  const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
+}
+
+function modelTurnInstructions() {
   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.',
@@ -89,13 +91,49 @@ export function buildModelTurnPrompt(modelTurn = {}) {
     'Each toolCalls[].arguments value must be a JSON-encoded string whose decoded value is an object.',
     'Use only tools listed below. Do not claim a tool executed; only request it.',
     'When the task is complete, return toolCalls:[] and finishReason:"stop".',
-    '',
-    `Messages:\n${JSON.stringify(messages)}`,
+  ];
+}
+
+export function buildModelTurnPrompt(modelTurn = {}) {
+  const messages = compactMessages(modelTurn.messages, 64);
+  const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
+  return [
+    ...modelTurnInstructions(),
     '',
     `Tools:\n${JSON.stringify(tools)}`,
+    '',
+    `Messages:\n${JSON.stringify(messages)}`,
   ].join('\n');
 }
 
+export function buildModelTurnDeltaPrompt(modelTurn = {}) {
+  const messages = compactMessages(modelTurn.messages, 24);
+  const includeTools = modelTurn?.session?.toolCatalogChanged === true;
+  const tools = includeTools
+    ? compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : [])
+    : [];
+  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.',
+    ...(includeTools ? ['', `Updated tools:\n${JSON.stringify(tools)}`] : []),
+    '',
+    `New messages:\n${JSON.stringify(messages)}`,
+    modelTurn?.session?.lastStateDigest
+      ? `State digest: ${modelTurn.session.lastStateDigest}`
+      : '',
+  ].filter(Boolean).join('\n');
+}
+
+export function buildModelTurnFallbackPrompt(modelTurn = {}) {
+  return buildModelTurnPrompt({
+    ...modelTurn,
+    messages: Array.isArray(modelTurn.fallbackMessages)
+      ? modelTurn.fallbackMessages
+      : modelTurn.messages,
+  });
+}
+
 export function modelTurnOutputSchema(modelTurn = {}) {
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
   const toolNames = tools.map((tool) => tool.name);

package/src/providers/codexAppServer.js

@@ -1,5 +1,6 @@
 import { createJsonRpcClient } from './jsonRpcClient.js';
 import { normalizeCompanionTokenUsage } from '../agentOutput.js';
+import { BRIDGE_VERSION } from '../config.js';
 
 /**
  * Codex App Server adapter — the primary local-agent path.
@@ -20,7 +21,7 @@ import { normalizeCompanionTokenUsage } from '../agentOutput.js';
 const CLIENT_INFO = {
   name: 'dexter_bridge',
   title: 'Dexter Bridge',
-  version: '0.5.0',
+  version: BRIDGE_VERSION,
 };
 
 export const CODEX_APP_SERVER_METHODS = {
@@ -382,10 +383,12 @@ export function createCodexAppServerAdapter({
         if (event.method === CODEX_APP_SERVER_NOTIFICATIONS.turnCompleted) {
           const turn = event.params?.turn || {};
           if (turn.status === 'failed') {
-            finish(reject, new Error(codexTurnErrorMessage(
+            const error = new Error(codexTurnErrorMessage(
               turn,
               'Codex turn failed without an error message.',
-            )));
+            ));
+            error.companionUsage = normalizeUsage(turn);
+            finish(reject, error);
             return;
           }
           finish(resolve, {
@@ -424,6 +427,18 @@ export function createCodexAppServerAdapter({
     }
   }
 
+  async function resetSession(sessionId) {
+    const threadId = threadsByRun.get(sessionId);
+    if (!threadId) return;
+    threadsByRun.delete(sessionId);
+    if (!client || client.closed) return;
+    await client.request(
+      CODEX_APP_SERVER_METHODS.threadUnsubscribe,
+      { threadId },
+      { timeoutMs: 10000 },
+    ).catch(() => undefined);
+  }
+
   async function logout() {
     if (!client || client.closed) return;
     try {
@@ -451,6 +466,7 @@ export function createCodexAppServerAdapter({
     usage,
     runModelTurn,
     cancel,
+    resetSession,
     logout,
     close,
   };