@gakim-digital/dexter-bridge 0.11.16 → 0.11.19

package/package.json

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

package/src/agent.js

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -6,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import crossSpawn from 'cross-spawn';
 import {
   getFramerProjectAuthorization,
+  readFramerWebsite,
   isCompanionPairingInvalidError,
   postRunEvent,
   reportFramerProjectAuthorizationVerification,
@@ -26,6 +28,7 @@ import {
 } from './config.js';
 import {
   assertOutcomeResponseContract,
+  buildFramerOutcomePrompt,
   buildOutcomePrompt,
   buildModelTurnDeltaPrompt,
   buildModelTurnFallbackPrompt,
@@ -327,6 +330,23 @@ function claudeModelEngineSystemPrompt(product) {
   ].join(' ');
 }
 
+// Content-addressed, so identical instructions reuse one file and stay
+// byte-identical for Claude Code's prompt cache.
+function writeClaudeSystemPromptFile(content) {
+  const directory = path.join(os.tmpdir(), 'instawebai-outcome-prompts');
+  const file = path.join(
+    directory,
+    `${crypto.createHash('sha256').update(content).digest('hex').slice(0, 32)}.md`,
+  );
+  if (!fs.existsSync(file)) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const partial = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(partial, content, { mode: 0o600 });
+    fs.renameSync(partial, file);
+  }
+  return file;
+}
+
 function claudeOutcomeSystemPrompt(product) {
   const name = normalizeBridgeProduct(product).name;
   if (normalizeBridgeProduct(product).id === 'dexter') {
@@ -336,7 +356,6 @@ function claudeOutcomeSystemPrompt(product) {
       'Inspect the project, perform the requested work, verify the result, and return the structured outcome.',
       'Do not access local credentials, unrelated files, other projects, account settings, or billing.',
       'Do not publish unless the assignment explicitly authorizes publishing.',
-      'Call progress_update before the first inspection or edit and at meaningful phase changes. Use one or two natural first-person sentences that name the specific page area, component, or behavior and the concrete change you are about to make or are making now; optionally say what you will check next. Avoid generic updates such as "working on the next step", "thinking", "loading", or "making changes".',
       'If framer_write is rejected by the safety boundary, do not retry JavaScript variants. Switch to framer_apply_changes, inspect the relevant state, or report the concrete blocker.',
       `Return only the structured outcome result requested by ${name}.`,
     ].join(' ');
@@ -383,6 +402,18 @@ function argsWithStructuredOutput(args, definition, env = process.env) {
   return args;
 }
 
+function framerWebHosts(framerHarness) {
+  const hosts = framerHarness?.context?.webAccess?.hosts;
+  if (!Array.isArray(hosts)) return [];
+  return [...new Set(
+    hosts
+      .map((value) => String(value || '').trim().toLowerCase())
+      .filter((value) =>
+        value.length <= 253
+        && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/.test(value)),
+  )].slice(0, 20);
+}
+
 function argsWithClaudeIsolation(args, definition, options = {}) {
   if (definition.id !== 'claude-code') return args;
   const isolated = argsWithoutVariadicFlag(args, '--tools');
@@ -405,8 +436,17 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
   const harnessTools = harnessToolNames.map(
     (name) => `mcp__instawebai__${name}`,
   );
+  const webHosts = options.framerHarness
+    ? framerWebHosts(options.framerHarness)
+    : [];
   const nativeTools = options.framerHarness
-    ? [...(options.nativeSkillsEnabled ? ['Skill'] : []), ...harnessTools]
+    ? [
+        ...(options.nativeSkillsEnabled ? ['Skill'] : []),
+        // Web access is limited to the sites the user named. WebSearch cannot
+        // be limited by domain, so only WebFetch is offered.
+        ...(webHosts.length ? ['WebFetch'] : []),
+        ...harnessTools,
+      ]
     : [
         'Read',
         'Write',
@@ -435,7 +475,16 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
     '--permission-mode',
     options.harnessMode && !options.framerHarness ? 'acceptEdits' : 'dontAsk',
   );
-  if (options.harnessMode) permissionMode.push('--allowedTools', nativeTools.join(','));
+  if (options.harnessMode) {
+    const allowedTools = options.framerHarness
+      ? [
+          ...(options.nativeSkillsEnabled ? ['Skill'] : []),
+          ...webHosts.map((host) => `WebFetch(domain:${host})`),
+          ...harnessTools,
+        ]
+      : nativeTools;
+    permissionMode.push('--allowedTools', ...allowedTools);
+  }
   if (!argsIncludeFlag(permissionMode, '--strict-mcp-config')) permissionMode.push('--strict-mcp-config');
   if (!argsIncludeFlag(permissionMode, '--no-chrome')) permissionMode.push('--no-chrome');
   let configured = permissionMode;
@@ -479,13 +528,18 @@ function argsWithClaudeModelEngine(args, definition, options = {}, env = process
   let isolated = argsWithoutFlagValue(args, '--system-prompt');
   isolated = argsWithoutFlagValue(isolated, '--append-system-prompt');
   isolated = argsWithoutFlagValue(isolated, '--agent');
+  isolated = argsWithoutFlagValue(isolated, '--system-prompt-file');
   isolated = argsWithoutFlagValue(isolated, '--effort');
   return [
     ...isolated,
-    '--system-prompt',
-    options.harnessMode
-      ? claudeOutcomeSystemPrompt(options.product)
-      : claudeModelEngineSystemPrompt(options.product),
+    ...(options.harnessMode && options.systemPromptFile
+      ? ['--system-prompt-file', options.systemPromptFile]
+      : [
+          '--system-prompt',
+          options.harnessMode
+            ? claudeOutcomeSystemPrompt(options.product)
+            : claudeModelEngineSystemPrompt(options.product),
+        ]),
     '--effort',
     claudeEffortForStep(options.step, env),
   ];
@@ -2283,7 +2337,15 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       1_000,
     ),
   );
-  const sessionKey = companionSessionKey(run);
+  const framerAgentOutcome =
+    run?.outcome?.kind === 'framer-project'
+    || run?.outcome?.context?.executionMode === 'framer-agent';
+  // 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
+    ? run?.runId || companionSessionKey(run)
+    : companionSessionKey(run);
   const infrastructureAbortController = new AbortController();
   const controlMonitorAbort = new AbortController();
   let finished = false;
@@ -2293,6 +2355,51 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
   let rejectCancellation;
   let latestTokenUsage = normalizeCompanionTokenUsage();
   let activityChain = Promise.resolve();
+  const webCalls = new Map();
+  const recordWebCall = (webCall) => {
+    if (!webCall || typeof webCall !== 'object') return;
+    const id = String(webCall.id || '').trim();
+    const tool =
+      webCall.tool === 'WebFetch'
+        ? 'WebFetch'
+        : webCall.tool === 'WebSearch'
+          ? 'WebSearch'
+          : '';
+    if (!id || !tool) return;
+    const current = webCalls.get(id) || {
+      tool,
+      site: null,
+      status: 'started',
+    };
+    webCalls.set(id, {
+      ...current,
+      tool,
+      site:
+        typeof webCall.site === 'string' && webCall.site.trim()
+          ? webCall.site.trim().toLowerCase().slice(0, 253)
+          : current.site,
+      status:
+        webCall.status === 'succeeded' || webCall.status === 'failed'
+          ? webCall.status
+          : current.status,
+      errorMessage:
+        webCall.status === 'failed' && typeof webCall.errorMessage === 'string'
+          ? clip(webCall.errorMessage, 300)
+          : current.errorMessage,
+    });
+    if (webCalls.size > 100) {
+      webCalls.delete(webCalls.keys().next().value);
+    }
+  };
+  const webCallSummary = () =>
+    [...webCalls.values()].map((call) => ({
+      tool: call.tool,
+      site: call.site,
+      status: call.status === 'succeeded' ? 'succeeded' : 'failed',
+      ...(call.status === 'failed'
+        ? { errorMessage: call.errorMessage || 'The web call did not complete.' }
+        : {}),
+    }));
   const cancellation = new Promise((_, reject) => {
     rejectCancellation = reject;
   });
@@ -2345,6 +2452,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     return activityChain;
   };
   const progress = (event = {}) => {
+    recordWebCall(event.webCall);
     if (event.tokenUsage) {
       latestTokenUsage = normalizeCompanionTokenUsage(event.tokenUsage);
     }
@@ -2385,9 +2493,15 @@ 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
+    // (a tool call costs a whole turn), so that text is the user's progress.
+    const narration =
+      framerAgentOutcome
+      && event.kind === 'output_delta'
+      && String(event.activity || '').startsWith('assistant:');
     const userFacingUpdate =
-      event.kind === 'status_update'
-      && event.source === 'harness';
+      (event.kind === 'status_update' && event.source === 'harness')
+      || narration;
     void postActivity({
       stage: 'outcome',
       outcomeId: run?.outcome?.outcomeId,
@@ -2397,9 +2511,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       provider: definition.id,
       tool: event.name || undefined,
       toolPhase: event.phase || undefined,
-      activity:
-        event.activity ||
-        (userFacingUpdate ? `assistant-progress:${Date.now()}` : undefined),
+      activity: narration
+        ? event.activity.replace(/^assistant:/, 'assistant-progress:')
+        : event.activity ||
+          (userFacingUpdate ? `assistant-progress:${Date.now()}` : undefined),
       paths: event.paths || undefined,
       tokenUsage: event.tokenUsage || undefined,
       occurredAt: event.occurredAt || new Date().toISOString(),
@@ -2445,18 +2560,16 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     }
   };
   const controlMonitor = monitorControl();
-  const rememberedSession =
-    rememberedCompanionSession(sessionKey) ||
-    (run?.outcome?.session?.providerSessionId
-      ? {
-          providerSessionId: run.outcome.session.providerSessionId,
-          agent: definition.id,
-          updatedAt: Date.now(),
-        }
-      : null);
-  const framerAgentOutcome =
-    run?.outcome?.kind === 'framer-project'
-    || run?.outcome?.context?.executionMode === 'framer-agent';
+  const rememberedSession = framerAgentOutcome
+    ? null
+    : rememberedCompanionSession(sessionKey) ||
+      (run?.outcome?.session?.providerSessionId
+        ? {
+            providerSessionId: run.outcome.session.providerSessionId,
+            agent: definition.id,
+            updatedAt: Date.now(),
+          }
+        : null);
   const materialized = materializeOutcomeWorkspace(run?.outcome, {
     sessionId: run?.outcome?.context?.harnessSessionId || sessionKey,
   });
@@ -2536,6 +2649,18 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
                   allowInsecureHttp: options.allowInsecureHttp,
                 })
             : undefined,
+        readWebsite:
+          options.apiBaseUrl && options.deviceToken
+            ? ({ url, screenshotTop }) =>
+                readFramerWebsite(options.apiBaseUrl, {
+                  deviceToken: options.deviceToken,
+                  runId: run.runId,
+                  url,
+                  screenshotTop,
+                  fetchImpl: options.fetchImpl,
+                  allowInsecureHttp: options.allowInsecureHttp,
+                })
+            : undefined,
         verifyProjectAuthorization:
           options.apiBaseUrl && options.deviceToken
             ? ({
@@ -2588,11 +2713,34 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           cancellation,
         ])
       : null;
-    prompt = buildOutcomePrompt(executionOutcome, product, {
+    const promptContext = {
       doctrine: run?.doctrine,
       doctrineVersion: run?.doctrineVersion,
       framerGuidance: framerGuidance?.content,
-    });
+      projectInventory: framerGuidance?.inventory,
+    };
+    // Claude Code gets the run-independent instructions as its system prompt,
+    // which it caches across sessions: later runs and follow-up messages read
+    // them from the cache instead of writing them again.
+    let systemPromptFile = null;
+    let systemPromptBytes = 0;
+    if (
+      framerAgentOutcome
+      && definition.id === 'claude-code'
+      && !options.providerAdapter?.runOutcome
+    ) {
+      const { instructions, task } = buildFramerOutcomePrompt(
+        executionOutcome,
+        product,
+        promptContext,
+      );
+      const systemPrompt = `${claudeOutcomeSystemPrompt(product)}\n\n${instructions}`;
+      systemPromptFile = writeClaudeSystemPromptFile(systemPrompt);
+      systemPromptBytes = Buffer.byteLength(systemPrompt, 'utf8');
+      prompt = task;
+    } else {
+      prompt = buildOutcomePrompt(executionOutcome, product, promptContext);
+    }
     const unresolvedTargets = preflight?.unresolvedTargets || [];
     if (unresolvedTargets.length > 0) {
       prompt = [
@@ -2607,7 +2755,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     harnessTools.configurePromptContext?.({
       doctrineLoaded: Boolean(run?.doctrine),
       doctrineVersion: run?.doctrineVersion,
-      promptBytes: Buffer.byteLength(prompt, 'utf8'),
+      promptBytes: systemPromptBytes + Buffer.byteLength(prompt, 'utf8'),
     });
     const gateway =
       definition.id === 'codex' ? null : await harnessTools.startGateway();
@@ -2667,7 +2815,8 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           maxDurationMs: outcomeMaxDurationMs,
           cwd: materialized.directory,
           nativeSkills,
-          framerHarness: framerAgentOutcome,
+          framerHarness: framerAgentOutcome ? executionOutcome : false,
+          webHosts: framerAgentOutcome ? framerWebHosts(executionOutcome) : [],
           imageFiles,
           harnessTools: {
             definitions: codexDynamicToolSpecs(harnessTools.definitions),
@@ -2708,7 +2857,8 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           maxDurationMs: outcomeMaxDurationMs,
           cwd: materialized.directory,
           harnessMode: true,
-          framerHarness: framerAgentOutcome,
+          systemPromptFile,
+          framerHarness: framerAgentOutcome ? executionOutcome : false,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
           imageFiles,
@@ -2731,7 +2881,8 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           maxDurationMs: outcomeMaxDurationMs,
           cwd: materialized.directory,
           harnessMode: true,
-          framerHarness: framerAgentOutcome,
+          systemPromptFile,
+          framerHarness: framerAgentOutcome ? executionOutcome : false,
           harnessToolNames: harnessTools.toolNames,
           nativeSkillsEnabled: Boolean(materializedNativeSkills),
           imageFiles,
@@ -2871,7 +3022,12 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           sourceHash:
             synchronization?.sourceHash || harnessTools.sourceHash() || null,
           ...(typeof harnessTools.summary === 'function'
-            ? { framer: harnessTools.summary() }
+            ? {
+                framer: {
+                  ...harnessTools.summary(),
+                  webCalls: webCallSummary(),
+                },
+              }
             : {}),
         }
       : completion;
@@ -2914,7 +3070,10 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     usageAccumulator.add(failure.companionUsage || {});
     const framer =
       typeof harnessTools.summary === 'function'
-        ? harnessTools.summary()
+        ? {
+            ...harnessTools.summary(),
+            webCalls: webCallSummary(),
+          }
         : undefined;
     failure.framer = framer;
     failure.companionUsage = {

package/src/agentOutput.js

@@ -320,6 +320,30 @@ function claudeToolProgress(name, input = {}, cwd) {
   };
 }
 
+function webSite(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  for (const candidate of value.match(/https?:\/\/[^\s"'<>]+/gi) || []) {
+    try {
+      return new URL(candidate).hostname.toLowerCase();
+    } catch {
+      // Keep looking for a valid URL.
+    }
+  }
+  return null;
+}
+
+function claudeToolResultMessage(part) {
+  if (typeof part?.content === 'string') return progressText(part.content, 300);
+  if (!Array.isArray(part?.content)) return '';
+  return progressText(
+    part.content
+      .map((item) => typeof item?.text === 'string' ? item.text : '')
+      .filter(Boolean)
+      .join(' '),
+    300,
+  );
+}
+
 function summedClaudeProgressUsage(turnUsage) {
   const total = normalizeCompanionTokenUsage();
   for (const usage of turnUsage.values()) {
@@ -403,7 +427,21 @@ export function createClaudeProgressParser(onProgress, options = {}) {
         continue;
       }
       const progress = claudeToolProgress(part.name, input, options.cwd);
-      tools.set(part.id, { name: part.name, ...progress });
+      const nativeWebTool =
+        part.name === 'WebFetch'
+          ? 'WebFetch'
+          : part.name === 'WebSearch'
+            ? 'WebSearch'
+            : null;
+      const webCall = nativeWebTool
+        ? {
+            id: part.id,
+            tool: nativeWebTool,
+            site: webSite(input.url || input.query),
+            status: 'started',
+          }
+        : null;
+      tools.set(part.id, { name: part.name, ...progress, webCall });
       emit({
         kind: 'item_started',
         name: part.name,
@@ -411,6 +449,7 @@ export function createClaudeProgressParser(onProgress, options = {}) {
         activity: `tool:${part.id}`,
         paths: progress.paths,
         message: progress.startedMessage,
+        ...(webCall ? { webCall } : {}),
       });
     }
   };
@@ -430,6 +469,17 @@ export function createClaudeProgressParser(onProgress, options = {}) {
         activity: `tool:${part.tool_use_id}`,
         paths: tool.paths,
         message: failed ? tool.failedMessage : tool.completedMessage,
+        ...(tool.webCall
+          ? {
+              webCall: {
+                ...tool.webCall,
+                status: failed ? 'failed' : 'succeeded',
+                ...(failed
+                  ? { errorMessage: claudeToolResultMessage(part) || tool.failedMessage }
+                  : {}),
+              },
+            }
+          : {}),
       });
     }
   };

package/src/api.js

@@ -235,6 +235,37 @@ export function getFramerProjectAuthorization(apiBaseUrl, {
   );
 }
 
+// Reads one page of a website the user named, through Dexter. A page render
+// can take most of a minute, so this waits longer than other calls.
+export function readFramerWebsite(apiBaseUrl, {
+  deviceToken,
+  runId,
+  url,
+  screenshotTop,
+  fetchImpl,
+  signal,
+  allowInsecureHttp,
+}) {
+  return requestJson(
+    apiBaseUrl,
+    `/ai/framer/companion/runs/${encodeURIComponent(runId)}/read-website`,
+    {
+      method: 'POST',
+      deviceToken,
+      fetchImpl,
+      signal,
+      allowInsecureHttp,
+      timeoutMs: 150_000,
+      body: {
+        url,
+        ...(Number.isInteger(screenshotTop) ? { screenshotTop } : {}),
+        platform: process.platform,
+        companionVersion: BRIDGE_VERSION,
+      },
+    },
+  );
+}
+
 export function reportFramerProjectAuthorizationVerification(apiBaseUrl, {
   deviceToken,
   runId,

package/src/config.js

@@ -44,6 +44,7 @@ export const BRIDGE_CAPABILITIES = [
   'framer-project-bootstrap-v1',
   'framer-project-verification-v1',
   'framer-interaction-verification-v4',
+  'framer-read-website-v1',
   'project-shell-v1',
   'build-fingerprint-v1',
   'tool-schema-parity-v1',