@gakim-digital/dexter-bridge 0.11.16 → 0.11.19

package/src/framerAgentTools.js

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import jsTokens from 'js-tokens';
+import { loadGoogleFontsCatalog, searchGoogleFonts } from './googleFontsFallback.js';
 import {
   canonicalIdMappings,
   evidenceNodeIds,
@@ -49,7 +50,7 @@ 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*\(/;
+  /\.(?:(?:set|add|delete|join|apply)(?:[A-Z_][A-Za-z0-9_]*)|(?:create|remove|update|insert|move|clone|duplicate|upload|publish|deploy|switch|merge|rename|leave)[A-Za-z0-9_]*)\s*\(/;
 const CODE_FILE_SOURCE_WRITE_PATTERN =
   /(?:\.setFileContent|\[\s*['"]setFileContent['"]\s*\])\s*\(/;
 const TASK_DOMAINS = [
@@ -81,19 +82,6 @@ const EMPTY_SCHEMA = {
 };
 
 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:
@@ -124,7 +112,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_read_project',
     description:
-      'Run Framer Agent readProject queries against the connected project. Use this for focused canvas inspection and screenshots.',
+      'Run Framer Agent readProject queries: "screenshot", "font-search", and "implementation-guide-from-index" are the only query types. Read nodes and layout with framer_read instead.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -148,6 +136,24 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'framer_read_website',
+    description:
+      'Read one page of a website the user named: exact copy per section, fonts and text styles, colours, image URLs (including CSS backgrounds), and desktop and phone screenshots. Use it before recreating or migrating that page. Only sites the user named can be read.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', minLength: 1, maxLength: 2048 },
+        screenshotTop: {
+          type: 'integer',
+          minimum: 0,
+          description: 'Desktop page offset in pixels for the screenshots. Use the value the previous result suggests to see further down.',
+        },
+      },
+      required: ['url'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'framer_plan_task',
     description:
@@ -210,7 +216,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_verify_interactions',
     description:
-      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
+      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap, or a field inside one such as link.href or hoverEffect.opacity) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -270,12 +276,20 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     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.',
+      'Apply Framer Agent DSL changes directly to the connected project. Prefer this for page, layout, style, design-token, component, and CMS-on-canvas work. Pass screenshotNodeIds to get screenshots of those nodes taken after the change in the same result, instead of a separate read.',
     inputSchema: {
       type: 'object',
       properties: {
         changes: { type: 'string', minLength: 1, maxLength: 250_000 },
         pagePath: { type: 'string', maxLength: 500, default: '/' },
+        screenshotNodeIds: {
+          type: 'array',
+          maxItems: MAX_SCREENSHOTS_PER_CALL,
+          uniqueItems: true,
+          items: { type: 'string', minLength: 1, maxLength: 200 },
+          description:
+            'Nodes (or component variants) to screenshot after the change is applied. The screenshots count as visual evidence after this mutation.',
+        },
       },
       required: ['changes'],
       additionalProperties: false,
@@ -342,7 +356,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_read',
     description:
-      'Execute read-only JavaScript with the official Framer Agent connection for capabilities not covered by readProject.',
+      'Execute read-only JavaScript with the official Framer Agent connection. Use it to read nodes and layout, for example with framer.agent.getNode, serialize, or serializeNodes; combine several reads in one script.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -521,12 +535,21 @@ function onDemandGuideCatalog(projectRoot) {
   return catalog;
 }
 
+// Returns a "## " or "### " section up to the next heading of the same or a
+// higher level.
 function markdownSection(markdown, heading) {
   const lines = markdown.split('\n');
-  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
+  const headingLevel = (line) => /^(#{1,6}) /.exec(line)?.[1].length || 0;
+  const start = lines.findIndex(
+    (line) => headingLevel(line) >= 2
+      && line.trim().replace(/^#+ /, '') === heading,
+  );
   if (start < 0) return '';
+  const level = headingLevel(lines[start]);
   const end = lines.findIndex(
-    (line, index) => index > start && line.startsWith('## '),
+    (line, index) => index > start
+      && headingLevel(line) > 0
+      && headingLevel(line) <= level,
   );
   return lines.slice(start, end < 0 ? undefined : end).join('\n').trim();
 }
@@ -1129,6 +1152,7 @@ export function createFramerAgentToolRuntime({
   fetchImpl = fetch,
   authorizeProject,
   verifyProjectAuthorization,
+  readWebsite,
 } = {}) {
   const projectId = normalizeProjectId(assignment?.context?.framerProjectId);
   const projectUrl = normalizeProjectUrl(
@@ -1177,7 +1201,6 @@ export function createFramerAgentToolRuntime({
   let lowLevelWriteCalls = 0;
   let imageSearchCalls = 0;
   let readCalls = 0;
-  let progressCalls = 0;
   let toolCallCount = 0;
   const toolCalls = [];
   let repeatedFailureFingerprint = null;
@@ -1188,6 +1211,7 @@ export function createFramerAgentToolRuntime({
   let lowLevelWriteDisabled = false;
   let lowLevelWriteBlockedCalls = 0;
   let instructionFallbacks = 0;
+  let fontSearchFallbacks = 0;
   let instructionLookupUnavailable = false;
   let branchChange = null;
   let lastInspectionAt = null;
@@ -1537,14 +1561,23 @@ export function createFramerAgentToolRuntime({
     // Every run gets the guidance an edit always needs: principles, command
     // syntax, tool APIs, scope and replica rules, and the edit loop. Topic
     // guides (CMS, components, creation strategy, examples, ...) are listed
-    // in a catalog and read on demand through framer_instructions.
+    // in a catalog and read on demand through framer_instructions. The CLI,
+    // session, and file-map parts of SKILL.md and index.md do not apply to
+    // Dexter's tools, and index.md changes every session, so both are left
+    // out; the guidance stays byte-identical across runs and can be cached.
+    // The project inventory changes with the project and is returned apart.
     const requestedFiles = [
-      { root: skillRoot, path: 'SKILL.md', label: 'SKILL.md' },
-      { root: projectRoot, path: 'index.md', label: 'project/index.md' },
       {
-        root: projectRoot,
-        path: 'project-inventory.md',
-        label: 'project/project-inventory.md',
+        root: skillRoot,
+        path: 'SKILL.md',
+        section: 'Method Selection',
+        label: 'SKILL.md#Method Selection',
+      },
+      {
+        root: skillRoot,
+        path: 'SKILL.md',
+        section: 'Core Usage Principles',
+        label: 'SKILL.md#Core Usage Principles',
       },
       { root: projectRoot, path: 'prompt/overview.md' },
       { root: projectRoot, path: 'prompt/core-principles.md' },
@@ -1590,8 +1623,10 @@ export function createFramerAgentToolRuntime({
       ...files.map((file) => `## ${file.path}\n\n${file.content}`),
       ...(catalogText ? [catalogText] : []),
     ].join('\n\n');
-    const inventory = files.find(
-      (file) => file.path.endsWith('project-inventory.md'),
+    const inventory = readGuidanceFile(
+      projectRoot,
+      'project-inventory.md',
+      MAX_GUIDANCE_FILE_BYTES,
     )?.content || '';
     guidanceMetadata = {
       loaded: Boolean(content),
@@ -1601,10 +1636,13 @@ export function createFramerAgentToolRuntime({
       projectContextHash: inventory
         ? crypto.createHash('sha256').update(inventory).digest('hex')
         : null,
-      files: files.map((file) => file.path),
-      bytes: Buffer.byteLength(content, 'utf8'),
+      files: [
+        ...files.map((file) => file.path),
+        ...(inventory ? ['project/project-inventory.md'] : []),
+      ],
+      bytes: Buffer.byteLength(content + inventory, 'utf8'),
     };
-    return { content, ...guidanceMetadata };
+    return { content, inventory, ...guidanceMetadata };
   };
 
   const configurePromptContext = ({
@@ -1717,7 +1755,74 @@ export function createFramerAgentToolRuntime({
         capture: captured.error,
       });
     }
-    return { images, viaDownload, viaSession, undelivered, failures };
+    screenshotsViaDownload += viaDownload;
+    screenshotsViaSession += viaSession;
+    screenshotsUndelivered += undelivered;
+    screenshotFailures.push(...failures);
+    screenshotFailures.splice(
+      0,
+      Math.max(0, screenshotFailures.length - MAX_SCREENSHOT_FAILURES_REPORTED),
+    );
+    return images;
+  };
+
+  const readProject = (queries, pagePath) => execCode(
+    [
+      `const result = await framer.agent.readProject(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });`,
+      'console.log(JSON.stringify(result, null, 2));',
+    ].join('\n'),
+  );
+
+  // Runs readProject screenshot queries and hands the pixels to the model.
+  const readScreenshots = async (queries, pagePath) => {
+    const result = await readProject(queries, pagePath);
+    return deliverScreenshots(queries, parseStructuredOutput(result.stdout));
+  };
+
+  // Framer bills style font searches to the workspace's AI credit and fails
+  // the whole read when they cannot run. Those searches are then answered
+  // from the Google Fonts catalog and the remaining queries are read again.
+  // Returns null when there is nothing to answer, so the original error stands.
+  const readProjectWithFontFallback = async (queries, pagePath) => {
+    try {
+      return await readProject(queries, pagePath);
+    } catch (error) {
+      const styleSearch = (query) =>
+        query.type === 'font-search' && typeof query.query === 'string';
+      if (!queries.some(styleSearch)) throw error;
+      let catalog;
+      try {
+        catalog = await loadGoogleFontsCatalog(fetchImpl);
+      } catch (catalogError) {
+        trace?.warn?.('google_fonts_fallback_unavailable', {
+          message: catalogError?.message,
+        });
+        throw error;
+      }
+      const remaining = queries.filter((query) => !styleSearch(query));
+      const remainingResults = remaining.length
+        ? parseStructuredOutput((await readProject(remaining, pagePath)).stdout)?.results || []
+        : [];
+      fontSearchFallbacks += 1;
+      trace?.warn?.('framer_font_search_fallback', {
+        message: boundedText(String(error?.message || ''), 300),
+      });
+      const reason = boundedText(String(error?.message || 'unavailable'), 160);
+      let next = 0;
+      return {
+        stdout: JSON.stringify({
+          results: queries.map((query) => (styleSearch(query)
+            ? {
+                type: 'font-search',
+                source: 'google-fonts',
+                note: `Framer's style font search failed (${reason}), so these candidates come from the Google Fonts library, which Framer includes. Choose by how the family looks, set fontName to it, and use a listed weight. If you know a Google Fonts family that fits better, confirm it with a font-search by name.`,
+                results: searchGoogleFonts(catalog, query),
+              }
+            : remainingResults[next++] ?? null)),
+        }),
+        stderr: '',
+      };
+    }
   };
 
   const referenceAssetFiles = Array.isArray(assignment?.context?.referenceAssetFiles)
@@ -2086,6 +2191,17 @@ export function createFramerAgentToolRuntime({
     ].join(' ');
   };
 
+  const evidenceRequirement = (check) => {
+    if (check === 'structural') return 'a focused live read';
+    if (check === 'visual') {
+      return 'a screenshot you inspect (screenshotNodeIds on your last framer_apply_changes provides it)';
+    }
+    if (check === 'interactions') {
+      return 'framer_verify_interactions for every declared behavior and target node';
+    }
+    return `a read tagged with verifies:["${check}"]`;
+  };
+
   const verificationRepairPrompt = () => {
     const current = verification();
     if (current.completed || mutationCalls === 0) return null;
@@ -2154,7 +2270,6 @@ export function createFramerAgentToolRuntime({
 
   const reserveToolCall = (name, category) => {
     toolCallCount += 1;
-    if (category === 'progress') progressCalls += 1;
     if (category === 'read') readCalls += 1;
     const call = {
       sequence: toolCallCount,
@@ -2219,25 +2334,6 @@ export function createFramerAgentToolRuntime({
         '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);
@@ -2256,6 +2352,7 @@ export function createFramerAgentToolRuntime({
     try {
       let result;
       let modelImages = [];
+      let screenshotRequestCount = 0;
       if (name === 'framer_write' && lowLevelWriteDisabled) {
         lowLevelWriteBlockedCalls += 1;
         throw toolError(
@@ -2324,6 +2421,23 @@ export function createFramerAgentToolRuntime({
           if (queries.length > 0) instructionFallbacks += 1;
           result = builtInInstructions(queries.length > 0);
         }
+      } else if (name === 'framer_read_website') {
+        if (typeof readWebsite !== 'function') {
+          throw toolError(
+            'FRAMER_WEBSITE_READ_UNAVAILABLE',
+            'Reading websites is not available in this run.',
+          );
+        }
+        const website = await readWebsite({
+          url: String(rawArguments.url || '').trim(),
+          screenshotTop: Number.isInteger(rawArguments.screenshotTop)
+            ? rawArguments.screenshotTop
+            : undefined,
+        });
+        modelImages = (Array.isArray(website?.images) ? website.images : [])
+          .filter((image) => typeof image?.data === 'string' && image.data)
+          .map((image) => ({ url: null, mimeType: image.mimeType || 'image/jpeg', data: image.data }));
+        result = { stdout: JSON.stringify(website?.result ?? {}), stderr: '' };
       } else if (name === 'framer_context') {
         result = await execCode(
           [
@@ -2356,7 +2470,10 @@ export function createFramerAgentToolRuntime({
           ...mergeBehaviorPlans(taskPlan, nextPlan),
         };
         result = {
-          stdout: JSON.stringify({ plan: taskPlanSnapshot() }),
+          stdout: JSON.stringify({
+            plan: taskPlanSnapshot(),
+            beforeFinishing: `After your final change, and before returning, produce: ${requiredChecks().map(evidenceRequirement).join('; ')}.`,
+          }),
           stderr: '',
         };
       } else if (name === 'framer_verify_interactions') {
@@ -2386,7 +2503,15 @@ export function createFramerAgentToolRuntime({
             .map((entry) => [entry.id, entry.node]),
         );
         const results = verifyBehaviorChecks({ checks, nodes });
-        markInspection();
+        // Live link values read here are link evidence too, so the model does
+        // not spend another turn re-reading them under verifies:["links"].
+        const linkChecks = results.filter((check) => /^link(\.|$)/.test(check.property));
+        markInspection({
+          verifies: linkChecks.length > 0
+            && linkChecks.every((check) => check.verdict === 'verified')
+            ? ['links']
+            : [],
+        });
         interactionVerificationCalls += 1;
         interactionVerifiedAt = new Date().toISOString();
         for (const checkResult of results) {
@@ -2415,28 +2540,15 @@ export function createFramerAgentToolRuntime({
           );
         }
         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'),
-        );
+        result = await readProjectWithFontFallback(queries, pagePath);
         const requestedScreenshots = screenshotQueries(rawArguments);
-        const delivery = requestedScreenshots.length
+        screenshotRequestCount = requestedScreenshots.length;
+        modelImages = requestedScreenshots.length
           ? await deliverScreenshots(
               requestedScreenshots,
               parseStructuredOutput(result.stdout),
             )
-          : { images: [], viaDownload: 0, viaSession: 0, undelivered: 0, failures: [] };
-        modelImages = delivery.images;
-        screenshotsViaDownload += delivery.viaDownload;
-        screenshotsViaSession += delivery.viaSession;
-        screenshotsUndelivered += delivery.undelivered;
-        screenshotFailures.push(...delivery.failures);
-        screenshotFailures.splice(
-          0,
-          Math.max(0, screenshotFailures.length - MAX_SCREENSHOT_FAILURES_REPORTED),
-        );
+          : [];
         markInspection({
           visual: modelImages.length > 0,
           visualAttempted: requestedScreenshots.length > 0,
@@ -2832,6 +2944,20 @@ export function createFramerAgentToolRuntime({
           ...summarizeFramerChanges(changes),
           renamedIds: canonicalIdMappings(parsedResult),
         });
+        // A screenshot taken here saves the model a whole turn re-reading
+        // its context just to look at the change.
+        const screenshotIds = Array.isArray(rawArguments.screenshotNodeIds)
+          ? uniqueStrings(rawArguments.screenshotNodeIds, MAX_SCREENSHOTS_PER_CALL)
+          : [];
+        if (screenshotIds.length > 0) {
+          const queries = screenshotIds.map((id) => ({ type: 'screenshot', id }));
+          modelImages = await readScreenshots(queries, pagePath);
+          screenshotRequestCount = queries.length;
+          markInspection({
+            visual: modelImages.length > 0,
+            visualAttempted: true,
+          });
+        }
       } else if (name === 'framer_read') {
         result = await execCode(
           validateCode(rawArguments.code, {
@@ -2898,17 +3024,25 @@ export function createFramerAgentToolRuntime({
       // Result size is what this call adds to every later model turn.
       toolCall.resultBytes = Buffer.byteLength(JSON.stringify(normalized), 'utf8');
       if (modelImages.length > 0) toolCall.imageCount = modelImages.length;
-      if (name !== 'framer_read_project') return normalized;
-      const screenshotCount = screenshotQueries(rawArguments).length;
+      if (name === 'framer_read_website') {
+        return modelImages.length ? { ...normalized, modelImages } : normalized;
+      }
+      // Naming the evidence still owed after the latest change lets the model
+      // finish it in this session instead of in a resumed repair turn.
+      const evidenceStillDue =
+        taskPlan && mutationCalls > 0 && (category === 'read' || screenshotRequestCount > 0)
+          ? missingVerificationChecks()
+          : [];
       return {
         ...normalized,
         ...(modelImages.length ? { modelImages } : {}),
-        ...(screenshotCount > modelImages.length
+        ...(screenshotRequestCount > modelImages.length
           ? {
               screenshotWarning:
-                `${screenshotCount - modelImages.length} screenshot(s) could not be downloaded for you to view. Treat that visual state as unverified.`,
+                `${screenshotRequestCount - modelImages.length} screenshot(s) could not be downloaded for you to view. Treat that visual state as unverified.`,
             }
           : {}),
+        ...(evidenceStillDue.length > 0 ? { evidenceStillDue } : {}),
       };
     } catch (error) {
       if (
@@ -2955,6 +3089,10 @@ export function createFramerAgentToolRuntime({
       }
       toolCall.durationMs = Date.now() - startedAt;
       toolCall.errorCode = error?.code || 'FRAMER_AGENT_TOOL_FAILED';
+      toolCall.errorMessage = boundedText(
+        String(error?.message || 'Framer Agent tool failed.'),
+        300,
+      );
       trace?.warn?.('framer_agent_tool_failed', {
         name,
         code: error?.code,
@@ -3082,7 +3220,6 @@ export function createFramerAgentToolRuntime({
           : {}),
       })),
       readCalls,
-      progressCalls,
       toolCallCount,
       toolDurationMs: toolCalls.reduce(
         (total, call) => total + call.durationMs,
@@ -3110,6 +3247,7 @@ export function createFramerAgentToolRuntime({
         lowLevelWriteBlockedCalls,
         instructionFallbacks,
       },
+      fontSearchFallbacks,
       branch: branchChange,
       lastInspectionAt,
       lastMutationAt,

package/src/framerBehaviorContract.js

@@ -110,8 +110,22 @@ function hasContent(value) {
 }
 
 // Finds the property on the node itself. Child nodes are skipped so a
-// descendant cannot satisfy a claim about its parent.
+// descendant cannot satisfy a claim about its parent. A dotted name such as
+// `link.href` or `hoverEffect.opacity`, the way the change language writes
+// it, reads the field inside the property's value.
 function propertyValues(node, property) {
+  const values = keyValues(node, property);
+  const [head, ...path] = property.split('.');
+  if (values.length > 0 || path.length === 0) return values;
+  return keyValues(node, head)
+    .map((value) => path.reduce(
+      (current, key) => (isRecord(current) ? current[key] : undefined),
+      value,
+    ))
+    .filter(hasContent);
+}
+
+function keyValues(node, property) {
   const values = [];
   const visit = (current, depth) => {
     if (depth > MAX_SEARCH_DEPTH || values.length >= 10) return;