@gakim-digital/dexter-bridge 0.5.21 → 0.11.0

package/src/framerAgentTools.js

@@ -0,0 +1,1108 @@
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60_000;
+const SESSION_TIMEOUT_MS = 10 * 60_000;
+const AUTHORIZATION_TIMEOUT_MS = 10 * 60_000;
+const AUTHORIZATION_POLL_MS = 2_000;
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9_-]{1,200}$/;
+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 EMPTY_SCHEMA = {
+  type: 'object',
+  properties: {},
+  additionalProperties: false,
+};
+
+export const FRAMER_AGENT_TOOL_DEFINITIONS = [
+  {
+    name: 'progress_update',
+    description:
+      'Tell the user what you are doing and why it matters in one or two natural first-person sentences. 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:
+      'Load Framer’s official agent command reference. Call this before the first canvas change unless the current session already established the command syntax.',
+    inputSchema: EMPTY_SCHEMA,
+  },
+  {
+    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: '/' },
+      },
+      required: ['queries'],
+      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 },
+      },
+      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.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', minLength: 1, maxLength: 200_000 },
+      },
+      required: ['code'],
+      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 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 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 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 wait(delayMs, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError());
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, Math.max(0, delayMs));
+    timer.unref?.();
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function authorizationUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value || ''));
+  } catch {
+    throw toolError(
+      'FRAMER_AGENT_AUTHORIZATION_URL_INVALID',
+      'Dexter received an invalid Framer authorization URL.',
+      502,
+    );
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  const trusted =
+    hostname === 'framer.com'
+    || hostname.endsWith('.framer.com')
+    || hostname === 'framerlocal.com'
+    || hostname.endsWith('.framerlocal.com');
+  if (
+    parsed.protocol !== 'https:'
+    || parsed.username
+    || parsed.password
+    || !trusted
+  ) {
+    throw toolError(
+      'FRAMER_AGENT_AUTHORIZATION_URL_INVALID',
+      'Dexter blocked an untrusted Framer authorization URL.',
+      502,
+    );
+  }
+  return parsed.toString();
+}
+
+export function openFramerAuthorizationUrl(
+  value,
+  {
+    platform = process.platform,
+    spawnImpl = spawn,
+  } = {},
+) {
+  const url = authorizationUrl(value);
+  const command =
+    platform === 'darwin'
+      ? '/usr/bin/open'
+      : platform === 'win32'
+        ? 'rundll32.exe'
+        : 'xdg-open';
+  const args =
+    platform === 'win32'
+      ? ['url.dll,FileProtocolHandler', url]
+      : [url];
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, {
+      stdio: 'ignore',
+      detached: true,
+      windowsHide: true,
+    });
+    child.once?.('error', (error) => reject(error));
+    child.once?.('spawn', () => {
+      child.unref?.();
+      resolve(true);
+    });
+  });
+}
+
+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'
+    || error?.code === 'FRAMER_AGENT_PROJECT_NOT_FOUND'
+    || /authoriz|log in|login|api key|project not found|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',
+      'Framer could not authorize this project. Make sure the browser is signed into an account with access to the open project, then reconnect it in Dexter.',
+      409,
+    );
+  }
+  return error;
+}
+
+export function createFramerAgentToolRuntime({
+  assignment,
+  cwd,
+  env = process.env,
+  trace,
+  onActivity,
+  runCli = runFramerAgentCli,
+  authorizeProject,
+  openAuthorizationUrl = openFramerAuthorizationUrl,
+  authorizationTimeoutMs = AUTHORIZATION_TIMEOUT_MS,
+} = {}) {
+  const projectId = normalizeProjectId(assignment?.context?.framerProjectId);
+  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 definitions = FRAMER_AGENT_TOOL_DEFINITIONS.filter((tool) =>
+    allowedToolNames.has(tool.name),
+  );
+  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 readCalls = 0;
+  let branchChange = null;
+  let lastInspectionAt = null;
+  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 (!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 acquireProjectAuthorization = async ({ forceRefresh = false } = {}) => {
+    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,
+      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') {
+      const url = authorizationUrl(authorization.authUrl);
+      reportActivity({
+        kind: 'status_update',
+        source: 'framer-agent',
+        message:
+          'Approve access to this Framer project in the browser. Dexter will continue automatically.',
+      });
+      try {
+        await openAuthorizationUrl(url);
+      } catch {
+        throw toolError(
+          'FRAMER_AGENT_AUTHORIZATION_OPEN_FAILED',
+          'Dexter could not open Framer authorization in the browser. Reconnect this project from Dexter settings.',
+          409,
+        );
+      }
+      const configuredExpiry = new Date(
+        String(authorization.expiresAt || ''),
+      ).getTime();
+      const deadline = Math.min(
+        Number.isFinite(configuredExpiry)
+          ? configuredExpiry
+          : Date.now() + authorizationTimeoutMs,
+        Date.now() + authorizationTimeoutMs,
+      );
+      while (
+        authorization?.status === 'authorization_required'
+        && Date.now() < deadline
+      ) {
+        await wait(
+          Math.max(
+            500,
+            Math.min(
+              5_000,
+              Number(authorization.pollIntervalMs) || AUTHORIZATION_POLL_MS,
+            ),
+          ),
+          abortController.signal,
+        );
+        authorization = await authorizeProject({
+          projectId,
+          initiate: false,
+          forceRefresh: false,
+          signal: abortController.signal,
+        });
+      }
+    }
+    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,
+      );
+    }
+    await executeCli(['project', 'auth', projectId, apiKey], {
+      timeoutMs: 30_000,
+    });
+    reportActivity({
+      kind: 'status_update',
+      source: 'framer-agent',
+      message: 'This Framer project is authorized for the local harness.',
+    });
+  };
+
+  const createSession = async () => {
+    return executeCli(['session', 'new', projectId], {
+      timeoutMs: SESSION_TIMEOUT_MS,
+    });
+  };
+
+  const ensureSession = async () => {
+    await ensureHostedSetup();
+    if (sessionId) return sessionId;
+    const cached = sessionsByProject.get(projectId);
+    if (cached) {
+      sessionId = cached;
+      return sessionId;
+    }
+    if (sessionPromise) return sessionPromise;
+    sessionPromise = (async () => {
+      reportActivity({
+        kind: 'status_update',
+        source: 'framer-agent',
+        message: 'Connecting the coding harness to this Framer project.',
+      });
+      if (!(await projectIsAuthorizedLocally())) {
+        await acquireProjectAuthorization();
+      }
+      let created;
+      try {
+        created = await createSession();
+      } catch (error) {
+        if (isAuthorizationFailure(error)) {
+          await acquireProjectAuthorization({ forceRefresh: true });
+          try {
+            created = await createSession();
+          } catch (retryError) {
+            throw projectConnectionError(retryError);
+          }
+        } else {
+          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,
+        );
+      }
+      sessionsByProject.set(projectId, sessionId);
+      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 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(projectId);
+      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, 200_000) } : { result: parsed }),
+      ...(result.stderr.trim()
+        ? { diagnostics: boundedText(result.stderr, 20_000) }
+        : {}),
+      ...(branchChange ? { branch: branchChange } : {}),
+    };
+  };
+
+  const markInspection = () => {
+    operationSequence += 1;
+    lastInspectionSequence = operationSequence;
+    lastInspectionAt = new Date().toISOString();
+  };
+
+  const markMutation = () => {
+    operationSequence += 1;
+    lastMutationSequence = operationSequence;
+  };
+
+  const synchronized = () =>
+    mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
+
+  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.',
+      );
+    }
+    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.',
+        );
+      }
+      reportActivity({
+        kind: 'status_update',
+        source: 'harness',
+        message,
+      });
+      return { acknowledged: true };
+    }
+
+    const startedAt = Date.now();
+    reportActivity({
+      kind: 'tool_active',
+      source: 'framer-agent',
+      name,
+      phase: 'started',
+      message:
+        name === 'framer_apply_changes' || name === 'framer_write'
+          ? 'Updating the Framer project'
+          : 'Inspecting the Framer project',
+    });
+    try {
+      let result;
+      if (name === 'framer_instructions') {
+        readCalls += 1;
+        result = await execCode(
+          'console.log(await framer.agent.getSystemPrompt())',
+        );
+      } else if (name === 'framer_context') {
+        readCalls += 1;
+        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_read_project') {
+        readCalls += 1;
+        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();
+      } 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.',
+          );
+        }
+        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;
+        markMutation();
+      } else if (name === 'framer_read') {
+        readCalls += 1;
+        result = await execCode(
+          validateCode(rawArguments.code, {
+            write: false,
+            allowPublishing,
+          }),
+        );
+        markInspection();
+      } else if (name === 'framer_write') {
+        result = await execCode(
+          validateCode(rawArguments.code, {
+            write: true,
+            allowPublishing,
+          }),
+        );
+        mutationCalls += 1;
+        markMutation();
+      } else {
+        throw toolError(
+          'FRAMER_AGENT_TOOL_UNKNOWN',
+          `Unknown Framer Agent tool: ${name}`,
+        );
+      }
+      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: Date.now() - startedAt,
+      });
+      return normalizedResult(result);
+    } catch (error) {
+      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,
+    invoke,
+    startGateway,
+    synchronize: async () => ({
+      synchronized: synchronized(),
+      sourceHash: null,
+      changed: mutationCalls > 0,
+    }),
+    inspect: async () => ({
+      synchronized: synchronized(),
+      sourceHash: null,
+      changed: mutationCalls > 0,
+      mutationCalls,
+      readCalls,
+      branch: branchChange,
+      lastInspectionAt,
+    }),
+    sourceHash: () => null,
+    hasPendingChanges: () => false,
+    directWorkspace: true,
+    summary: () => ({
+      projectId,
+      mutationCalls,
+      readCalls,
+      branch: branchChange,
+      lastInspectionAt,
+    }),
+    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;
+}