@gakim-digital/dexter-bridge 0.5.21 → 0.11.1

package/src/framerAgentTools.js

@@ -0,0 +1,2547 @@
+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 {
+  BEHAVIOR_ACTIVATIONS,
+  BEHAVIOR_LAYOUT_EFFECTS,
+  BEHAVIOR_MECHANISMS,
+  BEHAVIOR_PRESENTATIONS,
+  canonicalIdMappings,
+  evidenceNodeIds,
+  mergeBehaviorPlans,
+  normalizeBehaviorEvidence,
+  normalizeBehaviorPlan,
+  summarizeFramerChanges,
+  verifyBehaviorEvidence,
+} from './framerBehaviorContract.js';
+
+const require = createRequire(import.meta.url);
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const MAX_MODEL_RESULT_BYTES = 120 * 1024;
+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|create|remove|delete|update|insert|move|clone|duplicate|upload|publish|deploy|switch|merge|rename|join|leave|apply)[A-Za-z0-9_]*\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: 'progress_update',
+    description:
+      'Tell the user what you are about to do or are doing now in one or two natural first-person sentences. Name the specific page area, component, or behavior and the concrete change; optionally say what you will check next. Avoid generic updates such as "working on the next step", "thinking", "loading", or "making changes". Call this before the first Framer inspection or edit and at meaningful phase changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: { type: 'string', minLength: 1, maxLength: 500 },
+      },
+      required: ['message'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_instructions',
+    description:
+      'Get concise Framer Agent guidance, or request targeted official API documentation when an exact method or type is unclear. Most runs should rely on the tool descriptions and call this only when needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        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 against the connected project. Use this for focused canvas inspection and screenshots.',
+    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_plan_task',
+    description:
+      'After inspecting the live Framer target and before the first mutation, declare your semantic understanding, observable behavior requirements, chosen implementation mechanisms, and completion evidence. Dexter does not classify the request or choose mechanisms for you.',
+    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 },
+        },
+        behaviors: {
+          type: 'array',
+          maxItems: 20,
+          description:
+            'Required for interaction work. Describe observable behavior independently from its implementation.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', minLength: 1, maxLength: 120 },
+              description: { type: 'string', minLength: 5, maxLength: 500 },
+              triggerDescription: {
+                type: 'string',
+                minLength: 3,
+                maxLength: 300,
+              },
+              activation: {
+                type: 'string',
+                enum: BEHAVIOR_ACTIVATIONS,
+              },
+              presentation: {
+                type: 'string',
+                enum: BEHAVIOR_PRESENTATIONS,
+              },
+              stateChange: { type: 'boolean' },
+              layoutEffect: {
+                type: 'string',
+                enum: BEHAVIOR_LAYOUT_EFFECTS,
+              },
+              reversible: { type: 'boolean' },
+              repeatable: { type: 'boolean' },
+              expectedTargets: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 50,
+              },
+              expectedContent: {
+                type: 'array',
+                maxItems: 20,
+                items: { type: 'string', minLength: 1, maxLength: 500 },
+              },
+              initialState: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+              activatedState: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+            },
+            required: [
+              'id',
+              'description',
+              'triggerDescription',
+              'activation',
+              'presentation',
+              'stateChange',
+              'layoutEffect',
+              'reversible',
+              'repeatable',
+              'expectedTargets',
+              'initialState',
+              'activatedState',
+            ],
+            additionalProperties: false,
+          },
+        },
+        mechanisms: {
+          type: 'array',
+          maxItems: 20,
+          description:
+            'Required for every declared behavior. Choose the mechanism from live project capabilities and explain why it satisfies the behavior.',
+          items: {
+            type: 'object',
+            properties: {
+              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
+              mechanism: {
+                type: 'string',
+                enum: BEHAVIOR_MECHANISMS,
+              },
+              rationale: {
+                type: 'string',
+                minLength: 10,
+                maxLength: 800,
+              },
+              representativeFirst: { type: 'boolean', default: true },
+            },
+            required: ['behaviorId', 'mechanism', 'rationale'],
+            additionalProperties: false,
+          },
+        },
+        rejectedMechanisms: {
+          type: 'array',
+          maxItems: 30,
+          description:
+            'Mechanisms already disproven by user-observed failure or prior verification. Do not silently reuse them.',
+          items: {
+            type: 'object',
+            properties: {
+              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
+              behaviorSignature: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 128,
+              },
+              mechanism: {
+                type: 'string',
+                enum: BEHAVIOR_MECHANISMS,
+              },
+              reason: { type: 'string', minLength: 5, maxLength: 800 },
+              source: {
+                type: 'string',
+                enum: ['user_reported_failure', 'verification_failure'],
+              },
+            },
+            required: ['mechanism', 'reason'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['summary', 'domains', 'verification'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_verify_interactions',
+    description:
+      'Verify the observable behavior contract from the live Framer tree. The runtime derives the required action and invariants from the planned behavior and mechanism; supply only canonical evidence node IDs. This is the only tool that can satisfy interaction verification.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pagePath: { type: 'string', maxLength: 500, default: '/' },
+        checks: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 20,
+          items: {
+            type: 'object',
+            properties: {
+              description: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+              behaviorId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 120,
+              },
+              triggerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              event: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 80,
+              },
+              targetNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              componentNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              instanceNodeIds: {
+                type: 'array',
+                maxItems: 50,
+                uniqueItems: true,
+                items: {
+                  type: 'string',
+                  minLength: 1,
+                  maxLength: 200,
+                },
+              },
+              openVariantNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              closedVariantNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              openAnswerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              closedAnswerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+            },
+            required: [
+              'behaviorId',
+              'triggerNodeId',
+              'event',
+            ],
+            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_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.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        changes: { type: 'string', minLength: 1, maxLength: 250_000 },
+        pagePath: { type: 'string', maxLength: 500, default: '/' },
+      },
+      required: ['changes'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_read',
+    description:
+      'Execute read-only JavaScript with the official Framer Agent connection for capabilities not covered by readProject.',
+    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 applyChanges, such as code files, localization, redirects, assets, CMS, or branch operations. Publishing is disabled unless Dexter explicitly authorizes it. If a write is rejected as unsafe, do not retry JavaScript variants; switch to 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 hostedSetupPromise = 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 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) {
+  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;
+  return {
+    path: normalized,
+    content: boundedText(fs.readFileSync(absolutePath, 'utf8'), maximum),
+  };
+}
+
+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 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, inheritedRejectedMechanisms = []) {
+  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.',
+    );
+  }
+  const verification = new Set(['structural', ...requestedVerification]);
+  if (
+    domains.some((domain) =>
+      ['visual', 'interactions', 'responsive'].includes(domain))
+  ) verification.add('visual');
+  if (domains.includes('links')) verification.add('links');
+  if (domains.includes('interactions')) verification.add('interactions');
+  if (domains.includes('responsive')) verification.add('responsive');
+  if (domains.includes('code')) verification.add('code');
+  if (domains.includes('data')) verification.add('data');
+  const behaviorPlan = normalizeBehaviorPlan(
+    rawArguments,
+    inheritedRejectedMechanisms,
+  );
+  if (
+    domains.includes('interactions')
+    && behaviorPlan.behaviors.length === 0
+  ) {
+    throw toolError(
+      'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
+      'Interaction work requires observable behaviors and one compatible mechanism decision per behavior.',
+    );
+  }
+  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([
+    context.activePageId,
+    ...(Array.isArray(context.selectedNodeIds)
+      ? context.selectedNodeIds
+      : []),
+    grant.activePageId,
+    ...(Array.isArray(grant.selectedNodeIds)
+      ? grant.selectedNodeIds
+      : []),
+    ...(Array.isArray(grant.contextNodeIds)
+      ? grant.contextNodeIds
+      : []),
+    ...(Array.isArray(grant.writableNodeIds)
+      ? grant.writableNodeIds
+      : []),
+  ]);
+}
+
+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(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 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 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,
+  authorizeProject,
+  verifyProjectAuthorization,
+} = {}) {
+  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 allowPublishing = assignment?.context?.permissions?.publish === true;
+  const inheritedRejectedMechanisms =
+    assignment?.context?.repairContext?.rejectedMechanisms
+    || assignment?.repairContext?.rejectedMechanisms
+    || [];
+  const authorizedInstanceContainerIds = uniqueStrings(
+    assignment?.context?.permissions?.scopedComponentArtifacts
+      ?.instanceContainerNodeIds
+      || assignment?.context?.contextGrant?.writableNodeIds
+      || [],
+  );
+  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 progressCalls = 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 instructionLookupUnavailable = false;
+  let branchChange = null;
+  let lastInspectionAt = null;
+  let lastMutationAt = null;
+  let screenshotCalls = 0;
+  let interactionVerificationCalls = 0;
+  let interactionVerification = {
+    completed: false,
+    verificationLevel: 'unverified',
+    checks: [],
+    behaviors: [],
+    verifiedAt: null,
+  };
+  const representativeVerifiedBehaviorIds = new Set();
+  const repeatedBehaviorVerificationFailures = new Map();
+  const mutationReceipts = [];
+  let screenshotBeforeMutation = false;
+  let lastScreenshotSequence = 0;
+  let taskPlan = null;
+  const verificationEvidence = new Map();
+  let guidanceMetadata = {
+    loaded: false,
+    contentHash: null,
+    projectContextHash: null,
+    files: [],
+    bytes: 0,
+  };
+  let promptMetadata = {
+    doctrineLoaded: false,
+    doctrineVersion: null,
+  };
+  const framerAgentVersion = installedFramerAgentVersion();
+  let operationSequence = 0;
+  let lastMutationSequence = 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 ensureHostedSetup = async () => {
+    if (env.DEXTER_HOSTED_FRAMER_AUTO_SETUP !== 'true') return;
+    if (hasInstalledFramerSkill(env)) return;
+    if (!hostedSetupPromise) {
+      reportActivity({
+        kind: 'status_update',
+        source: 'framer-agent',
+        message: 'Preparing the Framer harness.',
+      });
+      hostedSetupPromise = executeCli(['setup'], {
+        timeoutMs: 30_000,
+      }).catch((error) => {
+        hostedSetupPromise = null;
+        throw error;
+      });
+    }
+    await hostedSetupPromise;
+  };
+
+  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 ensureHostedSetup();
+    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);
+        }
+        created = await createSession();
+      } 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 };
+    }
+    const requestedFiles = [
+      { root: skillRoot, path: 'SKILL.md', label: 'SKILL.md' },
+      { root: projectRoot, path: 'index.md', label: 'project/index.md' },
+      {
+        root: projectRoot,
+        path: 'project-inventory.md',
+        label: 'project/project-inventory.md',
+      },
+      { root: projectRoot, path: 'prompt/core-principles.md' },
+      { root: projectRoot, path: 'prompt/core-examples.md' },
+      { root: projectRoot, path: 'prompt/implementation-strategy.md' },
+      { root: projectRoot, path: 'prompt/updating-the-project.md' },
+      { root: projectRoot, path: 'prompt/tools.md' },
+      { root: projectRoot, path: 'prompt/overview.md' },
+      { root: projectRoot, path: 'prompt/guardrails.md' },
+      { root: projectRoot, path: 'prompt/critical-reminders.md' },
+      ...(visualVerificationRequired
+        ? [
+            { root: projectRoot, path: 'prompt/design-rules.md' },
+            { root: projectRoot, path: 'prompt/how-projects-work.md' },
+          ]
+        : []),
+    ];
+    const files = [];
+    let remainingBytes = MAX_GUIDANCE_BYTES;
+    for (const requestedFile of requestedFiles) {
+      const loaded = readGuidanceFile(
+        requestedFile.root,
+        requestedFile.path,
+        remainingBytes,
+      );
+      if (!loaded) continue;
+      files.push({
+        ...loaded,
+        path: requestedFile.label || requestedFile.path,
+      });
+      remainingBytes -= Buffer.byteLength(loaded.content, 'utf8');
+      if (remainingBytes <= 0) break;
+    }
+    const content = files
+      .map((file) => `## ${file.path}\n\n${file.content}`)
+      .join('\n\n');
+    const inventory = files.find(
+      (file) => file.path.endsWith('project-inventory.md'),
+    )?.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),
+      bytes: Buffer.byteLength(content, 'utf8'),
+    };
+    return { content, ...guidanceMetadata };
+  };
+
+  const configurePromptContext = ({
+    doctrineLoaded = false,
+    doctrineVersion = null,
+  } = {}) => {
+    promptMetadata = {
+      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,
+      });
+    }
+  };
+
+  const validateAuthoritativeNodeIds = async () => {
+    await ensureSession();
+    if (authoritativeNodeIds.length === 0) return;
+    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) => {',
+          '  const node = await framer.agent.getNode({ id: requestedId },',
+          `    { pagePath: ${JSON.stringify(activePagePath)} }).catch(() => null);`,
+          '  return { requestedId, resolvedId: node?.id ?? null };',
+          '}));',
+          'console.log(JSON.stringify({ resolved }));',
+        ].join('\n'),
+        { timeoutMs: 30_000 },
+      );
+      const parsed = parseStructuredOutput(result.stdout);
+      const resolved = Array.isArray(parsed?.resolved)
+        ? parsed.resolved
+        : [];
+      const invalid = authoritativeNodeIds.filter((requestedId) => {
+        const match = resolved.find(
+          (entry) =>
+            isRecord(entry)
+            && entry.requestedId === requestedId,
+        );
+        return !match || match.resolvedId !== requestedId;
+      });
+      if (invalid.length > 0) {
+        throw toolError(
+          'FRAMER_AGENT_NODE_ID_INVALID',
+          `Dexter received Framer targets that do not resolve to exact native node IDs: ${invalid.join(', ')}. Re-select the affected layers in Framer and try again.`,
+          409,
+        );
+      }
+      reportActivity({
+        kind: 'status_update',
+        source: 'framer-agent',
+        message: 'The selected Framer layers are ready.',
+      });
+    })().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 markInspection = ({ visual = false, verifies = [] } = {}) => {
+    operationSequence += 1;
+    lastInspectionSequence = operationSequence;
+    lastInspectionAt = new Date().toISOString();
+    verificationEvidence.set('structural', operationSequence);
+    if (visual) {
+      screenshotCalls += 1;
+      lastScreenshotSequence = operationSequence;
+      verificationEvidence.set('visual', operationSequence);
+      if (lastMutationSequence === 0) screenshotBeforeMutation = true;
+    }
+    for (const check of normalizeVerificationValues(
+      verifies,
+      GENERIC_VERIFICATION_CHECKS,
+    )) {
+      verificationEvidence.set(check, operationSequence);
+    }
+  };
+
+  const markMutation = () => {
+    operationSequence += 1;
+    lastMutationSequence = 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,
+              expectedContent: [...behavior.expectedContent],
+            })),
+            mechanisms: taskPlan.mechanisms.map((decision) => ({
+              ...decision,
+            })),
+            rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
+              ...entry,
+            })),
+            compatibility: taskPlan.compatibility.map((entry) => ({
+              ...entry,
+              requiredCapabilities: [...entry.requiredCapabilities],
+            })),
+          }
+        : {}),
+    };
+  };
+  const synchronized = () =>
+    mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
+  const verificationCheckCompleted = (check) => {
+    if (mutationCalls === 0) return true;
+    if (check === 'structural') return synchronized();
+    if (check === 'visual') {
+      return (
+        screenshotBeforeMutation
+        && lastScreenshotSequence > lastMutationSequence
+      );
+    }
+    return Number(verificationEvidence.get(check) || 0) > lastMutationSequence;
+  };
+  const visualVerificationRequired = () =>
+    applyChangesCalls > 0
+    || requiredVerificationChecks().includes('visual');
+  const visualVerificationCompleted = () =>
+    !visualVerificationRequired()
+    || mutationCalls === 0
+    || (
+      screenshotBeforeMutation
+      && lastScreenshotSequence > lastMutationSequence
+    );
+  const missingVerificationChecks = () => {
+    if (mutationCalls === 0) return [];
+    const missing = [];
+    if (!taskPlan) missing.push('task-plan');
+    const required = new Set([
+      'structural',
+      ...requiredVerificationChecks(),
+      ...(applyChangesCalls > 0 ? ['visual'] : []),
+    ]);
+    for (const check of required) {
+      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: visualVerificationCompleted(),
+    screenshotCalls,
+    ...(requiredVerificationChecks().includes('interactions')
+      || interactionVerificationCalls > 0
+      ? {
+          interactionVerificationCalls,
+          interactionVerification: {
+            completed: verificationCheckCompleted('interactions'),
+            verificationLevel:
+              verificationCheckCompleted('interactions')
+                ? interactionVerification.verificationLevel
+                : 'unverified',
+            checks: interactionVerification.checks.map((check) => ({
+              ...check,
+              failures: [...check.failures],
+            })),
+            behaviors: interactionVerification.behaviors.map((behavior) => ({
+              ...behavior,
+              failures: [...behavior.failures],
+            })),
+            verifiedAt: interactionVerification.verifiedAt,
+          },
+        }
+      : {}),
+    taskPlan: taskPlanSnapshot(),
+    requiredChecks: [
+      ...new Set([
+        'structural',
+        ...requiredVerificationChecks(),
+        ...(applyChangesCalls > 0 ? ['visual'] : []),
+      ]),
+    ],
+    completedChecks: [
+      ...new Set([
+        'structural',
+        ...requiredVerificationChecks(),
+        ...(applyChangesCalls > 0 ? ['visual'] : []),
+      ]),
+    ].filter(verificationCheckCompleted),
+    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 finalizeCompletion = (completion) => {
+    if (
+      completion?.status !== 'completed'
+      || mutationCalls === 0
+      || verification().completed
+    ) {
+      return 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 'before-and-after screenshot verification';
+      return `post-mutation ${check} verification`;
+    });
+    const reason =
+      `The harness ended before completing ${missing.join(' and ')}.`;
+    return {
+      ...completion,
+      status: 'failed',
+      summary: `${String(completion?.summary || '').trim()} ${reason}`.trim(),
+      checks: [
+        ...(Array.isArray(completion?.checks) ? completion.checks : []),
+        {
+          command: 'Harness-owned final verification',
+          status: 'failed',
+          output: reason,
+        },
+      ],
+      blockedReason: null,
+    };
+  };
+
+  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(
+          screenshotBeforeMutation
+            ? 'capture and inspect the affected canvas after the latest mutation'
+            : 'report that the required baseline screenshot was missed; do not claim visual verification',
+        );
+      } else {
+        missing.push(
+          check === 'interactions'
+            ? 'call framer_verify_interactions with canonical evidence node IDs for every declared behavior and chosen mechanism'
+            : `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 ')}.`,
+      'Repair only concrete problems you observe, 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.',
+        'Use framer_query_images for approved stock imagery only after checking user attachments and suitable existing project images.',
+        'Use framer_apply_changes for layout and styling. Read its diagnostics, verify the result, and repair concrete issues.',
+        '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 === 'progress') progressCalls += 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 = ({ canvas = false } = {}) => {
+    if (!taskPlan) {
+      throw toolError(
+        'FRAMER_HARNESS_PLAN_REQUIRED',
+        'Inspect the live Framer target, then call framer_plan_task before making a mutation.',
+      );
+    }
+    if (
+      (canvas || taskPlan.verification.includes('visual'))
+      && !screenshotBeforeMutation
+    ) {
+      throw toolError(
+        'FRAMER_HARNESS_BASELINE_SCREENSHOT_REQUIRED',
+        'Capture and inspect a screenshot of the affected canvas before the first visual mutation.',
+      );
+    }
+    const rejectedSelectedMechanisms = taskPlan.behaviors.filter((behavior) => {
+      const selected = taskPlan.mechanisms.find((decision) =>
+        decision.behaviorId === behavior.id);
+      return selected && taskPlan.rejectedMechanisms.some((rejected) =>
+        rejected.mechanism === selected.mechanism
+        && (
+          rejected.behaviorId === behavior.id
+          || rejected.behaviorSignature === behavior.signature
+        ));
+    });
+    if (rejectedSelectedMechanisms.length > 0) {
+      throw toolError(
+        'FRAMER_BEHAVIOR_MECHANISM_REPLAN_REQUIRED',
+        `Choose a different mechanism for ${rejectedSelectedMechanisms.map((behavior) => behavior.id).join(', ')} before making another mutation.`,
+      );
+    }
+    if (mutationCalls > 0) {
+      const pendingRepresentative = taskPlan.behaviors
+        .filter((behavior) => behavior.expectedTargets > 1)
+        .filter((behavior) =>
+          taskPlan.mechanisms.find((decision) =>
+            decision.behaviorId === behavior.id
+            && decision.representativeFirst))
+        .filter((behavior) =>
+          !representativeVerifiedBehaviorIds.has(behavior.id));
+      if (pendingRepresentative.length > 0) {
+        throw toolError(
+          'FRAMER_BEHAVIOR_REPRESENTATIVE_VERIFICATION_REQUIRED',
+          `Verify one representative implementation for ${pendingRepresentative.map((behavior) => behavior.id).join(', ')} before batching further mutations.`,
+        );
+      }
+    }
+  };
+
+  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 =
+      name === 'framer_apply_changes' || name === 'framer_write';
+    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.',
+      );
+    }
+    if (name === 'progress_update') {
+      const message = String(rawArguments.message || '').trim().slice(0, 500);
+      if (!message) {
+        throw toolError(
+          'FRAMER_AGENT_PROGRESS_INVALID',
+          'A progress message is required.',
+        );
+      }
+      const toolCall = reserveToolCall(name, 'progress');
+      reportActivity({
+        kind: 'status_update',
+        source: 'harness',
+        message,
+      });
+      repeatedFailureFingerprint = null;
+      repeatedFailureCount = 0;
+      toolCall.status = 'succeeded';
+      return { acknowledged: true };
+    }
+
+    const startedAt = Date.now();
+    const toolCall = reserveToolCall(name, category);
+    reportActivity({
+      kind: 'tool_active',
+      source: 'framer-agent',
+      name,
+      phase: 'started',
+      message:
+        name === 'framer_apply_changes' || name === 'framer_write'
+          ? 'Updating the Framer project'
+          : name === 'framer_plan_task'
+            ? 'Planning the Framer work and verification'
+          : 'Inspecting the Framer project',
+    });
+    try {
+      let result;
+      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)
+          : [];
+        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_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,
+          inheritedRejectedMechanisms,
+        );
+        if (
+          mutationCalls > 0
+          && nextPlan.verification.includes('visual')
+          && !screenshotBeforeMutation
+        ) {
+          throw toolError(
+            'FRAMER_HARNESS_BASELINE_SCREENSHOT_REQUIRED',
+            'Visual verification cannot be added after mutations when no baseline screenshot was captured.',
+          );
+        }
+        const previousMechanisms = new Map(
+          (taskPlan?.mechanisms || []).map((decision) => [
+            decision.behaviorId,
+            decision.mechanism,
+          ]),
+        );
+        const behaviorPlan = mergeBehaviorPlans(taskPlan, nextPlan);
+        taskPlan = {
+          summary: nextPlan.summary,
+          domains: uniqueStrings([
+            ...(taskPlan?.domains || []),
+            ...nextPlan.domains,
+          ]),
+          verification: uniqueStrings([
+            ...(taskPlan?.verification || []),
+            ...nextPlan.verification,
+          ]),
+          ...behaviorPlan,
+        };
+        for (const decision of taskPlan.mechanisms) {
+          const prior = previousMechanisms.get(decision.behaviorId);
+          if (prior && prior !== decision.mechanism) {
+            representativeVerifiedBehaviorIds.delete(decision.behaviorId);
+          }
+        }
+        result = {
+          stdout: JSON.stringify({
+            plan: {
+              summary: taskPlan.summary,
+              domains: [...taskPlan.domains],
+              verification: [...taskPlan.verification],
+              behaviors: taskPlan.behaviors.map((behavior) => ({
+                ...behavior,
+                expectedContent: [...behavior.expectedContent],
+              })),
+              mechanisms: taskPlan.mechanisms.map((decision) => ({
+                ...decision,
+              })),
+              compatibility: taskPlan.compatibility.map((entry) => ({
+                ...entry,
+                requiredCapabilities: [...entry.requiredCapabilities],
+              })),
+              rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
+                ...entry,
+              })),
+            },
+            instruction:
+              'Implement one representative first when required, verify it, then complete coverage and gather every derived verification result after the final mutation.',
+          }),
+          stderr: '',
+        };
+      } else if (name === 'framer_verify_interactions') {
+        if (mutationCalls === 0) {
+          throw toolError(
+            'FRAMER_HARNESS_INTERACTION_MUTATION_REQUIRED',
+            'Verify interactions only after the relevant Framer mutation has succeeded.',
+          );
+        }
+        if (!taskPlan?.behaviors?.length) {
+          throw toolError(
+            'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
+            'Declare observable behaviors and compatible mechanisms with framer_plan_task before interaction verification.',
+          );
+        }
+        const checks = normalizeBehaviorEvidence(
+          rawArguments.checks,
+          taskPlan,
+        );
+        const pagePath = normalizePagePath(rawArguments.pagePath);
+        const requestedIds = evidenceNodeIds(checks);
+        const liveResult = await execCode(
+          [
+            `const requestedIds = ${JSON.stringify(requestedIds)};`,
+            'const nodes = await Promise.all(requestedIds.map(async (id) => ({',
+            '  id,',
+            '  node: await framer.agent.serialize({ id, depth: 8 },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null),`,
+            '  parentId: await framer.agent.getParentNode({ id },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).then((node) => node?.id ?? null).catch(() => null),`,
+            '  ancestorIds: await framer.agent.getAncestors({ id },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).then((nodes) => Array.isArray(nodes) ? nodes.map((node) => node?.id).filter(Boolean) : []).catch(() => []),`,
+            '})));',
+            'console.log(JSON.stringify({ nodes }, null, 2));',
+          ].join('\n'),
+        );
+        const parsed = parseStructuredOutput(liveResult.stdout);
+        const nodesById = new Map(
+          (Array.isArray(parsed?.nodes) ? parsed.nodes : [])
+            .filter((entry) => isRecord(entry) && typeof entry.id === 'string')
+            .map((entry) => [entry.id, {
+              node: entry.node || null,
+              parentId:
+                typeof entry.parentId === 'string'
+                  ? entry.parentId
+                  : null,
+              ancestorIds: Array.isArray(entry.ancestorIds)
+                ? entry.ancestorIds
+                : [],
+            }]),
+        );
+        const verified = verifyBehaviorEvidence({
+          plan: taskPlan,
+          checks,
+          snapshots: nodesById,
+          context: {
+            lowLevelWriteCalls,
+            authorizedInstanceContainerIds,
+          },
+        });
+        markInspection();
+        interactionVerificationCalls += 1;
+        interactionVerification = {
+          ...verified,
+          verifiedAt: new Date().toISOString(),
+        };
+        for (const behaviorResult of verified.behaviors) {
+          const failedChecks = verified.checks.filter((check) =>
+            check.behaviorId === behaviorResult.behaviorId && !check.passed);
+          if (failedChecks.length === 0) {
+            repeatedBehaviorVerificationFailures.delete(
+              behaviorResult.behaviorId,
+            );
+            continue;
+          }
+          const failureFingerprint = crypto
+            .createHash('sha256')
+            .update(JSON.stringify({
+              mechanism: behaviorResult.mechanism,
+              failures: failedChecks
+                .flatMap((check) => check.failures)
+                .sort(),
+            }))
+            .digest('hex');
+          const prior = repeatedBehaviorVerificationFailures.get(
+            behaviorResult.behaviorId,
+          );
+          const count =
+            prior?.fingerprint === failureFingerprint
+              ? prior.count + 1
+              : 1;
+          repeatedBehaviorVerificationFailures.set(
+            behaviorResult.behaviorId,
+            { fingerprint: failureFingerprint, count },
+          );
+          if (count < 2 || !behaviorResult.mechanism) continue;
+          const alreadyRejected = taskPlan.rejectedMechanisms.some((rejected) =>
+            rejected.mechanism === behaviorResult.mechanism
+            && (
+              rejected.behaviorId === behaviorResult.behaviorId
+              || rejected.behaviorSignature
+                === behaviorResult.behaviorSignature
+            ));
+          if (alreadyRejected) continue;
+          taskPlan = {
+            ...taskPlan,
+            rejectedMechanisms: [
+              ...taskPlan.rejectedMechanisms,
+              {
+                behaviorId: behaviorResult.behaviorId,
+                behaviorSignature: behaviorResult.behaviorSignature,
+                mechanism: behaviorResult.mechanism,
+                reason:
+                  `Repeated structural verification failed: ${failedChecks
+                    .flatMap((check) => check.failures)
+                    .join('; ')
+                    .slice(0, 700)}`,
+                source: 'verification_failure',
+              },
+            ],
+          };
+        }
+        verified.representativeBehaviorIds.forEach((behaviorId) =>
+          representativeVerifiedBehaviorIds.add(behaviorId));
+        if (interactionVerification.completed) {
+          verificationEvidence.set('interactions', operationSequence);
+        } else {
+          verificationEvidence.delete('interactions');
+        }
+        result = {
+          stdout: JSON.stringify(interactionVerification),
+          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 execCode(
+          [
+            `const result = await framer.agent.readProject(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });`,
+            'console.log(JSON.stringify(result, null, 2));',
+          ].join('\n'),
+        );
+        markInspection({
+          visual: queries.some((query) => query.type === 'screenshot'),
+          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_apply_changes') {
+        const changes = String(rawArguments.changes || '').trim();
+        if (!changes) {
+          throw toolError(
+            'FRAMER_AGENT_CHANGES_REQUIRED',
+            'Framer Agent changes are required.',
+          );
+        }
+        requireTaskPlanForMutation({ canvas: true });
+        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),
+        });
+      } else if (name === 'framer_read') {
+        result = await execCode(
+          validateCode(rawArguments.code, {
+            write: false,
+            allowPublishing,
+          }),
+        );
+        markInspection({ verifies: rawArguments.verifies });
+      } else if (name === 'framer_write') {
+        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:
+          name === 'framer_apply_changes' || name === 'framer_write'
+            ? 'Updated the Framer project'
+            : 'Finished inspecting the Framer project',
+        durationMs,
+      });
+      return normalizedResult(result);
+    } 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';
+      trace?.warn?.('framer_agent_tool_failed', {
+        name,
+        code: error?.code,
+        message: error?.message,
+      });
+      reportActivity({
+        kind: 'tool_active',
+        source: 'framer-agent',
+        name,
+        phase: 'failed',
+        message:
+          name === 'framer_apply_changes' || name === 'framer_write'
+            ? '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,
+    sourceHash: () => null,
+    hasPendingChanges: () => false,
+    directWorkspace: true,
+    summary: () => ({
+      projectId,
+      projectUrl,
+      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,
+      progressCalls,
+      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,
+      },
+      branch: branchChange,
+      lastInspectionAt,
+      lastMutationAt,
+      taskPlan: taskPlanSnapshot(),
+      verification: verification(),
+      framerAgentVersion,
+      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,
+      },
+      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();
+  hostedSetupPromise = null;
+}