@gakim-digital/dexter-bridge 0.5.0 → 0.5.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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',
@@ -150,7 +195,7 @@ 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'];
+    return [...argsWithoutFlagValue(args, '--output-format'), '--output-format', 'json'];
   }
   if (definition.id === 'codex') {
     return argsIncludeFlag(args, '--json') ? args : [...args, '--json'];
@@ -158,6 +203,54 @@ 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 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 +315,9 @@ 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 schemaArgs = argsWithOutputSchema(isolatedArgs, definition, options.outputSchema);
+  const resumedArgs = argsWithResumedSession(schemaArgs, definition, options.resumeSessionId);
   return argsWithPromptInput(resumedArgs, definition);
 }
 
@@ -738,6 +833,7 @@ 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,
   });
   const timeoutMs = options.timeoutMs || Number(process.env.DEXTER_BRIDGE_AGENT_TIMEOUT_MS || 120000);
   options.trace?.info('agent_step_invoke', {
@@ -781,7 +877,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 +900,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 +941,19 @@ 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,
       ),
-    }, {
+    };
+    const adapterOptions = {
       send,
       trace: options.trace,
       controlPollMs: boundedDurationMs(
@@ -822,9 +962,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 +993,90 @@ 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),
+      });
+    } catch (error) {
+      if (callContextMode !== 'delta' || !resumeFailure(error)) throw failedModelCall(error);
+      fallbackAfterResumeFailure = true;
+      callContextMode = 'full';
+      prompt = buildModelTurnFallbackPrompt(run.modelTurn);
+      options.trace?.warn('agent_cli_resume_fallback', {
+        resumeSessionId,
+        error: errorMeta(error),
+        fallbackPromptChars: prompt.length,
+      });
+      result = await callLocalJsonAgent(definition.id, prompt, {
+        ...options,
+        model: selectedModelId,
+        runtime,
+        resumeSessionId: undefined,
+        outputSchema: modelTurnOutputSchema(run.modelTurn),
+      }).catch((error) => {
+        throw failedModelCall(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 +1111,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 +1183,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

@@ -92,7 +92,13 @@ 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(),
@@ -108,7 +114,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'

package/src/config.js

@@ -3,7 +3,7 @@ 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 = '0.5.1';
 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,
   };