@gakim-digital/dexter-bridge 0.12.1 → 0.13.0

package/src/cli.js

@@ -6,17 +6,27 @@ import {
   BRIDGE_BUILD_FINGERPRINT,
   BRIDGE_CAPABILITIES,
   BRIDGE_VERSION,
+  DEXTER_HOSTS,
+  bridgeDisplayName,
   clearConfig,
   defaultConfigDir,
+  dexterHostConfigDir,
   normalizeBridgeProduct,
   normalizeAgentName,
+  normalizeDexterHost,
   readConfig,
   resolveAgentName,
   resolveApiBaseUrl,
   resolveCompanionModelName,
   saveConfigPatch,
 } from './config.js';
-import { checkAgentAvailability, checkAllAgents, executeRun, processEnvWithCliPath } from './agent.js';
+import {
+  checkAgentAvailability,
+  checkAllAgents,
+  executeRun,
+  processEnvWithCliPath,
+  stopAgentProcesses,
+} from './agent.js';
 import { setUpCursorCli } from './providers/cursorAcp.js';
 import {
   claimPairing,
@@ -231,8 +241,10 @@ async function executeClaimedRun({
   preventIdleSleep = false,
 }) {
   const awakeGuard = preventIdleSleep ? startRunAwakeGuard() : null;
+  const running = Promise.resolve().then(() => execute(run, executeOptions));
+  activeRuns.add(running);
   try {
-    await execute(run, executeOptions);
+    await running;
     return true;
   } catch (error) {
     logger?.error?.('run_execution_failed', {
@@ -244,6 +256,7 @@ async function executeClaimedRun({
     console.error(`${productName} run ${run?.runId || 'unknown'} failed; continuing to poll.`);
     return false;
   } finally {
+    activeRuns.delete(running);
     awakeGuard?.close();
   }
 }
@@ -252,6 +265,28 @@ function wait(delayMs) {
   return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
 
+const activeRuns = new Set();
+const SHUTDOWN_GRACE_MS = 5_000;
+let signalsHandled = false;
+
+// Stopping the bridge stops its agents and lets their runs report the
+// cancellation before the process exits. A second signal exits at once.
+function stopRunsOnSignals() {
+  if (signalsHandled) return;
+  signalsHandled = true;
+  let stopping = false;
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(signal, () => {
+      const exitCode = 128 + os.constants.signals[signal];
+      if (stopping) process.exit(exitCode);
+      stopping = true;
+      stopAgentProcesses();
+      void Promise.race([Promise.allSettled([...activeRuns]), wait(SHUTDOWN_GRACE_MS)])
+        .then(() => process.exit(exitCode));
+    });
+  }
+}
+
 function isInvalidPairingError(error) {
   return isCompanionPairingInvalidError(error);
 }
@@ -280,7 +315,8 @@ function runCommand(command, args) {
 
 // Upgrades the Homebrew install at most once an hour. On success the process
 // exits non-zero so launchd restarts the service on the new version.
-async function selfUpdateWithHomebrew(configDir, logger) {
+async function selfUpdateWithHomebrew(logger) {
+  const configDir = defaultConfigDir();
   const lastAttempt = Date.parse(readConfig(configDir).lastSelfUpdateAt || '');
   if (Number.isFinite(lastAttempt) && Date.now() - lastAttempt < SELF_UPDATE_INTERVAL_MS) return;
   saveConfigPatch({ lastSelfUpdateAt: new Date().toISOString() }, configDir);
@@ -293,18 +329,23 @@ async function selfUpdateWithHomebrew(configDir, logger) {
   throw restart;
 }
 
-async function waitForPairing(configDir) {
+function productConfigDirs(rootDir) {
+  return DEXTER_HOSTS.map((host) => dexterHostConfigDir(rootDir, host));
+}
+
+// Resolves with the first folder that holds a pairing.
+async function waitForPairing(configDirs) {
   console.log('Waiting for a new pairing from Dexter...');
   while (true) {
-    const token = readConfig(configDir).deviceToken;
-    if (token) return token;
+    const paired = configDirs.find((dir) => readConfig(dir).deviceToken);
+    if (paired) return paired;
     await wait(PAIRING_WAIT_POLL_MS);
   }
 }
 
 function clearInvalidPairing(configDir, cause, rejectedToken) {
   const current = readConfig(configDir);
-  const product = normalizeBridgeProduct(current.product);
+  const name = bridgeDisplayName(current);
   // Another bridge command may have just saved a fresh pairing; keep it.
   if (!rejectedToken || current.deviceToken === rejectedToken) {
     saveConfigPatch({
@@ -314,7 +355,7 @@ function clearInvalidPairing(configDir, cause, rejectedToken) {
     }, configDir);
   }
   const error = new Error(
-    `This ${product.name} Bridge pairing was disconnected. Reopen ${product.name} and run the new pairing command.`,
+    `This ${name} Bridge pairing was disconnected. Reopen ${name} and run the new pairing command.`,
     { cause },
   );
   error.code = 'FRAMER_COMPANION_NOT_PAIRED';
@@ -550,27 +591,30 @@ async function pairCommand({ apiBaseUrl, args, flags, configDir }) {
     runtimeProfiles: availability.runtimeProfiles.map(publicRuntimeProfile),
     runtimeSelection,
   });
+  const product = normalizeBridgeProduct(result.product);
+  const dexterHost = product.id === 'dexter' ? normalizeDexterHost(result.product?.host) : null;
+  const pairedDir = dexterHost ? dexterHostConfigDir(configDir, dexterHost) : configDir;
   saveConfigPatch({
     apiBaseUrl,
     agent,
     model,
     runtimeSelection,
-    product: normalizeBridgeProduct(result.product),
+    product,
+    dexterHost,
     deviceToken: result.deviceToken,
     device: result.device,
     agentCommands: availability.agentCommands,
     pairedAt: new Date().toISOString(),
-  }, configDir);
-  const product = normalizeBridgeProduct(result.product);
-  console.log(`Paired ${product.name} Bridge: ${result.device?.name || 'device'}`);
+  }, pairedDir);
+  console.log(`Paired ${bridgeDisplayName({ product, dexterHost })} Bridge: ${result.device?.name || 'device'}`);
   if (runtimeSelection) {
     console.log(`Runtime: ${runtimeProfile?.label || runtimeLabel(runtimeSelection)}`);
   }
   console.log(`API: ${apiBaseUrl}`);
+  return pairedDir;
 }
 
 async function statusCommand({ apiBaseUrl, config, configDir }) {
-  const product = normalizeBridgeProduct(config.product);
   const deviceToken = requireDeviceToken(config);
   const runtimeSelection = requestedRuntime({}, config);
   const agent = runtimeSelection
@@ -598,8 +642,8 @@ async function statusCommand({ apiBaseUrl, config, configDir }) {
     if (isInvalidPairingError(error)) throw clearInvalidPairing(configDir, error);
     throw error;
   }
-  console.log(`Status: ${result.device?.online ? 'online' : 'paired'}`);
-  console.log(`Device: ${result.device?.name || `${product.name} Bridge`}`);
+  console.log(`${bridgeDisplayName(config)}: ${result.device?.online ? 'online' : 'paired'}`);
+  console.log(`Device: ${result.device?.name || `${bridgeDisplayName(config)} Bridge`}`);
   if (runtimeSelection) {
     console.log(`Runtime: ${runtimeProfile?.label || runtimeLabel(runtimeSelection)}`);
   }
@@ -613,20 +657,20 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
   if (!deviceToken) {
     // First run: pair interactively so `npx @gakim-digital/dexter-bridge` alone is
     if (runsAsBackgroundService()) {
-      deviceToken = await waitForPairing(configDir);
-      activeConfig = readConfig(configDir);
+      configDir = await waitForPairing(productConfigDirs(configDir));
     } else {
       if (!process.stdin.isTTY) requireDeviceToken(config);
       console.log('This local agent bridge is not paired yet.');
       console.log('Open the product connection screen and generate a new bridge command.');
       const code = await promptForPairingCode();
       if (!code) requireDeviceToken(config);
-      await pairCommand({ apiBaseUrl, args: [code], flags, configDir });
-      activeConfig = readConfig(configDir);
-      deviceToken = activeConfig.deviceToken;
+      configDir = await pairCommand({ apiBaseUrl, args: [code], flags, configDir });
     }
+    activeConfig = readConfig(configDir);
+    deviceToken = activeConfig.deviceToken;
   }
   const product = normalizeBridgeProduct(activeConfig.product);
+  const label = bridgeDisplayName(activeConfig);
   const runtimeSelection = requestedRuntime(flags, activeConfig);
   if (product.connectionScope === 'app-builder' && !runtimeSelection) {
     const error = new Error('This App Builder connection requires --runtime codex, --runtime claude-code, or --runtime opencode.');
@@ -673,8 +717,56 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
   };
   let pollFailureCount = 0;
   let nextCatalogRefreshAt = Date.now() + MODEL_CATALOG_REFRESH_MS;
+  let catalogRefresh = null;
+  // Agent probes can take tens of seconds, so the catalog refreshes in the
+  // background and never delays a queued run.
+  const refreshModelCatalog = (requestedAt) => {
+    catalogRefresh ||= (async () => {
+      try {
+        const refreshedAvailability = await inspectAvailability(activeConfig, runtimeSelection, {
+          forceModelRefresh: true,
+          previousRuntimeProfiles: availability.runtimeProfiles,
+        });
+        const refreshedRuntimeProfile = runtimeSelection
+          ? requireAvailableRuntime(refreshedAvailability, runtimeSelection)
+          : null;
+        const refreshedCheck = refreshedRuntimeProfile
+          ? null
+          : requireAvailableAgent(refreshedAvailability, agent);
+        availability = refreshedAvailability;
+        runtimeProfile = refreshedRuntimeProfile;
+        check = refreshedCheck;
+        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(requestedAt ? 'model_catalog_refresh_completed' : 'model_catalog_refreshed', {
+          ...(requestedAt ? { 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;
+        catalogRefresh = null;
+      }
+    })();
+    return catalogRefresh;
+  };
 
-  console.log(`${product.name} Bridge connected to ${apiBaseUrl}`);
+  console.log(`${label} Bridge connected to ${apiBaseUrl}`);
   console.log(
     `${runtimeSelection ? 'Runtime' : 'Agent'}: ${
       runtimeSelection ? runtimeProfile?.label || runtimeLabel(runtimeSelection) : agent
@@ -686,37 +778,7 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
 
   try {
     while (true) {
-      if (Date.now() >= nextCatalogRefreshAt) {
-        try {
-          const refreshedAvailability = await inspectAvailability(activeConfig, runtimeSelection, {
-            forceModelRefresh: true,
-            previousRuntimeProfiles: availability.runtimeProfiles,
-          });
-          const refreshedRuntimeProfile = runtimeSelection
-            ? requireAvailableRuntime(refreshedAvailability, runtimeSelection)
-            : null;
-          const refreshedCheck = refreshedRuntimeProfile
-            ? null
-            : requireAvailableAgent(refreshedAvailability, agent);
-          availability = refreshedAvailability;
-          runtimeProfile = refreshedRuntimeProfile;
-          check = refreshedCheck;
-          model = runtimeProfile
-            ? runtimeProfile.models.find((candidate) => candidate.id === requestedModel)?.id
-              || runtimeProfile.models[0].id
-            : availableModel(check, requestedModel);
-          metadata = availability.metadata;
-          profiles = runtimeProfileMap(availability.runtimeProfiles);
-          pollLogger.info('model_catalog_refreshed', {
-            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 (Date.now() >= nextCatalogRefreshAt) void refreshModelCatalog();
       let poll;
       try {
         poll = await pollRun(apiBaseUrl, {
@@ -726,6 +788,7 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
           model,
           metadata,
           runtimeProfiles: availability.runtimeProfiles.map(publicRuntimeProfile),
+          refreshingModelCatalog: Boolean(catalogRefresh),
         });
         pollFailureCount = 0;
       } catch (error) {
@@ -744,64 +807,29 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
           const disconnected = clearInvalidPairing(configDir, error, deviceToken);
           console.log(disconnected.message);
           if (!runsAsBackgroundService()) return;
-          deviceToken = await waitForPairing(configDir);
+          await waitForPairing([configDir]);
+          deviceToken = readConfig(configDir).deviceToken;
           pollFailureCount = 0;
           continue;
         }
         if (isUpdateRequiredError(error) && runsAsBackgroundService()) {
-          await selfUpdateWithHomebrew(configDir, pollLogger);
+          await selfUpdateWithHomebrew(pollLogger);
         }
         if (once) throw error;
         pollFailureCount += 1;
         const retryInMs = pollBackoffMs(pollFailureCount);
         pollLogger.error('poll_failed', { error: errorMeta(error) });
         if (pollFailureCount === 1 || (pollFailureCount & (pollFailureCount - 1)) === 0) {
-          console.error(`${product.name} polling failed; retrying in ${Math.round(retryInMs / 1000)}s.`);
+          console.error(`${label} polling failed; retrying in ${Math.round(retryInMs / 1000)}s.`);
         }
         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;
-        }
+        void refreshModelCatalog(poll.control.refreshModelCatalog.requestedAt);
       }
       if (poll.run) {
-        console.log(`Claimed run ${poll.run.runId}.`);
+        console.log(`Claimed ${label} run ${poll.run.runId}.`);
         const runtimeProfile = poll.run?.runtimeProfile || null;
         const runAgent = normalizeAgentName(
           poll.run?.companion?.agent
@@ -841,7 +869,7 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
         continue;
       }
       if (once) {
-        console.log(`No pending ${product.name} runs.`);
+        console.log(`No pending ${label} runs.`);
         return;
       }
     }
@@ -851,6 +879,22 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
   }
 }
 
+function pairedConfigDirs(rootDir) {
+  return productConfigDirs(rootDir).filter((dir) => readConfig(dir).deviceToken);
+}
+
+// One polling loop per paired product, so Dexter for Framer and Dexter for
+// Webflow both stay online from a single bridge process.
+async function startPairedBridges({ apiFlag, flags, rootDir }) {
+  stopRunsOnSignals();
+  const paired = pairedConfigDirs(rootDir);
+  await Promise.all((paired.length ? paired : [rootDir]).map((configDir) => {
+    const config = readConfig(configDir);
+    const apiBaseUrl = resolveApiBaseUrl({ flagValue: apiFlag, config });
+    return startCommand({ apiBaseUrl, config: { ...config, apiBaseUrl }, flags, configDir });
+  }));
+}
+
 function printDiagnostics(diagnostics) {
   const marks = { info: '✓', warn: '!', error: '✗' };
   for (const check of diagnostics.checks) {
@@ -897,31 +941,37 @@ export async function runCli(argv) {
       if (parsed.args[0]) {
         await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
       }
-      await startCommand({
-        apiBaseUrl,
-        config: { ...readConfig(configDir), apiBaseUrl },
-        flags: parsed.flags,
-        configDir,
-      });
+      await startPairedBridges({ apiFlag: parsed.flags.api, flags: parsed.flags, rootDir: configDir });
       return;
-    case 'pair':
-      await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
-      console.log(`Run \`dexter-bridge start\` to bring ${normalizeBridgeProduct(readConfig(configDir).product).name} online.`);
+    case 'pair': {
+      const pairedDir = await pairCommand({ apiBaseUrl, args: parsed.args, flags: parsed.flags, configDir });
+      console.log(`Run \`dexter-bridge start\` to bring ${bridgeDisplayName(readConfig(pairedDir))} online.`);
       return;
+    }
     case 'start':
-      await startCommand({ apiBaseUrl, config: { ...config, apiBaseUrl }, flags: parsed.flags, configDir });
+      await startPairedBridges({ apiFlag: parsed.flags.api, flags: parsed.flags, rootDir: configDir });
       return;
-    case 'status':
-      await statusCommand({ apiBaseUrl, config, configDir });
+    case 'status': {
+      const paired = pairedConfigDirs(configDir);
+      if (!paired.length) requireDeviceToken(config);
+      for (const dir of paired) {
+        const dirConfig = readConfig(dir);
+        await statusCommand({
+          apiBaseUrl: resolveApiBaseUrl({ flagValue: parsed.flags.api, config: dirConfig }),
+          config: dirConfig,
+          configDir: dir,
+        });
+      }
       return;
+    }
     case 'doctor':
       await doctorCommand(requestedRuntime(parsed.flags, config));
       return;
     case 'logout':
-      {
-        const product = normalizeBridgeProduct(config.product);
-        clearConfig(configDir);
-        console.log(`${product.name} Bridge local pairing removed.`);
+      for (const dir of productConfigDirs(configDir)) {
+        const dirConfig = readConfig(dir);
+        clearConfig(dir);
+        if (dirConfig.deviceToken) console.log(`${bridgeDisplayName(dirConfig)} Bridge local pairing removed.`);
       }
       return;
     default:

package/src/config.js

@@ -23,6 +23,8 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
     './framerTools.js',
     './framerMcpClient.js',
     './framerBehaviorContract.js',
+    './webflowTools.js',
+    './taskEvidence.js',
     './outcomeWorkspace.js',
     './runtimeProfiles.js',
     './providers/index.js',
@@ -47,6 +49,7 @@ export const BRIDGE_CAPABILITIES = [
   'framer-project-verification-v1',
   'framer-interaction-verification-v4',
   'framer-read-website-v1',
+  'webflow-site-v2',
   'project-shell-v1',
   'build-fingerprint-v1',
   'tool-schema-parity-v1',
@@ -261,6 +264,23 @@ export function normalizeBridgeProduct(value) {
   return BRIDGE_PRODUCTS.dexter;
 }
 
+export const DEXTER_HOSTS = ['framer', 'webflow'];
+
+export function normalizeDexterHost(value) {
+  return value === 'webflow' ? 'webflow' : 'framer';
+}
+
+// Each Dexter product keeps its own pairing so pairing one never replaces the other.
+export function dexterHostConfigDir(rootDir, host) {
+  return normalizeDexterHost(host) === 'webflow' ? path.join(rootDir, 'webflow') : rootDir;
+}
+
+export function bridgeDisplayName(config = {}) {
+  const product = normalizeBridgeProduct(config.product);
+  if (product.id !== 'dexter') return product.name;
+  return normalizeDexterHost(config.dexterHost) === 'webflow' ? 'Dexter for Webflow' : 'Dexter for Framer';
+}
+
 export function configFilePath(configDir = defaultConfigDir()) {
   return path.join(configDir, 'config.json');
 }

package/src/framerMcpClient.js

@@ -123,14 +123,14 @@ export function createFramerMcpClient({
     sdkClient = client;
   }
 
-  async function rawCall(name, args) {
-    if (typeof callTool === 'function') return callTool(name, args);
+  async function rawCall(name, args, callTimeoutMs = timeoutMs) {
+    if (typeof callTool === 'function') return callTool(name, args, { timeoutMs: callTimeoutMs });
     await connect();
     try {
       return await sdkClient.callTool(
         { name, arguments: args },
         undefined,
-        { timeout: timeoutMs, resetTimeoutOnProgress: true },
+        { timeout: callTimeoutMs, resetTimeoutOnProgress: true },
       );
     } catch (error) {
       if (isUnauthorized(error)) {
@@ -146,16 +146,16 @@ export function createFramerMcpClient({
 
   // An expired session is refused before the program runs, so reopening the
   // project and retrying once cannot apply a change twice.
-  async function call(name, args, retried = false) {
+  async function call(name, args, { retried = false, timeoutMs: callTimeoutMs } = {}) {
     let result;
     try {
-      result = unwrap(await rawCall(name, args));
+      result = unwrap(await rawCall(name, args, callTimeoutMs));
     } catch (error) {
       const expired = error?.code === 'FRAMER_MCP_SESSION_EXPIRED'
         || SESSION_EXPIRED_PATTERN.test(String(error?.message || ''));
       if (!expired || retried || !projectId || name === 'open_project') throw error;
       await openProject(projectId);
-      return call(name, { ...args, session }, true);
+      return call(name, { ...args, session }, { retried: true, timeoutMs: callTimeoutMs });
     }
     return result;
   }
@@ -181,9 +181,9 @@ export function createFramerMcpClient({
     readme: () => readme,
     session: () => session,
     projectId: () => projectId,
-    async exec(program) {
+    async exec(program, { timeoutMs: callTimeoutMs } = {}) {
       requireSession();
-      return call('exec', { session, program });
+      return call('exec', { session, program }, { timeoutMs: callTimeoutMs });
     },
     async readDocs(paths) {
       requireSession();