@gakim-digital/dexter-bridge 0.11.12 → 0.11.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.11.12",
+  "version": "0.11.14",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "@ai-sdk/openai-compatible": "^3.0.41",
     "@ai-sdk/xai": "^4.0.50",
     "@anthropic-ai/claude-agent-sdk": "^0.2.73",
-    "@framer/agent": "0.0.44",
+    "@framer/agent": "0.0.46",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@opencode-ai/sdk": "^1.18.25",
     "@openrouter/ai-sdk-provider": "^3.0.0",

package/src/agent.js

@@ -51,6 +51,7 @@ import { createLocalAgentAdapter } from './providers/index.js';
 import { discoverClaudeCodeModels } from './providers/claudeAgentSdk.js';
 import {
   collectOutcomeWorkspaceChanges,
+  materializeModelTurnImages,
   materializeOutcomeReferenceAssets,
   materializeOutcomeWorkspace,
   removeOutcomeReferenceAssets,
@@ -405,7 +406,7 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
     (name) => `mcp__instawebai__${name}`,
   );
   const nativeTools = options.framerHarness
-    ? harnessTools
+    ? [...(options.nativeSkillsEnabled ? ['Skill'] : []), ...harnessTools]
     : [
         'Read',
         'Write',
@@ -442,7 +443,12 @@ function argsWithClaudeIsolation(args, definition, options = {}) {
     configured = argsWithoutFlagValue(configured, '--mcp-config');
     configured.push('--mcp-config', JSON.stringify(options.mcpConfig));
   }
-  if (options.harnessMode && !argsIncludeFlag(configured, '--restricted')) {
+  // Restricted mode ignores the skills written into the run workspace, so a
+  // 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')) {
     configured.push('--restricted');
   }
   return configured;
@@ -1824,6 +1830,15 @@ function agentErrorWithOutputUsage(agent, error) {
 }
 
 async function executeModelTurnRun(run, send, agent, options = {}) {
+  const images = materializeModelTurnImages(run?.modelTurn?.messages);
+  try {
+    return await executeModelTurn(run, send, agent, { ...options, imageFiles: images.files });
+  } finally {
+    images.remove();
+  }
+}
+
+async function executeModelTurn(run, send, agent, options = {}) {
   const product = normalizeBridgeProduct(run?.product || options.product);
   const productName = product.name;
   if (normalizeAgentName(agent) === 'dry-run' && !options.providerAdapter) {
@@ -1949,6 +1964,7 @@ async function executeModelTurnRun(run, send, agent, options = {}) {
         1000,
       ),
       nativeSkills,
+      imageFiles: options.imageFiles,
     };
     const adapterOptions = {
       send,
@@ -2345,6 +2361,26 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       });
       return;
     }
+    if (event.kind === 'skill_used') {
+      // The harness loaded a skill on its own. Dexter shows which one; the
+      // aggregate of picked skills is already known to it.
+      const skill = (materializedNativeSkills?.skills || []).find(
+        (candidate) => candidate.nativeName === event.skillName,
+      );
+      if (!skill) return;
+      void postActivity({
+        stage: 'outcome',
+        outcomeId: run?.outcome?.outcomeId,
+        source: 'harness',
+        meaningful: true,
+        kind: 'skill_used',
+        provider: definition.id,
+        skillId: skill.skillId,
+        occurredAt: event.occurredAt || new Date().toISOString(),
+        message: `Using ${skill.name}`,
+      });
+      return;
+    }
     const meaningful =
       Boolean(event.message || event.name) ||
       event.kind === 'turn_started';

package/src/agentOutput.js

@@ -397,6 +397,11 @@ export function createClaudeProgressParser(onProgress, options = {}) {
         });
         continue;
       }
+      if (part.name === 'Skill' && progressText(input.skill)) {
+        tools.set(part.id, { suppressResult: true });
+        emit({ kind: 'skill_used', skillName: progressText(input.skill) });
+        continue;
+      }
       const progress = claudeToolProgress(part.name, input, options.cwd);
       tools.set(part.id, { name: part.name, ...progress });
       emit({
@@ -429,11 +434,45 @@ export function createClaudeProgressParser(onProgress, options = {}) {
     }
   };
 
+  // A large edit can take the model a minute to write, and nothing else is
+  // reported until it has finished writing. Report the moment it starts, and
+  // close that report when the finished tool call arrives.
+  const drafting = new Map();
+  const DRAFTING_MESSAGE = 'Preparing changes for the Framer project';
+  const processStreamEvent = (row) => {
+    const event = row.event;
+    const block = event?.type === 'content_block_start' ? event.content_block : null;
+    if (block?.type !== 'tool_use' || !block.id || drafting.has(block.id)) return;
+    const shortName = String(block.name || '').replace(/^mcp__instawebai__/, '');
+    if (!['framer_apply_changes', 'framer_update_code_file', 'framer_write'].includes(shortName)) return;
+    drafting.set(block.id, true);
+    emit({
+      kind: 'item_started',
+      phase: 'started',
+      activity: `tool-draft:${block.id}`,
+      message: DRAFTING_MESSAGE,
+    });
+  };
+  const finishDrafting = (row) => {
+    for (const part of Array.isArray(row.message?.content) ? row.message.content : []) {
+      if (part?.type !== 'tool_use' || drafting.get(part.id) !== true) continue;
+      drafting.set(part.id, false);
+      emit({
+        kind: 'item_completed',
+        phase: 'completed',
+        activity: `tool-draft:${part.id}`,
+        message: DRAFTING_MESSAGE,
+      });
+    }
+  };
+
   const processLine = (line) => {
     const trimmed = line.trim();
     if (!trimmed) return;
     try {
       const row = JSON.parse(trimmed);
+      if (row?.type === 'stream_event') processStreamEvent(row);
+      if (row?.type === 'assistant') finishDrafting(row);
       if (row?.type === 'assistant') processAssistant(row);
       if (row?.type === 'user') processUser(row);
     } catch {

package/src/cli.js

@@ -232,13 +232,63 @@ function isInvalidPairingError(error) {
   return isCompanionPairingInvalidError(error);
 }
 
-function clearInvalidPairing(configDir, cause) {
-  const product = normalizeBridgeProduct(readConfig(configDir).product);
-  saveConfigPatch({
-    deviceToken: null,
-    device: null,
-    pairedAt: null,
-  }, configDir);
+const HOMEBREW_FORMULA = 'gakim-digital/tap/dexter-bridge';
+const SELF_UPDATE_INTERVAL_MS = 60 * 60 * 1000;
+const PAIRING_WAIT_POLL_MS = 5000;
+
+// The Homebrew background service must recover on its own: the user never sees
+// its terminal, so exiting would leave Dexter silently offline.
+function runsAsBackgroundService() {
+  return process.env.DEXTER_BRIDGE_INSTALL_METHOD === 'homebrew' && !process.stdin.isTTY;
+}
+
+function isUpdateRequiredError(error) {
+  return error?.status === 426 || error?.body?.code === 'FRAMER_COMPANION_UPDATE_REQUIRED';
+}
+
+function runCommand(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: 'inherit' });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => resolve(code === 0));
+  });
+}
+
+// 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) {
+  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);
+  console.log('A newer Dexter Bridge is required. Updating with Homebrew...');
+  const updated = await runCommand('brew', ['upgrade', HOMEBREW_FORMULA]);
+  logger.info('self_update_finished', { updated });
+  if (!updated) return;
+  const restart = new Error('Dexter Bridge updated. Restarting on the new version.');
+  restart.exitCode = 75;
+  throw restart;
+}
+
+async function waitForPairing(configDir) {
+  console.log('Waiting for a new pairing from Dexter...');
+  while (true) {
+    const token = readConfig(configDir).deviceToken;
+    if (token) return token;
+    await wait(PAIRING_WAIT_POLL_MS);
+  }
+}
+
+function clearInvalidPairing(configDir, cause, rejectedToken) {
+  const current = readConfig(configDir);
+  const product = normalizeBridgeProduct(current.product);
+  // Another bridge command may have just saved a fresh pairing; keep it.
+  if (!rejectedToken || current.deviceToken === rejectedToken) {
+    saveConfigPatch({
+      deviceToken: null,
+      device: null,
+      pairedAt: null,
+    }, configDir);
+  }
   const error = new Error(
     `This ${product.name} Bridge pairing was disconnected. Reopen ${product.name} and run the new pairing command.`,
     { cause },
@@ -534,14 +584,19 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
   let deviceToken = config.deviceToken;
   if (!deviceToken) {
     // First run: pair interactively so `npx @gakim-digital/dexter-bridge` alone is
-    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;
+    if (runsAsBackgroundService()) {
+      deviceToken = await waitForPairing(configDir);
+      activeConfig = readConfig(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;
+    }
   }
   const product = normalizeBridgeProduct(activeConfig.product);
   const runtimeSelection = requestedRuntime(flags, activeConfig);
@@ -651,9 +706,22 @@ async function startCommand({ apiBaseUrl, config, flags, configDir }) {
             status: error.status,
             code: error.body?.code || null,
           });
-          const disconnected = clearInvalidPairing(configDir, error);
+          const savedToken = readConfig(configDir).deviceToken;
+          if (savedToken && savedToken !== deviceToken) {
+            // Re-paired by another bridge command; adopt the new pairing.
+            deviceToken = savedToken;
+            pollFailureCount = 0;
+            continue;
+          }
+          const disconnected = clearInvalidPairing(configDir, error, deviceToken);
           console.log(disconnected.message);
-          return;
+          if (!runsAsBackgroundService()) return;
+          deviceToken = await waitForPairing(configDir);
+          pollFailureCount = 0;
+          continue;
+        }
+        if (isUpdateRequiredError(error) && runsAsBackgroundService()) {
+          await selfUpdateWithHomebrew(configDir, pollLogger);
         }
         if (once) throw error;
         pollFailureCount += 1;

package/src/framerAgentTools.js

@@ -619,7 +619,7 @@ function installedFramerAgentVersion() {
   return null;
 }
 
-function readGuidanceFile(projectRoot, relativePath, remainingBytes) {
+function readGuidanceFile(projectRoot, relativePath, remainingBytes, section) {
   const normalized = relativePath.replaceAll('\\', '/');
   if (
     normalized.startsWith('/')
@@ -635,12 +635,27 @@ function readGuidanceFile(projectRoot, relativePath, remainingBytes) {
   }
   const maximum = Math.min(MAX_GUIDANCE_FILE_BYTES, remainingBytes);
   if (maximum <= 0) return null;
+  let content = fs.readFileSync(absolutePath, 'utf8');
+  if (section) {
+    content = markdownSection(content, section);
+    if (!content) return null;
+  }
   return {
     path: normalized,
-    content: boundedText(fs.readFileSync(absolutePath, 'utf8'), maximum),
+    content: boundedText(content, maximum),
   };
 }
 
+function markdownSection(markdown, heading) {
+  const lines = markdown.split('\n');
+  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
+  if (start < 0) return '';
+  const end = lines.findIndex(
+    (line, index) => index > start && line.startsWith('## '),
+  );
+  return lines.slice(start, end < 0 ? undefined : end).join('\n').trim();
+}
+
 function normalizeProjectId(value) {
   const projectId = String(value || '').trim();
   if (!PROJECT_ID_PATTERN.test(projectId)) {
@@ -1650,12 +1665,16 @@ export function createFramerAgentToolRuntime({
       { root: projectRoot, path: 'prompt/overview.md' },
       { root: projectRoot, path: 'prompt/guardrails.md' },
       { root: projectRoot, path: 'prompt/critical-reminders.md' },
-      ...(visualVerificationRequired
-        ? [
-            { root: projectRoot, path: 'prompt/design-rules.md' },
-            { root: projectRoot, path: 'prompt/how-projects-work.md' },
-          ]
-        : []),
+      // The byte cap clips how-projects-work.md before its 3D transform
+      // guidance, so that section loads on its own first.
+      {
+        root: projectRoot,
+        path: 'prompt/how-projects-work.md',
+        section: 'Transforms',
+        label: 'prompt/how-projects-work.md#transforms',
+      },
+      { root: projectRoot, path: 'prompt/design-rules.md' },
+      { root: projectRoot, path: 'prompt/how-projects-work.md' },
     ];
     const files = [];
     let remainingBytes = MAX_GUIDANCE_BYTES;
@@ -1664,6 +1683,7 @@ export function createFramerAgentToolRuntime({
         requestedFile.root,
         requestedFile.path,
         remainingBytes,
+        requestedFile.section,
       );
       if (!loaded) continue;
       files.push({

package/src/nativeSkills.js

@@ -174,7 +174,7 @@ function renderAggregateClaudeSkill(skills, nativeName) {
   return [
     '---',
     `name: ${yamlString(nativeName)}`,
-    `description: ${yamlString('Apply every selected InstaWebAI skill for this model turn.')}`,
+    `description: ${yamlString('Apply every skill the user selected for this request.')}`,
     'user-invocable: true',
     'disable-model-invocation: true',
     '---',
@@ -231,7 +231,7 @@ export function materializeNativeSkills(
     ['always', 'explicit', 'command'].includes(skill.trigger),
   );
   if (provider === 'claude-code' && requiredSkills.length > 0) {
-    aggregateName = `instawebai-active-${digest.slice(0, 8)}`;
+    aggregateName = `dexter-active-${digest.slice(0, 8)}`;
     const aggregateDirectory = path.join(skillsRoot, aggregateName);
     fs.mkdirSync(aggregateDirectory, { recursive: true, mode: 0o700 });
     aggregatePath = path.join(aggregateDirectory, 'SKILL.md');
@@ -260,7 +260,7 @@ export function claudeNativeSkillPrompt(prompt, materialized) {
   return [
     materialized?.aggregateName ? `/${materialized.aggregateName}` : '',
     catalog
-      ? `Available optional skills; invoke one only when it is relevant:\n${catalog}`
+      ? `Available optional skills; invoke one only when it is relevant, and do not use any skill that is not listed here:\n${catalog}`
       : '',
     String(prompt || ''),
   ].filter(Boolean).join('\n\n');

package/src/outcomeWorkspace.js

@@ -184,6 +184,30 @@ export function materializeOutcomeReferenceAssets(materialized, attachments) {
   return output;
 }
 
+// Image parts in a server-owned model turn become native image input for the
+// provider CLI; the caller removes the directory when the turn settles.
+export function materializeModelTurnImages(messages) {
+  const decoded = (Array.isArray(messages) ? messages : [])
+    .flatMap((message) => (Array.isArray(message?.content) ? message.content : []))
+    .filter((part) => part?.type === 'image' && typeof part.base64 === 'string')
+    .slice(0, 4)
+    .map((part) => decodedReferenceAsset({ dataUrl: `data:${part.mimeType};base64,${part.base64}` }))
+    .filter(Boolean);
+  if (!decoded.length) return { files: [], remove() {} };
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'dexter-turn-images-'));
+  const files = decoded.map((image, index) => {
+    const file = path.join(directory, `${String(index + 1).padStart(2, '0')}.${image.extension}`);
+    fs.writeFileSync(file, image.buffer, { mode: 0o600 });
+    return file;
+  });
+  return {
+    files,
+    remove() {
+      fs.rmSync(directory, { recursive: true, force: true });
+    },
+  };
+}
+
 export function removeOutcomeReferenceAssets(materialized) {
   if (!materialized?.directory) return;
   fs.rmSync(

package/src/protocol.js

@@ -141,11 +141,12 @@ function compactModelTurnContent(content) {
   if (!Array.isArray(content)) return content;
   return content.map((part) => {
     if (!isRecord(part) || part.type !== 'image') return part;
+    // Inline image bytes travel as native image input next to this prompt.
     return {
       type: 'image',
       mimeType: part.mimeType,
       url: part.url,
-      omittedBase64Bytes: typeof part.base64 === 'string' ? part.base64.length : undefined,
+      ...(typeof part.base64 === 'string' ? { attachedAsImageInput: true } : {}),
     };
   });
 }
@@ -494,6 +495,7 @@ export function buildOutcomePrompt(outcome = {}, product, promptContext = {}) {
       'For repeated behavior, declare every targetNodeId and one representativeTargetNodeId in the mechanism plan. Implement and verify only that representative before fan-out, then verify complete target coverage after the final mutation. Only a contradicted result permits one evidence-scoped repair. Repeated unchanged evidence or exhausted verification budget must end as partial rather than starting another loop.',
       'Do not reuse a mechanism recorded as rejected by the user or repeated contradictory live evidence. Unknown evidence never rejects a mechanism.',
       'For visual work, evaluate hierarchy, spacing, contrast, typography, balance, imagery, interaction states, and responsive integrity.',
+      'For depth and 3D, use native transforms through framer_apply_changes as described in the Framer guidance Transforms section: perspective on the parent, preserve3d on a container whose children must stay in 3D space, rotateX, rotateY, rotateZ, translateZ, and transformOrigin on the moving layers, and backfaceVisibility for flip faces. Rotations without a parent perspective render flat. Spend 3D on one signature moment, such as a tilted product mockup, layered card stack, flip card, or hover tilt; keep text readable, reduce or flatten the effect on smaller breakpoints, and confirm it in a screenshot. Do not fake 3D with images or code components when native transforms can achieve it.',
       'You decide when the run is complete. Avoid repeated inspection of unchanged evidence and stop when the requested outcome has been implemented and verified.',
       'Dexter will not perform a second design verification after you finish. Structural verification must be described honestly and must never be called runtime-tested unless an interaction was actually exercised.',
       'If Framer authorization or a required user decision is missing, return blocked with a concise explanation. Otherwise return completed only after you have finished and verified the work.',