@gakim-digital/dexter-bridge 0.5.1 → 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,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Local Companion bridge for the Dexter Framer plugin — runs Codex or Claude Code on your machine.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -178,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;
@@ -195,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 [...argsWithoutFlagValue(args, '--output-format'), '--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'];
@@ -214,6 +233,41 @@ function argsWithClaudeIsolation(args, definition) {
   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) {
@@ -316,7 +370,8 @@ export function buildAgentArgs(definition, modelDefinition, env = process.env, o
   const modelArgs = argsWithSelectedModel(requiredArgs, modelDefinition, definition);
   const structuredArgs = argsWithStructuredOutput(modelArgs, definition, env);
   const isolatedArgs = argsWithClaudeIsolation(structuredArgs, definition);
-  const schemaArgs = argsWithOutputSchema(isolatedArgs, definition, options.outputSchema);
+  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);
 }
@@ -593,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);
@@ -610,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'],
@@ -620,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,
@@ -657,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,
@@ -834,8 +917,14 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
   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,
@@ -847,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', {
@@ -952,6 +1056,13 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         120000,
         1000,
       ),
+      maxDurationMs: boundedDurationMs(
+        run?.modelTurn?.maxDurationMs
+          ?? options.maxDurationMs
+          ?? options.env?.DEXTER_BRIDGE_AGENT_MAX_DURATION_MS,
+        600000,
+        1000,
+      ),
     };
     const adapterOptions = {
       send,
@@ -1006,15 +1117,19 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         runtime,
         resumeSessionId,
         outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
       });
     } catch (error) {
-      if (callContextMode !== 'delta' || !resumeFailure(error)) throw failedModelCall(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(error),
+        error: errorMeta(failure),
         fallbackPromptChars: prompt.length,
       });
       result = await callLocalJsonAgent(definition.id, prompt, {
@@ -1023,8 +1138,10 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         runtime,
         resumeSessionId: undefined,
         outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
       }).catch((error) => {
-        throw failedModelCall(error);
+        throw failedModelCall(agentErrorWithOutputUsage(definition.id, error));
       });
     }
     const parsed = parseAgentOutput(definition.id, result.stdout);

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,
@@ -101,7 +115,7 @@ export function parseClaudeOutput(stdout) {
     || parsed.modelUsage;
   if (!hasEnvelope) {
     return {
-      resultText: String(stdout || '').trim(),
+      resultText: String(fallbackText || '').trim(),
       tokenUsage: normalizeCompanionTokenUsage(),
       modelUsage: [],
       usageAvailable: false,
@@ -136,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.1';
+export const BRIDGE_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
 export const BRIDGE_CAPABILITIES = [
   'model-turn-v1',
 ];