@gakim-digital/dexter-bridge 0.12.2 → 0.13.0

package/LICENSE

@@ -0,0 +1,16 @@
+Dexter Bridge License
+
+Copyright (c) 2026 InstaWeb AI. All rights reserved.
+
+Permission is granted to download, install, and run this software solely to
+connect your local machine to the Dexter / InstaWeb AI service. You may not
+modify, redistribute, sublicense, or sell this software or use it to build a
+competing service.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

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

package/src/agent.js

@@ -6,7 +6,10 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import crossSpawn from 'cross-spawn';
 import {
+  callWebflowPanelTool,
+  findWebflowImages,
   getFramerProjectAuthorization,
+  webflowMcpEndpoint,
   readFramerWebsite,
   isCompanionPairingInvalidError,
   postRunEvent,
@@ -29,6 +32,7 @@ import {
   assertOutcomeResponseContract,
   buildFramerOutcomePrompt,
   buildOutcomePrompt,
+  buildWebflowOutcomePrompt,
   buildModelTurnDeltaPrompt,
   buildModelTurnFallbackPrompt,
   buildModelTurnPrompt,
@@ -65,6 +69,7 @@ import {
   createHarnessToolRuntime,
 } from './harnessTools.js';
 import { createFramerAgentToolRuntime } from './framerTools.js';
+import { assertWebflowHarnessAgent, createWebflowToolRuntime } from './webflowTools.js';
 
 const HARNESS_MCP_SERVER_PATH = fileURLToPath(
   new URL('./harnessMcpServer.js', import.meta.url),
@@ -356,6 +361,18 @@ function writeClaudeSystemPromptFile(content) {
   return file;
 }
 
+function claudeWebflowOutcomeSystemPrompt(product) {
+  const name = normalizeBridgeProduct(product).name;
+  return [
+    `You are an autonomous Webflow harness embedded inside ${name}.`,
+    'Work only through the Dexter Webflow tools connected to the user-selected site.',
+    'Inspect the site, perform the requested work, verify the result, and return the structured outcome.',
+    'Do not access local credentials, unrelated files, other sites, account settings, or billing.',
+    'Do not publish unless the assignment explicitly authorizes publishing.',
+    `Return only the structured outcome result requested by ${name}.`,
+  ].join(' ');
+}
+
 function claudeOutcomeSystemPrompt(product) {
   const name = normalizeBridgeProduct(product).name;
   if (normalizeBridgeProduct(product).id === 'dexter') {
@@ -445,10 +462,11 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
   const harnessTools = harnessToolNames.map(
     (name) => `mcp__instawebai__${name}`,
   );
-  const webHosts = options.framerHarness
-    ? framerWebHosts(options.framerHarness)
+  const designHarness = options.designHarness || options.framerHarness;
+  const webHosts = designHarness
+    ? framerWebHosts(designHarness)
     : [];
-  const nativeTools = options.framerHarness
+  const nativeTools = designHarness
     ? [
         ...(options.nativeSkillsEnabled ? ['Skill'] : []),
         // Web access is limited to the sites the user named. WebSearch cannot
@@ -482,10 +500,10 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
   const permissionMode = argsWithoutFlagValue(projectSettingsOnly, '--permission-mode');
   permissionMode.push(
     '--permission-mode',
-    options.harnessMode && !options.framerHarness ? 'acceptEdits' : 'dontAsk',
+    options.harnessMode && !designHarness ? 'acceptEdits' : 'dontAsk',
   );
   if (options.harnessMode) {
-    const allowedTools = options.framerHarness
+    const allowedTools = designHarness
       ? [
           ...(options.nativeSkillsEnabled ? ['Skill'] : []),
           ...webHosts.map((host) => `WebFetch(domain:${host})`),
@@ -505,8 +523,8 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
   // Framer run with skills leaves it off. The explicit tool list above is what
   // keeps the shell and file tools out; it grants the Framer tools and Skill
   // only, and settings stay limited to the workspace the bridge created.
-  const framerRunWithSkills = Boolean(options.framerHarness && options.nativeSkillsEnabled);
-  if (options.harnessMode && !framerRunWithSkills && !argsIncludeFlag(configured, '--restricted')) {
+  const designRunWithSkills = Boolean(designHarness && options.nativeSkillsEnabled);
+  if (options.harnessMode && !designRunWithSkills && !argsIncludeFlag(configured, '--restricted')) {
     configured.push('--restricted');
   }
   return configured;
@@ -1188,6 +1206,15 @@ export function agentFailureMessage(command, code, stdout = '', stderr = '') {
   return agentFailureDetails(command, code, stdout, stderr).message;
 }
 
+// Agent CLIs run in their own process group, so a signal that stops the
+// bridge never reaches them; stopping the bridge aborts them explicitly.
+const bridgeShutdown = new AbortController();
+
+export function stopAgentProcesses() {
+  if (bridgeShutdown.signal.aborted) return;
+  bridgeShutdown.abort(new CompanionRunCancelledError('The Dexter bridge stopped.', 'device_disconnect'));
+}
+
 function runProcess(
   command,
   args,
@@ -1206,8 +1233,9 @@ function runProcess(
   } = {},
 ) {
   return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      const error = signal.reason instanceof Error ? signal.reason : new Error('The model process was cancelled.');
+    const stopped = [signal, bridgeShutdown.signal].find((candidate) => candidate?.aborted);
+    if (stopped) {
+      const error = stopped.reason instanceof Error ? stopped.reason : new Error('The model process was cancelled.');
       error.code = error.code || 'RUN_CANCELLED';
       reject(error);
       return;
@@ -1278,6 +1306,7 @@ function runProcess(
       clearTimeout(forceKillTimer);
       clearTimeout(terminationFallbackTimer);
       signal?.removeEventListener('abort', abort);
+      bridgeShutdown.signal.removeEventListener('abort', abort);
       error.stdout = stdout;
       error.stderr = stderr;
       reject(error);
@@ -1294,10 +1323,11 @@ function runProcess(
       }, killGraceMs);
       forceKillTimer.unref?.();
     };
-    const abort = () => {
+    const abort = (event) => {
       if (settled || terminationError) return;
       clearTimers();
-      const error = signal?.reason instanceof Error ? signal.reason : new Error('The model process was cancelled.');
+      const reason = event?.target?.reason;
+      const error = reason instanceof Error ? reason : new Error('The model process was cancelled.');
       error.code = error.code || 'RUN_CANCELLED';
       terminationError = error;
       terminateChildTree(error);
@@ -1342,6 +1372,7 @@ function runProcess(
       );
     }, hardDeadlineMs);
     signal?.addEventListener('abort', abort, { once: true });
+    bridgeShutdown.signal.addEventListener('abort', abort, { once: true });
     armInactivityTimer();
 
     child.stdout.on('data', (chunk) => {
@@ -1392,6 +1423,7 @@ function runProcess(
       clearTimeout(forceKillTimer);
       clearTimeout(terminationFallbackTimer);
       signal?.removeEventListener('abort', abort);
+      bridgeShutdown.signal.removeEventListener('abort', abort);
       stdoutProgress?.flush();
       const meta = {
         command,
@@ -1570,8 +1602,15 @@ class CompanionRunCancelledError extends Error {
 }
 
 function cancellationMessage(error) {
+  const webflow = error?.webflow || error?.companionUsage?.webflow;
+  if (webflow) {
+    const mutationCalls = Number(webflow.mutationCalls) || 0;
+    if (mutationCalls <= 0) return 'Stopped before Dexter completed a Webflow change.';
+    return `Stopped after ${mutationCalls} successful Webflow change ${mutationCalls === 1 ? 'call' : 'calls'}. Those changes remain in Webflow.`;
+  }
   const framer = error?.framer || error?.companionUsage?.framer;
-  const mutationCalls = Number(framer?.mutationCalls) || 0;
+  if (!framer) return 'Dexter stopped this request.';
+  const mutationCalls = Number(framer.mutationCalls) || 0;
   if (mutationCalls <= 0) {
     return 'Stopped before Dexter completed a Framer change.';
   }
@@ -1907,7 +1946,7 @@ async function callLocalJsonAgent(agent, prompt, options = {}) {
     onProgress: options.onProgress,
     stdoutProgress:
       definition.id === 'claude-code'
-        ? createClaudeProgressParser(options.onProgress, { cwd: options.cwd })
+        ? createClaudeProgressParser(options.onProgress, { cwd: options.cwd, trace: options.trace })
         : undefined,
   });
 }
@@ -2241,7 +2280,7 @@ async function executeModelTurn(run, send, agent, options = {}) {
       });
     } catch (error) {
       if (cliCancelled || error?.code === 'RUN_CANCELLED') {
-        throw new CompanionRunCancelledError();
+        throw new CompanionRunCancelledError(undefined, error?.cancellationSource);
       }
       const failure = agentErrorWithOutputUsage(definition.id, error);
       if (callContextMode !== 'delta' || !resumeFailure(failure)) throw failedModelCall(failure);
@@ -2273,7 +2312,7 @@ async function executeModelTurn(run, send, agent, options = {}) {
         onProgress: reportCliProgress,
       }).catch((error) => {
         if (cliCancelled || error?.code === 'RUN_CANCELLED') {
-          throw new CompanionRunCancelledError();
+          throw new CompanionRunCancelledError(undefined, error?.cancellationSource);
         }
         throw failedModelCall(agentErrorWithOutputUsage(definition.id, error));
       });
@@ -2383,10 +2422,13 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
   const framerAgentOutcome =
     run?.outcome?.kind === 'framer-project'
     || run?.outcome?.context?.executionMode === 'framer-mcp';
+  const webflowOutcome = run?.outcome?.kind === 'webflow-site';
+  if (webflowOutcome) assertWebflowHarnessAgent(definition.id);
+  const designOutcome = framerAgentOutcome || webflowOutcome;
   // Every Dexter message starts a fresh provider session. The assignment
   // already carries the recent conversation, and resuming would make every
   // turn of this run re-read the whole previous run as well.
-  const sessionKey = framerAgentOutcome
+  const sessionKey = designOutcome
     ? run?.runId || companionSessionKey(run)
     : companionSessionKey(run);
   const infrastructureAbortController = new AbortController();
@@ -2536,10 +2578,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       Boolean(event.message || event.name) ||
       event.kind === 'turn_started';
     if (!meaningful) return;
-    // Framer runs narrate in plain text rather than through a progress tool
+    // Design runs narrate in plain text rather than through a progress tool
     // (a tool call costs a whole turn), so that text is the user's progress.
     const narration =
-      framerAgentOutcome
+      designOutcome
       && event.kind === 'output_delta'
       && String(event.activity || '').startsWith('assistant:');
     const userFacingUpdate =
@@ -2603,7 +2645,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     }
   };
   const controlMonitor = monitorControl();
-  const rememberedSession = framerAgentOutcome
+  const rememberedSession = designOutcome
     ? null
     : rememberedCompanionSession(sessionKey) ||
       (run?.outcome?.session?.providerSessionId
@@ -2704,6 +2746,61 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
                 })
             : undefined,
       })
+    : webflowOutcome
+      ? createWebflowToolRuntime({
+          assignment: executionOutcome,
+          trace: options.trace,
+          onActivity: progress,
+          mcpEndpoint:
+            options.apiBaseUrl && options.deviceToken
+              ? webflowMcpEndpoint(options.apiBaseUrl, {
+                  deviceToken: options.deviceToken,
+                  runId: run.runId,
+                  allowInsecureHttp: options.allowInsecureHttp,
+                })
+              : undefined,
+          callPanelTool:
+            options.apiBaseUrl && options.deviceToken
+              ? ({ callId, name, arguments: toolArguments, signal }) =>
+                  callWebflowPanelTool(options.apiBaseUrl, {
+                    deviceToken: options.deviceToken,
+                    runId: run.runId,
+                    callId,
+                    name,
+                    arguments: toolArguments,
+                    fetchImpl: options.fetchImpl,
+                    signal,
+                    allowInsecureHttp: options.allowInsecureHttp,
+                  })
+              : undefined,
+          findImages:
+            options.apiBaseUrl && options.deviceToken
+              ? ({ query, orientation, count, signal }) =>
+                  findWebflowImages(options.apiBaseUrl, {
+                    deviceToken: options.deviceToken,
+                    runId: run.runId,
+                    query,
+                    orientation,
+                    count,
+                    fetchImpl: options.fetchImpl,
+                    signal,
+                    allowInsecureHttp: options.allowInsecureHttp,
+                  })
+              : undefined,
+          readWebsite:
+            options.apiBaseUrl && options.deviceToken
+              ? ({ url, screenshotTop, signal }) =>
+                  readFramerWebsite(options.apiBaseUrl, {
+                    deviceToken: options.deviceToken,
+                    runId: run.runId,
+                    url,
+                    screenshotTop,
+                    fetchImpl: options.fetchImpl,
+                    signal,
+                    allowInsecureHttp: options.allowInsecureHttp,
+                  })
+              : undefined,
+        })
     : createHarnessToolRuntime({
         assignment: executionOutcome,
         materialized,
@@ -2725,10 +2822,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
   let providerAttempts = 0;
   let result;
   try {
-    const preflight = framerAgentOutcome
+    const preflight = designOutcome
       ? await Promise.race([harnessTools.preflight(), cancellation])
       : null;
-    const framerGuidance = framerAgentOutcome
+    const projectGuidance = designOutcome
       ? await Promise.race([
           harnessTools.loadProjectGuidance(),
           cancellation,
@@ -2737,8 +2834,9 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     const promptContext = {
       doctrine: run?.doctrine,
       doctrineVersion: run?.doctrineVersion,
-      framerGuidance: framerGuidance?.content,
-      projectInventory: framerGuidance?.inventory,
+      framerGuidance: framerAgentOutcome ? projectGuidance?.content : undefined,
+      projectInventory: framerAgentOutcome ? projectGuidance?.inventory : undefined,
+      webflowGuidance: webflowOutcome ? projectGuidance?.content : undefined,
     };
     // Claude Code gets the run-independent instructions as its system prompt,
     // which it caches across sessions: later runs and follow-up messages read
@@ -2746,16 +2844,14 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     let systemPromptFile = null;
     let systemPromptBytes = 0;
     if (
-      framerAgentOutcome
+      designOutcome
       && definition.id === 'claude-code'
       && !options.providerAdapter?.runOutcome
     ) {
-      const { instructions, task } = buildFramerOutcomePrompt(
-        executionOutcome,
-        product,
-        promptContext,
-      );
-      const systemPrompt = `${claudeOutcomeSystemPrompt(product)}\n\n${instructions}`;
+      const { instructions, task } = webflowOutcome
+        ? buildWebflowOutcomePrompt(executionOutcome, product, promptContext)
+        : buildFramerOutcomePrompt(executionOutcome, product, promptContext);
+      const systemPrompt = `${(webflowOutcome ? claudeWebflowOutcomeSystemPrompt : claudeOutcomeSystemPrompt)(product)}\n\n${instructions}`;
       systemPromptFile = writeClaudeSystemPromptFile(systemPrompt);
       systemPromptBytes = Buffer.byteLength(systemPrompt, 'utf8');
       prompt = task;
@@ -2837,7 +2933,8 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           cwd: materialized.directory,
           nativeSkills,
           framerHarness: framerAgentOutcome ? executionOutcome : false,
-          webHosts: framerAgentOutcome ? framerWebHosts(executionOutcome) : [],
+          designHarness: designOutcome ? executionOutcome : false,
+          webHosts: designOutcome ? framerWebHosts(executionOutcome) : [],
           imageFiles,
           harnessTools: {
             definitions: codexDynamicToolSpecs(harnessTools.definitions),
@@ -2880,6 +2977,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           harnessMode: true,
           systemPromptFile,
           framerHarness: framerAgentOutcome ? executionOutcome : false,
+          designHarness: designOutcome ? executionOutcome : false,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
           imageFiles,
@@ -2904,6 +3002,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           harnessMode: true,
           systemPromptFile,
           framerHarness: framerAgentOutcome ? executionOutcome : false,
+          designHarness: designOutcome ? executionOutcome : false,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
           imageFiles,
@@ -2993,9 +3092,11 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         source: 'harness',
         message:
           repairPrompt === unappliedChangePrompt
-            ? 'Nothing has changed in Framer yet, so I’m making the change before I finish.'
+            ? `Nothing has changed in ${webflowOutcome ? 'Webflow' : 'Framer'} yet, so I’m making the change before I finish.`
             : rawCompletion.status === successStatus
-              ? 'I’m completing the final Framer verification before I finish.'
+              ? (webflowOutcome
+                ? 'I’m completing the final Webflow verification before I finish.'
+                : 'I’m completing the final Framer verification before I finish.')
               : 'Nothing is blocking this change, so I’m continuing the work.',
       });
       const repairResult = await Promise.race([
@@ -3055,7 +3156,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
             synchronization?.sourceHash || harnessTools.sourceHash() || null,
           ...(typeof harnessTools.summary === 'function'
             ? {
-                framer: {
+                [webflowOutcome ? 'webflow' : 'framer']: {
                   ...harnessTools.summary(),
                   webCalls: webCallSummary(),
                 },
@@ -3098,19 +3199,22 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     const failure =
       error instanceof Error
         ? error
-        : new Error(String(error || 'The Framer outcome failed.'));
+        : new Error(String(error || 'The Dexter run failed.'));
     usageAccumulator.add(failure.companionUsage || {});
-    const framer =
+    const harnessSummary =
       typeof harnessTools.summary === 'function'
         ? {
             ...harnessTools.summary(),
             webCalls: webCallSummary(),
           }
         : undefined;
-    failure.framer = framer;
+    if (webflowOutcome) failure.webflow = harnessSummary;
+    else failure.framer = harnessSummary;
     failure.companionUsage = {
       ...usageAccumulator.snapshot(),
-      ...(framer ? { framer } : {}),
+      ...(harnessSummary
+        ? { [webflowOutcome ? 'webflow' : 'framer']: harnessSummary }
+        : {}),
     };
     throw failure;
   } finally {
@@ -3118,7 +3222,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     controlMonitorAbort.abort();
     await controlMonitor.catch(() => undefined);
     await harnessTools
-      .close({ waitForPending: !cancelRequested })
+      .close({ waitForPending: !cancelRequested && !bridgeShutdown.signal.aborted })
       .catch(() => undefined);
     removeOutcomeReferenceAssets(materialized);
     removeOutcomeWorkspace(materialized);

package/src/agentOutput.js

@@ -521,6 +521,12 @@ export function createClaudeProgressParser(onProgress, options = {}) {
     if (!trimmed) return;
     try {
       const row = JSON.parse(trimmed);
+      if (row?.type === 'system' && row.subtype !== 'init') {
+        options.trace?.warn?.('claude_system_event', { event: JSON.stringify(row).slice(0, 1_000) });
+      }
+      if (row?.type === 'rate_limit_event' && row.rate_limit_info?.status !== 'allowed') {
+        options.trace?.warn?.('claude_rate_limit', { rateLimit: row.rate_limit_info });
+      }
       if (row?.type === 'stream_event') processStreamEvent(row);
       if (row?.type === 'assistant') finishDrafting(row);
       if (row?.type === 'assistant') processAssistant(row);

package/src/api.js

@@ -184,6 +184,7 @@ export function pollRun(apiBaseUrl, {
   model,
   metadata,
   runtimeProfiles,
+  refreshingModelCatalog = false,
   fetchImpl,
   allowInsecureHttp,
 }) {
@@ -202,6 +203,7 @@ export function pollRun(apiBaseUrl, {
       status: 'polling',
       metadata: bridgeMetadata(normalizedAgent, normalizedModel, metadata),
       runtimeProfiles,
+      refreshingModelCatalog,
     },
   });
 }
@@ -265,6 +267,79 @@ export function readFramerWebsite(apiBaseUrl, {
   );
 }
 
+// The run's Webflow MCP endpoint on Dexter's API. The Webflow token never leaves the API.
+export function webflowMcpEndpoint(apiBaseUrl, { deviceToken, runId, allowInsecureHttp }) {
+  return {
+    url: `${normalizeApiBaseUrl(apiBaseUrl, { allowInsecureHttp })}/ai/framer/companion/runs/${encodeURIComponent(runId)}/webflow-mcp`,
+    headers: {
+      ...bearerHeaders(deviceToken),
+      'X-Dexter-Companion-Version': BRIDGE_VERSION,
+      'X-Dexter-Platform': process.platform,
+    },
+  };
+}
+
+export function callWebflowPanelTool(apiBaseUrl, {
+  deviceToken,
+  runId,
+  callId,
+  name,
+  arguments: toolArguments,
+  fetchImpl,
+  signal,
+  allowInsecureHttp,
+}) {
+  return requestJson(
+    apiBaseUrl,
+    `/ai/framer/companion/runs/${encodeURIComponent(runId)}/panel-tools`,
+    {
+      method: 'POST',
+      deviceToken,
+      fetchImpl,
+      signal,
+      allowInsecureHttp,
+      timeoutMs: 45_000,
+      body: {
+        callId,
+        name,
+        arguments: toolArguments || {},
+        platform: process.platform,
+        companionVersion: BRIDGE_VERSION,
+      },
+    },
+  );
+}
+
+export function findWebflowImages(apiBaseUrl, {
+  deviceToken,
+  runId,
+  query,
+  orientation,
+  count,
+  fetchImpl,
+  signal,
+  allowInsecureHttp,
+}) {
+  return requestJson(
+    apiBaseUrl,
+    `/ai/framer/companion/runs/${encodeURIComponent(runId)}/find-images`,
+    {
+      method: 'POST',
+      deviceToken,
+      fetchImpl,
+      signal,
+      allowInsecureHttp,
+      body: {
+        query,
+        ...(orientation ? { orientation } : {}),
+        ...(count ? { count } : {}),
+        platform: process.platform,
+        companionVersion: BRIDGE_VERSION,
+      },
+    },
+  );
+}
+
 export function postRunEvent(apiBaseUrl, {
   deviceToken,
   runId,