@gakim-digital/dexter-bridge 0.11.6 → 0.11.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.11.6",
+  "version": "0.11.9",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import crossSpawn from 'cross-spawn';
 import {
   getFramerProjectAuthorization,
+  isCompanionPairingInvalidError,
   postRunEvent,
   reportFramerProjectAuthorizationVerification,
 } from './api.js';
@@ -182,6 +183,10 @@ function nowIso() {
 const TERMINAL_EVENT_TYPES = new Set(['done', 'error']);
 const TERMINAL_EVENT_MAX_ATTEMPTS = 5;
 const TOOL_EVENT_MAX_ATTEMPTS = 3;
+// Progress/status events are retried too, but briefly: they are posted in
+// order on one chain, so a long backoff would stall every later event.
+const STREAM_EVENT_MAX_ATTEMPTS = 3;
+const STREAM_EVENT_MAX_RETRY_DELAY_MS = 2_000;
 
 function waitForRetry(delayMs) {
   return new Promise((resolve) => setTimeout(resolve, delayMs));
@@ -205,14 +210,20 @@ function createEventPoster({
   trace,
   allowInsecureHttp = false,
 }) {
+  // Stream events carry a per-run sequence so the API can drop a retried
+  // event it already published (for example after a lost response). Tool
+  // calls are idempotent by callId and terminal events by run completion.
+  let sequence = 0;
   return async function send(type, payload = {}) {
     const eventId = `${type}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    const stream = !TERMINAL_EVENT_TYPES.has(type) && type !== 'tool_call';
+    const eventSequence = stream ? (sequence += 1) : undefined;
     const started = Date.now();
     const maxAttempts = TERMINAL_EVENT_TYPES.has(type)
       ? TERMINAL_EVENT_MAX_ATTEMPTS
       : type === 'tool_call'
         ? TOOL_EVENT_MAX_ATTEMPTS
-        : 1;
+        : STREAM_EVENT_MAX_ATTEMPTS;
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
       trace?.info('event_post_start', {
         type,
@@ -229,6 +240,7 @@ function createEventPoster({
           event: {
             type,
             eventId,
+            ...(eventSequence ? { sequence: eventSequence } : {}),
             payload,
           },
         });
@@ -244,7 +256,11 @@ function createEventPoster({
         });
         return response;
       } catch (error) {
-        const retryDelayMs = attempt < maxAttempts ? terminalEventRetryDelay(error, attempt) : null;
+        const baseDelayMs = attempt < maxAttempts ? terminalEventRetryDelay(error, attempt) : null;
+        const retryDelayMs =
+          stream && baseDelayMs !== null
+            ? Math.min(STREAM_EVENT_MAX_RETRY_DELAY_MS, baseDelayMs)
+            : baseDelayMs;
         trace?.error('event_post_failed', {
           type,
           eventId,
@@ -378,7 +394,12 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
         'preview_control',
         'browser_control',
         'data_inspect',
+        'data_schema_get',
+        'data_schema_apply',
         'verification_run',
+        'platform_catalog_search',
+        'platform_resource_configure',
+        'platform_resource_status',
       ];
   const harnessTools = harnessToolNames.map(
     (name) => `mcp__instawebai__${name}`,
@@ -673,7 +694,40 @@ export function buildAgentArgs(definition, modelDefinition, env = process.env, o
     options.responseContract,
   );
   const resumedArgs = argsWithResumedSession(schemaArgs, definition, options.resumeSessionId);
-  return argsWithPromptInput(resumedArgs, definition);
+  return argsWithPromptInput(argsWithImages(resumedArgs, definition, options.imageFiles), definition);
+}
+
+function argsWithImages(args, definition, imageFiles = []) {
+  if (!imageFiles.length) return args;
+  if (definition.id === 'codex') {
+    const withoutStdin = args.filter((arg) => arg !== '-');
+    return [...withoutStdin, ...imageFiles.map((file) => `--image=${file}`)];
+  }
+  if (definition.id === 'claude-code') {
+    const streamed = argsWithoutFlagValue(argsWithoutFlagValue(args, '--input-format'), '--output-format');
+    streamed.push('--input-format', 'stream-json', '--output-format', 'stream-json');
+    if (!argsIncludeFlag(streamed, '--verbose')) streamed.push('--verbose');
+    return streamed;
+  }
+  return args;
+}
+
+const IMAGE_MEDIA_TYPES = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+
+// Claude Code's stream-json input carries images as native content blocks.
+function claudeStreamJsonPrompt(prompt, imageFiles) {
+  const content = [
+    ...imageFiles.map((file) => ({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: IMAGE_MEDIA_TYPES[path.extname(file).toLowerCase()] || 'image/png',
+        data: fs.readFileSync(file).toString('base64'),
+      },
+    })),
+    { type: 'text', text: prompt },
+  ];
+  return `${JSON.stringify({ type: 'user', message: { role: 'user', content } })}\n`;
 }
 
 export function parseEnvOutput(output) {
@@ -1523,6 +1577,9 @@ async function callProviderAdapter(
         if (controlRequestsCancellation(response)) await requestCancel();
       })
       .catch((error) => {
+        if (isCompanionPairingInvalidError(error)) {
+          void requestCancel();
+        }
         if (!finished) {
           trace?.warn('adapter_activity_post_failed', {
             error: errorMeta(error),
@@ -1562,6 +1619,10 @@ async function callProviderAdapter(
         if (controlRequestsCancellation(response)) await requestCancel();
       } catch (error) {
         if (monitorAbort.signal.aborted) return;
+        if (isCompanionPairingInvalidError(error)) {
+          await requestCancel();
+          return;
+        }
         trace?.warn('adapter_control_poll_failed', { error: errorMeta(error) });
       }
     }
@@ -1713,17 +1774,11 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
   const definition = definitionForAgent(agent);
   const command = options.runtime?.command || commandFromEnv(definition.commandEnv, definition.fallbackCommand);
   const modelDefinition = companionModelDefinition(options.model, definition.id);
-  const args = buildAgentArgs(definition, modelDefinition, process.env, {
-    resumeSessionId: options.resumeSessionId,
-    outputSchema: options.outputSchema,
-    responseContract: options.responseContract,
-    step: options.step,
-    product: options.product,
-    nativeSkillsEnabled: options.nativeSkillsEnabled,
-    harnessMode: options.harnessMode,
-    mcpConfig: options.mcpConfig,
-    harnessToolNames: options.harnessToolNames,
-  });
+  const args = buildAgentArgs(definition, modelDefinition, process.env, options);
+  const processInput =
+    definition.id === 'claude-code' && options.imageFiles?.length
+      ? claudeStreamJsonPrompt(prompt, options.imageFiles)
+      : prompt;
   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,
@@ -1743,7 +1798,7 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
     timeoutMs,
     maxDurationMs,
   });
-  return runProcess(command, args, prompt, {
+  return runProcess(command, args, processInput, {
     timeoutMs,
     maxDurationMs,
     trace: options.trace,
@@ -1847,7 +1902,7 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
           callId: run.runId,
           step: Number(run?.modelTurn?.step ?? 0),
           model: selectedModelId,
-          status: 'failed',
+          callStatus: 'failed',
           durationMs: Date.now() - callStartedAt,
           promptChars: prompt.length,
           requestedContextMode: deltaRequested ? 'delta' : 'full',
@@ -2006,6 +2061,9 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
           if (controlRequestsCancellation(response)) requestCliCancel();
         })
         .catch((error) => {
+          if (isCompanionPairingInvalidError(error)) {
+            requestCliCancel();
+          }
           if (!cliFinished) {
             options.trace?.warn('cli_activity_post_failed', {
               error: errorMeta(error),
@@ -2044,6 +2102,10 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
           if (cliCancelled) return;
         } catch (error) {
           if (monitorAbort.signal.aborted) return;
+          if (isCompanionPairingInvalidError(error)) {
+            requestCliCancel();
+            return;
+          }
           options.trace?.warn('cli_control_poll_failed', {
             error: errorMeta(error),
           });
@@ -2150,7 +2212,7 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
   };
   const usage = {
     ...usageSnapshot,
-    modelCalls: [{ ...callTelemetry, status: 'succeeded' }],
+    modelCalls: [{ ...callTelemetry, callStatus: 'succeeded' }],
   };
   let completion;
   try {
@@ -2158,7 +2220,7 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
   } catch (error) {
     error.companionUsage = {
       ...usage,
-      modelCalls: [{ ...callTelemetry, status: 'rejected' }],
+      modelCalls: [{ ...callTelemetry, callStatus: 'rejected' }],
     };
     throw error;
   }
@@ -2255,6 +2317,9 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         }
       })
       .catch((error) => {
+        if (isCompanionPairingInvalidError(error)) {
+          void requestCancel('device_disconnect');
+        }
         if (!finished) {
           options.trace?.warn?.('outcome_activity_post_failed', {
             error: errorMeta(error),
@@ -2331,6 +2396,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           await requestCancel(controlCancellationSource(response));
         }
       } catch (error) {
+        if (isCompanionPairingInvalidError(error)) {
+          await requestCancel('device_disconnect');
+          return;
+        }
         if (!controlMonitorAbort.signal.aborted && !cancelRequested) {
           options.trace?.warn?.('outcome_control_poll_failed', {
             error: errorMeta(error),
@@ -2374,6 +2443,23 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         },
       }
     : run.outcome;
+  const referenceImagePaths = referenceAssetFiles.map((file) =>
+    path.join(materialized.directory, file.path),
+  );
+  const materializedReferenceIds = new Set(
+    referenceAssetFiles.map((file) => file.id),
+  );
+  // Materialized images ride on the first provider turn as native image input.
+  const referenceAssets = [
+    ...new Set(
+      requestAttachments
+        .map((attachment) => String(attachment?.id || '').slice(0, 180))
+        .filter(Boolean),
+    ),
+  ].map((id) => ({
+    id,
+    materialized: materializedReferenceIds.has(id),
+  }));
   const nativeSkills = normalizeNativeSkills(run?.outcome?.nativeSkills);
   const nativeProvider =
     definition.id === 'claude-code'
@@ -2400,6 +2486,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         trace: options.trace,
         onActivity: progress,
         runCli: options.framerAgentRunCli,
+        fetchImpl: options.framerScreenshotFetch,
         authorizeProject:
           options.apiBaseUrl && options.deviceToken
             ? ({ initiate, forceRefresh, signal }) =>
@@ -2519,6 +2606,9 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       resumeSessionIdOverride,
       step = 0,
     ) => {
+      // User attachments ride on the first turn as native image input, exactly
+      // as if pasted into the agent; follow-up turns already have them in context.
+      const imageFiles = step === 0 ? referenceImagePaths : [];
       if (options.providerAdapter?.runOutcome) {
         const providerResult = await options.providerAdapter.runOutcome({
           runId: run.runId,
@@ -2533,6 +2623,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           cwd: materialized.directory,
           nativeSkills,
           framerHarness: framerAgentOutcome,
+          imageFiles,
           harnessTools: {
             definitions: codexDynamicToolSpecs(harnessTools.definitions),
             invoke: harnessTools.invoke,
@@ -2575,6 +2666,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           framerHarness: framerAgentOutcome,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
+          imageFiles,
           signal: infrastructureAbortController.signal,
           ...(mcpConfig ? { mcpConfig } : {}),
           onProgress: progress,
@@ -2597,6 +2689,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           framerHarness: framerAgentOutcome,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
+          imageFiles,
           signal: infrastructureAbortController.signal,
           ...(mcpConfig ? { mcpConfig } : {}),
           onProgress: progress,
@@ -2741,6 +2834,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       outcome: {
         ...normalized,
         files,
+        referenceAssets,
       },
       model: selectedModelId,
       providerSessionId:
@@ -2753,9 +2847,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           callId: run.runId,
           outcomeId: run?.outcome?.outcomeId,
           model: selectedModelId,
-          status:
+          callStatus: 'succeeded',
+          outcomeStatus:
             normalized.status === successStatus
-              ? 'succeeded'
+              ? 'completed'
               : normalized.status,
           durationMs: Date.now() - callStartedAt,
           providerAttemptCount: Math.max(1, providerAttempts),
@@ -2810,6 +2905,7 @@ export async function executeRun(
     inspectAgentAuthentication,
     runtimeProfile: suppliedRuntimeProfile,
     framerAgentRunCli,
+    framerScreenshotFetch,
     allowInsecureHttp = false,
   } = {},
 ) {
@@ -2928,6 +3024,7 @@ export async function executeRun(
       product,
       runtimeProfile,
       framerAgentRunCli,
+      framerScreenshotFetch,
       apiBaseUrl,
       deviceToken,
       fetchImpl,
@@ -2991,6 +3088,7 @@ export function checkCommand(command, args = ['--version'], timeoutMs = 10000) {
 
 export async function checkAgentAvailability(agent, model, options = {}) {
   const normalizedAgent = normalizeAgentName(agent);
+  const modelCatalogRefreshedAt = nowIso();
   if (normalizedAgent === 'dry-run') {
     return {
       ok: true,
@@ -3002,6 +3100,8 @@ export async function checkAgentAvailability(agent, model, options = {}) {
       installed: true,
       signedIn: true,
       status: 'ready',
+      modelCatalogSource: 'runtime',
+      modelCatalogRefreshedAt,
     };
   }
   const definition = definitionForAgent(normalizedAgent);
@@ -3025,6 +3125,8 @@ export async function checkAgentAvailability(agent, model, options = {}) {
       installed: false,
       signedIn: false,
       status: 'unavailable',
+      modelCatalogSource: 'fallback',
+      modelCatalogRefreshedAt,
     };
   }
   if (normalizedAgent === 'codex') {
@@ -3051,9 +3153,19 @@ export async function checkAgentAvailability(agent, model, options = {}) {
           error:
             detection.error
             || 'Codex is not signed in. Run `codex login` on this computer, then run the bridge command again.',
+          modelCatalogSource: 'fallback',
+          modelCatalogRefreshedAt,
         };
       }
-      const reportedModels = await adapter.models();
+      let reportedModels = supportedModels;
+      let modelCatalogSource = 'fallback';
+      let modelCatalogError = null;
+      try {
+        reportedModels = await adapter.models();
+        modelCatalogSource = 'runtime';
+      } catch (error) {
+        modelCatalogError = error?.message || String(error);
+      }
       return {
         ...runtime,
         ...detection,
@@ -3062,7 +3174,9 @@ export async function checkAgentAvailability(agent, model, options = {}) {
         label: definition.label,
         models: reportedModels.map((candidate) => candidate.id),
         modelDetails: reportedModels,
-        modelCatalogSource: 'runtime',
+        modelCatalogSource,
+        modelCatalogRefreshedAt,
+        ...(modelCatalogError ? { modelCatalogError } : {}),
         installed: true,
         signedIn: true,
         status: 'ready',
@@ -3108,6 +3222,7 @@ export async function checkAgentAvailability(agent, model, options = {}) {
     models: reportedModels.map((candidate) => candidate.id),
     modelDetails: reportedModels,
     modelCatalogSource,
+    modelCatalogRefreshedAt,
     ...(modelCatalogError ? { modelCatalogError } : {}),
     installed: true,
   };

package/src/agentOutput.js

@@ -301,6 +301,11 @@ function claudeToolProgress(name, input = {}, cwd) {
     preview_control: ['Starting the live preview', 'Started the live preview'],
     browser_control: ['Checking the app in the browser', 'Finished checking the app in the browser'],
     data_inspect: ['Checking app data', 'Finished checking app data'],
+    data_schema_get: ['Reading the app tables', 'Finished reading the app tables'],
+    data_schema_apply: ['Updating the app tables', 'Finished updating the app tables'],
+    platform_catalog_search: ['Looking up connections', 'Found the available connections'],
+    platform_resource_configure: ['Setting up a connection', 'Finished setting up the connection'],
+    platform_resource_status: ['Checking a connection', 'Finished checking the connection'],
     verification_run: ['Running final verification', 'Finished final verification'],
   };
   const [startedMessage, completedMessage] = messages[shortName] || [

package/src/api.js

@@ -16,6 +16,15 @@ export class DexterBridgeApiError extends Error {
   }
 }
 
+export function isCompanionPairingInvalidError(error) {
+  return error instanceof DexterBridgeApiError
+    && error.status === 401
+    && (
+      error.body?.code === 'FRAMER_COMPANION_NOT_PAIRED'
+      || /not paired|pair again/i.test(error.message)
+    );
+}
+
 function bearerHeaders(deviceToken) {
   return deviceToken ? { Authorization: `Bearer ${deviceToken}` } : {};
 }

package/src/cli.js

@@ -19,8 +19,8 @@ import {
 import { checkAgentAvailability, checkAllAgents, executeRun } from './agent.js';
 import {
   claimPairing,
-  DexterBridgeApiError,
   heartbeat,
+  isCompanionPairingInvalidError,
   pollRun,
 } from './api.js';
 import {
@@ -30,6 +30,7 @@ import {
 } from './logger.js';
 import { createLocalAgentAdapter } from './providers/index.js';
 import {
+  diagnosticsFromAgentCheck,
   discoverRuntimeProfiles,
   normalizeRuntimeSelection,
   publicRuntimeProfile,
@@ -228,12 +229,7 @@ function wait(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)
-    );
+  return isCompanionPairingInvalidError(error);
 }
 
 function clearInvalidPairing(configDir, cause) {
@@ -266,7 +262,48 @@ function agentEnvironment(config = {}, baseEnv = process.env) {
   return env;
 }
 
-async function inspectAvailability(config = {}, runtimeSelection = null) {
+function modelCatalogStatus(runtimeProfiles = []) {
+  return Object.fromEntries(
+    runtimeProfiles.flatMap((profile) => {
+      const agent =
+        profile.driver === 'codex-app-server'
+          ? 'codex'
+          : profile.driver === 'claude-code-cli'
+            ? 'claude-code'
+            : null;
+      return agent ? [[agent, profile.modelCatalog]] : [];
+    }),
+  );
+}
+
+function preserveLastKnownModelCatalog(previousProfiles = [], nextProfiles = []) {
+  const previousById = new Map(previousProfiles.map((profile) => [profile.id, profile]));
+  return nextProfiles.map((profile) => {
+    const previous = previousById.get(profile.id);
+    if (
+      !previous?.models?.length
+      || profile.modelCatalog?.source === 'runtime'
+      || !profile.modelCatalog?.error
+    ) {
+      return profile;
+    }
+    return {
+      ...profile,
+      models: previous.models,
+      modelCatalog: {
+        ...profile.modelCatalog,
+        source: 'stale',
+        modelCount: previous.models.length,
+      },
+    };
+  });
+}
+
+async function inspectAvailability(
+  config = {},
+  runtimeSelection = null,
+  { forceModelRefresh = false, previousRuntimeProfiles = [] } = {},
+) {
   try {
     const bridgeEnv = agentEnvironment(config);
     const checks =
@@ -275,22 +312,33 @@ async function inspectAvailability(config = {}, runtimeSelection = null) {
             agents: [
               await checkAgentAvailability(runtimeSelection, undefined, {
                 env: bridgeEnv,
+                forceModelRefresh,
               }),
             ],
             dryRun: null,
           }
         : runtimeSelection === 'opencode'
           ? { agents: [], dryRun: null }
-          : await checkAllAgents({ env: bridgeEnv });
+          : await checkAllAgents({ env: bridgeEnv, forceModelRefresh });
     const allChecks = [...checks.agents, ...(checks.dryRun ? [checks.dryRun] : [])];
     const available = allChecks.filter((check) => check.ok);
-    const runtimeProfiles = await discoverRuntimeProfiles({
+    const discoveredRuntimeProfiles = await discoverRuntimeProfiles({
       agentChecks: checks.agents,
       config,
       env: bridgeEnv,
       runtimeSelection,
     });
+    const runtimeProfiles = preserveLastKnownModelCatalog(
+      previousRuntimeProfiles,
+      discoveredRuntimeProfiles,
+    );
     const profileModels = runtimeProfiles.flatMap((profile) => profile.models || []);
+    const catalogStatus = modelCatalogStatus(runtimeProfiles);
+    const refreshedAt = Object.values(catalogStatus)
+      .map((status) => status?.refreshedAt)
+      .filter(Boolean)
+      .sort()
+      .at(-1);
     return {
       metadata: {
         availableAgents: available.map((check) => check.agent).join(','),
@@ -298,6 +346,8 @@ async function inspectAvailability(config = {}, runtimeSelection = null) {
         availableModelDetails: JSON.stringify(
           profileModels,
         ),
+        modelCatalogStatus: JSON.stringify(catalogStatus),
+        ...(refreshedAt ? { modelCatalogRefreshedAt: refreshedAt } : {}),
         agentVersions: available.map((check) => `${check.agent}=${check.version || 'unknown'}`).join(','),
         bridgeCapabilities: BRIDGE_CAPABILITIES.join(','),
         bridgeVersion: BRIDGE_VERSION,
@@ -555,7 +605,10 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
     while (true) {
       if (Date.now() >= nextCatalogRefreshAt) {
         try {
-          const refreshedAvailability = await inspectAvailability(activeConfig, runtimeSelection);
+          const refreshedAvailability = await inspectAvailability(activeConfig, runtimeSelection, {
+            forceModelRefresh: true,
+            previousRuntimeProfiles: availability.runtimeProfiles,
+          });
           const refreshedRuntimeProfile = runtimeSelection
             ? requireAvailableRuntime(refreshedAvailability, runtimeSelection)
             : null;
@@ -598,7 +651,9 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
             status: error.status,
             code: error.body?.code || null,
           });
-          throw clearInvalidPairing(configDir, error);
+          const disconnected = clearInvalidPairing(configDir, error);
+          console.log(disconnected.message);
+          return;
         }
         if (once) throw error;
         pollFailureCount += 1;
@@ -610,6 +665,45 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
         await wait(retryInMs);
         continue;
       }
+      if (poll?.control?.refreshModelCatalog) {
+        try {
+          const refreshedAvailability = await inspectAvailability(activeConfig, runtimeSelection, {
+            forceModelRefresh: true,
+            previousRuntimeProfiles: availability.runtimeProfiles,
+          });
+          availability = refreshedAvailability;
+          runtimeProfile = runtimeSelection
+            ? requireAvailableRuntime(refreshedAvailability, runtimeSelection)
+            : null;
+          check = runtimeProfile
+            ? null
+            : requireAvailableAgent(refreshedAvailability, agent);
+          model = runtimeProfile
+            ? runtimeProfile.models.find((candidate) => candidate.id === requestedModel)?.id
+              || runtimeProfile.models[0].id
+            : availableModel(check, requestedModel);
+          metadata = availability.metadata;
+          profiles = runtimeProfileMap(availability.runtimeProfiles);
+          await heartbeat(apiBaseUrl, {
+            deviceToken,
+            status: 'ready',
+            agent,
+            model,
+            metadata,
+            runtimeProfiles: availability.runtimeProfiles.map(publicRuntimeProfile),
+            allowInsecureHttp: flags['allow-insecure-http'],
+          });
+          pollLogger.info('model_catalog_refresh_completed', {
+            requestedAt: poll.control.refreshModelCatalog.requestedAt,
+            models: availability.runtimeProfiles.flatMap((profile) =>
+              profile.models.map((candidate) => candidate.id)),
+          });
+        } catch (error) {
+          pollLogger.warn('model_catalog_refresh_failed', { error: errorMeta(error) });
+        } finally {
+          nextCatalogRefreshAt = Date.now() + MODEL_CATALOG_REFRESH_MS;
+        }
+      }
       if (poll.run) {
         console.log(`Claimed run ${poll.run.runId}.`);
         const runtimeProfile = poll.run?.runtimeProfile || null;
@@ -661,19 +755,28 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
   }
 }
 
-async function doctorCommand(runtimeSelection = null) {
-  if (runtimeSelection) {
-    const availability = await inspectAvailability({}, runtimeSelection);
-    const profile = requireAvailableRuntime(availability, runtimeSelection);
-    console.log(`${runtimeLabel(runtimeSelection)}: ready`);
-    console.log(`Models: ${profile.models.map((model) => model.displayName || model.id).join(', ')}`);
-    return;
+function printDiagnostics(diagnostics) {
+  const marks = { info: '✓', warn: '!', error: '✗' };
+  for (const check of diagnostics.checks) {
+    console.log(`  ${marks[check.level] || '-'} ${check.message}`);
+    if (check.hint) console.log(`    ${check.hint}`);
   }
-  const checks = await checkAllAgents();
-  for (const check of checks.agents) {
-    if (check.ok) console.log(`${check.command}: ok ${check.output || ''}`.trim());
-    else console.log(`${check.command}: unavailable (${check.error})`);
+}
+
+async function doctorCommand(runtimeSelection = null) {
+  const bridgeEnv = agentEnvironment({});
+  const checks =
+    runtimeSelection === 'codex' || runtimeSelection === 'claude-code'
+      ? [await checkAgentAvailability(runtimeSelection, undefined, { env: bridgeEnv })]
+      : (await checkAllAgents({ env: bridgeEnv })).agents;
+  let failed = false;
+  for (const check of checks) {
+    const diagnostics = diagnosticsFromAgentCheck(check, bridgeEnv);
+    failed ||= diagnostics.status === 'fail';
+    console.log(`${check.label || check.agent}: ${diagnostics.status}`);
+    printDiagnostics(diagnostics);
   }
+  if (failed && runtimeSelection) process.exitCode = 1;
 }
 
 export async function runCli(argv) {

package/src/config.js

@@ -52,6 +52,7 @@ export const BRIDGE_CAPABILITIES = [
   'runtime-profiles-v1',
   'native-skills-v1',
   'model-progress-v1',
+  'model-catalog-refresh-v1',
 ];
 export const BRIDGE_PRODUCTS = {
   dexter: {