@gakim-digital/dexter-bridge 0.5.1 → 0.5.6

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.6",
   "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,11 +180,21 @@ 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',
 };
 
+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 +212,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 +240,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 +377,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 +655,27 @@ export function agentFailureMessage(command, code, stdout = '', stderr = '') {
 
 function runProcess(command, args, stdin, {
   timeoutMs = 120000,
+  maxDurationMs,
   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;
+    // 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,43 +687,109 @@ 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'],
       env: childEnv,
       cwd,
       windowsHide: invocation.windowsHide,
+      detached: platform !== 'win32',
     });
     let stdout = '';
     let stderr = '';
     let settled = false;
-    const timer = setTimeout(() => {
+    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;
-      child.kill('SIGTERM');
-      const error = new Error(`${command} timed out after ${timeoutMs}ms.`);
+      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;
+      clearTimers();
+      terminateChildTree();
+      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);
+    signal?.addEventListener('abort', abort, { once: true });
+    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);
+      clearTimers();
+      clearTimeout(forceKillTimer);
+      signal?.removeEventListener('abort', abort);
       trace?.error('agent_process_error', {
         command,
         durationMs: Date.now() - started,
@@ -657,7 +800,9 @@ function runProcess(command, args, stdin, {
     child.on('close', (code) => {
       if (settled) return;
       settled = true;
-      clearTimeout(timer);
+      clearTimers();
+      clearTimeout(forceKillTimer);
+      signal?.removeEventListener('abort', abort);
       const meta = {
         command,
         code,
@@ -742,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.');
@@ -827,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);
@@ -834,8 +1056,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 +1075,29 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
     promptChars: prompt.length,
     resumeSessionId: options.resumeSessionId,
     timeoutMs,
+    maxDurationMs,
   });
   return runProcess(command, args, prompt, {
     timeoutMs,
+    maxDurationMs,
     trace: options.trace,
+    signal: options.signal,
   });
 }
 
+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,15 +1196,22 @@ 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,
       trace: options.trace,
       controlPollMs: boundedDurationMs(
         options.controlPollMs ?? options.env?.DEXTER_BRIDGE_CONTROL_POLL_MS,
-        5000,
-        10,
-        30000,
+        250,
+        50,
+        1000,
       ),
     };
     let result;
@@ -987,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) {
@@ -998,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, {
@@ -1006,15 +1292,23 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         runtime,
         resumeSessionId,
         outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+        signal: cliAbort.signal,
       });
     } catch (error) {
-      if (callContextMode !== 'delta' || !resumeFailure(error)) throw failedModelCall(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 || {});
       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,9 +1317,19 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         runtime,
         resumeSessionId: undefined,
         outputSchema: modelTurnOutputSchema(run.modelTurn),
+        step: run?.modelTurn?.step,
+        maxDurationMs: run?.modelTurn?.maxDurationMs ?? options.maxDurationMs,
+        signal: cliAbort.signal,
       }).catch((error) => {
-        throw failedModelCall(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);
@@ -1092,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') {
@@ -1149,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,
@@ -1205,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/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/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,11 +1,28 @@
 import fs from 'node:fs';
+import crypto from 'node:crypto';
 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_BUILD_FINGERPRINT = crypto
+  .createHash('sha256')
+  .update([
+    '../package.json',
+    './agent.js',
+    './agentOutput.js',
+    './cli.js',
+    './config.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',
 ];
 // 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
@@ -28,10 +45,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

@@ -82,7 +82,27 @@ 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.',
@@ -90,7 +110,11 @@ function modelTurnInstructions() {
     '{"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.',
     '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".',
   ];
 }
 
@@ -98,7 +122,7 @@ export function buildModelTurnPrompt(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)}`,
     '',
@@ -112,10 +136,18 @@ export function buildModelTurnDeltaPrompt(modelTurn = {}) {
   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)}`,
@@ -136,13 +168,19 @@ export function buildModelTurnFallbackPrompt(modelTurn = {}) {
 
 export function modelTurnOutputSchema(modelTurn = {}) {
   const tools = compactToolCatalog(Array.isArray(modelTurn.tools) ? modelTurn.tools : []);
-  const toolNames = tools.map((tool) => tool.name);
+  const toolChoice = normalizedToolChoice(modelTurn);
+  const availableToolNames = tools.map((tool) => tool.name);
+  const toolNames =
+    toolChoice.toolName && availableToolNames.includes(toolChoice.toolName)
+      ? [toolChoice.toolName]
+      : availableToolNames;
   return {
     type: 'object',
     properties: {
       text: { type: 'string' },
       toolCalls: {
         type: 'array',
+        ...(toolChoice.required ? { minItems: 1 } : {}),
         maxItems: toolNames.length ? 12 : 0,
         items: {
           type: 'object',
@@ -163,7 +201,9 @@ export function modelTurnOutputSchema(modelTurn = {}) {
       },
       finishReason: {
         type: 'string',
-        enum: ['tool_calls', 'stop', 'length'],
+        enum: toolChoice.required
+          ? ['tool_calls']
+          : ['tool_calls', 'stop', 'length'],
       },
     },
     required: ['text', 'toolCalls', 'finishReason'],