@gakim-digital/dexter-bridge 0.11.23 → 0.12.0

package/src/framerTools.js

@@ -0,0 +1,1253 @@
+import crypto from 'node:crypto';
+import jsTokens from 'js-tokens';
+import { createFramerMcpClient } from './framerMcpClient.js';
+import {
+  evidenceNodeIds,
+  mergeBehaviorPlans,
+  normalizeBehaviorEvidence,
+  normalizeBehaviorPlan,
+  summarizeBehaviorVerification,
+  verifyBehaviorChecks,
+} from './framerBehaviorContract.js';
+
+export const UNAPPLIED_CHANGE_CHECK = 'Harness change check';
+export const PROPERTY_ERROR_CHECK = 'Unapplied properties';
+export const CLAIMED_TARGET_CHECK = 'Claimed targets';
+export const VERIFICATION_CHECK = 'Harness-owned final verification';
+
+const LITERAL_TOKEN_TYPES = new Set(['StringLiteral', 'NoSubstitutionTemplate', 'TemplateHead', 'TemplateMiddle', 'TemplateTail']);
+const UNSAFE_EXEC_PATTERN = /\b(?:process|globalThis|global|require|import\s*\(|child_process|worker_threads|fs|os|net|tls|dgram|http|https|fetch|WebSocket|eval|Function)\b/;
+const READ_MUTATING_PATTERN = /\b(?:tree\.(?:insert|patch|remove|move|duplicate|replaceText|patchFormDestinations|createComponentFromFrame|makeExternalComponentLocal|createBranch|renameBranch|joinBranch|leaveBranch|switchBranch|mergeBranch|deleteBranch)|api\.files\.(?:create|write|applyPatch|delete)|api\.publishing\.(?:publish|deployToProduction)|api\.store)\b/;
+const PUBLISH_PATTERN = /\b(?:api\.publishing\.(?:publish|deployToProduction)|tree\.(?:mergeBranch|deleteBranch|switchBranch))\b/;
+// Node properties and the project APIs (api.fonts, api.images, api.files) are
+// preloaded because guessed property names and fonts Framer cannot load are
+// the usual rejected properties, and each repair costs a model turn plus the
+// doc reads before it.
+const GUIDANCE_PATHS = [
+  'references/workflow/part-1.md',
+  'references/script/tree-api/part-1.md',
+  'references/script/node-properties/part-1.md',
+  'references/script/node-properties/part-2.md',
+  'references/script/project-apis/part-1.md',
+];
+const CONTEXT_PATH = 'context.md';
+const PRELOADED_PATHS = new Set([CONTEXT_PATH, ...GUIDANCE_PATHS]);
+// Lines that only fit a client reading docs itself, or that name a session,
+// would steer the model into extra turns or change the cached prompt per run.
+const STRIP_GUIDANCE = /one (?:doc|document)(?: or part)? per (?:call|turn)|one at a time with read_docs|fetch several parts|Pass session|@framer\/agent setup|project auth|session new/i;
+const PRELOADED_GUIDANCE_NOTE = `${CONTEXT_PATH}, ${GUIDANCE_PATHS.join(', ')} and the README are already included below. Do not read them again. Use framer_instructions only when a specific API question blocks your next edit, not to read general guidance before you start, and pass every path you need in one call. This run has no skills catalog and no Skill tool; skip the README's skills gate.`;
+const MAX_RESULT_CHARS = 6_000;
+// Users judge progress by the canvas, so a run that is still only reading
+// after this long is told to start building.
+const FIRST_EDIT_NUDGE_MS = 60_000;
+const FIRST_EDIT_NUDGE = 'Nothing is on the canvas yet. You know enough to start: make your first framer_edit now with a small first section, such as the navigation and the hero headline, then build the rest two sections per edit. Read more only when a specific detail blocks the next edit.';
+const FONT_ERROR_HINT = 'A font Framer rejected is not available to this project. Follow the preloaded project APIs guidance: resolve the family through api.fonts before setting it, or use a family the project already uses. Fix it in your next framer_edit, not at the end.';
+const ACTIVE_PAGE_OUTLINE_DEPTH = 2;
+const FONT_KEYS = new Set(['font', 'fontFamily', 'family']);
+const PROJECT_MISMATCH_PATTERN = /permission|forbidden|not found|does not have access|no access|can't open|cannot open/i;
+
+// Item shapes the behavior contract (framerBehaviorContract.js) accepts.
+const BEHAVIOR_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', description: 'Short unique id, such as "whatsapp-links".' },
+    description: { type: 'string', description: 'What the user should experience.' },
+    targetNodeIds: { type: 'array', items: { type: 'string' }, description: 'Every node that should carry the behavior.' },
+  },
+  required: ['id', 'description'],
+  additionalProperties: false,
+};
+const BEHAVIOR_CHECK_SCHEMA = {
+  type: 'object',
+  properties: {
+    behaviorId: { type: 'string' },
+    nodeId: { type: 'string' },
+    property: { type: 'string', description: 'The Framer property that carries the behavior, such as link.href.' },
+    contains: { type: 'string', description: 'Text the property value must contain.' },
+  },
+  required: ['behaviorId', 'nodeId', 'property'],
+  additionalProperties: false,
+};
+
+const TOOL_DEFINITIONS = [
+  {
+    name: 'framer_read',
+    description: 'Read the open Framer project by running a program. Use api.tree.getNode, getNodes, serialize, and serializeNodes. Stock image search is api.images.search({ query }), one call per query. Fonts are api.fonts.get and api.fonts.list({ query }). There is no framer global. This tool cannot change the project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        program: { type: 'string', description: 'JavaScript that returns the data you need. It runs inside Framer with api.tree, api.fonts, and api.images.' },
+      },
+      required: ['program'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_edit',
+    description: 'Change the open Framer project by running a program. Use api.tree.insert, patch, remove, move, and replaceText. Place an SVG with tree.insert("SVGNode", id, { svg, intrinsicWidth, intrinsicHeight }). Write code files with api.files.create, write, or applyPatch. Search stock images with api.images.search({ query }). Place an image by setting fill to await api.tree.assetReference(url) with a public image URL. Load fonts with api.fonts. Pass screenshotNodeIds for the nodes you want to see after the edit. Include plan on your first framer_edit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        program: { type: 'string' },
+        reason: { type: 'string', description: 'The concrete change this program makes.' },
+        screenshotNodeIds: { type: 'array', items: { type: 'string' }, maxItems: 4 },
+        plan: {
+          type: 'object',
+          description: 'Your task plan, on the first framer_edit: a summary, the task domains, and the evidence you will produce (for example structural, visual, interactions). For interactive or animated results, list each behavior with every node that should carry it.',
+          properties: {
+            summary: { type: 'string' },
+            domains: { type: 'array', items: { type: 'string' } },
+            verification: { type: 'array', items: { type: 'string' } },
+            behaviors: { type: 'array', items: BEHAVIOR_SCHEMA },
+          },
+          required: ['summary', 'domains', 'verification'],
+          additionalProperties: false,
+        },
+      },
+      required: ['program'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_instructions',
+    description: 'Read Framer MCP documents by path, such as references/script/tree-api/part-2.md. Pass every path you need in one call; each call costs a turn.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        paths: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 6 },
+      },
+      required: ['paths'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_view_image',
+    description: 'Show one or more image URLs to yourself so you can judge them. Use public attachment URLs and image URLs already in the project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        urls: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 6 },
+      },
+      required: ['urls'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_verify_interactions',
+    description: 'Check that each declared behavior sits on the node properties you name. This is structural evidence, not runtime playback.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        checks: { type: 'array', items: BEHAVIOR_CHECK_SCHEMA },
+        behaviors: { type: 'array', items: BEHAVIOR_SCHEMA },
+      },
+      required: ['checks'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_read_website',
+    description: 'Read one page of a website the user named: exact copy per section, fonts and text styles, colours, image URLs (including CSS backgrounds), and desktop and phone screenshots. Use it before recreating or migrating that page. Only sites the user named can be read.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', minLength: 1, maxLength: 2048 },
+        screenshotTop: {
+          type: 'integer',
+          minimum: 0,
+          description: 'Desktop page offset in pixels for the screenshots. Use the value the previous result suggests to see further down.',
+        },
+      },
+      required: ['url'],
+      additionalProperties: false,
+    },
+  },
+];
+
+export const FRAMER_AGENT_TOOL_DEFINITIONS = TOOL_DEFINITIONS;
+
+function toolError(code, message, statusCode = 400) {
+  return Object.assign(new Error(message), { code, statusCode });
+}
+
+function codeOutsideLiterals(code) {
+  let visible = '';
+  for (const token of jsTokens(String(code || ''))) {
+    visible += LITERAL_TOKEN_TYPES.has(token.type) ? ' ' : token.value;
+  }
+  return visible;
+}
+
+// Text blocks inside a layer have virtual ids such as "v:dD8FHq_BL:0"; they
+// belong to the layer named in the middle.
+function layerIdOf(id) {
+  const text = String(id || '');
+  return text.startsWith('v:') ? text.split(':')[1] || '' : text;
+}
+
+function validateProgram(program, { write = false, allowPublishing = false } = {}) {
+  const code = String(program || '').trim();
+  if (!code) {
+    throw toolError('FRAMER_AGENT_CODE_REQUIRED', 'A Framer program is required.');
+  }
+  const visible = codeOutsideLiterals(code);
+  if (UNSAFE_EXEC_PATTERN.test(visible)) {
+    throw toolError(
+      'FRAMER_AGENT_CODE_UNSAFE',
+      'This program uses a capability Dexter does not allow in Framer MCP.',
+    );
+  }
+  if (!write && READ_MUTATING_PATTERN.test(visible)) {
+    throw toolError(
+      'FRAMER_AGENT_READ_ONLY_VIOLATION',
+      'Use framer_edit to change the project.',
+    );
+  }
+  if (!allowPublishing && PUBLISH_PATTERN.test(visible)) {
+    throw toolError(
+      'FRAMER_AGENT_PUBLISH_NOT_AUTHORIZED',
+      'Publishing and branch merge, delete, or switch are not authorized for this run.',
+    );
+  }
+  return code;
+}
+
+function stripGuidance(text) {
+  return String(text || '')
+    .split('\n')
+    .filter((line) => !STRIP_GUIDANCE.test(line))
+    .join('\n')
+    .trim();
+}
+
+// "`color` is not a supported property." → color;
+// "Cannot apply `{ fill: "https://…" }`: …" → fill.
+function propertyNameOf(message) {
+  const text = String(message || '');
+  return text.match(/`\{\s*"?([A-Za-z0-9_.$-]+)"?\s*:/)?.[1]
+    || text.match(/`([A-Za-z0-9_.$-]+)`/)?.[1]
+    || '';
+}
+
+// Framer reports values that failed to apply as
+// { "`color` is not a supported property.": ["node-id", …] }. Node ids are the
+// ones the program used, so ids of nodes it inserted map through renamedIds.
+export function propertyErrorsOf(output, renamedIds = {}) {
+  const raw = output?.tree?.errors ?? output?.errors;
+  const errors = [];
+  const push = (nodeId, message, property) => {
+    const id = String(nodeId || '').trim();
+    if (!id) return;
+    const text = String(message || '').slice(0, 500);
+    errors.push({
+      nodeId: String(renamedIds[id] || id).slice(0, 200),
+      property: String(property || propertyNameOf(text)).slice(0, 120),
+      message: text,
+    });
+  };
+  if (Array.isArray(raw)) {
+    for (const error of raw) {
+      if (!error || typeof error !== 'object') continue;
+      push(error.nodeId || error.id, error.message || error.error, error.property || error.attribute);
+    }
+  } else if (raw && typeof raw === 'object') {
+    for (const [message, nodeIds] of Object.entries(raw)) {
+      for (const nodeId of Array.isArray(nodeIds) ? nodeIds : [nodeIds]) {
+        push(typeof nodeId === 'object' ? nodeId?.id : nodeId, message);
+      }
+    }
+  }
+  return errors.slice(0, 50);
+}
+
+// Framer's design linter reports { "<warning>": [node ids or details] } under
+// tree.linter.warnings. Each warning keeps up to five affected entries.
+export function linterWarningsOf(output) {
+  const raw = output?.tree?.linter?.warnings ?? output?.linter?.warnings;
+  if (Array.isArray(raw)) return raw.slice(0, 20);
+  if (!raw || typeof raw !== 'object') return [];
+  return Object.entries(raw).slice(0, 20).map(([message, entries]) => {
+    const list = Array.isArray(entries) ? entries : [entries];
+    return {
+      message: String(message).slice(0, 500),
+      nodes: list.slice(0, 5).map((entry) => (
+        entry && typeof entry === 'object'
+          ? {
+              id: String(entry.id || '').slice(0, 200),
+              ...(entry.text ? { text: String(entry.text).slice(0, 120) } : {}),
+              ...(entry.backgroundNodeIds ? { backgroundNodeIds: entry.backgroundNodeIds } : {}),
+            }
+          : String(entry).slice(0, 200)
+      )),
+      count: list.length,
+    };
+  });
+}
+
+// Font families named anywhere in serialized nodes, so the model can reuse
+// what the page already loads instead of guessing a family Framer rejects.
+export function fontFamiliesIn(value, found = new Set()) {
+  if (Array.isArray(value)) {
+    for (const entry of value) fontFamiliesIn(entry, found);
+  } else if (value && typeof value === 'object') {
+    for (const [key, entry] of Object.entries(value)) {
+      if (FONT_KEYS.has(key)) {
+        const family = typeof entry === 'string' ? entry : entry?.family || entry?.fontFamily;
+        if (typeof family === 'string' && family.trim()) found.add(family.trim());
+      }
+      if (entry && typeof entry === 'object') fontFamiliesIn(entry, found);
+    }
+  }
+  return [...found].slice(0, 20);
+}
+
+function isFontError(error) {
+  return /font/i.test(`${error?.property || ''} ${error?.message || ''}`);
+}
+
+function boundedResult(value) {
+  if (value === undefined) return undefined;
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return String(value).slice(0, MAX_RESULT_CHARS);
+  }
+  if (text === undefined || text.length <= MAX_RESULT_CHARS) return value;
+  return `${text.slice(0, MAX_RESULT_CHARS)}… (truncated; return less data from the program)`;
+}
+
+function outputOf(result) {
+  const structured = result?.structured || {};
+  return structured.output && typeof structured.output === 'object' ? structured.output : structured;
+}
+
+function imagesFromExec(result, output) {
+  const listed = Array.isArray(output?.images) ? output.images : [];
+  const fromOutput = listed.flatMap((image) => {
+    const data = image?.data || image?.base64;
+    if (typeof data !== 'string' || !data) return [];
+    return [{ mimeType: image.mimeType || image.mediaType || 'image/png', data }];
+  });
+  return [...fromOutput, ...(result?.images || [])];
+}
+
+// The edit program runs with a recording view of `api`. Every layer an edit
+// call changes is noted as it happens, including ids computed in loops, and
+// so is every code file written. A call that edits an existing layer in place
+// counts only when the layer reads differently right after the call than right
+// before it; Framer's own change count leaves out text edits. Calls that throw
+// are noted even when the program catches the error. The real `api` object is
+// never modified.
+const RECORDING_PRELUDE = `
+const __dexterTouched = [];
+const __dexterFiles = [];
+const __dexterFailed = [];
+const __dexterUnchanged = [];
+const __dexterIdOf = (value) => typeof value === 'string' ? value : (value && typeof value.id === 'string' ? value.id : null);
+// Text blocks have virtual ids such as "v:dD8FHq_BL:1:0"; they belong to the layer in the middle.
+const __dexterLayerOf = (value) => { const id = __dexterIdOf(value); return id && id.startsWith('v:') ? id.split(':')[1] || null : id; };
+const __dexterNote = (...values) => { for (const value of values) { const id = __dexterIdOf(value); if (id) __dexterTouched.push(id); } };
+const __dexterStateOf = (tree, id) => {
+  if (!id) return null;
+  try {
+    const node = tree.get(id);
+    if (!node || typeof node.then === 'function') return null;
+    return JSON.stringify(node);
+  } catch { return null; }
+};
+const __dexterCompared = new Set(['patch', 'replaceText', 'remove']);
+const __dexterTreeRecorders = {
+  insert: (args, result) => __dexterNote(args[1], result),
+  move: (args) => __dexterNote(args[0]),
+  duplicate: (args, result) => __dexterNote(args[0], args[1], result),
+  patchFormDestinations: (args) => __dexterNote(args[0]),
+  createComponentFromFrame: (args, result) => __dexterNote(args[0], result),
+  makeExternalComponentLocal: (args, result) => __dexterNote(args[0], result),
+};
+const __dexterTreeTarget = { insert: 1 };
+const __dexterFileRecorders = Object.fromEntries(['create', 'write', 'applyPatch', 'delete'].map((op) => [op, (args, result) => {
+  __dexterFiles.push({ op, path: typeof args[0] === 'string' ? args[0] : '', diagnostics: result && Array.isArray(result.diagnostics) ? result.diagnostics : [] });
+}]));
+// The proxy sits on an empty stand-in that forwards to the real object, so
+// methods can be wrapped even when Framer freezes its API objects.
+const __dexterRecording = (object, recorders, children = {}, compared = new Set(), targets = {}) => new Proxy({}, {
+  has: (_, key) => Reflect.has(object, key),
+  ownKeys: () => Reflect.ownKeys(object),
+  getOwnPropertyDescriptor: (_, key) => {
+    const descriptor = Reflect.getOwnPropertyDescriptor(object, key);
+    return descriptor ? { ...descriptor, configurable: true } : undefined;
+  },
+  get(_, key) {
+    const value = Reflect.get(object, key);
+    if (children[key] && value && typeof value === 'object') return children[key](value);
+    if (typeof value !== 'function') return value;
+    const recorder = recorders[key];
+    const checked = compared.has(key);
+    if (!recorder && !checked) return (...args) => value.apply(object, args);
+    return (...args) => {
+      const fail = (error) => {
+        if (__dexterFailed.length < 50) {
+          __dexterFailed.push({ call: String(key), target: __dexterIdOf(args[targets[key] || 0]) || '', message: String((error && error.message) || error).slice(0, 300) });
+        }
+        throw error;
+      };
+      const layer = checked ? __dexterLayerOf(args[0]) : null;
+      const before = checked ? __dexterStateOf(object, layer) : null;
+      const settle = (result) => {
+        if (!checked) { recorder(args, result); return result; }
+        const after = __dexterStateOf(object, layer);
+        // Without a readable layer, the call's own answer is all there is.
+        const changed = before !== null || after !== null ? before !== after : result !== false;
+        if (changed) __dexterNote(layer);
+        else if (__dexterUnchanged.length < 50) __dexterUnchanged.push({ call: String(key), target: __dexterIdOf(args[0]) || '' });
+        return result;
+      };
+      let result;
+      try { result = value.apply(object, args); } catch (error) { fail(error); }
+      if (result && typeof result.then === 'function') return result.then(settle, fail);
+      return settle(result);
+    };
+  },
+});
+const __dexterApi = __dexterRecording(api, {}, {
+  tree: (tree) => __dexterRecording(tree, __dexterTreeRecorders, {}, __dexterCompared, __dexterTreeTarget),
+  files: (files) => __dexterRecording(files, __dexterFileRecorders),
+});
+`;
+
+function wrapperParts(program) {
+  const source = String(program || '');
+  // Framer shows a leading "// @step" comment as progress, so it stays first.
+  // The line it leaves behind keeps the program's own line numbers intact.
+  const step = source.match(/^\s*(\/\/\s*@step[^\n]*)/)?.[1] || '';
+  const body = step ? source.replace(step, '') : source;
+  // A program that throws still keeps the changes it made before the throw,
+  // so the error is caught here and returned with the record of those changes.
+  const prefix = `${step}
+${RECORDING_PRELUDE}
+let __dexterResult;
+let __dexterError = null;
+try {
+  __dexterResult = await (async (api) => {
+`;
+  const suffix = `
+  })(__dexterApi);
+} catch (error) {
+  __dexterError = { name: String((error && error.name) || 'Error'), message: String((error && error.message) || error) };
+}
+return { result: __dexterResult, dexterError: __dexterError, dexterFiles: __dexterFiles, dexterTouched: __dexterTouched, dexterFailed: __dexterFailed, dexterUnchanged: __dexterUnchanged };
+`;
+  return { prefix, body, suffix };
+}
+
+export function wrapProgram(program) {
+  const { prefix, body, suffix } = wrapperParts(program);
+  return `${prefix}${body}${suffix}`;
+}
+
+// Lines the wrapper adds before the model's program; Framer's compile errors
+// count from the top of the wrapped program.
+export function wrappedLineOffset(program) {
+  return wrapperParts(program).prefix.split('\n').length - 1;
+}
+
+// Framer reports a failed program as { error, errorType } with a long stack.
+// The model gets the first line, with line numbers in its own program.
+export function programErrorOf(output, lineOffset = 0) {
+  const inner = output?.result && typeof output.result === 'object' ? output.result : {};
+  const caught = inner.dexterError;
+  const raw = caught ? `${caught.name}: ${caught.message}` : output?.error;
+  if (!raw) return null;
+  let message = String(raw).split('\n')[0].slice(0, 600);
+  if (lineOffset > 0) {
+    message = message.replace(/Agent script line (\d+)/, (_, line) => `Program line ${Math.max(1, Number(line) - lineOffset)}`);
+  }
+  return {
+    type: caught ? 'script_error' : String(output?.errorType || 'script_error'),
+    message,
+  };
+}
+
+function screenshotProgram(ids) {
+  return `const taken = []
+for (const id of ${JSON.stringify(ids)}) {
+  try { await api.tree.screenshot(id); taken.push(id) } catch {}
+}
+return taken`;
+}
+
+function claimedTargetProgram(claimed, touched) {
+  return `
+const { tree } = api;
+const touched = new Set(${JSON.stringify(touched.slice(0, 500))});
+const verdicts = {};
+for (const id of ${JSON.stringify(claimed.slice(0, 200))}) {
+  const node = tree.get(id);
+  if (!node) { verdicts[id] = 'missing'; continue; }
+  const ancestors = (await tree.getAncestorsFor(id)) || [];
+  if (ancestors.some((ancestor) => touched.has(ancestor.id))) { verdicts[id] = 'related'; continue; }
+  let related = false;
+  for (const descendant of tree.walk(id)) {
+    if (touched.has(descendant.id)) { related = true; break; }
+  }
+  verdicts[id] = related ? 'related' : 'untouched';
+}
+return verdicts;
+`;
+}
+
+function mismatchMessage(name) {
+  const account = name ? ` (${name})` : '';
+  return `Your connected Framer account${account} can't open this project — connect the account that owns it.`;
+}
+
+export function createFramerAgentToolRuntime({
+  assignment,
+  onActivity,
+  authorizeProject,
+  readWebsite,
+  mcpClient,
+  getAccessToken,
+  trace,
+} = {}) {
+  const context = assignment?.context && typeof assignment.context === 'object' ? assignment.context : {};
+  const projectId = String(context.framerProjectId || '').trim();
+  const projectUrl = String(context.framerProjectUrl || '').trim();
+  const activePageId = String(context.activePageId || '').trim();
+  const allowPublishing = context.permissions?.publish === true;
+  const allowedTools = Array.isArray(assignment?.toolProtocol?.tools)
+    ? new Set(assignment.toolProtocol.tools)
+    : null;
+  const definitions = TOOL_DEFINITIONS.filter((tool) => !allowedTools || allowedTools.has(tool.name));
+  const reportActivity = typeof onActivity === 'function' ? onActivity : () => undefined;
+
+  let framerUserName = null;
+  let cachedToken = null;
+  let opened = false;
+  let branchChange = null;
+  let mutationCalls = 0;
+  let readCalls = 0;
+  let toolCallCount = 0;
+  let plan = null;
+  let behaviorPlan = null;
+  let behaviorResults = [];
+  let lastMutationAt = 0;
+  let lastReadAfterMutationAt = 0;
+  let lastVisualAt = 0;
+  let firstToolAt = null;
+  let guidance = { content: '', inventory: '', loaded: false, files: [] };
+  const mutationReceipts = [];
+  // Layer id → result of the latest edit call on it ('changed' or 'failed').
+  const editOutcomes = new Map();
+  const toolCalls = [];
+  let serial = Promise.resolve();
+  let server = null;
+  let gateway = null;
+  let closed = false;
+  const abortController = new AbortController();
+  let pendingRepair = null;
+
+  // Access tokens last minutes; the API refreshes them. A token is reused
+  // until a minute before it expires, and replaced at once when Framer
+  // refuses it.
+  const tokenGetter = getAccessToken || (async ({ force } = {}) => {
+    if (!force && cachedToken && cachedToken.expiresAt - Date.now() > 60_000) {
+      return cachedToken.accessToken;
+    }
+    if (typeof authorizeProject !== 'function') {
+      throw toolError('FRAMER_ACCOUNT_CONNECTION_REQUIRED', 'Connect your Framer account in Dexter before starting.', 409);
+    }
+    const authorization = await authorizeProject({ forceRefresh: Boolean(force), signal: abortController.signal });
+    if (authorization?.status !== 'ready' || !authorization.accessToken) {
+      cachedToken = null;
+      throw toolError('FRAMER_ACCOUNT_CONNECTION_REQUIRED', 'Connect your Framer account in Dexter before starting.', 409);
+    }
+    framerUserName = authorization.framerUserName || framerUserName;
+    const expiresAt = Date.parse(authorization.expiresAt || '');
+    cachedToken = {
+      accessToken: authorization.accessToken,
+      expiresAt: Number.isFinite(expiresAt) ? expiresAt : Date.now() + 5 * 60_000,
+    };
+    return authorization.accessToken;
+  });
+
+  const client = mcpClient || createFramerMcpClient({ getAccessToken: tokenGetter });
+
+  function lingeringPropertyErrors() {
+    let open = [];
+    for (const receipt of mutationReceipts) {
+      const touched = new Set(receipt.touchedNodeIds || []);
+      open = open.filter((error) => !touched.has(error.nodeId));
+      open.push(...(receipt.propertyErrors || []));
+    }
+    return open;
+  }
+
+  function touchedIds() {
+    const ids = new Set();
+    for (const receipt of mutationReceipts) {
+      for (const id of receipt.touchedNodeIds || []) ids.add(id);
+      for (const [from, to] of Object.entries(receipt.renamedIds || {})) {
+        if (from) ids.add(from);
+        if (to) ids.add(to);
+      }
+    }
+    return ids;
+  }
+
+  async function ensureProject() {
+    if (opened) return;
+    if (!projectId) {
+      throw toolError('FRAMER_HARNESS_PROJECT_REQUIRED', 'This run does not identify a Framer project.');
+    }
+    try {
+      await client.openProject(projectUrl || projectId);
+      opened = true;
+    } catch (error) {
+      if (error?.code === 'FRAMER_ACCOUNT_CONNECTION_REQUIRED') throw error;
+      if (PROJECT_MISMATCH_PATTERN.test(String(error?.message || error))) {
+        throw toolError('FRAMER_ACCOUNT_PROJECT_MISMATCH', mismatchMessage(framerUserName), 409);
+      }
+      throw error;
+    }
+  }
+
+  function recordCall(name, category, status, extra = {}) {
+    toolCallCount += 1;
+    toolCalls.push({ name, category, status, durationMs: extra.durationMs || 0, ...extra });
+  }
+
+  function applyReceipt(result, screenshotNodeIds) {
+    const output = outputOf(result);
+    const tree = output.tree && typeof output.tree === 'object' ? output.tree : {};
+    const changedNodeCount = Number(tree.changedNodeCount || output.changedNodeCount || 0) || 0;
+    const inner = output.result && typeof output.result === 'object' ? output.result : {};
+    const recordedFiles = [
+      ...(Array.isArray(output.dexterFiles) ? output.dexterFiles : []),
+      ...(Array.isArray(inner.dexterFiles) ? inner.dexterFiles : []),
+    ];
+    const codeFiles = recordedFiles.map((file) => ({
+      op: String(file.op || 'write').slice(0, 40),
+      path: String(file.path || '').slice(0, 500),
+      diagnostics: Array.isArray(file.diagnostics) ? file.diagnostics.slice(0, 20) : [],
+    }));
+    const renamedIds = tree.renamedIds && typeof tree.renamedIds === 'object' ? tree.renamedIds : {};
+    const resolve = (ids) => [...new Set(ids.map((id) => renamedIds[String(id)] || String(id)))].slice(0, 500);
+    // Only the recording wrapper's lists count: they hold what the program
+    // actually did inside Framer.
+    const calls = (list) => (Array.isArray(list) ? list : [])
+      .filter((call) => call && typeof call === 'object')
+      .slice(0, 50)
+      .map((call) => ({
+        call: String(call.call || '').slice(0, 60),
+        target: String(renamedIds[call.target] || call.target || '').slice(0, 200),
+        ...(call.message ? { message: String(call.message).slice(0, 300) } : {}),
+      }));
+    const failedCalls = calls(inner.dexterFailed);
+    const receipt = {
+      changedNodeCount,
+      renamedIds,
+      propertyErrors: propertyErrorsOf(output, renamedIds),
+      linterWarnings: linterWarningsOf(output),
+      codeFiles,
+      touchedNodeIds: resolve(Array.isArray(inner.dexterTouched) ? inner.dexterTouched : []),
+      failedCalls,
+      unchangedCalls: calls(inner.dexterUnchanged),
+      branchChange: output.branchChange || result.structured.branchChange || null,
+    };
+    for (const call of failedCalls) {
+      const id = layerIdOf(call.target);
+      if (id) editOutcomes.set(id, 'failed');
+    }
+    for (const id of receipt.touchedNodeIds) editOutcomes.set(layerIdOf(id), 'changed');
+    if (receipt.branchChange?.url) {
+      branchChange = {
+        title: String(receipt.branchChange.title || 'a Framer branch'),
+        id: String(receipt.branchChange.id || ''),
+        url: String(receipt.branchChange.url),
+      };
+      reportActivity({
+        kind: 'status_update',
+        source: 'framer-mcp',
+        message: `Edits are on branch ${branchChange.title}.`,
+      });
+    }
+    // A layer that reads differently after the edit is the evidence; Framer's
+    // count only adds changes the wrapper cannot see.
+    const changed = receipt.touchedNodeIds.length > 0 || codeFiles.length > 0 || changedNodeCount > 0;
+    if (changed) {
+      mutationCalls += 1;
+      lastMutationAt = Date.now();
+      mutationReceipts.push(receipt);
+    }
+    const images = imagesFromExec(result, output);
+    if (images.length > 0 || (screenshotNodeIds || []).length > 0 && images.length > 0) {
+      lastVisualAt = Date.now();
+    }
+    return { receipt, images, changed, output };
+  }
+
+  function recordPlan(rawPlan) {
+    const nextBehaviors = normalizeBehaviorPlan({ behaviors: rawPlan.behaviors || [] });
+    plan = {
+      summary: String(rawPlan.summary || '').slice(0, 1000),
+      domains: Array.isArray(rawPlan.domains) ? rawPlan.domains.map(String).slice(0, 12) : [],
+      verification: Array.isArray(rawPlan.verification) ? rawPlan.verification.map(String).slice(0, 12) : [],
+    };
+    behaviorPlan = mergeBehaviorPlans(behaviorPlan, nextBehaviors);
+  }
+
+  function firstEditNudge() {
+    if (mutationCalls > 0 || !definitions.some((tool) => tool.name === 'framer_edit')) return null;
+    return Date.now() - firstToolAt >= FIRST_EDIT_NUDGE_MS ? FIRST_EDIT_NUDGE : null;
+  }
+
+  function verification() {
+    const required = new Set(plan?.verification || []);
+    const missingChecks = [];
+    if (mutationCalls > 0 && lastReadAfterMutationAt < lastMutationAt) missingChecks.push('structural');
+    if (required.has('visual') && mutationCalls > 0 && lastVisualAt < lastMutationAt) missingChecks.push('visual');
+    if (required.has('interactions') && behaviorPlan) {
+      const summary = summarizeBehaviorVerification(behaviorPlan, behaviorResults);
+      if (summary.status !== 'verified') missingChecks.push('interactions');
+    }
+    return {
+      visualRequired: required.has('visual'),
+      visualCompleted: required.has('visual') && mutationCalls > 0 && lastVisualAt >= lastMutationAt,
+      completed: missingChecks.length === 0,
+      missingChecks,
+    };
+  }
+
+  // The structural read is the harness's job at the end of the run, so the
+  // model is only told about evidence it must produce itself.
+  function evidenceStillDue() {
+    if (mutationCalls === 0) return [];
+    return verification().missingChecks.filter((check) => check !== 'structural');
+  }
+
+  async function invokeUnsafe(name, args = {}) {
+    if (closed) throw toolError('FRAMER_AGENT_RUNTIME_CLOSED', 'This Framer run has finished.');
+    if (!definitions.some((tool) => tool.name === name)) {
+      throw toolError('FRAMER_AGENT_TOOL_UNKNOWN', `Unknown Framer tool ${name}.`);
+    }
+    const startedAt = Date.now();
+    if (firstToolAt === null) firstToolAt = startedAt;
+    reportActivity({ kind: 'tool_active', source: 'framer-mcp', name, phase: 'started' });
+    // Doc paths are kept on the call record so runs show which documents
+    // models keep asking for; those belong in the preloaded guidance.
+    const callExtra = {};
+    try {
+      let payload;
+      let category = 'read';
+      if (name === 'framer_read_website') {
+        if (typeof readWebsite !== 'function') {
+          throw toolError('FRAMER_READ_WEBSITE_UNAVAILABLE', 'Website reading is unavailable for this run.');
+        }
+        const website = await readWebsite({
+          url: String(args.url || '').trim(),
+          screenshotTop: Number.isInteger(args.screenshotTop) ? args.screenshotTop : undefined,
+        });
+        // Screenshots go to the model as images; inside the JSON text they
+        // would blow past the model's tool-result limit.
+        const images = (Array.isArray(website?.images) ? website.images : [])
+          .filter((image) => typeof image?.data === 'string' && image.data)
+          .map((image) => ({ mimeType: image.mimeType || 'image/jpeg', data: image.data }));
+        payload = {
+          result: website?.result ?? {},
+          ...(images.length ? { modelImages: images } : {}),
+        };
+        if (images.length) lastVisualAt = Date.now();
+        readCalls += 1;
+      } else if (name === 'framer_instructions') {
+        const paths = [...new Set((Array.isArray(args.paths) ? args.paths : []).map(String))].slice(0, 6);
+        callExtra.paths = paths;
+        await ensureProject();
+        // One wrong path must not cost the pages that exist.
+        const pages = await readDocsTolerant(paths);
+        const found = new Set(pages.map((page) => page.path));
+        const missing = paths.filter((docPath) => !found.has(docPath));
+        const preloaded = paths.filter((docPath) => PRELOADED_PATHS.has(docPath));
+        payload = {
+          pages: pages.map((page) => ({ path: page.path, content: stripGuidance(page.content) })),
+          ...(missing.length ? { missing } : {}),
+          ...(preloaded.length ? { note: `${preloaded.join(', ')} ${preloaded.length === 1 ? 'is' : 'are'} already in your instructions; do not read preloaded documents again.` } : {}),
+        };
+      } else if (name === 'framer_view_image') {
+        await ensureProject();
+        const result = await client.viewImage(args.urls);
+        const images = imagesFromExec(result, outputOf(result));
+        payload = { viewed: (args.urls || []).length, ...(images.length ? { modelImages: images } : {}) };
+        if (images.length) lastVisualAt = Date.now();
+      } else if (name === 'framer_read') {
+        const program = validateProgram(args.program, { write: false, allowPublishing });
+        await ensureProject();
+        const result = await client.exec(program);
+        const applied = applyReceipt(result, []);
+        if (applied.changed) {
+          throw toolError(
+            'FRAMER_AGENT_READ_ONLY_VIOLATION',
+            'A read changed the Framer project. Use framer_edit for changes.',
+          );
+        }
+        const readError = programErrorOf(applied.output);
+        if (readError) {
+          throw toolError('FRAMER_PROGRAM_FAILED', `${readError.message} (${readError.type})`);
+        }
+        readCalls += 1;
+        if (mutationCalls > 0) lastReadAfterMutationAt = Date.now();
+        const due = evidenceStillDue();
+        payload = {
+          result: boundedResult(applied.output.result ?? null),
+          ...(applied.images.length ? { modelImages: applied.images } : {}),
+          ...(due.length ? { evidenceStillDue: due } : {}),
+        };
+      } else if (name === 'framer_edit') {
+        category = 'mutation';
+        const program = validateProgram(args.program, { write: true, allowPublishing });
+        if (args.plan && typeof args.plan === 'object') recordPlan(args.plan);
+        const screenshotNodeIds = Array.isArray(args.screenshotNodeIds) ? args.screenshotNodeIds : [];
+        await ensureProject();
+        const result = await client.exec(wrapProgram(program));
+        const applied = applyReceipt(result, screenshotNodeIds);
+        const programError = programErrorOf(applied.output, wrappedLineOffset(program));
+        // Layers created by this program only get their real ids once it
+        // finishes, so screenshots are taken in a second call.
+        let screenshotWarning = null;
+        const shotIds = [...new Set(screenshotNodeIds.map((id) => applied.receipt.renamedIds[id] || id))]
+          .map((id) => String(id).slice(0, 200))
+          .filter(Boolean)
+          .slice(0, 4);
+        if (shotIds.length) {
+          try {
+            const shot = await client.exec(screenshotProgram(shotIds));
+            applied.images.push(...imagesFromExec(shot, outputOf(shot)));
+            const taken = outputOf(shot).result;
+            const missing = shotIds.filter((id) => !Array.isArray(taken) || !taken.includes(id));
+            if (missing.length) screenshotWarning = `No screenshot for ${missing.join(', ')}.`;
+          } catch (error) {
+            screenshotWarning = `Screenshots failed: ${String(error?.message || error).split('\n')[0].slice(0, 200)}`;
+          }
+        }
+        if (applied.images.length) lastVisualAt = Date.now();
+        const due = evidenceStillDue();
+        const inner = applied.output.result && typeof applied.output.result === 'object'
+          ? applied.output.result
+          : {};
+        const programResult = boundedResult(inner.result);
+        payload = {
+          ...(programError
+            ? {
+                programError: {
+                  ...programError,
+                  note: applied.changed
+                    ? 'The program stopped early. Changes made before the error were kept; read the project before retrying so they are not applied twice.'
+                    : 'The program stopped before changing anything.',
+                },
+              }
+            : {}),
+          ...(screenshotWarning ? { screenshotWarning } : {}),
+          ...(programResult !== undefined ? { result: programResult } : {}),
+          changedNodeCount: applied.receipt.changedNodeCount,
+          // Framer gives inserted nodes new ids; later programs must use them.
+          renamedIds: applied.receipt.renamedIds,
+          touchedNodeIds: applied.receipt.touchedNodeIds,
+          ...(applied.receipt.unchangedCalls.length
+            ? {
+                unchangedCalls: applied.receipt.unchangedCalls,
+                unchangedCallsNote: 'These calls ran but left the layer exactly as it was.',
+              }
+            : {}),
+          ...(applied.receipt.failedCalls.length
+            ? {
+                failedCalls: applied.receipt.failedCalls,
+                failedCallsNote: 'These calls threw and changed nothing, even where your program caught the error. Fix them in your next framer_edit, or say in your summary what was not changed.',
+              }
+            : {}),
+          propertyErrors: applied.receipt.propertyErrors,
+          ...(applied.receipt.propertyErrors.some(isFontError) ? { propertyErrorHint: FONT_ERROR_HINT } : {}),
+          ...(applied.receipt.linterWarnings.length ? { linterWarnings: applied.receipt.linterWarnings } : {}),
+          codeFiles: applied.receipt.codeFiles,
+          ...(applied.receipt.branchChange ? { branchChange: applied.receipt.branchChange } : {}),
+          ...(applied.images.length ? { modelImages: applied.images } : {}),
+          ...(due.length ? { evidenceStillDue: due } : {}),
+        };
+      } else if (name === 'framer_verify_interactions') {
+        behaviorPlan = mergeBehaviorPlans(behaviorPlan, normalizeBehaviorPlan({ behaviors: args.behaviors || [] }));
+        const checks = normalizeBehaviorEvidence(args.checks, behaviorPlan);
+        const nodeIds = evidenceNodeIds(checks);
+        await ensureProject();
+        // Serialized nodes are plain data; live node objects can crash
+        // Framer's worker when returned.
+        const result = await client.exec(
+          `return await api.tree.serializeNodes(${JSON.stringify(nodeIds)}, { depth: 0 });`,
+        );
+        const output = outputOf(result);
+        const nodes = output.result || output.nodes || output;
+        const list = Array.isArray(nodes) ? nodes : nodes?.nodes;
+        const nodeMap = new Map();
+        if (Array.isArray(list)) {
+          for (const node of list) {
+            if (node?.id) nodeMap.set(node.id, node);
+          }
+        } else if (nodes && typeof nodes === 'object') {
+          for (const [id, node] of Object.entries(nodes)) nodeMap.set(id, node);
+        }
+        behaviorResults = verifyBehaviorChecks({ checks, nodes: nodeMap });
+        readCalls += 1;
+        if (mutationCalls > 0) lastReadAfterMutationAt = Date.now();
+        payload = summarizeBehaviorVerification(behaviorPlan, behaviorResults);
+      } else {
+        throw toolError('FRAMER_AGENT_TOOL_UNKNOWN', `Unknown Framer tool ${name}.`);
+      }
+      recordCall(name, category, 'succeeded', { ...callExtra, durationMs: Date.now() - startedAt });
+      const nudge = category === 'read' ? firstEditNudge() : null;
+      if (nudge) payload = { ...payload, nextStep: nudge };
+      reportActivity({
+        kind: 'tool_active',
+        source: 'framer-mcp',
+        name,
+        phase: 'completed',
+        durationMs: Date.now() - startedAt,
+      });
+      return payload;
+    } catch (error) {
+      recordCall(name, name === 'framer_edit' ? 'mutation' : 'read', 'failed', {
+        ...callExtra,
+        errorCode: error?.code,
+        durationMs: Date.now() - startedAt,
+      });
+      reportActivity({
+        kind: 'tool_active',
+        source: 'framer-mcp',
+        name,
+        phase: 'failed',
+        message: error?.message,
+        durationMs: Date.now() - startedAt,
+      });
+      throw error;
+    }
+  }
+
+  function invoke(name, args = {}) {
+    const operation = serial.then(() => invokeUnsafe(name, args));
+    serial = operation.catch(() => undefined);
+    return operation;
+  }
+
+  // Each path is read on its own so one missing document does not lose the
+  // others.
+  async function readDocsTolerant(paths) {
+    const pages = await Promise.all(paths.map(async (docPath) => {
+      try {
+        const [page] = await client.readDocs([docPath]);
+        if (page && String(page.content || '').trim()) return page;
+        trace?.warn?.('framer_doc_empty', { path: docPath });
+      } catch (error) {
+        trace?.warn?.('framer_doc_failed', { path: docPath, message: String(error?.message || error).slice(0, 300) });
+      }
+      return null;
+    }));
+    return pages.filter(Boolean);
+  }
+
+  // The active page's top levels, so the model knows what is on the page
+  // without spending a turn reading it.
+  async function readActivePageOutline() {
+    if (!activePageId) return '';
+    const result = await client.exec(
+      `return await api.tree.serializeNodes(${JSON.stringify([activePageId])}, { depth: ${ACTIVE_PAGE_OUTLINE_DEPTH} });`,
+    );
+    const output = outputOf(result);
+    if (output.error || output.result == null) return '';
+    const outline = boundedResult(output.result);
+    const fonts = fontFamiliesIn(output.result);
+    return [
+      `Active page ${activePageId}, read when this run started (top ${ACTIVE_PAGE_OUTLINE_DEPTH} levels):\n${typeof outline === 'string' ? outline : JSON.stringify(outline)}`,
+      fonts.length ? `Fonts this page already uses, safe to set directly: ${fonts.join(', ')}.` : '',
+    ].filter(Boolean).join('\n');
+  }
+
+  async function loadProjectGuidance() {
+    await ensureProject();
+    // Guidance and the page outline are helpful and must not block the run.
+    const [pages, contextPages, activePage] = await Promise.all([
+      readDocsTolerant(GUIDANCE_PATHS),
+      readDocsTolerant([CONTEXT_PATH]),
+      readActivePageOutline().catch(() => ''),
+    ]);
+    const inventory = [
+      stripGuidance(contextPages.map((page) => page.content).join('\n\n')),
+      activePage,
+    ].filter(Boolean).join('\n\n');
+    const readme = stripGuidance(client.readme());
+    const content = [
+      PRELOADED_GUIDANCE_NOTE,
+      readme,
+      ...pages.map((page) => stripGuidance(page.content)),
+    ].filter(Boolean).join('\n\n');
+    guidance = {
+      content,
+      inventory,
+      loaded: Boolean(content || inventory),
+      files: [
+        readme ? 'README' : null,
+        ...pages.map((page) => page.path),
+        contextPages.length ? CONTEXT_PATH : null,
+        activePage ? 'active-page' : null,
+      ].filter(Boolean),
+    };
+    return { content: guidance.content, inventory: guidance.inventory };
+  }
+
+  function verificationRepairText() {
+    if (mutationCalls === 0) return null;
+    const missing = verification().missingChecks;
+    const propertyErrors = lingeringPropertyErrors();
+    const lines = [];
+    if (propertyErrors.length) {
+      lines.push(`Framer did not apply every property: ${propertyErrors.map((error) => `${error.nodeId}.${error.property}: ${error.message}`).join('; ')}. Repair those properties with framer_edit.`);
+    }
+    if (pendingRepair?.claimed?.length) {
+      lines.push(`These claimed node ids were not touched by an edit: ${pendingRepair.claimed.join(', ')}. Edit those nodes or remove them from changedNodeIds.`);
+    }
+    if (pendingRepair?.failed?.length) {
+      lines.push(`Your latest edit of these claimed node ids failed, so it changed nothing: ${pendingRepair.failed.join(', ')}. Apply that change with framer_edit, or remove them from changedNodeIds and say in the summary what was not changed.`);
+    }
+    for (const check of missing) {
+      if (check === 'structural') lines.push('perform a focused live read after the latest mutation');
+      else if (check === 'visual') lines.push('capture and inspect a screenshot of the affected canvas after the latest mutation');
+      else if (check === 'interactions') lines.push('confirm declared behaviors with framer_verify_interactions');
+    }
+    if (!lines.length) return null;
+    return lines.join(' ');
+  }
+
+  // The read after the last change is a mechanical check, so the harness
+  // performs it instead of sending the model back for another turn.
+  async function completeStructuralRead() {
+    if (mutationCalls === 0 || lastReadAfterMutationAt >= lastMutationAt) return;
+    const touched = mutationReceipts.at(-1)?.touchedNodeIds || [];
+    const ids = (touched.length ? touched : activePageId ? [activePageId] : []).slice(0, 50);
+    if (!ids.length) return;
+    const startedAt = Date.now();
+    try {
+      await ensureProject();
+      const result = await client.exec(
+        `return (await api.tree.serializeNodes(${JSON.stringify(ids)}, { depth: 0 })) != null;`,
+      );
+      if (outputOf(result).error) throw new Error(String(outputOf(result).error));
+      readCalls += 1;
+      lastReadAfterMutationAt = Date.now();
+      recordCall('framer_read', 'read', 'succeeded', { harness: true, durationMs: Date.now() - startedAt });
+    } catch (error) {
+      recordCall('framer_read', 'read', 'failed', { harness: true, errorCode: error?.code, durationMs: Date.now() - startedAt });
+    }
+  }
+
+  async function assessCompletion(completion) {
+    await completeStructuralRead();
+    const claimed = Array.isArray(completion?.changedNodeIds)
+      ? completion.changedNodeIds.filter((id) => typeof id === 'string' && id.trim())
+      : [];
+    const known = touchedIds();
+    // A layer whose latest edit threw is not changed by that edit, even when
+    // an earlier edit in the run touched it.
+    const failed = claimed.filter((id) => editOutcomes.get(layerIdOf(id)) === 'failed');
+    let missing = claimed.filter((id) => !failed.includes(id) && !known.has(id));
+    if (missing.length) {
+      // A claimed layer also counts when an edit changed a layer inside it or
+      // around it, such as a card whose title was rewritten.
+      try {
+        await ensureProject();
+        const result = await client.exec(claimedTargetProgram(missing, [...known]));
+        const verdicts = outputOf(result).result;
+        if (verdicts && typeof verdicts === 'object') {
+          missing = missing.filter((id) => verdicts[id] !== 'related');
+        }
+        readCalls += 1;
+      } catch {
+        // Without a read the claim cannot be checked either way, so it is
+        // not held against the run; the change-count check still applies.
+        missing = [];
+      }
+    }
+    pendingRepair = { claimed: missing, failed };
+    return pendingRepair;
+  }
+
+  function unappliedChangePrompt(completion) {
+    if (completion?.projectChanged !== true || mutationCalls > 0) return null;
+    return [
+      'Your summary says you changed the Framer project, but no layer reads differently after your edits.',
+      'Continue the same task: find every target the user meant, apply the change with framer_edit, verify it, then return the required JSON outcome.',
+      'If you cannot find or change a target, name it in the summary and set projectChanged to false.',
+    ].join(' ');
+  }
+
+  function unblockedFailurePrompt(completion) {
+    if (completion?.status !== 'failed' || mutationCalls > 0) return null;
+    const lastEdit = [...toolCalls].reverse().find((call) => call.category === 'mutation');
+    if (lastEdit?.status === 'failed') return null;
+    return [
+      'You returned failed without changing the Framer project, and no tool refused the work.',
+      'Continue the same task from the current project state: plan it, apply the change, verify it, then return the required JSON outcome.',
+    ].join(' ');
+  }
+
+  function failedChecks(completion) {
+    const checks = [];
+    if (completion?.projectChanged === true && mutationCalls === 0) {
+      checks.push({
+        command: UNAPPLIED_CHANGE_CHECK,
+        status: 'failed',
+        output: 'No layer changed for a summary that claimed a change.',
+      });
+    }
+    const propertyErrors = lingeringPropertyErrors();
+    if (propertyErrors.length) {
+      checks.push({
+        command: PROPERTY_ERROR_CHECK,
+        status: 'failed',
+        output: propertyErrors.map((error) => `${error.nodeId}.${error.property}`).join(', '),
+      });
+    }
+    const unbacked = [...(pendingRepair?.claimed || []), ...(pendingRepair?.failed || [])];
+    if (unbacked.length) {
+      checks.push({
+        command: CLAIMED_TARGET_CHECK,
+        status: 'failed',
+        output: unbacked.join(', '),
+      });
+    }
+    // The model's own plan sets the evidence it owes; a run that changed the
+    // project and skipped it is not accepted as done.
+    const state = verification();
+    if (mutationCalls > 0 && !state.completed) {
+      const missing = state.missingChecks.map((check) => {
+        if (check === 'structural') return 'a read after the last change';
+        if (check === 'visual') return 'a screenshot after the last change';
+        return `${check} verification after the last change`;
+      });
+      checks.push({
+        command: VERIFICATION_CHECK,
+        status: 'failed',
+        output: `The run ended before ${missing.join(' and ')}.`,
+      });
+    }
+    return checks;
+  }
+
+  function finalizeCompletion(completion) {
+    if (completion?.status !== 'completed') return completion;
+    const extra = failedChecks(completion);
+    if (!extra.length) return completion;
+    const unapplied = extra.some((check) => check.command === UNAPPLIED_CHANGE_CHECK);
+    return {
+      ...completion,
+      status: 'failed',
+      projectChanged: unapplied ? false : completion.projectChanged,
+      summary: unapplied
+        ? 'I didn’t change anything in Framer this time, even though I was about to say I had. Please try again, or select the element you want changed.'
+        : completion.summary,
+      checks: [...(completion.checks || []), ...extra],
+    };
+  }
+
+  async function startGateway() {
+    if (gateway) return gateway;
+    const { createServer } = await import('node:http');
+    const token = crypto.randomBytes(32).toString('base64url');
+    server = createServer((request, response) => {
+      const fail = (status, code, message) => {
+        response.writeHead(status, { 'content-type': 'application/json' });
+        response.end(JSON.stringify({ ok: false, error: { code, message } }));
+      };
+      if (request.method !== 'POST' || request.url !== '/tool') {
+        fail(404, 'FRAMER_MCP_GATEWAY_NOT_FOUND', 'Framer tool endpoint not found.');
+        return;
+      }
+      if (request.headers.authorization !== `Bearer ${token}`) {
+        fail(401, 'FRAMER_MCP_GATEWAY_UNAUTHORIZED', 'Invalid Framer tool token.');
+        return;
+      }
+      let body = '';
+      request.on('data', (chunk) => {
+        body += chunk.toString('utf8');
+        if (body.length > 512 * 1024) request.destroy();
+      });
+      request.on('end', async () => {
+        try {
+          const payload = JSON.parse(body || '{}');
+          const result = await invoke(String(payload.name || ''), payload.arguments || {});
+          response.writeHead(200, { 'content-type': 'application/json' });
+          response.end(JSON.stringify({ ok: true, result }));
+        } catch (error) {
+          fail(Number(error?.statusCode) || 400, error?.code || 'FRAMER_MCP_TOOL_FAILED', error?.message || 'Framer tool failed.');
+        }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    gateway = { url: `http://127.0.0.1:${address.port}/tool`, token };
+    return gateway;
+  }
+
+  return {
+    definitions,
+    toolNames: definitions.map((definition) => definition.name),
+    preflight: async () => {
+      await ensureProject();
+      return { unresolvedTargets: [] };
+    },
+    loadProjectGuidance,
+    configurePromptContext() {},
+    invoke,
+    startGateway,
+    synchronize: async () => ({ synchronized: true, sourceHash: null }),
+    inspect: async () => ({ synchronized: true, sourceHash: null }),
+    assessCompletion,
+    finalizeCompletion,
+    verificationRepairPrompt: () => verificationRepairText(),
+    unappliedChangePrompt,
+    unblockedFailurePrompt,
+    sourceHash: () => null,
+    hasPendingChanges: () => false,
+    directWorkspace: true,
+    summary: () => ({
+      projectId,
+      projectUrl,
+      mutationCalls,
+      readCalls,
+      toolCallCount,
+      toolCalls: toolCalls.map((call) => ({ ...call })),
+      mutationReceipts: mutationReceipts.map((receipt) => ({ ...receipt })),
+      branch: branchChange,
+      verification: verification(),
+      framerGuidanceLoaded: guidance.loaded,
+      guidance: {
+        loaded: guidance.loaded,
+        files: [...guidance.files],
+      },
+    }),
+    fatalInfrastructureError: () => null,
+    waitForFatalInfrastructure: () => new Promise(() => undefined),
+    close: async ({ waitForPending = true } = {}) => {
+      closed = true;
+      abortController.abort();
+      if (waitForPending) await serial.catch(() => undefined);
+      await client.close?.().catch(() => undefined);
+      if (server) {
+        if (!waitForPending) server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+        server = null;
+      }
+    },
+  };
+}
+
+export function __resetFramerAgentToolRuntimeForTests() {}