@gakim-digital/dexter-bridge 0.11.23 → 0.12.0

package/README.md

@@ -32,16 +32,15 @@ command cannot claim the pairing code for a different runtime.
 
 Dexter Framer runs are harness-first. The API sends one scoped outcome
 assignment to the connected Codex, Claude Code, or OpenCode runtime. That
-harness inspects and edits the selected Framer project directly through the
-official `@framer/agent` connection while the plugin remains the chat,
-progress, cancellation, and result interface.
+harness inspects and edits the selected Framer project directly through
+Framer MCP while the plugin remains the chat, progress, cancellation, and
+result interface.
 
 The Framer harness receives only these project-scoped tools:
 
-- `framer_instructions` and `framer_context`
-- `framer_read_project`, `framer_verify_interactions`, and `framer_apply_changes`
-- restricted `framer_read` and `framer_write`
-- `progress_update`
+- `framer_read` and `framer_edit`
+- `framer_instructions` and `framer_view_image`
+- `framer_plan_task`, `framer_verify_interactions`, and `framer_read_website`
 
 Native shell, filesystem, web, and unrelated-project access are disabled for
 Framer outcome runs. Publishing is denied unless a future assignment explicitly
@@ -57,27 +56,17 @@ the live node. Results are `verified`, `contradicted` (the value differs), or
 reported as unverified; an unchecked target or a contradiction leaves the run
 incomplete.
 
-Project connection is handled inside Dexter and completes before the model
+Account connection is handled inside Dexter and completes before the model
 starts:
 
-- The plugin reads the exact active project or branch URL directly from Framer.
-- The user adds a Framer project API key once in Dexter. The API verifies it
-  through Framer's documented `connect(projectId, apiKey)` plus
-  `getProjectInfo()` flow, then encrypts and stores it only after that succeeds.
-- The active hosted runtime redeems that verified credential only for the
-  matching run and device, then installs it with Framer’s official
-  `project auth` command against the authoritative 20-character project ID.
-- The runtime opens an official Framer Agent session, reads the active branch
-  back from Framer, and confirms the authoritative project ID again.
-- Rejected credentials are revoked. Replacing a key creates a new credential
-  version, so a cached runtime session cannot reuse the replacement.
-- Hosted worker images bundle the Framer skills and seed them into each
-  runtime's private writable home before processing runs.
-
-The user never runs `@framer/agent setup`, `project auth`, or `session new`.
-The raw project credential is scoped to the matching active run and paired
-device, is excluded from run payloads and logs, and is never sent to the Framer
-plugin after the one-time authenticated submission.
+- The user connects a Framer account once. Dexter stores the refresh token
+  encrypted and gives the bridge only a short-lived access token.
+- The bridge opens the project through Framer MCP. Edits on a published project
+  land on a Framer branch, and Dexter says so.
+- Disconnecting in Dexter, or revoking Dexter in Framer, stops later runs until
+  the account is connected again.
+
+The user never creates a project API key. The refresh token stays on the API.
 
 The bridge reports provider token usage on terminal events, including
 interrupted and cancelled runs. Claude-reported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.11.23",
+  "version": "0.12.0",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {
@@ -39,7 +39,6 @@
     "@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.46",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@opencode-ai/sdk": "^1.18.25",
     "@openrouter/ai-sdk-provider": "^3.0.0",

package/src/agent.js

@@ -10,7 +10,6 @@ import {
   readFramerWebsite,
   isCompanionPairingInvalidError,
   postRunEvent,
-  reportFramerProjectAuthorizationVerification,
 } from './api.js';
 import {
   createCompanionUsageAccumulator,
@@ -65,7 +64,7 @@ import {
   codexDynamicToolSpecs,
   createHarnessToolRuntime,
 } from './harnessTools.js';
-import { createFramerAgentToolRuntime } from './framerAgentTools.js';
+import { createFramerAgentToolRuntime } from './framerTools.js';
 
 const HARNESS_MCP_SERVER_PATH = fileURLToPath(
   new URL('./harnessMcpServer.js', import.meta.url),
@@ -366,7 +365,7 @@ 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.',
-      '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.',
+      'Edit the project with framer_edit programs that call api.tree. If a program is rejected, read the error and repair that program instead of inventing another interface.',
       `Return only the structured outcome result requested by ${name}.`,
     ].join(' ');
   }
@@ -2383,7 +2382,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
   );
   const framerAgentOutcome =
     run?.outcome?.kind === 'framer-project'
-    || run?.outcome?.context?.executionMode === 'framer-agent';
+    || run?.outcome?.context?.executionMode === 'framer-mcp';
   // 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.
@@ -2678,8 +2677,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         env: options.env,
         trace: options.trace,
         onActivity: progress,
-        runCli: options.framerAgentRunCli,
-        fetchImpl: options.framerScreenshotFetch,
+        mcpClient: options.framerMcpClient,
         authorizeProject:
           options.apiBaseUrl && options.deviceToken
             ? ({ initiate, forceRefresh, signal }) =>
@@ -2705,29 +2703,6 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
                   allowInsecureHttp: options.allowInsecureHttp,
                 })
             : undefined,
-        verifyProjectAuthorization:
-          options.apiBaseUrl && options.deviceToken
-            ? ({
-                status,
-                framerProjectId,
-                framerProjectUrl,
-                credentialVersion,
-                errorCode,
-                signal,
-              }) =>
-                reportFramerProjectAuthorizationVerification(options.apiBaseUrl, {
-                  deviceToken: options.deviceToken,
-                  runId: run.runId,
-                  status,
-                  framerProjectId,
-                  framerProjectUrl,
-                  credentialVersion,
-                  errorCode,
-                  fetchImpl: options.fetchImpl,
-                  signal,
-                  allowInsecureHttp: options.allowInsecureHttp,
-                })
-            : undefined,
       })
     : createHarnessToolRuntime({
         assignment: executionOutcome,
@@ -2738,7 +2713,9 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
       });
   let prompt = '';
   const successStatus = outcomeSuccessStatus(executionOutcome, product);
-  const schema = outcomeOutputSchema(successStatus);
+  const schema = outcomeOutputSchema(successStatus, {
+    reportsProjectChange: framerAgentOutcome,
+  });
   assertOutcomeResponseContract(
     STRUCTURED_RESPONSE_CONTRACTS.OUTCOME,
     schema,
@@ -2996,10 +2973,16 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     ) {
       synchronization = await harnessTools.synchronize();
     }
+    if (typeof harnessTools.assessCompletion === 'function') {
+      await harnessTools.assessCompletion(rawCompletion);
+    }
+    const unappliedChangePrompt =
+      rawCompletion.status === successStatus
+        ? harnessTools.unappliedChangePrompt?.(rawCompletion) || null
+        : null;
     const repairPrompt =
       rawCompletion.status === successStatus
-      && typeof harnessTools.verificationRepairPrompt === 'function'
-        ? harnessTools.verificationRepairPrompt()
+        ? harnessTools.verificationRepairPrompt?.() || unappliedChangePrompt
         : harnessTools.unblockedFailurePrompt?.(rawCompletion) || null;
     if (
       repairPrompt
@@ -3009,9 +2992,11 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         kind: 'status_update',
         source: 'harness',
         message:
-          rawCompletion.status === successStatus
-            ? 'I’m completing the final Framer verification before I finish.'
-            : 'Nothing is blocking this change, so I’m continuing the work.',
+          repairPrompt === unappliedChangePrompt
+            ? 'Nothing has changed in Framer yet, so I’m making the change before I finish.'
+            : rawCompletion.status === successStatus
+              ? '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([
         executeProviderOutcome(
@@ -3052,6 +3037,9 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         updatedAt: Date.now(),
       });
     }
+    if (typeof harnessTools.assessCompletion === 'function') {
+      await harnessTools.assessCompletion(rawCompletion);
+    }
     const completion =
       typeof harnessTools.finalizeCompletion === 'function'
         ? harnessTools.finalizeCompletion(rawCompletion)
@@ -3155,6 +3143,7 @@ export async function executeRun(
     inspectAgentAuthentication,
     runtimeProfile: suppliedRuntimeProfile,
     framerAgentRunCli,
+    framerMcpClient,
     framerScreenshotFetch,
     allowInsecureHttp = false,
   } = {},
@@ -3275,6 +3264,7 @@ export async function executeRun(
       product,
       runtimeProfile,
       framerAgentRunCli,
+      framerMcpClient,
       framerScreenshotFetch,
       apiBaseUrl,
       deviceToken,

package/src/agentOutput.js

@@ -494,7 +494,7 @@ export function createClaudeProgressParser(onProgress, options = {}) {
     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_add_svg', 'framer_update_code_file', 'framer_write'].includes(shortName)) return;
+    if (shortName !== 'framer_edit') return;
     drafting.set(block.id, true);
     emit({
       kind: 'item_started',

package/src/api.js

@@ -61,7 +61,6 @@ export async function requestJson(apiBaseUrl, path, {
     timedOut = true;
     controller.abort();
   }, Math.max(1, Number(timeoutMs) || 30_000));
-  timeout.unref?.();
   try {
     const response = await fetchImpl(`${normalizeApiBaseUrl(apiBaseUrl, {
       allowInsecureHttp,
@@ -266,40 +265,6 @@ export function readFramerWebsite(apiBaseUrl, {
   );
 }
 
-export function reportFramerProjectAuthorizationVerification(apiBaseUrl, {
-  deviceToken,
-  runId,
-  status,
-  framerProjectId,
-  framerProjectUrl,
-  credentialVersion,
-  errorCode,
-  fetchImpl,
-  signal,
-  allowInsecureHttp,
-}) {
-  return requestJson(
-    apiBaseUrl,
-    `/ai/framer/companion/runs/${encodeURIComponent(runId)}/framer-authorization/verification`,
-    {
-      method: 'POST',
-      deviceToken,
-      fetchImpl,
-      signal,
-      allowInsecureHttp,
-      body: {
-        status,
-        framerProjectId,
-        ...(framerProjectUrl ? { framerProjectUrl } : {}),
-        credentialVersion,
-        ...(errorCode ? { errorCode } : {}),
-        platform: process.platform,
-        companionVersion: BRIDGE_VERSION,
-      },
-    },
-  );
-}
-
 export function postRunEvent(apiBaseUrl, {
   deviceToken,
   runId,

package/src/config.js

@@ -20,7 +20,8 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
     './nativeSkills.js',
     './harnessTools.js',
     './harnessMcpServer.js',
-    './framerAgentTools.js',
+    './framerTools.js',
+    './framerMcpClient.js',
     './framerBehaviorContract.js',
     './outcomeWorkspace.js',
     './runtimeProfiles.js',
@@ -41,7 +42,7 @@ export const BRIDGE_CAPABILITIES = [
   'model-turn-v1',
   'outcome-run-v1',
   'harness-tools-v1',
-  'framer-agent-v1',
+  'framer-mcp-v1',
   'framer-project-bootstrap-v1',
   'framer-project-verification-v1',
   'framer-interaction-verification-v4',

package/src/framerBehaviorContract.js

@@ -1,5 +1,3 @@
-import crypto from 'node:crypto';
-
 // Dexter does not model Framer's interaction features. The model decides how
 // to build a behavior from Framer's own documentation; this module only checks
 // that the properties the model says carry the behavior exist on the live
@@ -111,8 +109,7 @@ function hasContent(value) {
 
 // Finds the property on the node itself. Child nodes are skipped so a
 // descendant cannot satisfy a claim about its parent. A dotted name such as
-// `link.href` or `hoverEffect.opacity`, the way the change language writes
-// it, reads the field inside the property's value.
+// `link.href` or `hoverEffect.opacity` reads the field inside the property's value.
 function propertyValues(node, property) {
   const values = keyValues(node, property);
   const [head, ...path] = property.split('.');
@@ -230,89 +227,3 @@ export function summarizeBehaviorVerification(plan, checkResults) {
         : 'verified';
   return { status, behaviors };
 }
-
-export function summarizeFramerChanges(changes) {
-  const commands = String(changes || '')
-    .split(';')
-    .map((command) => command.trim())
-    .filter(Boolean)
-    .slice(0, 200)
-    .map((command) => {
-      const created = command.match(/^\+([A-Za-z0-9_]+)\s+([^\s]+)/);
-      if (created) {
-        return {
-          operation: 'create',
-          nodeType: created[1],
-          nodeId: created[2],
-          parentId: command.match(/\bparent="([^"]+)"/)?.[1],
-        };
-      }
-      const set = command.match(/^SET\s+([^\s]+)/i);
-      if (set) {
-        return {
-          operation: 'set',
-          nodeId: set[1],
-          eventActions: Array.from(
-            command.matchAll(
-              /\b(on[A-Za-z]+)\.\d+\.action="([A-Z_]+)"/g,
-            ),
-          ).map((match) => ({ event: match[1], action: match[2] })),
-        };
-      }
-      const variant = command.match(/^CREATE_VARIANT\s+([^\s]+)\s+from="([^"]+)"/i);
-      if (variant) {
-        return {
-          operation: 'create_variant',
-          nodeId: variant[1],
-          sourceNodeId: variant[2],
-        };
-      }
-      const removed = command.match(/^DEL\s+([^\s;]+)/i);
-      if (removed) return { operation: 'delete', nodeId: removed[1] };
-      const duplicated = command.match(/^DUPE\s+([^\s]+).*?\bnewId="([^"]+)"/i);
-      if (duplicated) {
-        return {
-          operation: 'duplicate',
-          nodeId: duplicated[2],
-          sourceNodeId: duplicated[1],
-        };
-      }
-      const moved = command.match(/^MOVE\s+([^\s]+)/i);
-      if (moved) return { operation: 'move', nodeId: moved[1] };
-      const operation = text(command.split(/\s+/)[0], 40).toLowerCase();
-      return { operation: operation || 'unknown' };
-    });
-  return {
-    changeHash: crypto
-      .createHash('sha256')
-      .update(String(changes || ''))
-      .digest('hex'),
-    commandCount: commands.length,
-    commands,
-  };
-}
-
-export function canonicalIdMappings(value) {
-  const mappings = {};
-  const visit = (current) => {
-    if (Array.isArray(current)) {
-      current.forEach(visit);
-      return;
-    }
-    if (!isRecord(current)) return;
-    if (isRecord(current.renamedIds)) {
-      for (const [temporaryId, canonicalId] of Object.entries(
-        current.renamedIds,
-      )) {
-        const safeTemporary = text(temporaryId, 200);
-        const safeCanonical = text(canonicalId, 200);
-        if (safeTemporary && safeCanonical) {
-          mappings[safeTemporary] = safeCanonical;
-        }
-      }
-    }
-    Object.values(current).forEach(visit);
-  };
-  visit(value);
-  return mappings;
-}

package/src/framerMcpClient.js

@@ -0,0 +1,214 @@
+const MCP_ENDPOINT = 'https://mcp.framer.com/mcp';
+// Framer recommends one long program per change, so a call may run for
+// minutes. The SDK default of 60 seconds would abandon a program Framer is
+// still applying and lose its change receipt.
+const CALL_TIMEOUT_MS = 10 * 60_000;
+const SESSION_EXPIRED_PATTERN = /unknown or expired session/i;
+// open_project answers in text only: "Opened <id>. Pass session <handle> to
+// every tool that works on it. …" followed by the project README.
+const SESSION_TEXT_PATTERN = /\bPass session\s+([A-Za-z0-9_-]+)/i;
+
+function textOf(result) {
+  const content = Array.isArray(result?.content) ? result.content : [];
+  return content
+    .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n')
+    .trim();
+}
+
+function imagesOf(result) {
+  const content = Array.isArray(result?.content) ? result.content : [];
+  return content.flatMap((part) => {
+    if (part?.type !== 'image' || typeof part.data !== 'string') return [];
+    return [{
+      mimeType: typeof part.mimeType === 'string' ? part.mimeType : 'image/png',
+      data: part.data,
+    }];
+  });
+}
+
+function toolError(message, code, extra = {}) {
+  return Object.assign(new Error(message), { code, ...extra });
+}
+
+function unwrap(result) {
+  if (!result || result.isError) {
+    const message = textOf(result) || 'Framer MCP call failed.';
+    throw toolError(
+      message,
+      SESSION_EXPIRED_PATTERN.test(message) ? 'FRAMER_MCP_SESSION_EXPIRED' : 'FRAMER_MCP_TOOL_FAILED',
+    );
+  }
+  let structured = result.structuredContent && typeof result.structuredContent === 'object'
+    ? result.structuredContent
+    : null;
+  const text = textOf(result);
+  if (!structured && text) {
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object') structured = parsed;
+    } catch {
+      structured = null;
+    }
+  }
+  return {
+    structured: structured || {},
+    text,
+    images: imagesOf(result),
+    raw: result,
+  };
+}
+
+export function sessionFromOpenResult(result) {
+  const structured = result?.structured || {};
+  const value = structured.session || structured.sessionId || structured.handle;
+  if (typeof value === 'string' && value.trim()) return value.trim();
+  return String(result?.text || '').match(SESSION_TEXT_PATTERN)?.[1] || null;
+}
+
+// The README without the per-session preamble, so the guidance stays the same
+// from run to run and can be cached.
+export function readmeFromOpenResult(result) {
+  const structured = result?.structured || {};
+  const readme = structured.readme || structured.README;
+  const text = typeof readme === 'string' && readme.trim() ? readme : String(result?.text || '');
+  const heading = text.search(/^#\s/m);
+  if (heading > 0) return text.slice(heading).trim();
+  return text
+    .split(/\n\s*\n/)
+    .filter((paragraph) => !SESSION_TEXT_PATTERN.test(paragraph))
+    .join('\n\n')
+    .trim();
+}
+
+function isUnauthorized(error) {
+  return error?.code === 401 || /\bHTTP 401\b|status 401/i.test(String(error?.message || ''));
+}
+
+export function createFramerMcpClient({
+  getAccessToken,
+  callTool,
+  fetchImpl = globalThis.fetch,
+  endpoint = MCP_ENDPOINT,
+  timeoutMs = CALL_TIMEOUT_MS,
+} = {}) {
+  let sdkClient = null;
+  let transport = null;
+  let session = null;
+  let readme = '';
+  let projectId = null;
+
+  // Every request carries the current access token, so an expiring token is
+  // replaced without reconnecting or reopening the project. A 401 means the
+  // request was refused before it ran, so retrying it once is safe.
+  async function authorizedFetch(url, init = {}) {
+    const send = async (force) => {
+      const headers = new Headers(init.headers || {});
+      headers.set('Authorization', `Bearer ${await getAccessToken({ force })}`);
+      return fetchImpl(url, { ...init, headers });
+    };
+    const response = await send(false);
+    if (response.status !== 401) return response;
+    return send(true);
+  }
+
+  async function connect() {
+    if (sdkClient) return;
+    const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
+    const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
+    transport = new StreamableHTTPClientTransport(new URL(endpoint), { fetch: authorizedFetch });
+    const client = new Client({ name: 'dexter-bridge', version: '1' });
+    await client.connect(transport);
+    sdkClient = client;
+  }
+
+  async function rawCall(name, args) {
+    if (typeof callTool === 'function') return callTool(name, args);
+    await connect();
+    try {
+      return await sdkClient.callTool(
+        { name, arguments: args },
+        undefined,
+        { timeout: timeoutMs, resetTimeoutOnProgress: true },
+      );
+    } catch (error) {
+      if (isUnauthorized(error)) {
+        throw toolError(
+          'Framer refused Dexter’s access. Connect your Framer account again in Dexter.',
+          'FRAMER_ACCOUNT_CONNECTION_REQUIRED',
+          { statusCode: 409 },
+        );
+      }
+      throw error;
+    }
+  }
+
+  // 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) {
+    let result;
+    try {
+      result = unwrap(await rawCall(name, args));
+    } 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 result;
+  }
+
+  async function openProject(id) {
+    const result = await call('open_project', { projectId: id });
+    const nextSession = sessionFromOpenResult(result);
+    if (!nextSession) {
+      throw toolError('Framer did not open a project session.', 'FRAMER_MCP_SESSION_MISSING');
+    }
+    session = nextSession;
+    projectId = id;
+    readme = readmeFromOpenResult(result);
+    return { session, readme, structured: result.structured };
+  }
+
+  function requireSession() {
+    if (!session) throw toolError('Framer project is not open.', 'FRAMER_MCP_SESSION_MISSING');
+  }
+
+  return {
+    openProject,
+    readme: () => readme,
+    session: () => session,
+    projectId: () => projectId,
+    async exec(program) {
+      requireSession();
+      return call('exec', { session, program });
+    },
+    async readDocs(paths) {
+      requireSession();
+      const list = (Array.isArray(paths) ? paths : [paths]).filter((value) => typeof value === 'string' && value.trim());
+      const pages = [];
+      for (const docPath of list) {
+        const result = await call('read_docs', { session, path: docPath });
+        const content = result.structured.content
+          || result.structured.markdown
+          || result.structured.text
+          || result.text
+          || '';
+        pages.push({ path: docPath, content: String(content) });
+      }
+      return pages;
+    },
+    async viewImage(urls) {
+      requireSession();
+      return call('view_image', { session, urls });
+    },
+    async close() {
+      session = null;
+      if (transport?.close) await transport.close().catch(() => undefined);
+      transport = null;
+      sdkClient = null;
+    },
+  };
+}