@gakim-digital/dexter-bridge 0.11.23 → 0.12.0

package/src/framerAgentTools.js

@@ -1,3298 +0,0 @@
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import jsTokens from 'js-tokens';
-import { loadGoogleFontsCatalog, searchGoogleFonts } from './googleFontsFallback.js';
-import {
-  canonicalIdMappings,
-  evidenceNodeIds,
-  mergeBehaviorPlans,
-  normalizeBehaviorEvidence,
-  normalizeBehaviorPlan,
-  summarizeBehaviorVerification,
-  summarizeFramerChanges,
-  verifyBehaviorChecks,
-} from './framerBehaviorContract.js';
-
-const require = createRequire(import.meta.url);
-const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
-const MAX_MODEL_RESULT_BYTES = 120 * 1024;
-const MAX_CODE_FILE_CONTENT_CHARS = 200_000;
-const MAX_SVG_MARKUP_CHARS = 200_000;
-const MAX_SVG_ATTRIBUTES = 24;
-const UNSAFE_SVG_PATTERN =
-  /<\s*(?:script|foreignObject|iframe)\b|\son[a-z]+\s*=|javascript:|(?:xlink:)?href\s*=\s*["']\s*(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
-const MUTATION_TOOL_NAMES = new Set([
-  'framer_apply_changes',
-  'framer_add_svg',
-  'framer_update_code_file',
-  'framer_write',
-]);
-const MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
-const MAX_SCREENSHOTS_PER_CALL = 4;
-const SCREENSHOT_FETCH_TIMEOUT_MS = 20_000;
-const SESSION_SCREENSHOT_TIMEOUT_MS = 60_000;
-const MAX_SCREENSHOT_FAILURES_REPORTED = 8;
-const SCREENSHOT_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif']);
-const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60_000;
-const SESSION_TIMEOUT_MS = 10 * 60_000;
-const MAX_UNSAFE_WRITE_FAILURES = 2;
-const MAX_LOW_LEVEL_WRITE_FAILURES = 3;
-const MAX_GUIDANCE_BYTES = 180 * 1024;
-const MAX_GUIDANCE_FILE_BYTES = 48 * 1024;
-const PROJECT_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
-const PROJECT_SEGMENT_PATTERN =
-  /^(?:.+--)?([A-Za-z0-9]+)(?:-[A-Za-z0-9]+)?$/;
-const FRAMER_PROJECT_HOST_PATTERN = /(^|\.)framer(?:local)?\.com$/i;
-const PAGE_PATH_PATTERN = /^\/[^\0\r\n]{0,499}$/;
-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 MUTATING_EXEC_PATTERN =
-  /\.(?:(?:set|add|delete|join|apply)(?:[A-Z_][A-Za-z0-9_]*)|(?:create|remove|update|insert|move|clone|duplicate|upload|publish|deploy|switch|merge|rename|leave)[A-Za-z0-9_]*)\s*\(/;
-const CODE_FILE_SOURCE_WRITE_PATTERN =
-  /(?:\.setFileContent|\[\s*['"]setFileContent['"]\s*\])\s*\(/;
-const TASK_DOMAINS = [
-  'visual',
-  'content',
-  'links',
-  'interactions',
-  'responsive',
-  'data',
-  'code',
-  'structure',
-];
-const VERIFICATION_CHECKS = [
-  'structural',
-  'visual',
-  'links',
-  'interactions',
-  'responsive',
-  'code',
-  'data',
-];
-const GENERIC_VERIFICATION_CHECKS = VERIFICATION_CHECKS.filter(
-  (check) => check !== 'interactions',
-);
-const EMPTY_SCHEMA = {
-  type: 'object',
-  properties: {},
-  additionalProperties: false,
-};
-
-export const FRAMER_AGENT_TOOL_DEFINITIONS = [
-  {
-    name: 'framer_instructions',
-    description:
-      'Read on-demand project guides by id from the "On-demand guides" catalog, or request targeted official API documentation when an exact method or type is unclear.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        guides: {
-          type: 'array',
-          maxItems: 6,
-          items: { type: 'string', minLength: 1, maxLength: 120 },
-        },
-        queries: {
-          type: 'array',
-          maxItems: 8,
-          items: { type: 'string', minLength: 1, maxLength: 120 },
-        },
-      },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_context',
-    description:
-      'Read current project context, including pages, components, styles, fonts, CMS collections, and the active branch.',
-    inputSchema: EMPTY_SCHEMA,
-  },
-  {
-    name: 'framer_read_project',
-    description:
-      'Run Framer Agent readProject queries: "screenshot", "font-search", and "implementation-guide-from-index" are the only query types. Read nodes and layout with framer_read instead.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        queries: {
-          type: 'array',
-          minItems: 1,
-          maxItems: 50,
-          items: { type: 'object', additionalProperties: true },
-        },
-        pagePath: { type: 'string', maxLength: 500, default: '/' },
-        verifies: {
-          type: 'array',
-          uniqueItems: true,
-          maxItems: 6,
-          items: { type: 'string', enum: GENERIC_VERIFICATION_CHECKS },
-          description:
-            'Verification evidence this read is intended to establish after mutations. Interaction verification requires framer_verify_interactions.',
-        },
-      },
-      required: ['queries'],
-      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,
-    },
-  },
-  {
-    name: 'framer_plan_task',
-    description:
-      'After inspecting the live Framer target and before the first mutation, declare your understanding of the task and the evidence you will produce. Dexter does not classify the request or choose how to build it; use any capability the Framer guidance documents.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        summary: {
-          type: 'string',
-          minLength: 10,
-          maxLength: 1000,
-        },
-        domains: {
-          type: 'array',
-          minItems: 1,
-          uniqueItems: true,
-          items: { type: 'string', enum: TASK_DOMAINS },
-        },
-        verification: {
-          type: 'array',
-          minItems: 1,
-          uniqueItems: true,
-          items: { type: 'string', enum: VERIFICATION_CHECKS },
-          description:
-            'The evidence you will produce before completion. Dexter enforces exactly this list and adds nothing to it. Include "visual" when the result must be judged by eye, such as layout or styling work or a build from a reference image, then inspect a screenshot after your final mutation.',
-        },
-        behaviors: {
-          type: 'array',
-          maxItems: 20,
-          description:
-            'Interactive or animated behaviors the result must have, such as links, hover or tap effects, overlays, variants, appear, loop, or ticker motion. Declaring behaviors adds interaction verification.',
-          items: {
-            type: 'object',
-            properties: {
-              id: { type: 'string', minLength: 1, maxLength: 120 },
-              description: {
-                type: 'string',
-                minLength: 5,
-                maxLength: 500,
-                description: 'What the visitor should experience.',
-              },
-              targetNodeIds: {
-                type: 'array',
-                maxItems: 50,
-                uniqueItems: true,
-                items: { type: 'string', minLength: 1, maxLength: 200 },
-                description:
-                  'Every node that should carry this behavior once the work is done. Update the plan if they change, for example after replacing nodes.',
-              },
-            },
-            required: ['id', 'description'],
-            additionalProperties: false,
-          },
-        },
-      },
-      required: ['summary', 'domains', 'verification'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_verify_interactions',
-    description:
-      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap, or a field inside one such as link.href or hoverEffect.opacity) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        pagePath: { type: 'string', maxLength: 500, default: '/' },
-        checks: {
-          type: 'array',
-          minItems: 1,
-          maxItems: 50,
-          items: {
-            type: 'object',
-            properties: {
-              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
-              nodeId: { type: 'string', minLength: 1, maxLength: 200 },
-              property: { type: 'string', minLength: 1, maxLength: 120 },
-              contains: { type: 'string', minLength: 1, maxLength: 500 },
-            },
-            required: ['behaviorId', 'nodeId', 'property'],
-            additionalProperties: false,
-          },
-        },
-      },
-      required: ['checks'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_query_images',
-    description:
-      'Search Framer Agent’s approved image source for real-world imagery. Use this only when the design needs a concrete photo or editorial image and no suitable user attachment or existing project image is available.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: { type: 'string', minLength: 2, maxLength: 200 },
-        count: { type: 'integer', minimum: 1, maximum: 8, default: 4 },
-        orientation: {
-          type: 'string',
-          enum: ['landscape', 'portrait', 'squarish'],
-        },
-      },
-      required: ['query'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_upload_attachment',
-    description:
-      'Upload one of the user attachments listed in context.referenceAssetFiles into this Framer project and return its framerusercontent.com URL. Use the returned url as an image fill in framer_apply_changes. This is the only way to place a user attachment in the project.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        attachmentId: { type: 'string', minLength: 1, maxLength: 180 },
-      },
-      required: ['attachmentId'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_apply_changes',
-    description:
-      'Apply Framer Agent DSL changes directly to the connected project. Prefer this for page, layout, style, design-token, component, and CMS-on-canvas work. Pass screenshotNodeIds to get screenshots of those nodes taken after the change in the same result, instead of a separate read.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        changes: { type: 'string', minLength: 1, maxLength: 250_000 },
-        pagePath: { type: 'string', maxLength: 500, default: '/' },
-        screenshotNodeIds: {
-          type: 'array',
-          maxItems: MAX_SCREENSHOTS_PER_CALL,
-          uniqueItems: true,
-          items: { type: 'string', minLength: 1, maxLength: 200 },
-          description:
-            'Nodes (or component variants) to screenshot after the change is applied. The screenshots count as visual evidence after this mutation.',
-        },
-      },
-      required: ['changes'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_add_svg',
-    description:
-      'Create an SVG layer from markup you write and place it inside a parent node. Use it for geometric and decorative artwork such as line work, starbursts, rings, sparkles, wireframe shapes, dividers, and simple marks. Use icon sets for icons, real text for text, and images for photos. Returns the new SVG node id; check it in a screenshot. To revise its markup later, use framer_write with setAttributes({ svg }) on that node.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        svg: {
-          type: 'string',
-          minLength: 1,
-          maxLength: MAX_SVG_MARKUP_CHARS,
-          description:
-            'One self-contained <svg> element with a viewBox. No scripts, event handlers, foreignObject, or external references.',
-        },
-        parentId: { type: 'string', minLength: 1, maxLength: 200 },
-        index: { type: 'integer', minimum: 0 },
-        name: { type: 'string', minLength: 1, maxLength: 120 },
-        attributes: {
-          type: 'object',
-          description:
-            'Optional Framer layer attributes for the SVG node, for example {"position":"absolute","top":"40px","left":"0px","width":"320px","height":"320px","rotation":12,"opacity":0.6}. Defaults to position relative at the SVG\'s own size.',
-        },
-      },
-      required: ['svg', 'parentId'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_read_code_file',
-    description:
-      'Read the complete source of an existing Framer code file by its exact project path. Use this instead of generic JavaScript when inspecting a code component or override. Files up to 200,000 characters are returned without the general Framer result cap, together with completeness metadata, a source hash, and the version ID required for a safe update.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', minLength: 1, maxLength: 1_000 },
-      },
-      required: ['path'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_update_code_file',
-    description:
-      'Replace an existing Framer code file with complete updated source. Always read the file first and pass its exact version ID. Dexter resolves the CodeFile, rejects stale edits, saves through Framer, type-checks, and reads the saved source back.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', minLength: 1, maxLength: 1_000 },
-        expectedVersionId: { type: 'string', minLength: 1, maxLength: 300 },
-        content: {
-          type: 'string',
-          maxLength: MAX_CODE_FILE_CONTENT_CHARS,
-        },
-      },
-      required: ['path', 'expectedVersionId', 'content'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_read',
-    description:
-      'Execute read-only JavaScript with the official Framer Agent connection. Use it to read nodes and layout, for example with framer.agent.getNode, serialize, or serializeNodes; combine several reads in one script.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        code: { type: 'string', minLength: 1, maxLength: 200_000 },
-        verifies: {
-          type: 'array',
-          uniqueItems: true,
-          maxItems: 6,
-          items: { type: 'string', enum: GENERIC_VERIFICATION_CHECKS },
-          description:
-            'Verification evidence this read is intended to establish after mutations. Interaction verification requires framer_verify_interactions.',
-        },
-      },
-      required: ['code'],
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'framer_write',
-    description:
-      'Execute project-scoped JavaScript with the official Framer Agent connection for mutations not covered by dedicated tools or applyChanges, such as localization, redirects, assets, CMS, or branch operations. Use framer_update_code_file for existing code files. Publishing is disabled unless Dexter explicitly authorizes it. If a write is rejected as unsafe, do not retry JavaScript variants; switch to a dedicated tool, framer_apply_changes, or report the concrete blocker.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        code: { type: 'string', minLength: 1, maxLength: 200_000 },
-        reason: {
-          type: 'string',
-          minLength: 10,
-          maxLength: 500,
-          description:
-            'Explain the specific Framer capability needed and why framer_apply_changes cannot perform it.',
-        },
-      },
-      required: ['code', 'reason'],
-      additionalProperties: false,
-    },
-  },
-];
-
-const TOOL_BY_NAME = new Map(
-  FRAMER_AGENT_TOOL_DEFINITIONS.map((definition) => [
-    definition.name,
-    definition,
-  ]),
-);
-const sessionsByProject = new Map();
-let framerSetupPromise = null;
-
-function isRecord(value) {
-  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
-}
-
-function toolError(code, message, statusCode = 400) {
-  return Object.assign(new Error(message), { code, statusCode });
-}
-
-function boundedText(value, maximum) {
-  const text = String(value || '');
-  if (Buffer.byteLength(text, 'utf8') <= maximum) return text;
-  return `${text.slice(0, maximum)}\n...[output clipped]`;
-}
-
-function hasInstalledFramerSkill(env) {
-  const home = String(env?.HOME || '').trim();
-  if (!home) return false;
-  return [
-    path.join(home, '.agents', 'skills', 'framer', 'SKILL.md'),
-    path.join(home, '.claude', 'skills', 'framer', 'SKILL.md'),
-  ].some((skillPath) => fs.existsSync(skillPath));
-}
-
-function framerSkillRoot(env) {
-  const home = String(env?.HOME || '').trim();
-  if (!home) return null;
-  return [
-    path.join(home, '.agents', 'skills', 'framer'),
-    path.join(home, '.claude', 'skills', 'framer'),
-  ].find((root) => fs.existsSync(path.join(root, 'SKILL.md'))) || null;
-}
-
-function isMissingFramerSkillError(error) {
-  return /could not find an installed framer skill|run [`'"]?@framer\/agent setup/i.test(
-    String(error?.message || ''),
-  );
-}
-
-function installedFramerAgentVersion() {
-  try {
-    let current = path.dirname(resolveFramerAgentCli());
-    for (let depth = 0; depth < 8; depth += 1) {
-      const packagePath = path.join(current, 'package.json');
-      if (fs.existsSync(packagePath)) {
-        const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-        if (manifest?.name === '@framer/agent') {
-          return String(manifest.version || '').trim() || null;
-        }
-      }
-      const parent = path.dirname(current);
-      if (parent === current) break;
-      current = parent;
-    }
-  } catch {
-    // Version telemetry must never block a run.
-  }
-  return null;
-}
-
-function readGuidanceFile(projectRoot, relativePath, remainingBytes, section) {
-  const normalized = relativePath.replaceAll('\\', '/');
-  if (
-    normalized.startsWith('/')
-    || normalized.split('/').some((segment) => segment === '..')
-  ) return null;
-  const absolutePath = path.resolve(projectRoot, normalized);
-  if (
-    absolutePath !== projectRoot
-    && !absolutePath.startsWith(`${projectRoot}${path.sep}`)
-  ) return null;
-  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
-    return null;
-  }
-  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(content, maximum),
-  };
-}
-
-const CORE_GUIDE_SECTIONS = [
-  { file: 'how-projects-work', section: 'Scope Types' },
-  { file: 'how-projects-work', section: 'Replicas' },
-  { file: 'how-projects-work', section: 'Transforms' },
-  { file: 'implementation-strategy', section: 'Determining Strategy' },
-  { file: 'implementation-strategy', section: 'Edit Strategy' },
-  { file: 'implementation-strategy', section: 'Update Loop' },
-];
-const ON_DEMAND_GUIDE_FILES = [
-  { file: 'how-projects-work', sections: true },
-  { file: 'implementation-strategy', sections: true },
-  { file: 'core-examples', sections: false },
-];
-
-// Lists the topic guides that are not part of every prompt, keyed by
-// "file#Section" (or "file" for a whole file), from the files on disk.
-function onDemandGuideCatalog(projectRoot) {
-  const catalog = new Map();
-  for (const { file, sections } of ON_DEMAND_GUIDE_FILES) {
-    const relativePath = `prompt/${file}.md`;
-    const absolutePath = path.join(projectRoot, relativePath);
-    if (!fs.existsSync(absolutePath)) continue;
-    if (!sections) {
-      catalog.set(file, { root: projectRoot, path: relativePath });
-      continue;
-    }
-    const headings = fs.readFileSync(absolutePath, 'utf8')
-      .split('\n')
-      .filter((line) => line.startsWith('## '))
-      .map((line) => line.slice(3).trim())
-      .filter((heading) => !CORE_GUIDE_SECTIONS.some(
-        (core) => core.file === file && core.section === heading,
-      ));
-    for (const heading of headings) {
-      catalog.set(`${file}#${heading}`, {
-        root: projectRoot,
-        path: relativePath,
-        section: heading,
-      });
-    }
-  }
-  return catalog;
-}
-
-// Returns a "## " or "### " section up to the next heading of the same or a
-// higher level.
-function markdownSection(markdown, heading) {
-  const lines = markdown.split('\n');
-  const headingLevel = (line) => /^(#{1,6}) /.exec(line)?.[1].length || 0;
-  const start = lines.findIndex(
-    (line) => headingLevel(line) >= 2
-      && line.trim().replace(/^#+ /, '') === heading,
-  );
-  if (start < 0) return '';
-  const level = headingLevel(lines[start]);
-  const end = lines.findIndex(
-    (line, index) => index > start
-      && headingLevel(line) > 0
-      && headingLevel(line) <= level,
-  );
-  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)) {
-    throw toolError(
-      'FRAMER_AGENT_PROJECT_INVALID',
-      'The Framer project identifier is missing or invalid.',
-    );
-  }
-  return projectId;
-}
-
-function projectIdFromUrl(url) {
-  const segments = url.pathname.split('/').filter(Boolean);
-  if (
-    segments.length !== 2
-    || segments[0]?.toLowerCase() !== 'projects'
-    || !segments[1]
-  ) return '';
-  try {
-    const projectId = decodeURIComponent(segments[1])
-      .match(PROJECT_SEGMENT_PATTERN)?.[1] || '';
-    return PROJECT_ID_PATTERN.test(projectId) ? projectId : '';
-  } catch {
-    return '';
-  }
-}
-
-function normalizeProjectUrl(value, expectedProjectId) {
-  let url;
-  try {
-    url = new URL(String(value || '').trim());
-  } catch {
-    throw toolError(
-      'FRAMER_AGENT_PROJECT_URL_INVALID',
-      'The exact Framer project URL is missing or invalid.',
-    );
-  }
-  if (
-    url.protocol !== 'https:'
-    || !FRAMER_PROJECT_HOST_PATTERN.test(url.hostname)
-    || url.username
-    || url.password
-  ) {
-    throw toolError(
-      'FRAMER_AGENT_PROJECT_URL_INVALID',
-      'The exact Framer project URL is missing or invalid.',
-    );
-  }
-  const projectId = projectIdFromUrl(url);
-  if (!projectId || projectId !== expectedProjectId) {
-    throw toolError(
-      'FRAMER_AGENT_PROJECT_MISMATCH',
-      'The Framer project URL does not match the project selected in Dexter.',
-      409,
-    );
-  }
-  url.hash = '';
-  return url.toString();
-}
-
-function normalizePagePath(value) {
-  const pagePath = String(value || '/').trim() || '/';
-  if (!PAGE_PATH_PATTERN.test(pagePath)) {
-    throw toolError(
-      'FRAMER_AGENT_PAGE_PATH_INVALID',
-      'The Framer page path must start with "/" and contain no control characters.',
-    );
-  }
-  return pagePath;
-}
-
-function normalizeCodeFilePath(value) {
-  const filePath = String(value || '').trim();
-  if (
-    !filePath
-    || filePath.length > 1_000
-    || /[\0\r\n]/.test(filePath)
-  ) {
-    throw toolError(
-      'FRAMER_CODE_FILE_PATH_INVALID',
-      'A valid Framer code-file path is required.',
-    );
-  }
-  return filePath;
-}
-
-function structuredResultError(result, fallbackCode, fallbackMessage) {
-  const error = isRecord(result?.error) ? result.error : {};
-  const code =
-    typeof error.code === 'string' && error.code.trim()
-      ? error.code.trim().slice(0, 120)
-      : fallbackCode;
-  const message =
-    typeof error.message === 'string' && error.message.trim()
-      ? error.message.trim().slice(0, 2_000)
-      : fallbackMessage;
-  const statusCode =
-    code === 'FRAMER_CODE_FILE_NOT_FOUND' || code === 'FRAMER_SVG_PARENT_NOT_FOUND'
-      ? 404
-      : code === 'FRAMER_CODE_FILE_VERSION_CONFLICT'
-        ? 409
-        : code === 'FRAMER_CODE_FILE_TOO_LARGE'
-          ? 413
-        : 400;
-  return toolError(code, message, statusCode);
-}
-
-function uniqueStrings(values, maximum = 500) {
-  return Array.from(
-    new Set(
-      values
-        .filter((value) => typeof value === 'string')
-        .map((value) => value.trim())
-        .filter(Boolean),
-    ),
-  ).slice(0, maximum);
-}
-
-function normalizeVerificationValues(values, allowed) {
-  return uniqueStrings(Array.isArray(values) ? values : [])
-    .filter((value) => allowed.includes(value));
-}
-
-function normalizeTaskPlan(rawArguments) {
-  const summary = String(rawArguments.summary || '').trim().slice(0, 1000);
-  const domains = normalizeVerificationValues(
-    rawArguments.domains,
-    TASK_DOMAINS,
-  );
-  const requestedVerification = normalizeVerificationValues(
-    rawArguments.verification,
-    VERIFICATION_CHECKS,
-  );
-  if (summary.length < 10 || domains.length === 0) {
-    throw toolError(
-      'FRAMER_HARNESS_PLAN_INVALID',
-      'Describe the understood task and declare at least one task domain.',
-    );
-  }
-  // The model's declared verification is authoritative; domains describe the
-  // work and never add checks on their own.
-  const verification = new Set(['structural', ...requestedVerification]);
-  const behaviorPlan = normalizeBehaviorPlan(rawArguments);
-  if (behaviorPlan.behaviors.length > 0) {
-    if (!domains.includes('interactions')) domains.push('interactions');
-    verification.add('interactions');
-  }
-  return {
-    summary,
-    domains,
-    verification: [...verification],
-    ...behaviorPlan,
-  };
-}
-
-function workingPreferencesFromAssignment(assignment) {
-  const context = isRecord(assignment?.context) ? assignment.context : {};
-  const grant = isRecord(context.contextGrant) ? context.contextGrant : {};
-  const supplied = isRecord(context.workingPreferences)
-    ? context.workingPreferences
-    : {};
-  const selectedNodeIds = uniqueStrings([
-    ...(Array.isArray(context.selectedNodeIds)
-      ? context.selectedNodeIds
-      : []),
-    ...(Array.isArray(grant.selectedNodeIds)
-      ? grant.selectedNodeIds
-      : []),
-  ]);
-  const selectionFirst =
-    supplied.focus === 'selection-first'
-    || (
-      selectedNodeIds.length > 0
-      && grant.writeScope === 'selection'
-    );
-  return {
-    mode: selectionFirst ? 'selection-first' : 'standard',
-    writeScope: String(
-      supplied.writeScope || grant.writeScope || 'none',
-    ).trim() || 'none',
-    selectionFirst,
-    preferBatchedMutations: supplied.preferBatchedMutations !== false,
-    avoidRepeatedInspection: supplied.avoidRepeatedInspection !== false,
-    expandScopeOnlyWhenNeeded:
-      supplied.expandScopeOnlyWhenNeeded !== false,
-  };
-}
-
-function toolDefinitionsForPreferences(requestedTools, preferences) {
-  return FRAMER_AGENT_TOOL_DEFINITIONS
-    .filter((tool) => requestedTools.has(tool.name))
-    .map((tool) => {
-      if (!preferences.selectionFirst) return tool;
-      if (tool.name === 'framer_context') {
-        return {
-          ...tool,
-          description:
-            'Read broad project context only when the selected subtree lacks a concrete dependency required for the request. Do not use this as the default first inspection.',
-        };
-      }
-      if (tool.name === 'framer_read_project') {
-        return {
-          ...tool,
-          description:
-            'Run supported Framer readProject queries, especially screenshots. For node-tree inspection, prefer framer_read with framer.agent.getNode({ id }), getNodes({ ids }), serialize, or other focused node APIs. Batch related queries when practical.',
-        };
-      }
-      if (tool.name === 'framer_apply_changes') {
-        return {
-          ...tool,
-          description:
-            'Apply related changes inside the authorized selection in coherent batches when practical. Read the returned diagnostics, verify the result, and make any further repair batches the work requires.',
-        };
-      }
-      if (tool.name === 'framer_read') {
-        return {
-          ...tool,
-          description:
-            'Use focused JavaScript for node-tree inspection and Framer capabilities not covered by readProject. Start with the selected nodes, reuse prior evidence, and expand only when a concrete dependency requires it.',
-        };
-      }
-      if (tool.name === 'framer_write') {
-        return {
-          ...tool,
-          description:
-            'Use project-scoped JavaScript only when framer_apply_changes cannot perform the required authorized capability. Explain that limitation in reason, prefer cohesive operations, and keep mutations within the authorized write scope. Do not retry JavaScript variants after a safety rejection.',
-        };
-      }
-      return tool;
-    });
-}
-
-function boundedStructuredValue(value, maximum = MAX_MODEL_RESULT_BYTES) {
-  let serialized;
-  try {
-    serialized = JSON.stringify(value);
-  } catch {
-    return {
-      truncated: true,
-      output: '[Framer result could not be serialized.]',
-    };
-  }
-  if (Buffer.byteLength(serialized, 'utf8') <= maximum) return value;
-  return {
-    truncated: true,
-    output: boundedText(serialized, maximum),
-  };
-}
-
-function authoritativeNodeIdsFromAssignment(assignment) {
-  const context = isRecord(assignment?.context) ? assignment.context : {};
-  const grant = isRecord(context.contextGrant) ? context.contextGrant : {};
-  return uniqueStrings([
-    ...(Array.isArray(context.selectedNodeIds)
-      ? context.selectedNodeIds
-      : []),
-    ...(Array.isArray(grant.selectedNodeIds)
-      ? grant.selectedNodeIds
-      : []),
-    ...(Array.isArray(grant.contextNodeIds)
-      ? grant.contextNodeIds
-      : []),
-    ...(Array.isArray(grant.writableNodeIds)
-      ? grant.writableNodeIds
-      : []),
-  ]);
-}
-
-const LITERAL_TOKEN_TYPES = new Set([
-  'StringLiteral',
-  'NoSubstitutionTemplate',
-  'TemplateHead',
-  'TemplateMiddle',
-  'TemplateTail',
-  'SingleLineComment',
-  'MultiLineComment',
-  'RegularExpressionLiteral',
-]);
-
-// Blanks string, template, comment, and regex text so data such as image URLs
-// or product copy is not mistaken for a forbidden global. Template
-// substitutions stay visible because they are code.
-function codeOutsideLiterals(code) {
-  let visible = '';
-  for (const token of jsTokens(code)) {
-    visible += LITERAL_TOKEN_TYPES.has(token.type) ? ' ' : token.value;
-  }
-  return visible;
-}
-
-function validateCode(value, { write = false, allowPublishing = false } = {}) {
-  const code = String(value || '').trim();
-  if (!code) {
-    throw toolError(
-      'FRAMER_AGENT_CODE_REQUIRED',
-      'Framer Agent code is required.',
-    );
-  }
-  if (UNSAFE_EXEC_PATTERN.test(codeOutsideLiterals(code))) {
-    throw toolError(
-      'FRAMER_AGENT_CODE_UNSAFE',
-      'Framer Agent code may use only the provided framer, state, and console globals.',
-    );
-  }
-  if (!write && MUTATING_EXEC_PATTERN.test(code)) {
-    throw toolError(
-      'FRAMER_AGENT_READ_ONLY_VIOLATION',
-      'Use framer_write or framer_apply_changes for project mutations.',
-    );
-  }
-  if (
-    !allowPublishing &&
-    /\.(?:publish|deploy)\s*\(/.test(code)
-  ) {
-    throw toolError(
-      'FRAMER_AGENT_PUBLISH_NOT_AUTHORIZED',
-      'Publishing is not authorized for this Dexter run.',
-    );
-  }
-  return code;
-}
-
-function normalizeSvgMarkup(value) {
-  const svg = String(value || '').trim();
-  if (!/^<svg\b[\s\S]*<\/svg>$/i.test(svg) || svg.length > MAX_SVG_MARKUP_CHARS) {
-    throw toolError(
-      'FRAMER_SVG_INVALID',
-      `Provide one <svg>…</svg> element of at most ${MAX_SVG_MARKUP_CHARS} characters.`,
-    );
-  }
-  if (UNSAFE_SVG_PATTERN.test(svg)) {
-    throw toolError(
-      'FRAMER_SVG_UNSAFE',
-      'SVG markup must be self-contained: no scripts, event handlers, foreignObject, or external references.',
-    );
-  }
-  return svg;
-}
-
-function normalizeSvgAttributes(value) {
-  if (value === undefined) return {};
-  if (!isRecord(value) || Object.keys(value).length > MAX_SVG_ATTRIBUTES) {
-    throw toolError(
-      'FRAMER_SVG_ATTRIBUTES_INVALID',
-      `attributes must be an object with at most ${MAX_SVG_ATTRIBUTES} Framer layer attributes.`,
-    );
-  }
-  const { svg: _ignored, ...attributes } = value;
-  return attributes;
-}
-
-function extractJsonArray(value) {
-  const text = String(value || '').trim();
-  const start = text.indexOf('[');
-  const end = text.lastIndexOf(']');
-  if (start < 0 || end <= start) return [];
-  try {
-    const parsed = JSON.parse(text.slice(start, end + 1));
-    return Array.isArray(parsed) ? parsed : [];
-  } catch {
-    return [];
-  }
-}
-
-function abortError() {
-  return Object.assign(new Error('The Framer authorization was cancelled.'), {
-    name: 'AbortError',
-    code: 'ABORT_ERR',
-  });
-}
-
-function isFramerScreenshotUrl(value) {
-  try {
-    const url = new URL(String(value || ''));
-    return url.protocol === 'https:'
-      && (url.hostname === 'framerusercontent.com'
-        || url.hostname.endsWith('.framerusercontent.com'));
-  } catch {
-    return false;
-  }
-}
-
-function screenshotQueries(rawArguments) {
-  return (Array.isArray(rawArguments?.queries) ? rawArguments.queries : [])
-    .filter((query) => query?.type === 'screenshot')
-    .slice(0, MAX_SCREENSHOTS_PER_CALL);
-}
-
-// Screenshot results are URLs the model cannot open, so the bridge downloads
-// them and hands the pixels to the model as image content. Failures carry a
-// short reason so delivery problems are visible in run telemetry.
-async function downloadScreenshotImage(url, fetchImpl) {
-  if (!isFramerScreenshotUrl(url)) return { error: 'untrusted_url' };
-  try {
-    const response = await fetchImpl(url, {
-      signal: AbortSignal.timeout(SCREENSHOT_FETCH_TIMEOUT_MS),
-    });
-    if (!response.ok) return { error: `http_${response.status}` };
-    const mimeType = String(response.headers.get('content-type') || '')
-      .split(';')[0]
-      .trim()
-      .toLowerCase();
-    if (!SCREENSHOT_MIME_TYPES.has(mimeType)) return { error: 'unsupported_type' };
-    const bytes = Buffer.from(await response.arrayBuffer());
-    if (!bytes.length) return { error: 'empty' };
-    if (bytes.length > MAX_SCREENSHOT_BYTES) return { error: 'too_large' };
-    return { image: { url, mimeType, data: bytes.toString('base64') } };
-  } catch (error) {
-    return {
-      error: String(error?.cause?.code || error?.name || 'fetch_failed').slice(0, 60),
-    };
-  }
-}
-
-function parseStructuredOutput(value) {
-  const text = String(value || '').trim();
-  if (!text) return null;
-  const candidates = [text];
-  const firstObject = text.indexOf('{');
-  const lastObject = text.lastIndexOf('}');
-  if (firstObject >= 0 && lastObject > firstObject) {
-    candidates.push(text.slice(firstObject, lastObject + 1));
-  }
-  const firstArray = text.indexOf('[');
-  const lastArray = text.lastIndexOf(']');
-  if (firstArray >= 0 && lastArray > firstArray) {
-    candidates.push(text.slice(firstArray, lastArray + 1));
-  }
-  for (const candidate of candidates) {
-    try {
-      return JSON.parse(candidate);
-    } catch {
-      // Keep the original text when the command intentionally prints prose.
-    }
-  }
-  return null;
-}
-
-function parseBranchChange(value) {
-  const match = String(value || '').match(
-    /\[FRAMER_BRANCH_CHANGE\]\s+title="([^"]*)"\s+id="([^"]*)"\s+url="([^"]*)"/,
-  );
-  return match
-    ? { title: match[1], id: match[2], url: match[3] }
-    : null;
-}
-
-export function resolveFramerAgentCli() {
-  try {
-    return require.resolve('@framer/agent');
-  } catch {
-    throw toolError(
-      'FRAMER_AGENT_NOT_INSTALLED',
-      'The official Framer Agent runtime is missing. Update Dexter Bridge and reconnect.',
-      503,
-    );
-  }
-}
-
-export function runFramerAgentCli(args, {
-  cwd = process.cwd(),
-  env = process.env,
-  input,
-  signal,
-  timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS,
-  onOutput,
-  cliPath = resolveFramerAgentCli(),
-} = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [cliPath, ...args], {
-      cwd,
-      env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-      signal,
-    });
-    let stdout = '';
-    let stderr = '';
-    let outputBytes = 0;
-    let settled = false;
-    let timer;
-    const finish = (callback, value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      callback(value);
-    };
-    const append = (channel, chunk) => {
-      const text = chunk.toString('utf8');
-      outputBytes += Buffer.byteLength(text, 'utf8');
-      if (outputBytes > MAX_OUTPUT_BYTES) {
-        child.kill('SIGTERM');
-        finish(
-          reject,
-          toolError(
-            'FRAMER_AGENT_OUTPUT_TOO_LARGE',
-            'The Framer Agent command returned too much output.',
-          ),
-        );
-        return;
-      }
-      if (channel === 'stdout') stdout += text;
-      else stderr += text;
-      onOutput?.({ channel, text });
-    };
-    child.stdout.on('data', (chunk) => append('stdout', chunk));
-    child.stderr.on('data', (chunk) => append('stderr', chunk));
-    child.once('error', (error) => finish(reject, error));
-    child.once('close', (code, signal) => {
-      if (settled) return;
-      if (code === 0) {
-        finish(resolve, {
-          stdout: boundedText(stdout, MAX_OUTPUT_BYTES),
-          stderr: boundedText(stderr, MAX_OUTPUT_BYTES),
-          code,
-          signal,
-        });
-        return;
-      }
-      const message = boundedText(stderr || stdout, 8_000).trim();
-      finish(
-        reject,
-        toolError(
-          /authoriz|log in|login|api key/i.test(message)
-            ? 'FRAMER_AGENT_AUTHORIZATION_REQUIRED'
-            : 'FRAMER_AGENT_COMMAND_FAILED',
-          message || `Framer Agent exited with code ${code}.`,
-          /authoriz|log in|login|api key/i.test(message) ? 409 : 500,
-        ),
-      );
-    });
-    timer = setTimeout(() => {
-      child.kill('SIGTERM');
-      finish(
-        reject,
-        toolError(
-          'FRAMER_AGENT_TIMEOUT',
-          'The Framer Agent command timed out.',
-          504,
-        ),
-      );
-    }, Math.max(1_000, Number(timeoutMs) || DEFAULT_COMMAND_TIMEOUT_MS));
-    timer.unref?.();
-    if (input !== undefined) child.stdin.end(String(input));
-    else child.stdin.end();
-  });
-}
-
-function sessionIdFromOutput(value) {
-  return String(value || '')
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .find(
-      (line) =>
-        line &&
-        !line.startsWith('[') &&
-        !/^framer external agents/i.test(line) &&
-        /^[A-Za-z0-9_-]{4,200}$/.test(line),
-    ) || null;
-}
-
-function isAuthorizationFailure(error) {
-  return (
-    error?.code === 'FRAMER_AGENT_AUTHORIZATION_REQUIRED'
-    || /authoriz|log in|login|api key|does not have access|session expired/i.test(
-      String(error?.message || ''),
-    )
-  );
-}
-
-function projectConnectionError(error) {
-  if (/project not found/i.test(String(error?.message || ''))) {
-    return toolError(
-      'FRAMER_AGENT_PROJECT_NOT_FOUND',
-      'The project key passed Server API verification, but Framer Agent could not find the authoritative project ID. Reopen the project in Framer, reconnect it in Dexter, and try again.',
-      409,
-    );
-  }
-  if (isAuthorizationFailure(error)) {
-    return toolError(
-      'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
-      'The project key passed Server API verification, but Framer Agent rejected it while creating the editing session. Reconnect the open project in Dexter with a current key from General → API Keys, then try again.',
-      409,
-    );
-  }
-  return error;
-}
-
-export function createFramerAgentToolRuntime({
-  assignment,
-  cwd,
-  env = process.env,
-  trace,
-  onActivity,
-  runCli = runFramerAgentCli,
-  fetchImpl = fetch,
-  authorizeProject,
-  verifyProjectAuthorization,
-  readWebsite,
-} = {}) {
-  const projectId = normalizeProjectId(assignment?.context?.framerProjectId);
-  const projectUrl = normalizeProjectUrl(
-    assignment?.context?.framerProjectUrl,
-    projectId,
-  );
-  const sessionCacheKey = projectId;
-  const requestedTools = Array.isArray(assignment?.toolProtocol?.tools)
-    ? assignment.toolProtocol.tools
-    : FRAMER_AGENT_TOOL_DEFINITIONS.map((tool) => tool.name);
-  const allowedToolNames = new Set(
-    requestedTools.filter((name) => TOOL_BY_NAME.has(name)),
-  );
-  const workingPreferences = workingPreferencesFromAssignment(assignment);
-  const definitions = toolDefinitionsForPreferences(
-    allowedToolNames,
-    workingPreferences,
-  );
-  const exposedToolNames = new Set(
-    definitions.map((definition) => definition.name),
-  );
-  const missingToolNames = uniqueStrings(requestedTools)
-    .filter((name) => !exposedToolNames.has(name));
-  if (missingToolNames.length > 0) {
-    throw toolError(
-      'FRAMER_HARNESS_TOOL_CATALOG_INCOMPLETE',
-      `Dexter could not start because this bridge does not expose the required Framer tools: ${missingToolNames.join(', ')}.`,
-      500,
-    );
-  }
-  const allowPublishing = assignment?.context?.permissions?.publish === true;
-  const activePagePath = normalizePagePath(
-    assignment?.context?.activePagePath,
-  );
-  const authoritativeNodeIds =
-    authoritativeNodeIdsFromAssignment(assignment);
-  let sessionId = null;
-  let sessionPromise = null;
-  let nodeValidationPromise = null;
-  let server = null;
-  let gateway = null;
-  let closed = false;
-  let serial = Promise.resolve();
-  let mutationCalls = 0;
-  let applyChangesCalls = 0;
-  let lowLevelWriteCalls = 0;
-  let imageSearchCalls = 0;
-  let readCalls = 0;
-  let toolCallCount = 0;
-  const toolCalls = [];
-  let repeatedFailureFingerprint = null;
-  let repeatedFailureCount = 0;
-  let repeatedFailureStops = 0;
-  let unsafeWriteFailures = 0;
-  let lowLevelWriteFailures = 0;
-  let lowLevelWriteDisabled = false;
-  let lowLevelWriteBlockedCalls = 0;
-  let instructionFallbacks = 0;
-  let fontSearchFallbacks = 0;
-  let instructionLookupUnavailable = false;
-  let branchChange = null;
-  let lastInspectionAt = null;
-  let lastMutationAt = null;
-  let screenshotCalls = 0;
-  let interactionVerificationCalls = 0;
-  // Latest result per behavior/node/property, with the operation sequence it
-  // was observed at, so checks from several calls (or pages) accumulate.
-  const interactionCheckResults = new Map();
-  let interactionVerifiedAt = null;
-  const mutationReceipts = [];
-  let lastScreenshotSequence = 0;
-  let lastScreenshotAttemptSequence = 0;
-  let screenshotsViaDownload = 0;
-  let screenshotsViaSession = 0;
-  let screenshotsUndelivered = 0;
-  const screenshotFailures = [];
-  let taskPlan = null;
-  const verificationEvidence = new Map();
-  let guideCatalog = new Map();
-  const guidesRead = [];
-  let guidanceMetadata = {
-    loaded: false,
-    contentHash: null,
-    projectContextHash: null,
-    files: [],
-    bytes: 0,
-  };
-  let promptMetadata = {
-    promptBytes: 0,
-    doctrineLoaded: false,
-    doctrineVersion: null,
-  };
-  let framerSetupAttempts = 0;
-  let framerSetupRecoveredSession = false;
-  let framerSetupCompleted = hasInstalledFramerSkill(env);
-  const framerAgentVersion = installedFramerAgentVersion();
-  let operationSequence = 0;
-  let lastMutationSequence = 0;
-  let lastCodeMutationSequence = 0;
-  let lastInspectionSequence = 0;
-  const abortController = new AbortController();
-
-  const reportActivity = (event) => {
-    try {
-      void Promise.resolve(onActivity?.(event)).catch(() => undefined);
-    } catch {
-      // Observability must never interrupt a Framer operation.
-    }
-  };
-
-  const executeCli = async (args, options = {}) => {
-    const result = await runCli(args, {
-      cwd,
-      env,
-      signal: abortController.signal,
-      ...options,
-    });
-    const nextBranch = parseBranchChange(result.stdout);
-    if (nextBranch) branchChange = nextBranch;
-    return result;
-  };
-
-  const ensureFramerSetup = async ({ force = false } = {}) => {
-    const automaticSetupEnabled =
-      runCli === runFramerAgentCli
-      || env.DEXTER_FRAMER_AUTO_SETUP === 'true';
-    if (!force && !automaticSetupEnabled) return;
-    if (!force && hasInstalledFramerSkill(env)) {
-      framerSetupCompleted = true;
-      return;
-    }
-    if (!framerSetupPromise) {
-      framerSetupAttempts += 1;
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message: 'Getting Framer ready.',
-      });
-      framerSetupPromise = executeCli(['setup'], {
-        timeoutMs: 30_000,
-      })
-        .then(() => {
-          if (!hasInstalledFramerSkill(env)) {
-            throw toolError(
-              'FRAMER_AGENT_SETUP_FAILED',
-              'Framer setup completed without installing the required Framer skill.',
-              503,
-            );
-          }
-          framerSetupCompleted = true;
-        })
-        .catch((error) => {
-          if (error?.code === 'FRAMER_AGENT_SETUP_FAILED') throw error;
-          throw toolError(
-            'FRAMER_AGENT_SETUP_FAILED',
-            `Dexter could not prepare the Framer editing tools: ${String(error?.message || 'Framer setup failed.')}`,
-            503,
-          );
-        })
-        .finally(() => {
-          framerSetupPromise = null;
-        });
-    }
-    await framerSetupPromise;
-    framerSetupCompleted = hasInstalledFramerSkill(env);
-  };
-
-  const projectIsAuthorizedLocally = async () => {
-    const listed = await executeCli(['project', 'list'], {
-      timeoutMs: 30_000,
-    }).catch(() => ({ stdout: '[]', stderr: '' }));
-    return extractJsonArray(listed.stdout).some(
-      (item) => isRecord(item) && item.projectId === projectId,
-    );
-  };
-
-  const resolveProjectAuthorization = async () => {
-    if (typeof authorizeProject !== 'function') {
-      throw toolError(
-        'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
-        'This Framer project needs to be connected before Dexter can use it.',
-        409,
-      );
-    }
-    let authorization = await authorizeProject({
-      projectId,
-      initiate: true,
-      forceRefresh: false,
-      signal: abortController.signal,
-    });
-    if (authorization?.framerProjectId !== projectId) {
-      throw toolError(
-        'FRAMER_AGENT_PROJECT_MISMATCH',
-        'Dexter received authorization for a different Framer project.',
-        409,
-      );
-    }
-    if (authorization?.status === 'authorization_required') {
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message:
-          'This Framer project needs a project API key before Dexter can continue.',
-      });
-      throw toolError(
-        'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
-        'Connect this Framer project in Dexter by adding a project API key, then retry.',
-        409,
-      );
-    }
-    const apiKey = String(authorization?.apiKey || '').trim();
-    if (authorization?.status !== 'ready' || !apiKey) {
-      throw toolError(
-        'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
-        'Framer project authorization was not completed. Reconnect this project in Dexter and try again.',
-        409,
-      );
-    }
-    const authorizedProjectUrl = normalizeProjectUrl(
-      authorization.framerProjectUrl,
-      projectId,
-    );
-    return { ...authorization, apiKey, framerProjectUrl: authorizedProjectUrl };
-  };
-
-  const installProjectAuthorization = async (authorization) => {
-    await executeCli(['project', 'auth', projectId, authorization.apiKey], {
-      timeoutMs: 30_000,
-    });
-    reportActivity({
-      kind: 'status_update',
-      source: 'framer-agent',
-      message: 'This Framer project is authorized for the coding harness.',
-    });
-  };
-
-  const createSession = async () => {
-    return executeCli(['session', 'new', projectId], {
-      timeoutMs: SESSION_TIMEOUT_MS,
-    });
-  };
-
-  const reportRejectedAuthorization = async (authorization, error) => {
-    if (
-      typeof verifyProjectAuthorization !== 'function'
-      || !authorization?.credentialVersion
-    ) return;
-    await verifyProjectAuthorization({
-      status: 'rejected',
-      framerProjectId: projectId,
-      framerProjectUrl: projectUrl,
-      credentialVersion: authorization.credentialVersion,
-      errorCode: String(error?.code || 'FRAMER_AGENT_AUTHORIZATION_REJECTED')
-        .slice(0, 120),
-      signal: abortController.signal,
-    }).catch(() => undefined);
-  };
-
-  const verifyConnectedProject = async (activeSessionId, authorization) => {
-    const result = await executeCli(['exec', '-s', activeSessionId], {
-      input: [
-        'const [project, branch] = await Promise.all([',
-        '  framer.getProjectInfo(),',
-        '  framer.agent.getActiveBranch(),',
-        ']);',
-        'console.log(JSON.stringify({ projectName: project?.name ?? null, projectUrl: branch?.url ?? null }));',
-      ].join('\n'),
-      timeoutMs: 30_000,
-    });
-    const observed = parseStructuredOutput(result.stdout);
-    const observedProjectUrl = normalizeProjectUrl(
-      observed?.projectUrl,
-      projectId,
-    );
-    if (
-      typeof verifyProjectAuthorization === 'function'
-      && authorization?.credentialVersion
-    ) {
-      await verifyProjectAuthorization({
-        status: 'verified',
-        framerProjectId: projectId,
-        framerProjectUrl: observedProjectUrl,
-        credentialVersion: authorization.credentialVersion,
-        signal: abortController.signal,
-      });
-    }
-  };
-
-  const ensureSession = async () => {
-    await ensureFramerSetup();
-    if (sessionId) return sessionId;
-    if (sessionPromise) return sessionPromise;
-    sessionPromise = (async () => {
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message: 'Connecting the coding harness to this Framer project.',
-      });
-      let authorization = null;
-      if (typeof authorizeProject === 'function') {
-        authorization = await resolveProjectAuthorization();
-      }
-
-      const cached = sessionsByProject.get(sessionCacheKey);
-      if (
-        cached
-        && (
-          typeof authorizeProject !== 'function'
-          || (
-            authorization?.verificationStatus === 'verified'
-            && cached.credentialVersion === authorization.credentialVersion
-          )
-        )
-      ) {
-        sessionId = cached.sessionId;
-        return sessionId;
-      }
-      if (cached) {
-        await executeCli(['session', 'destroy', cached.sessionId], {
-          timeoutMs: 10_000,
-        }).catch(() => undefined);
-        sessionsByProject.delete(sessionCacheKey);
-      }
-      if (!authorization && !(await projectIsAuthorizedLocally())) {
-        throw toolError(
-          'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
-          'This Framer project needs to be connected before Dexter can use it.',
-          409,
-        );
-      }
-      let created;
-      try {
-        if (authorization) {
-          await installProjectAuthorization(authorization);
-        }
-        try {
-          created = await createSession();
-        } catch (error) {
-          if (!isMissingFramerSkillError(error)) throw error;
-          await ensureFramerSetup({ force: true });
-          created = await createSession();
-          framerSetupRecoveredSession = true;
-        }
-      } catch (error) {
-        if (isAuthorizationFailure(error)) {
-          await reportRejectedAuthorization(authorization, error);
-        }
-        throw projectConnectionError(error);
-      }
-      sessionId = sessionIdFromOutput(created.stdout);
-      if (!sessionId) {
-        const refreshed = await executeCli(['session', 'list'], {
-          timeoutMs: 10_000,
-        }).catch(() => ({ stdout: '[]', stderr: '' }));
-        const connected = extractJsonArray(refreshed.stdout).find(
-          (item) => isRecord(item) && item.projectId === projectId && item.id,
-        );
-        sessionId = connected?.id ? String(connected.id) : null;
-      }
-      if (!sessionId) {
-        throw toolError(
-          'FRAMER_AGENT_SESSION_UNAVAILABLE',
-          'Framer Agent connected but did not return a usable project session.',
-          503,
-        );
-      }
-      try {
-        await verifyConnectedProject(sessionId, authorization);
-      } catch (error) {
-        await executeCli(['session', 'destroy', sessionId], {
-          timeoutMs: 10_000,
-        }).catch(() => undefined);
-        sessionId = null;
-        if (
-          isAuthorizationFailure(error)
-          || error?.code === 'FRAMER_AGENT_PROJECT_MISMATCH'
-        ) {
-          await reportRejectedAuthorization(authorization, error);
-        }
-        throw projectConnectionError(error);
-      }
-      sessionsByProject.set(sessionCacheKey, {
-        sessionId,
-        credentialVersion: authorization?.credentialVersion || null,
-      });
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message: 'The coding harness is connected to the Framer canvas.',
-      });
-      return sessionId;
-    })().finally(() => {
-      sessionPromise = null;
-    });
-    return sessionPromise;
-  };
-
-  const loadProjectGuidance = async () => {
-    await ensureSession();
-    const skillRoot = framerSkillRoot(env);
-    if (!skillRoot) return { content: '', ...guidanceMetadata };
-    const projectRoot = path.join(skillRoot, 'projects', projectId);
-    if (!fs.existsSync(projectRoot)) {
-      return { content: '', ...guidanceMetadata };
-    }
-    // Every run gets the guidance an edit always needs: principles, command
-    // syntax, tool APIs, scope and replica rules, and the edit loop. Topic
-    // guides (CMS, components, creation strategy, examples, ...) are listed
-    // in a catalog and read on demand through framer_instructions. The CLI,
-    // session, and file-map parts of SKILL.md and index.md do not apply to
-    // Dexter's tools, and index.md changes every session, so both are left
-    // out; the guidance stays byte-identical across runs and can be cached.
-    // The project inventory changes with the project and is returned apart.
-    const requestedFiles = [
-      {
-        root: skillRoot,
-        path: 'SKILL.md',
-        section: 'Method Selection',
-        label: 'SKILL.md#Method Selection',
-      },
-      {
-        root: skillRoot,
-        path: 'SKILL.md',
-        section: 'Core Usage Principles',
-        label: 'SKILL.md#Core Usage Principles',
-      },
-      { root: projectRoot, path: 'prompt/overview.md' },
-      { root: projectRoot, path: 'prompt/core-principles.md' },
-      { root: projectRoot, path: 'prompt/guardrails.md' },
-      { root: projectRoot, path: 'prompt/critical-reminders.md' },
-      { root: projectRoot, path: 'prompt/design-rules.md' },
-      { root: projectRoot, path: 'prompt/updating-the-project.md' },
-      { root: projectRoot, path: 'prompt/tools.md' },
-      ...CORE_GUIDE_SECTIONS.map(({ file, section }) => ({
-        root: projectRoot,
-        path: `prompt/${file}.md`,
-        section,
-        label: `prompt/${file}.md#${section}`,
-      })),
-    ];
-    const files = [];
-    let remainingBytes = MAX_GUIDANCE_BYTES;
-    for (const requestedFile of requestedFiles) {
-      const loaded = readGuidanceFile(
-        requestedFile.root,
-        requestedFile.path,
-        remainingBytes,
-        requestedFile.section,
-      );
-      if (!loaded) continue;
-      files.push({
-        ...loaded,
-        path: requestedFile.label || requestedFile.path,
-      });
-      remainingBytes -= Buffer.byteLength(loaded.content, 'utf8');
-      if (remainingBytes <= 0) break;
-    }
-    guideCatalog = onDemandGuideCatalog(projectRoot);
-    const catalogText = guideCatalog.size > 0
-      ? [
-          '## On-demand guides',
-          '',
-          'Read a guide with framer_instructions({ guides: [id] }) before work that depends on it.',
-          ...[...guideCatalog.keys()].map((id) => `- ${id}`),
-        ].join('\n')
-      : '';
-    const content = [
-      ...files.map((file) => `## ${file.path}\n\n${file.content}`),
-      ...(catalogText ? [catalogText] : []),
-    ].join('\n\n');
-    const inventory = readGuidanceFile(
-      projectRoot,
-      'project-inventory.md',
-      MAX_GUIDANCE_FILE_BYTES,
-    )?.content || '';
-    guidanceMetadata = {
-      loaded: Boolean(content),
-      contentHash: content
-        ? crypto.createHash('sha256').update(content).digest('hex')
-        : null,
-      projectContextHash: inventory
-        ? crypto.createHash('sha256').update(inventory).digest('hex')
-        : null,
-      files: [
-        ...files.map((file) => file.path),
-        ...(inventory ? ['project/project-inventory.md'] : []),
-      ],
-      bytes: Buffer.byteLength(content + inventory, 'utf8'),
-    };
-    return { content, inventory, ...guidanceMetadata };
-  };
-
-  const configurePromptContext = ({
-    doctrineLoaded = false,
-    doctrineVersion = null,
-    promptBytes = 0,
-  } = {}) => {
-    promptMetadata = {
-      promptBytes: Math.max(0, Number(promptBytes) || 0),
-      doctrineLoaded: doctrineLoaded === true,
-      doctrineVersion:
-        typeof doctrineVersion === 'string' && doctrineVersion.trim()
-          ? doctrineVersion.trim().slice(0, 160)
-          : null,
-    };
-  };
-
-  const execCode = async (code, { timeoutMs } = {}) => {
-    let activeSessionId = await ensureSession();
-    try {
-      return await executeCli(['exec', '-s', activeSessionId], {
-        input: code,
-        timeoutMs,
-      });
-    } catch (error) {
-      if (
-        error?.code !== 'FRAMER_AGENT_COMMAND_FAILED'
-        || !/session|connection|not found|closed|expired/i.test(
-          String(error?.message || ''),
-        )
-      ) {
-        throw error;
-      }
-      sessionsByProject.delete(sessionCacheKey);
-      sessionId = null;
-      activeSessionId = await ensureSession();
-      return executeCli(['exec', '-s', activeSessionId], {
-        input: code,
-        timeoutMs,
-      });
-    }
-  };
-
-  // Captures a node through the Framer session itself. This needs no access
-  // to the screenshot CDN, so it works where that download is blocked.
-  const captureSessionScreenshot = async (nodeId) => {
-    for (const scale of [1, 0.5]) {
-      try {
-        const result = await execCode(
-          [
-            `const shot = await framer.screenshot(${JSON.stringify(nodeId)}, { format: 'jpeg', quality: 80, scale: ${scale} });`,
-            'console.log(JSON.stringify({ mimeType: shot.mimeType, data: Buffer.from(shot.data).toString("base64") }));',
-          ].join('\n'),
-          { timeoutMs: SESSION_SCREENSHOT_TIMEOUT_MS },
-        );
-        const parsed = parseStructuredOutput(result.stdout);
-        const mimeType = String(parsed?.mimeType || '').toLowerCase();
-        const data = typeof parsed?.data === 'string' ? parsed.data : '';
-        if (!SCREENSHOT_MIME_TYPES.has(mimeType)) return { error: 'unsupported_type' };
-        const bytes = Buffer.from(data, 'base64').length;
-        if (!bytes) return { error: 'empty' };
-        if (bytes > MAX_SCREENSHOT_BYTES) return { error: 'too_large' };
-        return { image: { url: null, mimeType, data } };
-      } catch (error) {
-        if (error?.code === 'FRAMER_AGENT_OUTPUT_TOO_LARGE' && scale === 1) continue;
-        return { error: String(error?.code || 'capture_failed').slice(0, 60) };
-      }
-    }
-    return { error: 'too_large' };
-  };
-
-  const deliverScreenshots = async (queries, parsed) => {
-    const results = (Array.isArray(parsed?.results) ? parsed.results : [])
-      .filter((entry) => typeof entry?.image_url === 'string');
-    const images = [];
-    const failures = [];
-    let viaDownload = 0;
-    let viaSession = 0;
-    let undelivered = 0;
-    for (const [index, query] of queries.entries()) {
-      const nodeId = typeof query.id === 'string' ? query.id.trim() : '';
-      const entry =
-        (nodeId && results.find((candidate) => candidate.id === nodeId))
-        || results[index];
-      const downloaded = entry
-        ? await downloadScreenshotImage(entry.image_url, fetchImpl)
-        : { error: 'no_image_url' };
-      if (downloaded.image) {
-        images.push(downloaded.image);
-        viaDownload += 1;
-        continue;
-      }
-      const captured = nodeId
-        ? await captureSessionScreenshot(nodeId)
-        : { error: 'no_node_id' };
-      if (captured.image) {
-        images.push(captured.image);
-        viaSession += 1;
-        failures.push({
-          target: nodeId,
-          download: downloaded.error,
-          recoveredVia: 'session',
-        });
-        continue;
-      }
-      undelivered += 1;
-      failures.push({
-        target: nodeId || 'url',
-        download: downloaded.error,
-        capture: captured.error,
-      });
-    }
-    screenshotsViaDownload += viaDownload;
-    screenshotsViaSession += viaSession;
-    screenshotsUndelivered += undelivered;
-    screenshotFailures.push(...failures);
-    screenshotFailures.splice(
-      0,
-      Math.max(0, screenshotFailures.length - MAX_SCREENSHOT_FAILURES_REPORTED),
-    );
-    return images;
-  };
-
-  const readProject = (queries, pagePath) => execCode(
-    [
-      `const result = await framer.agent.readProject(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });`,
-      'console.log(JSON.stringify(result, null, 2));',
-    ].join('\n'),
-  );
-
-  // Runs readProject screenshot queries and hands the pixels to the model.
-  const readScreenshots = async (queries, pagePath) => {
-    const result = await readProject(queries, pagePath);
-    return deliverScreenshots(queries, parseStructuredOutput(result.stdout));
-  };
-
-  // Framer bills style font searches to the workspace's AI credit and fails
-  // the whole read when they cannot run. Those searches are then answered
-  // from the Google Fonts catalog and the remaining queries are read again.
-  // Returns null when there is nothing to answer, so the original error stands.
-  const readProjectWithFontFallback = async (queries, pagePath) => {
-    try {
-      return await readProject(queries, pagePath);
-    } catch (error) {
-      const styleSearch = (query) =>
-        query.type === 'font-search' && typeof query.query === 'string';
-      if (!queries.some(styleSearch)) throw error;
-      let catalog;
-      try {
-        catalog = await loadGoogleFontsCatalog(fetchImpl);
-      } catch (catalogError) {
-        trace?.warn?.('google_fonts_fallback_unavailable', {
-          message: catalogError?.message,
-        });
-        throw error;
-      }
-      const remaining = queries.filter((query) => !styleSearch(query));
-      const remainingResults = remaining.length
-        ? parseStructuredOutput((await readProject(remaining, pagePath)).stdout)?.results || []
-        : [];
-      fontSearchFallbacks += 1;
-      trace?.warn?.('framer_font_search_fallback', {
-        message: boundedText(String(error?.message || ''), 300),
-      });
-      const reason = boundedText(String(error?.message || 'unavailable'), 160);
-      let next = 0;
-      return {
-        stdout: JSON.stringify({
-          results: queries.map((query) => (styleSearch(query)
-            ? {
-                type: 'font-search',
-                source: 'google-fonts',
-                note: `Framer's style font search failed (${reason}), so these candidates come from the Google Fonts library, which Framer includes. Choose by how the family looks, set fontName to it, and use a listed weight. If you know a Google Fonts family that fits better, confirm it with a font-search by name.`,
-                results: searchGoogleFonts(catalog, query),
-              }
-            : remainingResults[next++] ?? null)),
-        }),
-        stderr: '',
-      };
-    }
-  };
-
-  const referenceAssetFiles = Array.isArray(assignment?.context?.referenceAssetFiles)
-    ? assignment.context.referenceAssetFiles
-    : [];
-  const uploadedAttachments = new Map();
-  const uploadAttachment = async (attachmentId) => {
-    const file = referenceAssetFiles.find((candidate) => candidate?.id === attachmentId);
-    if (!file) {
-      throw toolError(
-        'FRAMER_ATTACHMENT_NOT_FOUND',
-        `No user attachment "${attachmentId}" is available in this run. Use an id from context.referenceAssetFiles.`,
-      );
-    }
-    const cached = uploadedAttachments.get(attachmentId);
-    if (cached) return cached;
-    const root = path.resolve(cwd || '.');
-    const filePath = path.resolve(root, String(file.path || ''));
-    if (!filePath.startsWith(`${root}${path.sep}`) || !fs.existsSync(filePath)) {
-      throw toolError(
-        'FRAMER_ATTACHMENT_NOT_FOUND',
-        `The attachment "${attachmentId}" is no longer available on this computer.`,
-      );
-    }
-    const dataUrl = `data:${file.mimeType || 'image/png'};base64,${fs.readFileSync(filePath).toString('base64')}`;
-    const result = await execCode(
-      [
-        `const asset = await framer.uploadImage({ image: ${JSON.stringify(dataUrl)} });`,
-        `console.log(JSON.stringify({ attachmentId: ${JSON.stringify(attachmentId)}, url: asset.url, thumbnailUrl: asset.thumbnailUrl }));`,
-      ].join('\n'),
-      { timeoutMs: 60_000 },
-    );
-    uploadedAttachments.set(attachmentId, result);
-    return result;
-  };
-
-  // Selected layers that do not resolve to native nodes (stale selections,
-  // aliases, layers inside component instances) no longer stop the run. The
-  // model is told which targets to locate by name, and the reason is kept for
-  // debugging.
-  let unresolvedTargets = [];
-  const validateAuthoritativeNodeIds = async () => {
-    await ensureSession();
-    if (authoritativeNodeIds.length === 0) return { unresolvedTargets };
-    if (nodeValidationPromise) return nodeValidationPromise;
-    nodeValidationPromise = (async () => {
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message: 'Validating the selected Framer layers.',
-      });
-      const result = await execCode(
-        [
-          `const requestedIds = ${JSON.stringify(authoritativeNodeIds)};`,
-          'const resolved = await Promise.all(requestedIds.map(async (requestedId) => {',
-          '  try {',
-          '    const node = await framer.agent.getNode({ id: requestedId },',
-          `      { pagePath: ${JSON.stringify(activePagePath)} });`,
-          '    return { requestedId, resolvedId: node?.id ?? null, error: node ? null : "not found on the active page" };',
-          '  } catch (error) {',
-          '    return { requestedId, resolvedId: null, error: String(error?.message || error).slice(0, 200) };',
-          '  }',
-          '}));',
-          'console.log(JSON.stringify({ resolved }));',
-        ].join('\n'),
-        { timeoutMs: 30_000 },
-      );
-      const parsed = parseStructuredOutput(result.stdout);
-      const resolved = Array.isArray(parsed?.resolved)
-        ? parsed.resolved
-        : [];
-      unresolvedTargets = authoritativeNodeIds.flatMap((requestedId) => {
-        const match = resolved.find(
-          (entry) =>
-            isRecord(entry)
-            && entry.requestedId === requestedId,
-        );
-        if (match?.resolvedId === requestedId) return [];
-        return [{
-          id: requestedId,
-          reason: !match
-            ? 'not checked'
-            : match.resolvedId
-              ? `resolves to ${match.resolvedId}`
-              : String(match.error || 'not found on the active page'),
-        }];
-      });
-      reportActivity({
-        kind: 'status_update',
-        source: 'framer-agent',
-        message: unresolvedTargets.length > 0
-          ? 'Some selected layers could not be matched exactly, so Dexter will locate them by name.'
-          : 'The selected Framer layers are ready.',
-      });
-      return { unresolvedTargets };
-    })().catch((error) => {
-      nodeValidationPromise = null;
-      throw error;
-    });
-    return nodeValidationPromise;
-  };
-
-  const normalizedResult = (result) => {
-    const parsed = parseStructuredOutput(result.stdout);
-    return {
-      ...(parsed === null
-        ? { output: boundedText(result.stdout, MAX_MODEL_RESULT_BYTES) }
-        : { result: boundedStructuredValue(parsed) }),
-      ...(result.stderr.trim()
-        ? { diagnostics: boundedText(result.stderr, 20_000) }
-        : {}),
-      ...(branchChange ? { branch: branchChange } : {}),
-    };
-  };
-  const normalizedCodeFileReadResult = (result) => ({
-    result: parseStructuredOutput(result.stdout),
-    ...(result.stderr.trim()
-      ? { diagnostics: boundedText(result.stderr, 20_000) }
-      : {}),
-    ...(branchChange ? { branch: branchChange } : {}),
-  });
-
-  const markInspection = ({
-    visual = false,
-    visualAttempted = false,
-    verifies = [],
-  } = {}) => {
-    operationSequence += 1;
-    lastInspectionSequence = operationSequence;
-    lastInspectionAt = new Date().toISOString();
-    verificationEvidence.set('structural', operationSequence);
-    if (visualAttempted) lastScreenshotAttemptSequence = operationSequence;
-    if (visual) {
-      screenshotCalls += 1;
-      lastScreenshotSequence = operationSequence;
-      verificationEvidence.set('visual', operationSequence);
-    }
-    for (const check of normalizeVerificationValues(
-      verifies,
-      GENERIC_VERIFICATION_CHECKS,
-    )) {
-      verificationEvidence.set(check, operationSequence);
-    }
-  };
-
-  const markMutation = ({ code = false } = {}) => {
-    operationSequence += 1;
-    lastMutationSequence = operationSequence;
-    if (code) lastCodeMutationSequence = operationSequence;
-    lastMutationAt = new Date().toISOString();
-  };
-
-  const requiredVerificationChecks = () =>
-    taskPlan?.verification || [];
-  const taskPlanSnapshot = () => {
-    if (!taskPlan) return null;
-    return {
-      summary: taskPlan.summary,
-      domains: [...taskPlan.domains],
-      verification: [...taskPlan.verification],
-      ...(taskPlan.behaviors.length > 0
-        ? {
-            behaviors: taskPlan.behaviors.map((behavior) => ({
-              ...behavior,
-              targetNodeIds: [...behavior.targetNodeIds],
-            })),
-          }
-        : {}),
-    };
-  };
-  // Only checks observed after the latest mutation describe the current project.
-  const freshInteractionChecks = () =>
-    [...interactionCheckResults.values()]
-      .filter((entry) => entry.sequence > lastMutationSequence)
-      .map((entry) => entry.result);
-  const interactionSummary = () =>
-    summarizeBehaviorVerification(taskPlan, freshInteractionChecks());
-  const interactionStatus = () => {
-    if (!taskPlan?.behaviors?.length || mutationCalls === 0) return 'not_required';
-    return interactionSummary().status;
-  };
-  const synchronized = () =>
-    mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
-  const verificationCheckCompleted = (check) => {
-    if (mutationCalls === 0) return true;
-    if (check === 'structural') return synchronized();
-    if (check === 'interactions') {
-      return ['verified', 'not_required'].includes(interactionStatus());
-    }
-    // Canvas edits cannot change a code file, so only code edits stale it.
-    const staleAfter =
-      check === 'code' ? lastCodeMutationSequence : lastMutationSequence;
-    return Number(verificationEvidence.get(check) || 0) > staleAfter;
-  };
-  const visualVerificationRequired = () =>
-    requiredVerificationChecks().includes('visual');
-  // The model asked for the final canvas, but no screenshot could be handed to
-  // it. That is reported as unverified rather than blamed on the model.
-  const visualVerificationUnavailable = () =>
-    mutationCalls > 0
-    && lastScreenshotAttemptSequence > lastMutationSequence
-    && lastScreenshotSequence <= lastMutationSequence;
-  const visualVerificationStatus = () => {
-    if (!visualVerificationRequired() || mutationCalls === 0) return 'not_required';
-    if (verificationCheckCompleted('visual')) return 'seen';
-    return visualVerificationUnavailable() ? 'unavailable' : 'missing';
-  };
-  const requiredChecks = () => [
-    ...new Set(['structural', ...requiredVerificationChecks()]),
-  ];
-  // Checks the model attempted but that live evidence could not confirm. They
-  // are reported as unverified and do not fail the run.
-  const unavailableChecks = () => [
-    ...(visualVerificationStatus() === 'unavailable' ? ['visual'] : []),
-    ...(interactionStatus() === 'unverified' ? ['interactions'] : []),
-  ];
-  const missingVerificationChecks = () => {
-    if (mutationCalls === 0) return [];
-    const missing = [];
-    if (!taskPlan) missing.push('task-plan');
-    const unavailable = unavailableChecks();
-    for (const check of requiredChecks()) {
-      if (unavailable.includes(check)) continue;
-      if (!verificationCheckCompleted(check)) missing.push(check);
-    }
-    return missing;
-  };
-  const verification = () => ({
-    ownedBy: 'harness',
-    required: mutationCalls > 0,
-    completed: missingVerificationChecks().length === 0,
-    structuralCompleted: synchronized(),
-    visualRequired: visualVerificationRequired() && mutationCalls > 0,
-    visualCompleted: visualVerificationStatus() !== 'missing',
-    visualStatus: visualVerificationStatus(),
-    screenshotCalls,
-    // Every failed CDN download is listed; recoveredVia marks the ones the
-    // session capture still delivered to the model.
-    screenshotDelivery: {
-      delivered: screenshotsViaDownload + screenshotsViaSession,
-      viaDownload: screenshotsViaDownload,
-      viaSession: screenshotsViaSession,
-      undelivered: screenshotsUndelivered,
-      failures: screenshotFailures.map((failure) => ({ ...failure })),
-    },
-    ...(requiredVerificationChecks().includes('interactions')
-      || interactionVerificationCalls > 0
-      ? {
-          interactionVerificationCalls,
-          interactionVerification: {
-            status: interactionStatus(),
-            behaviors: taskPlan?.behaviors?.length ? interactionSummary().behaviors : [],
-            checks: freshInteractionChecks().map((check) => ({ ...check })),
-            verifiedAt: interactionVerifiedAt,
-          },
-        }
-      : {}),
-    taskPlan: taskPlanSnapshot(),
-    requiredChecks: requiredChecks(),
-    completedChecks: requiredChecks().filter(verificationCheckCompleted),
-    unavailableChecks: unavailableChecks(),
-    missingChecks: missingVerificationChecks(),
-    lastMutationAt,
-    lastInspectionAt,
-  });
-
-  const inspectFinalState = async () => {
-    await serial;
-    return {
-      synchronized: synchronized(),
-      sourceHash: null,
-      changed: mutationCalls > 0,
-      mutationCalls,
-      readCalls,
-      branch: branchChange,
-      lastInspectionAt,
-      lastMutationAt,
-      taskPlan: taskPlanSnapshot(),
-      verification: verification(),
-    };
-  };
-
-  const withUnavailableChecks = (completion) => {
-    const unavailable = unavailableChecks();
-    if (unavailable.length === 0) return completion;
-    const unverifiedBehaviors = interactionSummary().behaviors
-      .filter((behavior) => behavior.verdict === 'unknown')
-      .map((behavior) => `${behavior.behaviorId} (${behavior.unknowns[0] || 'not confirmed'})`);
-    return {
-      ...completion,
-      checks: [
-        ...(Array.isArray(completion?.checks) ? completion.checks : []),
-        ...(unavailable.includes('visual')
-          ? [{
-              command: 'Visual verification',
-              status: 'skipped',
-              output:
-                'Screenshots of the final canvas could not be delivered to the model, so the visual result is unverified.',
-            }]
-          : []),
-        ...(unavailable.includes('interactions')
-          ? [{
-              command: 'Interaction verification',
-              status: 'skipped',
-              output:
-                `The live project did not expose evidence for: ${unverifiedBehaviors.join('; ')}. These behaviors are unverified.`,
-            }]
-          : []),
-      ],
-    };
-  };
-
-  const finalizeCompletion = (completion) => {
-    if (completion?.status !== 'completed' || mutationCalls === 0) {
-      return completion;
-    }
-    if (verification().completed) return withUnavailableChecks(completion);
-    const missing = missingVerificationChecks().map((check) => {
-      if (check === 'task-plan') return 'a harness task and verification plan';
-      if (check === 'structural') return 'a final structural read';
-      if (check === 'visual') return 'post-mutation screenshot verification';
-      return `post-mutation ${check} verification`;
-    });
-    const interactionDetails = (taskPlan?.behaviors?.length ? interactionSummary().behaviors : [])
-      .filter((behavior) => behavior.verdict === 'contradicted' || !behavior.checked)
-      .map((behavior) =>
-        `${behavior.behaviorId}=${behavior.verdict === 'contradicted' ? behavior.contradictions[0] : 'not checked after the latest change'}`);
-    const reason = [
-      `The harness ended before completing ${missing.join(' and ')}.`,
-      ...(interactionDetails.length > 0
-        ? [`Interaction evidence: ${interactionDetails.join('; ')}.`]
-        : []),
-    ].join(' ');
-    const failed = withUnavailableChecks(completion);
-    return {
-      ...failed,
-      status: 'failed',
-      summary:
-        String(completion?.summary || '').trim()
-        || 'The requested changes were applied.',
-      checks: [
-        ...(Array.isArray(failed?.checks) ? failed.checks : []),
-        {
-          command: 'Harness-owned final verification',
-          status: 'failed',
-          output: reason,
-        },
-      ],
-      blockedReason: null,
-    };
-  };
-
-  // A model that reports failure without changing anything and without a
-  // refused plan or edit gave up on its own. It gets one prompt to continue.
-  const unblockedFailurePrompt = (completion) => {
-    if (completion?.status !== 'failed' || mutationCalls > 0) return null;
-    const lastGate = [...toolCalls]
-      .reverse()
-      .find((call) => call.category === 'plan' || call.category === 'mutation');
-    if (lastGate?.status === 'failed') return null;
-    return [
-      'You returned failed without changing the Framer project, and no tool refused the work.',
-      'Nothing in this run is blocking you and there is no time limit.',
-      'Continue the same task from the current project state: plan it, apply the change, verify it, then return the required JSON outcome.',
-      'Return failed or blocked only for a concrete blocker you can name.',
-    ].join(' ');
-  };
-
-  const evidenceRequirement = (check) => {
-    if (check === 'structural') return 'a focused live read';
-    if (check === 'visual') {
-      return 'a screenshot you inspect (screenshotNodeIds on your last framer_apply_changes provides it)';
-    }
-    if (check === 'interactions') {
-      return 'framer_verify_interactions for every declared behavior and target node';
-    }
-    return `a read tagged with verifies:["${check}"]`;
-  };
-
-  const verificationRepairPrompt = () => {
-    const current = verification();
-    if (current.completed || mutationCalls === 0) return null;
-    const missing = [];
-    for (const check of current.missingChecks || []) {
-      if (check === 'task-plan') {
-        missing.push(
-          'declare the task domains and verification plan with framer_plan_task',
-        );
-      } else if (check === 'structural') {
-        missing.push('perform a focused live read after the latest mutation');
-      } else if (check === 'visual') {
-        missing.push(
-          'capture and inspect a screenshot of the affected canvas after the latest mutation',
-        );
-      } else if (check === 'interactions') {
-        const summary = interactionSummary();
-        const unchecked = summary.behaviors
-          .filter((behavior) => !behavior.checked)
-          .map((behavior) => behavior.uncheckedTargets.length
-            ? `${behavior.behaviorId} on ${behavior.uncheckedTargets.join(', ')}`
-            : behavior.behaviorId);
-        const contradicted = summary.behaviors
-          .filter((behavior) => behavior.verdict === 'contradicted')
-          .map((behavior) => behavior.contradictions[0]);
-        missing.push([
-          unchecked.length
-            ? `call framer_verify_interactions for ${unchecked.join('; ')}, naming the Framer property that carries each behavior`
-            : '',
-          contradicted.length
-            ? `fix or explain these mismatches: ${contradicted.join('; ')}`
-            : '',
-        ].filter(Boolean).join(' and '));
-      } else {
-        missing.push(`perform a focused read tagged with verifies:["${check}"] after the latest mutation`);
-      }
-    }
-    return [
-      'Continue the same Framer task from its current project state.',
-      'Do not redo successful work.',
-      `Before returning, ${missing.join(' and ')}.`,
-      'If the live project does not expose a property, report that behavior as unverified rather than changing working parts. Then return the required JSON outcome.',
-    ].join(' ');
-  };
-
-  const builtInInstructions = (documentationUnavailable = false) => ({
-    stdout: JSON.stringify({
-      source: documentationUnavailable
-        ? 'built-in-fallback'
-        : 'built-in',
-      guidance: [
-        'Use framer_read with framer.agent.getNode({ id }) or getNodes({ ids }) for node inspection.',
-        'Use framer_read_project for supported project queries such as screenshots.',
-        'To place a user attachment in the project, call framer_upload_attachment with its id from context.referenceAssetFiles and use the returned url as the image fill. Never upload user files to external services.',
-        'Use framer_query_images for approved stock imagery only after checking user attachments and suitable existing project images.',
-        'Use framer_add_svg for geometric or decorative artwork you draw as SVG markup; use icon sets for icons and real text for text.',
-        'Use framer_apply_changes for layout and styling. Read its diagnostics, verify the result, and repair concrete issues.',
-        'Use framer_read_code_file and framer_update_code_file for existing code components and overrides instead of generic JavaScript.',
-        'If framer_write is rejected as unsafe, do not retry JavaScript variants. Switch to framer_apply_changes or report the concrete blocker.',
-        'Batch related work when practical, reuse evidence already collected, and stop when the requested outcome is satisfied.',
-      ],
-      documentationUnavailable,
-    }),
-    stderr: '',
-  });
-
-  const reserveToolCall = (name, category) => {
-    toolCallCount += 1;
-    if (category === 'read') readCalls += 1;
-    const call = {
-      sequence: toolCallCount,
-      name,
-      category,
-      status: 'failed',
-      durationMs: 0,
-    };
-    toolCalls.push(call);
-    return call;
-  };
-
-  const callFingerprint = (name, rawArguments) =>
-    crypto
-      .createHash('sha256')
-      .update(`${name}\n${JSON.stringify(rawArguments)}`)
-      .digest('hex');
-
-  const requireTaskPlanForMutation = () => {
-    if (!taskPlan) {
-      throw toolError(
-        'FRAMER_HARNESS_PLAN_REQUIRED',
-        'Inspect the live Framer target, then call framer_plan_task before making a mutation.',
-      );
-    }
-  };
-
-  async function invokeUnsafe(name, rawArguments = {}) {
-    if (closed) {
-      throw toolError(
-        'FRAMER_AGENT_RUNTIME_CLOSED',
-        'The Framer Agent runtime is closed.',
-      );
-    }
-    if (!allowedToolNames.has(name) || !TOOL_BY_NAME.has(name)) {
-      throw toolError(
-        'FRAMER_AGENT_TOOL_UNKNOWN',
-        `Unavailable Framer Agent tool: ${name}`,
-      );
-    }
-    if (!isRecord(rawArguments)) {
-      throw toolError(
-        'FRAMER_AGENT_TOOL_INPUT_INVALID',
-        'Framer Agent tool arguments must be an object.',
-      );
-    }
-    const mutation = MUTATION_TOOL_NAMES.has(name);
-    const category =
-      name === 'framer_plan_task'
-        ? 'plan'
-        : mutation
-          ? 'mutation'
-          : 'read';
-    const fingerprint = callFingerprint(name, rawArguments);
-    if (
-      repeatedFailureFingerprint === fingerprint
-      && repeatedFailureCount >= 5
-    ) {
-      repeatedFailureStops += 1;
-      throw toolError(
-        'FRAMER_AGENT_REPEATED_CALL_LOOP',
-        'The same Framer tool call has failed five times in a row. Change the approach or report the concrete blocker.',
-      );
-    }
-
-    const startedAt = Date.now();
-    const toolCall = reserveToolCall(name, category);
-    reportActivity({
-      kind: 'tool_active',
-      source: 'framer-agent',
-      name,
-      phase: 'started',
-      message:
-        mutation
-          ? 'Updating the Framer project'
-          : name === 'framer_plan_task'
-            ? 'Planning the Framer work and verification'
-          : 'Inspecting the Framer project',
-    });
-    try {
-      let result;
-      let modelImages = [];
-      let screenshotRequestCount = 0;
-      if (name === 'framer_write' && lowLevelWriteDisabled) {
-        lowLevelWriteBlockedCalls += 1;
-        throw toolError(
-          'FRAMER_AGENT_WRITE_FALLBACK_REQUIRED',
-          'Low-level JavaScript writes are disabled for this run after repeated safety rejections. Use framer_apply_changes, inspect the project, or report the concrete blocker.',
-        );
-      } else if (name === 'framer_instructions') {
-        const queries = Array.isArray(rawArguments.queries)
-          ? uniqueStrings(rawArguments.queries, 8)
-          : [];
-        const guideIds = Array.isArray(rawArguments.guides)
-          ? uniqueStrings(rawArguments.guides, 6)
-          : [];
-        if (guideIds.length > 0) {
-          const guides = guideIds.flatMap((id) => {
-            const entry = guideCatalog.get(id);
-            const loaded = entry
-              ? readGuidanceFile(
-                  entry.root,
-                  entry.path,
-                  MAX_GUIDANCE_FILE_BYTES,
-                  entry.section,
-                )
-              : null;
-            if (!loaded) return [];
-            if (!guidesRead.includes(id)) guidesRead.push(id);
-            return [{ id, content: loaded.content }];
-          });
-          const unknown = guideIds.filter(
-            (id) => !guides.some((guide) => guide.id === id),
-          );
-          result = {
-            stdout: JSON.stringify({
-              guides,
-              ...(unknown.length > 0
-                ? {
-                    unknownGuides: unknown,
-                    availableGuides: [...guideCatalog.keys()],
-                  }
-                : {}),
-            }),
-            stderr: '',
-          };
-        } else if (queries.length > 0 && !instructionLookupUnavailable) {
-          try {
-            result = await executeCli(
-              ['docs', ...queries],
-              { timeoutMs: 30_000 },
-            );
-          } catch (error) {
-            instructionFallbacks += 1;
-            instructionLookupUnavailable = true;
-            trace?.warn?.('framer_agent_docs_fallback', {
-              code: error?.code,
-              message: error?.message,
-            });
-            reportActivity({
-              kind: 'status_update',
-              source: 'framer-agent',
-              message:
-                'Targeted Framer documentation is unavailable, so I am continuing with the built-in harness guidance.',
-            });
-            result = builtInInstructions(true);
-          }
-        } else {
-          if (queries.length > 0) instructionFallbacks += 1;
-          result = builtInInstructions(queries.length > 0);
-        }
-      } else if (name === 'framer_read_website') {
-        if (typeof readWebsite !== 'function') {
-          throw toolError(
-            'FRAMER_WEBSITE_READ_UNAVAILABLE',
-            'Reading websites is not available in this run.',
-          );
-        }
-        const website = await readWebsite({
-          url: String(rawArguments.url || '').trim(),
-          screenshotTop: Number.isInteger(rawArguments.screenshotTop)
-            ? rawArguments.screenshotTop
-            : undefined,
-        });
-        modelImages = (Array.isArray(website?.images) ? website.images : [])
-          .filter((image) => typeof image?.data === 'string' && image.data)
-          .map((image) => ({ url: null, mimeType: image.mimeType || 'image/jpeg', data: image.data }));
-        result = { stdout: JSON.stringify(website?.result ?? {}), stderr: '' };
-      } else if (name === 'framer_context') {
-        result = await execCode(
-          [
-            'const [context, branch] = await Promise.all([',
-            '  framer.agent.getContext(),',
-            '  framer.agent.getActiveBranch().catch(() => null),',
-            ']);',
-            'console.log(JSON.stringify({ context, branch }, null, 2));',
-          ].join('\n'),
-        );
-        markInspection();
-      } else if (name === 'framer_plan_task') {
-        if (lastInspectionSequence === 0) {
-          throw toolError(
-            'FRAMER_HARNESS_INSPECTION_REQUIRED',
-            'Inspect the live Framer target before declaring the task and verification plan.',
-          );
-        }
-        const nextPlan = normalizeTaskPlan(rawArguments);
-        taskPlan = {
-          summary: nextPlan.summary,
-          domains: uniqueStrings([
-            ...(taskPlan?.domains || []),
-            ...nextPlan.domains,
-          ]),
-          verification: uniqueStrings([
-            ...(taskPlan?.verification || []),
-            ...nextPlan.verification,
-          ]),
-          ...mergeBehaviorPlans(taskPlan, nextPlan),
-        };
-        result = {
-          stdout: JSON.stringify({
-            plan: taskPlanSnapshot(),
-            beforeFinishing: `After your final change, and before returning, produce: ${requiredChecks().map(evidenceRequirement).join('; ')}.`,
-          }),
-          stderr: '',
-        };
-      } else if (name === 'framer_verify_interactions') {
-        if (!taskPlan?.behaviors?.length) {
-          throw toolError(
-            'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
-            'Declare the behaviors to confirm in framer_plan_task before verifying them.',
-          );
-        }
-        const checks = normalizeBehaviorEvidence(rawArguments.checks, taskPlan);
-        const pagePath = normalizePagePath(rawArguments.pagePath);
-        const liveResult = await execCode(
-          [
-            `const requestedIds = ${JSON.stringify(evidenceNodeIds(checks))};`,
-            'const nodes = await Promise.all(requestedIds.map(async (id) => ({',
-            '  id,',
-            '  node: await framer.agent.serialize({ id, depth: 1 },',
-            `    { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null),`,
-            '})));',
-            'console.log(JSON.stringify({ nodes }, null, 2));',
-          ].join('\n'),
-        );
-        const parsed = parseStructuredOutput(liveResult.stdout);
-        const nodes = new Map(
-          (Array.isArray(parsed?.nodes) ? parsed.nodes : [])
-            .filter((entry) => isRecord(entry) && typeof entry.id === 'string' && entry.node)
-            .map((entry) => [entry.id, entry.node]),
-        );
-        const results = verifyBehaviorChecks({ checks, nodes });
-        // Live link values read here are link evidence too, so the model does
-        // not spend another turn re-reading them under verifies:["links"].
-        const linkChecks = results.filter((check) => /^link(\.|$)/.test(check.property));
-        markInspection({
-          verifies: linkChecks.length > 0
-            && linkChecks.every((check) => check.verdict === 'verified')
-            ? ['links']
-            : [],
-        });
-        interactionVerificationCalls += 1;
-        interactionVerifiedAt = new Date().toISOString();
-        for (const checkResult of results) {
-          interactionCheckResults.set(
-            `${checkResult.behaviorId}\n${checkResult.nodeId}\n${checkResult.property}`,
-            { sequence: operationSequence, result: checkResult },
-          );
-        }
-        const summary = interactionSummary();
-        result = {
-          stdout: JSON.stringify({
-            status: summary.status,
-            checks: results,
-            behaviors: summary.behaviors,
-          }),
-          stderr: liveResult.stderr,
-        };
-      } else if (name === 'framer_read_project') {
-        const queries = Array.isArray(rawArguments.queries)
-          ? rawArguments.queries.slice(0, 50)
-          : [];
-        if (!queries.length || queries.some((query) => !isRecord(query))) {
-          throw toolError(
-            'FRAMER_AGENT_QUERY_INVALID',
-            'framer_read_project requires one or more query objects.',
-          );
-        }
-        const pagePath = normalizePagePath(rawArguments.pagePath);
-        result = await readProjectWithFontFallback(queries, pagePath);
-        const requestedScreenshots = screenshotQueries(rawArguments);
-        screenshotRequestCount = requestedScreenshots.length;
-        modelImages = requestedScreenshots.length
-          ? await deliverScreenshots(
-              requestedScreenshots,
-              parseStructuredOutput(result.stdout),
-            )
-          : [];
-        markInspection({
-          visual: modelImages.length > 0,
-          visualAttempted: requestedScreenshots.length > 0,
-          verifies: rawArguments.verifies,
-        });
-      } else if (name === 'framer_query_images') {
-        const query = String(rawArguments.query || '').trim();
-        if (query.length < 2) {
-          throw toolError(
-            'FRAMER_AGENT_IMAGE_QUERY_INVALID',
-            'A specific image-search query is required.',
-          );
-        }
-        const count = Math.max(
-          1,
-          Math.min(8, Math.floor(Number(rawArguments.count) || 4)),
-        );
-        const orientation = ['landscape', 'portrait', 'squarish']
-          .includes(rawArguments.orientation)
-          ? rawArguments.orientation
-          : undefined;
-        result = await execCode(
-          [
-            'const result = await framer.agent.queryImages({',
-            '  source: "unsplash",',
-            `  query: ${JSON.stringify(query)},`,
-            `  count: ${count},`,
-            ...(orientation
-              ? [`  orientation: ${JSON.stringify(orientation)},`]
-              : []),
-            '});',
-            'console.log(JSON.stringify(result, null, 2));',
-          ].join('\n'),
-          { timeoutMs: 30_000 },
-        );
-        imageSearchCalls += 1;
-      } else if (name === 'framer_upload_attachment') {
-        result = await uploadAttachment(String(rawArguments.attachmentId || ''));
-      } else if (name === 'framer_add_svg') {
-        const svg = normalizeSvgMarkup(rawArguments.svg);
-        const parentId = String(rawArguments.parentId || '').trim();
-        if (!parentId) {
-          throw toolError(
-            'FRAMER_SVG_PARENT_REQUIRED',
-            'framer_add_svg needs the id of the parent node.',
-          );
-        }
-        const index = Number.isInteger(rawArguments.index) && rawArguments.index >= 0
-          ? rawArguments.index
-          : null;
-        const svgName = String(rawArguments.name || '').trim().slice(0, 120) || 'SVG';
-        const attributes = normalizeSvgAttributes(rawArguments.attributes);
-        requireTaskPlanForMutation();
-        // addSVG has no parent option and replaces a selected SVG, so clear
-        // the selection, find the one new SVG node, then move it into place.
-        result = await execCode(
-          [
-            `const svg = ${JSON.stringify(svg)};`,
-            `const parentId = ${JSON.stringify(parentId)};`,
-            `const index = ${JSON.stringify(index)};`,
-            `const attributes = ${JSON.stringify({ name: svgName, position: 'relative', ...attributes })};`,
-            'const fail = (code, message) => console.log(JSON.stringify({ ok: false, error: { code, message } }));',
-            'const parent = await framer.getNode(parentId);',
-            'if (!parent) {',
-            '  fail("FRAMER_SVG_PARENT_NOT_FOUND", `No node exists with id "${parentId}".`);',
-            '} else {',
-            '  const previousIds = new Set((await framer.getNodesWithType("SVGNode")).map((node) => node.id));',
-            '  try { await framer.setSelection([]); } catch {}',
-            '  await framer.addSVG({ svg, name: attributes.name });',
-            '  let node = null;',
-            '  for (let attempt = 0; attempt < 6 && !node; attempt += 1) {',
-            '    if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, 150));',
-            '    const inserted = (await framer.getNodesWithType("SVGNode")).filter((candidate) => !previousIds.has(candidate.id));',
-            '    if (inserted.length === 1) node = inserted[0];',
-            '  }',
-            '  if (!node) {',
-            '    fail("FRAMER_SVG_NOT_INSERTED", "Framer did not expose exactly one new SVG node after inserting the markup.");',
-            '  } else {',
-            '    try {',
-            '      await framer.setParent(node.id, parentId, index ?? undefined);',
-            '      await node.setAttributes(attributes);',
-            '      const placedParent = await node.getParent();',
-            '      if (placedParent?.id !== parentId) throw new Error("The SVG did not land inside the requested parent.");',
-            '      const placed = await framer.getNode(node.id);',
-            '      console.log(JSON.stringify({',
-            '        ok: true,',
-            '        node: {',
-            '          id: node.id,',
-            '          name: placed?.name ?? attributes.name,',
-            '          parentId,',
-            '          position: placed?.position ?? null,',
-            '          width: placed?.width ?? null,',
-            '          height: placed?.height ?? null,',
-            '        },',
-            '      }));',
-            '    } catch (error) {',
-            '      await framer.removeNodes([node.id]).catch(() => undefined);',
-            '      fail("FRAMER_SVG_PLACEMENT_FAILED", String(error?.message || error));',
-            '    }',
-            '  }',
-            '}',
-          ].join('\n'),
-        );
-        const parsed = parseStructuredOutput(result.stdout);
-        if (!isRecord(parsed) || parsed.ok !== true) {
-          throw structuredResultError(
-            parsed,
-            'FRAMER_SVG_PLACEMENT_FAILED',
-            'Dexter could not place the SVG in the Framer project.',
-          );
-        }
-        mutationCalls += 1;
-        markMutation();
-        mutationReceipts.push({
-          sequence: operationSequence,
-          kind: 'framer_add_svg',
-          nodeId: parsed.node?.id ?? null,
-          parentId,
-          svgHash: crypto.createHash('sha256').update(svg).digest('hex'),
-        });
-      } else if (name === 'framer_read_code_file') {
-        const filePath = normalizeCodeFilePath(rawArguments.path);
-        result = await execCode(
-          [
-            `const requestedPath = ${JSON.stringify(filePath)};`,
-            'try {',
-            '  const file = await framer.getCodeFile(requestedPath);',
-            '  if (!file) {',
-            '    console.log(JSON.stringify({',
-            '      ok: false,',
-            '      error: {',
-            '        code: "FRAMER_CODE_FILE_NOT_FOUND",',
-            '        message: `No Framer code file exists at "${requestedPath}".`,',
-            '      },',
-            '    }));',
-            '  } else {',
-            '    const content = typeof file.content === "string" ? file.content : "";',
-            `    const maximumContentChars = ${MAX_CODE_FILE_CONTENT_CHARS};`,
-            '    if (content.length > maximumContentChars) {',
-            '      console.log(JSON.stringify({',
-            '        ok: false,',
-            '        error: {',
-            '          code: "FRAMER_CODE_FILE_TOO_LARGE",',
-            '          message: `The Framer code file contains ${content.length} characters; Dexter supports complete code-file reads up to ${maximumContentChars} characters.`,',
-            '        },',
-            '      }));',
-            '    } else {',
-            '      console.log(JSON.stringify({',
-            '        ok: true,',
-            '        file: {',
-            '          id: file.id,',
-            '          name: file.name,',
-            '          path: file.path,',
-            '          versionId: file.versionId,',
-            '          content,',
-            '          exports: file.exports,',
-            '        },',
-            '      }));',
-            '    }',
-            '  }',
-            '} catch (error) {',
-            '  console.log(JSON.stringify({',
-            '    ok: false,',
-            '    error: {',
-            '      code: "FRAMER_CODE_FILE_READ_FAILED",',
-            '      message: String(error?.message || error),',
-            '    },',
-            '  }));',
-            '}',
-          ].join('\n'),
-        );
-        const parsed = parseStructuredOutput(result.stdout);
-        if (!isRecord(parsed) || parsed.ok !== true) {
-          throw structuredResultError(
-            parsed,
-            'FRAMER_CODE_FILE_READ_FAILED',
-            `Dexter could not read ${filePath}.`,
-          );
-        }
-        const content =
-          typeof parsed.file?.content === 'string'
-            ? parsed.file.content
-            : '';
-        result = {
-          ...result,
-          stdout: JSON.stringify({
-            ...parsed,
-            file: {
-              ...parsed.file,
-              content,
-              complete: true,
-              contentChars: content.length,
-              contentBytes: Buffer.byteLength(content, 'utf8'),
-              lineCount:
-                content.length === 0
-                  ? 0
-                  : content.split(/\r\n|\r|\n/).length,
-              sourceHash: crypto
-                .createHash('sha256')
-                .update(content)
-                .digest('hex'),
-            },
-          }),
-        };
-        markInspection();
-      } else if (name === 'framer_update_code_file') {
-        const filePath = normalizeCodeFilePath(rawArguments.path);
-        const expectedVersionId =
-          String(rawArguments.expectedVersionId || '').trim();
-        const content =
-          typeof rawArguments.content === 'string'
-            ? rawArguments.content
-            : '';
-        if (!expectedVersionId) {
-          throw toolError(
-            'FRAMER_CODE_FILE_VERSION_REQUIRED',
-            'Read the Framer code file first and provide its current version ID.',
-          );
-        }
-        requireTaskPlanForMutation();
-        result = await execCode(
-          [
-            `const requestedPath = ${JSON.stringify(filePath)};`,
-            `const expectedVersionId = ${JSON.stringify(expectedVersionId)};`,
-            `const nextContent = ${JSON.stringify(content)};`,
-            'try {',
-            '  const file = await framer.getCodeFile(requestedPath);',
-            '  if (!file) {',
-            '    console.log(JSON.stringify({',
-            '      ok: false,',
-            '      error: {',
-            '        code: "FRAMER_CODE_FILE_NOT_FOUND",',
-            '        message: `No Framer code file exists at "${requestedPath}".`,',
-            '      },',
-            '    }));',
-            '  } else if (file.versionId !== expectedVersionId) {',
-            '    console.log(JSON.stringify({',
-            '      ok: false,',
-            '      error: {',
-            '        code: "FRAMER_CODE_FILE_VERSION_CONFLICT",',
-            '        message: `The Framer code file changed after it was read. Read "${requestedPath}" again before updating it.`,',
-            '      },',
-            '      actualVersionId: file.versionId,',
-            '    }));',
-            '  } else if (typeof file.setFileContent !== "function") {',
-            '    console.log(JSON.stringify({',
-            '      ok: false,',
-            '      error: {',
-            '        code: "FRAMER_CODE_FILE_UPDATE_UNAVAILABLE",',
-            '        message: "This Framer session does not expose CodeFile.setFileContent.",',
-            '      },',
-            '    }));',
-            '  } else if (typeof framer.isAllowedTo === "function" && !framer.isAllowedTo("CodeFile.setFileContent")) {',
-            '    console.log(JSON.stringify({',
-            '      ok: false,',
-            '      error: {',
-            '        code: "FRAMER_CODE_FILE_WRITE_NOT_ALLOWED",',
-            '        message: "Framer has not granted this session permission to update code files.",',
-            '      },',
-            '    }));',
-            '  } else {',
-            '    const updated = await file.setFileContent(nextContent);',
-            '    let saved = null;',
-            '    for (let attempt = 0; attempt < 3; attempt += 1) {',
-            '      saved = await framer.getCodeFile(updated?.id || file.id);',
-            '      if (saved?.content === nextContent) break;',
-            '      if (attempt < 2) {',
-            '        await new Promise((resolve) => setTimeout(resolve, 250 * (attempt + 1)));',
-            '      }',
-            '    }',
-            '    if (!saved || saved.content !== nextContent) {',
-            '      console.log(JSON.stringify({',
-            '        ok: false,',
-            '        error: {',
-            '          code: "FRAMER_CODE_FILE_READBACK_MISMATCH",',
-            '          message: "Framer did not return the expected source after saving the code file.",',
-            '        },',
-            '      }));',
-            '    } else {',
-            '      let diagnostics = [];',
-            '      let typecheckError = null;',
-            '      try {',
-            '        diagnostics = typeof saved.typecheck === "function"',
-            '          ? await saved.typecheck()',
-            '          : await framer.typecheckCode(saved.path, saved.content);',
-            '      } catch (error) {',
-            '        typecheckError = String(error?.message || error);',
-            '      }',
-            '      const normalizedDiagnostics = Array.isArray(diagnostics)',
-            '        ? diagnostics.slice(0, 40).map((diagnostic) => ({',
-            '            message: diagnostic?.message,',
-            '            code: diagnostic?.code,',
-            '            category: diagnostic?.category,',
-            '            fileName: diagnostic?.fileName,',
-            '            span: diagnostic?.span,',
-            '          }))',
-            '        : [];',
-            '      const hasErrors = normalizedDiagnostics.some((diagnostic) =>',
-            '        diagnostic.category === 1',
-            '        || String(diagnostic.category || "").toLowerCase() === "error"',
-            '      );',
-            '      console.log(JSON.stringify({',
-            '        ok: true,',
-            '        file: {',
-            '          id: saved.id,',
-            '          name: saved.name,',
-            '          path: saved.path,',
-            '          versionId: saved.versionId,',
-            '        },',
-            '        previousVersionId: expectedVersionId,',
-            '        readbackMatches: true,',
-            '        typecheck: {',
-            '          passed: !typecheckError && !hasErrors,',
-            '          error: typecheckError,',
-            '          diagnostics: normalizedDiagnostics,',
-            '        },',
-            '      }));',
-            '    }',
-            '  }',
-            '} catch (error) {',
-            '  console.log(JSON.stringify({',
-            '    ok: false,',
-            '    error: {',
-            '      code: "FRAMER_CODE_FILE_UPDATE_FAILED",',
-            '      message: String(error?.message || error),',
-            '    },',
-            '  }));',
-            '}',
-          ].join('\n'),
-        );
-        const parsed = parseStructuredOutput(result.stdout);
-        if (!isRecord(parsed) || parsed.ok !== true) {
-          throw structuredResultError(
-            parsed,
-            'FRAMER_CODE_FILE_UPDATE_FAILED',
-            `Dexter could not update ${filePath}.`,
-          );
-        }
-        mutationCalls += 1;
-        markMutation({ code: true });
-        const mutationSequence = operationSequence;
-        markInspection({
-          verifies: parsed.typecheck?.passed === true ? ['code'] : [],
-        });
-        const contentHash = crypto
-          .createHash('sha256')
-          .update(content)
-          .digest('hex');
-        mutationReceipts.push({
-          sequence: mutationSequence,
-          kind: 'framer_update_code_file',
-          path: filePath,
-          previousVersionId: expectedVersionId,
-          versionId:
-            typeof parsed.file?.versionId === 'string'
-              ? parsed.file.versionId
-              : null,
-          contentHash,
-          readbackMatches: parsed.readbackMatches === true,
-          typecheckPassed: parsed.typecheck?.passed === true,
-        });
-        result = {
-          ...result,
-          stdout: JSON.stringify({
-            ...parsed,
-            contentHash,
-          }),
-        };
-      } else if (name === 'framer_apply_changes') {
-        const changes = String(rawArguments.changes || '').trim();
-        if (!changes) {
-          throw toolError(
-            'FRAMER_AGENT_CHANGES_REQUIRED',
-            'Framer Agent changes are required.',
-          );
-        }
-        requireTaskPlanForMutation();
-        const pagePath = normalizePagePath(rawArguments.pagePath);
-        result = await execCode(
-          [
-            `const result = await framer.agent.applyChanges(${JSON.stringify(changes)}, { pagePath: ${JSON.stringify(pagePath)} });`,
-            'console.log(JSON.stringify(result ?? { ok: true }, null, 2));',
-          ].join('\n'),
-        );
-        mutationCalls += 1;
-        applyChangesCalls += 1;
-        markMutation();
-        const parsedResult = parseStructuredOutput(result.stdout);
-        mutationReceipts.push({
-          sequence: operationSequence,
-          kind: 'framer_apply_changes',
-          pagePath,
-          ...summarizeFramerChanges(changes),
-          renamedIds: canonicalIdMappings(parsedResult),
-        });
-        // A screenshot taken here saves the model a whole turn re-reading
-        // its context just to look at the change.
-        const screenshotIds = Array.isArray(rawArguments.screenshotNodeIds)
-          ? uniqueStrings(rawArguments.screenshotNodeIds, MAX_SCREENSHOTS_PER_CALL)
-          : [];
-        if (screenshotIds.length > 0) {
-          const queries = screenshotIds.map((id) => ({ type: 'screenshot', id }));
-          modelImages = await readScreenshots(queries, pagePath);
-          screenshotRequestCount = queries.length;
-          markInspection({
-            visual: modelImages.length > 0,
-            visualAttempted: true,
-          });
-        }
-      } else if (name === 'framer_read') {
-        result = await execCode(
-          validateCode(rawArguments.code, {
-            write: false,
-            allowPublishing,
-          }),
-        );
-        markInspection({ verifies: rawArguments.verifies });
-      } else if (name === 'framer_write') {
-        if (CODE_FILE_SOURCE_WRITE_PATTERN.test(String(rawArguments.code || ''))) {
-          throw toolError(
-            'FRAMER_CODE_FILE_TOOL_REQUIRED',
-            'Use framer_read_code_file followed by framer_update_code_file to edit an existing Framer code file.',
-          );
-        }
-        const code = validateCode(rawArguments.code, {
-          write: true,
-          allowPublishing,
-        });
-        const reason = String(rawArguments.reason || '').trim();
-        if (reason.length < 10) {
-          throw toolError(
-            'FRAMER_AGENT_WRITE_REASON_REQUIRED',
-            'Explain why this operation cannot be completed with framer_apply_changes before using framer_write.',
-          );
-        }
-        requireTaskPlanForMutation();
-        result = await execCode(code);
-        mutationCalls += 1;
-        lowLevelWriteCalls += 1;
-        markMutation();
-        mutationReceipts.push({
-          sequence: operationSequence,
-          kind: 'framer_write',
-          reason: reason.slice(0, 500),
-          codeHash: crypto.createHash('sha256').update(code).digest('hex'),
-        });
-      } else {
-        throw toolError(
-          'FRAMER_AGENT_TOOL_UNKNOWN',
-          `Unknown Framer Agent tool: ${name}`,
-        );
-      }
-      const durationMs = Date.now() - startedAt;
-      repeatedFailureFingerprint = null;
-      repeatedFailureCount = 0;
-      toolCall.status = 'succeeded';
-      toolCall.durationMs = durationMs;
-      reportActivity({
-        kind: 'tool_active',
-        source: 'framer-agent',
-        name,
-        phase: 'completed',
-        message:
-          mutation
-            ? 'Updated the Framer project'
-            : 'Finished inspecting the Framer project',
-        durationMs,
-      });
-      const normalized =
-        name === 'framer_read_code_file'
-          ? normalizedCodeFileReadResult(result)
-          : normalizedResult(result);
-      // Result size is what this call adds to every later model turn.
-      toolCall.resultBytes = Buffer.byteLength(JSON.stringify(normalized), 'utf8');
-      if (modelImages.length > 0) toolCall.imageCount = modelImages.length;
-      if (name === 'framer_read_website') {
-        return modelImages.length ? { ...normalized, modelImages } : normalized;
-      }
-      // Naming the evidence still owed after the latest change lets the model
-      // finish it in this session instead of in a resumed repair turn.
-      const evidenceStillDue =
-        taskPlan && mutationCalls > 0 && (category === 'read' || screenshotRequestCount > 0)
-          ? missingVerificationChecks()
-          : [];
-      return {
-        ...normalized,
-        ...(modelImages.length ? { modelImages } : {}),
-        ...(screenshotRequestCount > modelImages.length
-          ? {
-              screenshotWarning:
-                `${screenshotRequestCount - modelImages.length} screenshot(s) could not be downloaded for you to view. Treat that visual state as unverified.`,
-            }
-          : {}),
-        ...(evidenceStillDue.length > 0 ? { evidenceStillDue } : {}),
-      };
-    } catch (error) {
-      if (
-        name === 'framer_write'
-        && error?.code === 'FRAMER_AGENT_CODE_UNSAFE'
-      ) {
-        unsafeWriteFailures += 1;
-        if (
-          !lowLevelWriteDisabled
-          && unsafeWriteFailures >= MAX_UNSAFE_WRITE_FAILURES
-        ) {
-          lowLevelWriteDisabled = true;
-          reportActivity({
-            kind: 'status_update',
-            source: 'framer-agent',
-            message:
-              'Repeated low-level writes were rejected by the safety boundary, so I switched the run to the safer Framer change path.',
-          });
-        }
-      }
-      if (
-        name === 'framer_write'
-        && error?.code === 'FRAMER_AGENT_COMMAND_FAILED'
-      ) {
-        lowLevelWriteFailures += 1;
-        if (
-          !lowLevelWriteDisabled
-          && lowLevelWriteFailures >= MAX_LOW_LEVEL_WRITE_FAILURES
-        ) {
-          lowLevelWriteDisabled = true;
-          reportActivity({
-            kind: 'status_update',
-            source: 'framer-agent',
-            message:
-              'Repeated low-level Framer writes failed, so I switched the run back to semantic Framer changes and focused inspection.',
-          });
-        }
-      }
-      if (repeatedFailureFingerprint === fingerprint) {
-        repeatedFailureCount += 1;
-      } else {
-        repeatedFailureFingerprint = fingerprint;
-        repeatedFailureCount = 1;
-      }
-      toolCall.durationMs = Date.now() - startedAt;
-      toolCall.errorCode = error?.code || 'FRAMER_AGENT_TOOL_FAILED';
-      toolCall.errorMessage = boundedText(
-        String(error?.message || 'Framer Agent tool failed.'),
-        300,
-      );
-      trace?.warn?.('framer_agent_tool_failed', {
-        name,
-        code: error?.code,
-        message: error?.message,
-      });
-      reportActivity({
-        kind: 'tool_active',
-        source: 'framer-agent',
-        name,
-        phase: 'failed',
-        message:
-          mutation
-            ? 'The Framer project update failed'
-            : 'The Framer project inspection failed',
-        durationMs: Date.now() - startedAt,
-      });
-      throw error;
-    }
-  }
-
-  function invoke(name, args = {}) {
-    const operation = serial.then(() => invokeUnsafe(name, args));
-    serial = operation.catch(() => undefined);
-    return operation;
-  }
-
-  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_AGENT_GATEWAY_NOT_FOUND', 'Framer Agent tool endpoint not found.');
-        return;
-      }
-      if (request.headers.authorization !== `Bearer ${token}`) {
-        fail(401, 'FRAMER_AGENT_GATEWAY_UNAUTHORIZED', 'Invalid Framer Agent 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_AGENT_TOOL_FAILED',
-            error?.message || 'Framer Agent tool failed.',
-          );
-        }
-      });
-    });
-    await new Promise((resolve, reject) => {
-      server.once('error', reject);
-      server.listen(0, '127.0.0.1', resolve);
-    });
-    const address = server.address();
-    if (!address || typeof address !== 'object') {
-      throw new Error('Framer Agent tool gateway did not bind to a local port.');
-    }
-    gateway = {
-      url: `http://127.0.0.1:${address.port}/tool`,
-      token,
-    };
-    return gateway;
-  }
-
-  return {
-    definitions,
-    toolNames: definitions.map((definition) => definition.name),
-    preflight: validateAuthoritativeNodeIds,
-    loadProjectGuidance,
-    configurePromptContext,
-    invoke,
-    startGateway,
-    synchronize: inspectFinalState,
-    inspect: inspectFinalState,
-    finalizeCompletion,
-    verificationRepairPrompt,
-    unblockedFailurePrompt,
-    sourceHash: () => null,
-    hasPendingChanges: () => false,
-    directWorkspace: true,
-    summary: () => ({
-      projectId,
-      projectUrl,
-      unresolvedTargets: unresolvedTargets.map((target) => ({ ...target })),
-      mutationCalls,
-      applyChangesCalls,
-      lowLevelWriteCalls,
-      imageSearchCalls,
-      interactionVerificationCalls,
-      mutationReceipts: mutationReceipts.map((receipt) => ({
-        ...receipt,
-        ...(Array.isArray(receipt.commands)
-          ? {
-              commands: receipt.commands.map((command) => ({
-                ...command,
-                ...(Array.isArray(command.eventActions)
-                  ? {
-                      eventActions: command.eventActions.map((action) => ({
-                        ...action,
-                      })),
-                    }
-                  : {}),
-              })),
-            }
-          : {}),
-        ...(receipt.renamedIds
-          ? { renamedIds: { ...receipt.renamedIds } }
-          : {}),
-      })),
-      readCalls,
-      toolCallCount,
-      toolDurationMs: toolCalls.reduce(
-        (total, call) => total + call.durationMs,
-        0,
-      ),
-      toolCalls: toolCalls.map((call) => ({ ...call })),
-      workingPreferences: {
-        focus: workingPreferences.mode,
-        writeScope: workingPreferences.writeScope,
-        preferBatchedMutations:
-          workingPreferences.preferBatchedMutations,
-        avoidRepeatedInspection:
-          workingPreferences.avoidRepeatedInspection,
-        expandScopeOnlyWhenNeeded:
-          workingPreferences.expandScopeOnlyWhenNeeded,
-      },
-      loopProtection: {
-        identicalFailureLimit: 5,
-        blockedCalls: repeatedFailureStops,
-        unsafeWriteFailureLimit: MAX_UNSAFE_WRITE_FAILURES,
-        unsafeWriteFailures,
-        lowLevelWriteFailureLimit: MAX_LOW_LEVEL_WRITE_FAILURES,
-        lowLevelWriteFailures,
-        lowLevelWriteDisabled,
-        lowLevelWriteBlockedCalls,
-        instructionFallbacks,
-      },
-      fontSearchFallbacks,
-      branch: branchChange,
-      lastInspectionAt,
-      lastMutationAt,
-      taskPlan: taskPlanSnapshot(),
-      verification: verification(),
-      framerAgentVersion,
-      framerSetup: {
-        completed: framerSetupCompleted,
-        attempts: framerSetupAttempts,
-        recoveredSession: framerSetupRecoveredSession,
-      },
-      framerGuidanceLoaded: guidanceMetadata.loaded,
-      doctrineLoaded: promptMetadata.doctrineLoaded,
-      guidanceHash: guidanceMetadata.contentHash,
-      projectContextHash: guidanceMetadata.projectContextHash,
-      visualVerificationRequired:
-        verification().visualRequired,
-      visualVerificationCompleted:
-        verification().visualCompleted,
-      guidance: {
-        loaded: guidanceMetadata.loaded,
-        contentHash: guidanceMetadata.contentHash,
-        projectContextHash: guidanceMetadata.projectContextHash,
-        files: [...guidanceMetadata.files],
-        bytes: guidanceMetadata.bytes,
-        guidesRead: [...guidesRead],
-      },
-      doctrine: { ...promptMetadata },
-    }),
-    fatalInfrastructureError: () => null,
-    waitForFatalInfrastructure: () => new Promise(() => undefined),
-    close: async ({ waitForPending = true } = {}) => {
-      closed = true;
-      abortController.abort();
-      if (waitForPending) await serial.catch(() => undefined);
-      if (server) {
-        if (!waitForPending) server.closeAllConnections?.();
-        await new Promise((resolve) => server.close(() => resolve()));
-        server = null;
-      }
-    },
-  };
-}
-
-export function __resetFramerAgentToolRuntimeForTests() {
-  sessionsByProject.clear();
-  framerSetupPromise = null;
-}