@gakim-digital/dexter-bridge 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gakim-digital/dexter-bridge",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Local bridge for InstaWebAI and Dexter — runs Codex, Claude Code, or OpenCode on your machine.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import crossSpawn from 'cross-spawn';
 import {
-  callWebflowPanelTool,
+  callPanelTool,
   findWebflowImages,
   getFramerProjectAuthorization,
   webflowMcpEndpoint,
@@ -2385,6 +2385,10 @@ async function executeModelTurn(run, send, agent, options = {}) {
   });
 }
 
+// Rounds in which a model that finished with unmet checks is sent back to fix
+// them, within the run's time limit.
+const OUTCOME_REPAIR_ROUNDS = 3;
+
 async function executeOutcomeRun(run, send, agent, options = {}) {
   const product = normalizeBridgeProduct(run?.product || options.product);
   const definition = definitionForRuntimeProfile(run?.runtimeProfile, agent);
@@ -2745,6 +2749,20 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
                   allowInsecureHttp: options.allowInsecureHttp,
                 })
             : undefined,
+        callPanelTool:
+          options.apiBaseUrl && options.deviceToken
+            ? ({ callId, name, arguments: toolArguments, signal }) =>
+                callPanelTool(options.apiBaseUrl, {
+                  deviceToken: options.deviceToken,
+                  runId: run.runId,
+                  callId,
+                  name,
+                  arguments: toolArguments,
+                  fetchImpl: options.fetchImpl,
+                  signal,
+                  allowInsecureHttp: options.allowInsecureHttp,
+                })
+            : undefined,
       })
     : webflowOutcome
       ? createWebflowToolRuntime({
@@ -2762,7 +2780,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
           callPanelTool:
             options.apiBaseUrl && options.deviceToken
               ? ({ callId, name, arguments: toolArguments, signal }) =>
-                  callWebflowPanelTool(options.apiBaseUrl, {
+                  callPanelTool(options.apiBaseUrl, {
                     deviceToken: options.deviceToken,
                     runId: run.runId,
                     callId,
@@ -3072,32 +3090,34 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
     ) {
       synchronization = await harnessTools.synchronize();
     }
-    if (typeof harnessTools.assessCompletion === 'function') {
-      await harnessTools.assessCompletion(rawCompletion);
-    }
-    const unappliedChangePrompt =
-      rawCompletion.status === successStatus
-        ? harnessTools.unappliedChangePrompt?.(rawCompletion) || null
-        : null;
-    const repairPrompt =
-      rawCompletion.status === successStatus
-        ? harnessTools.verificationRepairPrompt?.() || unappliedChangePrompt
-        : harnessTools.unblockedFailurePrompt?.(rawCompletion) || null;
-    if (
-      repairPrompt
-      && Date.now() - callStartedAt < outcomeMaxDurationMs - 5_000
-    ) {
+    // The model sees what Dexter's reads found and decides what to do with it.
+    // Findings it has already weighed are not sent again: finishing with the
+    // same findings is its judgment, and the outcome reports them as they are.
+    let assessedCompletion = null;
+    let previousRepairPrompt = null;
+    for (let round = 0; round < OUTCOME_REPAIR_ROUNDS; round += 1) {
+      if (typeof harnessTools.assessCompletion === 'function') {
+        await harnessTools.assessCompletion(rawCompletion);
+        assessedCompletion = rawCompletion;
+      }
+      const unappliedChangePrompt =
+        rawCompletion.status === successStatus
+          ? harnessTools.unappliedChangePrompt?.(rawCompletion) || null
+          : null;
+      const repairPrompt =
+        rawCompletion.status === successStatus
+          ? harnessTools.verificationRepairPrompt?.() || unappliedChangePrompt
+          : harnessTools.unblockedFailurePrompt?.(rawCompletion) || null;
+      if (
+        !repairPrompt
+        || repairPrompt === previousRepairPrompt
+        || Date.now() - callStartedAt >= outcomeMaxDurationMs - 5_000
+      ) break;
+      previousRepairPrompt = repairPrompt;
       progress({
         kind: 'status_update',
         source: 'harness',
-        message:
-          repairPrompt === unappliedChangePrompt
-            ? `Nothing has changed in ${webflowOutcome ? 'Webflow' : 'Framer'} yet, so I’m making the change before I finish.`
-            : rawCompletion.status === successStatus
-              ? (webflowOutcome
-                ? 'I’m completing the final Webflow verification before I finish.'
-                : 'I’m completing the final Framer verification before I finish.')
-              : 'Nothing is blocking this change, so I’m continuing the work.',
+        message: 'I’m checking the result against your request before I finish.',
       });
       const repairResult = await Promise.race([
         executeProviderOutcome(
@@ -3138,7 +3158,7 @@ async function executeOutcomeRun(run, send, agent, options = {}) {
         updatedAt: Date.now(),
       });
     }
-    if (typeof harnessTools.assessCompletion === 'function') {
+    if (typeof harnessTools.assessCompletion === 'function' && assessedCompletion !== rawCompletion) {
       await harnessTools.assessCompletion(rawCompletion);
     }
     const completion =

package/src/api.js

@@ -279,7 +279,7 @@ export function webflowMcpEndpoint(apiBaseUrl, { deviceToken, runId, allowInsecu
   };
 }
 
-export function callWebflowPanelTool(apiBaseUrl, {
+export function callPanelTool(apiBaseUrl, {
   deviceToken,
   runId,
   callId,

package/src/config.js

@@ -22,7 +22,7 @@ export const BRIDGE_BUILD_FINGERPRINT = crypto
     './harnessMcpServer.js',
     './framerTools.js',
     './framerMcpClient.js',
-    './framerBehaviorContract.js',
+    './framerRequirementContract.js',
     './webflowTools.js',
     './taskEvidence.js',
     './outcomeWorkspace.js',
@@ -47,7 +47,7 @@ export const BRIDGE_CAPABILITIES = [
   'framer-mcp-v1',
   'framer-project-bootstrap-v1',
   'framer-project-verification-v1',
-  'framer-interaction-verification-v4',
+  'framer-requirement-verification-v1',
   'framer-read-website-v1',
   'webflow-site-v2',
   'project-shell-v1',

package/src/framerRequirementContract.js

@@ -0,0 +1,332 @@
+// The model turns the user's request into requirements it can check: a value
+// a layer must carry, a link, a size, a distance, a layer that must stay
+// inside its parent. This module checks them against live Framer data, so a
+// requirement counts as met because Framer shows it, not because the model
+// says so. Dexter does not model Framer's features: the model names the layer
+// and the property, and this module reads what is there.
+
+const MAX_SEARCH_DEPTH = 6;
+const MAX_OBSERVED_CHARS = 1000;
+const DEFAULT_TOLERANCE_PX = 2;
+export const MEASURES = ['width', 'height', 'gap', 'insideParent'];
+
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function text(value, maximum = 500) {
+  return typeof value === 'string'
+    ? value.trim().slice(0, maximum)
+    : '';
+}
+
+function uniqueStrings(values, maximum = 50) {
+  return Array.from(new Set(
+    (Array.isArray(values) ? values : [])
+      .map((value) => text(value, 500))
+      .filter(Boolean),
+  )).slice(0, maximum);
+}
+
+function contractError(code, message) {
+  return Object.assign(new Error(message), { code, statusCode: 400 });
+}
+
+function normalizeRequirement(raw, index) {
+  const id = text(raw?.id, 120);
+  const description = text(raw?.text, 500);
+  if (!isRecord(raw) || !id || description.length < 3) {
+    throw contractError(
+      'FRAMER_REQUIREMENT_INVALID',
+      `Requirement ${index + 1} needs an id and the text of what must be true.`,
+    );
+  }
+  return { id, text: description, nodeIds: uniqueStrings(raw.nodeIds, 50) };
+}
+
+export function normalizeRequirements(rawRequirements) {
+  const requirements = (Array.isArray(rawRequirements) ? rawRequirements : [])
+    .slice(0, 40)
+    .map(normalizeRequirement);
+  const ids = new Set();
+  for (const requirement of requirements) {
+    if (ids.has(requirement.id)) {
+      throw contractError(
+        'FRAMER_REQUIREMENT_INVALID',
+        `Requirement ids must be unique; "${requirement.id}" is duplicated.`,
+      );
+    }
+    ids.add(requirement.id);
+  }
+  return requirements;
+}
+
+export function mergeRequirements(current, next) {
+  const byId = new Map(current.map((item) => [item.id, item]));
+  next.forEach((item) => byId.set(item.id, item));
+  return [...byId.values()];
+}
+
+function finiteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+export function normalizeChecks(rawChecks, requirements) {
+  const requirementIds = new Set(requirements.map((item) => item.id));
+  const checks = (Array.isArray(rawChecks) ? rawChecks : []).slice(0, 80);
+  if (!checks.length) {
+    throw contractError(
+      'FRAMER_CHECKS_REQUIRED',
+      'Send at least one check: a requirement id, a layer id, and either a property or a measure.',
+    );
+  }
+  return checks.map((raw, index) => {
+    const requirementId = text(raw?.requirementId, 120);
+    const nodeId = text(raw?.nodeId, 200);
+    const property = text(raw?.property, 120);
+    const measure = text(raw?.measure, 40);
+    const invalid = (reason) => contractError(
+      'FRAMER_CHECK_INVALID',
+      `Check ${index + 1} ${reason}`,
+    );
+    if (!isRecord(raw) || !requirementIds.has(requirementId) || !nodeId) {
+      throw invalid(`must name a requirement from your plan (${[...requirementIds].join(', ') || 'none planned'}) and a layer id.`);
+    }
+    if (Boolean(property) === Boolean(measure)) {
+      throw invalid('needs either a property or a measure, not both.');
+    }
+    if (property) {
+      return raw.absent === true
+        ? { requirementId, nodeId, property, absent: true }
+        : { requirementId, nodeId, property, contains: text(raw.contains, 500) };
+    }
+    if (!MEASURES.includes(measure)) {
+      throw invalid(`has an unknown measure; use one of ${MEASURES.join(', ')}.`);
+    }
+    const otherNodeId = text(raw.otherNodeId, 200);
+    if (measure === 'gap' && !otherNodeId) throw invalid('measures a gap, so it needs otherNodeId.');
+    const expected = finiteNumber(raw.expected);
+    if (measure !== 'insideParent' && expected === null) {
+      throw invalid(`measures ${measure}, so it needs the expected number of pixels.`);
+    }
+    return {
+      requirementId,
+      nodeId,
+      measure,
+      ...(otherNodeId ? { otherNodeId } : {}),
+      ...(expected !== null ? { expected } : {}),
+      tolerance: Math.max(0, finiteNumber(raw.tolerance) ?? DEFAULT_TOLERANCE_PX),
+    };
+  });
+}
+
+export function checkNodeIds(checks) {
+  return uniqueStrings(checks.filter((check) => check.property).map((check) => check.nodeId), 200);
+}
+
+export function measureChecks(checks) {
+  return checks.filter((check) => check.measure);
+}
+
+function hasContent(value) {
+  if (value === undefined || value === null || value === '') return false;
+  if (Array.isArray(value)) return value.length > 0;
+  if (isRecord(value)) return Object.keys(value).length > 0;
+  return true;
+}
+
+// Finds the property on the node itself. Child nodes are skipped so a
+// descendant cannot satisfy a claim about its parent. A dotted name such as
+// `link.href` or `hoverEffect.opacity` 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;
+    if (Array.isArray(current)) {
+      current.forEach((item) => visit(item, depth + 1));
+      return;
+    }
+    if (!isRecord(current)) return;
+    for (const [key, nested] of Object.entries(current)) {
+      if (key === 'children') continue;
+      if (key === property) {
+        if (hasContent(nested)) values.push(nested);
+      } else {
+        visit(nested, depth + 1);
+      }
+    }
+  };
+  visit(node, 0);
+  return values;
+}
+
+function serialized(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '';
+  }
+}
+
+function propertyVerdict(check, nodes) {
+  const node = nodes instanceof Map ? nodes.get(check.nodeId) : nodes?.[check.nodeId];
+  if (!node) return { ...check, verdict: 'unknown', reason: `layer ${check.nodeId} was not found` };
+  const values = propertyValues(node, check.property);
+  if (check.absent) {
+    return values.length === 0
+      ? { ...check, verdict: 'verified', observedValue: 'not set' }
+      : {
+          ...check,
+          verdict: 'contradicted',
+          reason: `${check.property} on ${check.nodeId} is set to ${serialized(values.length === 1 ? values[0] : values).slice(0, 200)}`,
+          observedValue: serialized(values.length === 1 ? values[0] : values).slice(0, MAX_OBSERVED_CHARS),
+        };
+  }
+  if (values.length === 0) {
+    return { ...check, verdict: 'unknown', reason: `${check.property} is not set on ${check.nodeId}` };
+  }
+  const observed = serialized(values.length === 1 ? values[0] : values);
+  if (check.contains && !observed.toLowerCase().includes(check.contains.toLowerCase())) {
+    return {
+      ...check,
+      verdict: 'contradicted',
+      reason: `${check.property} on ${check.nodeId} is ${observed.slice(0, 200)}, not ${check.contains}`,
+      observedValue: observed.slice(0, MAX_OBSERVED_CHARS),
+    };
+  }
+  return { ...check, verdict: 'verified', observedValue: observed.slice(0, MAX_OBSERVED_CHARS) };
+}
+
+// `measured` holds what the measuring program found for each measure check,
+// in the same order: { value } in pixels, { inside, overflow } for
+// insideParent, { unmeasured, note } when Framer could not lay the layer out
+// for Dexter, or { error }.
+function measureVerdict(check, measured) {
+  if (measured?.unmeasured) {
+    return { ...check, verdict: 'unmeasured', reason: measured.note || `${check.nodeId} could not be measured on this page` };
+  }
+  if (!measured || measured.error) {
+    return { ...check, verdict: 'unknown', reason: measured?.error || `${check.nodeId} could not be measured` };
+  }
+  if (check.measure === 'insideParent') {
+    return measured.inside
+      ? { ...check, verdict: 'verified', observedValue: 'inside its parent' }
+      : {
+          ...check,
+          verdict: 'contradicted',
+          reason: `${check.nodeId} sticks out of its parent by ${measured.overflow}px`,
+          observedValue: `overflows by ${measured.overflow}px`,
+        };
+  }
+  const value = Number(measured.value);
+  const label = check.measure === 'gap' ? `gap between ${check.nodeId} and ${check.otherNodeId}` : `${check.measure} of ${check.nodeId}`;
+  if (Math.abs(value - check.expected) <= check.tolerance) {
+    return { ...check, verdict: 'verified', observedValue: `${value}px` };
+  }
+  return {
+    ...check,
+    verdict: 'contradicted',
+    reason: `${label} measures ${value}px, not ${check.expected}px`,
+    observedValue: `${value}px`,
+  };
+}
+
+export function verifyChecks({ checks, nodes, measurements = [] }) {
+  let measureIndex = 0;
+  return checks.map((check) => (check.property
+    ? propertyVerdict(check, nodes)
+    : measureVerdict(check, measurements[measureIndex++])));
+}
+
+// Summarizes the latest check results for every requirement. A requirement is
+// met once every layer it names has a verified check (or, naming none, once
+// one check verified it) and no check contradicts it. A measure Dexter could
+// not take is neither met nor failed: the requirement is unmeasured, and the
+// model judges it another way, such as from a screenshot.
+// status: missing (a requirement or one of its layers was never checked),
+// contradicted (Framer shows something else), unverified (a property or
+// layer could not be found), or verified.
+export function summarizeRequirements(requirements, checkResults) {
+  const items = requirements.map((requirement) => {
+    const results = checkResults.filter((result) => result.requirementId === requirement.id);
+    const verifiedNodeIds = new Set(
+      results.filter((result) => result.verdict === 'verified').map((result) => result.nodeId),
+    );
+    const contradictions = results
+      .filter((result) => result.verdict === 'contradicted')
+      .map((result) => result.reason);
+    const checkedNodeIds = new Set(results.map((result) => result.nodeId));
+    const uncheckedNodeIds = requirement.nodeIds.filter((nodeId) => !checkedNodeIds.has(nodeId));
+    const covered = requirement.nodeIds.length > 0
+      ? requirement.nodeIds.every((nodeId) => verifiedNodeIds.has(nodeId))
+      : verifiedNodeIds.size > 0;
+    const unmeasuredOnly = results.length > 0
+      && results.every((result) => result.verdict === 'verified' || result.verdict === 'unmeasured');
+    return {
+      requirementId: requirement.id,
+      text: requirement.text,
+      checked: results.length > 0 && uncheckedNodeIds.length === 0,
+      verdict: contradictions.length > 0
+        ? 'contradicted'
+        : covered ? 'verified' : unmeasuredOnly ? 'unmeasured' : 'unknown',
+      uncheckedNodeIds,
+      contradictions: uniqueStrings(contradictions, 20),
+      unknowns: uniqueStrings(
+        results.filter((result) => result.verdict === 'unknown').map((result) => result.reason),
+        20,
+      ),
+      unmeasured: uniqueStrings(
+        results.filter((result) => result.verdict === 'unmeasured').map((result) => result.reason),
+        20,
+      ),
+    };
+  });
+  const status = items.some((item) => !item.checked)
+    ? 'missing'
+    : items.some((item) => item.verdict === 'contradicted')
+      ? 'contradicted'
+      : items.some((item) => item.verdict === 'unknown')
+        ? 'unverified'
+        : 'verified';
+  return { status, requirements: items };
+}
+
+// Compares two snapshots of layers that had to stay as they were. A snapshot
+// maps a layer id to { name, rect, props } where props is the serialized
+// layer without children and rect is null when Dexter could not measure the
+// layer, so only its settings are compared. Boxes are compared only when both
+// readings came from the same source (the user's editor or Framer MCP).
+export function unchangedViolations(before, after, tolerance = 1) {
+  const changes = [];
+  for (const [id, earlier] of Object.entries(before || {})) {
+    const later = after?.[id];
+    const name = earlier.name || id;
+    if (!later) {
+      changes.push(`${name} was removed`);
+      continue;
+    }
+    const a = earlier.rect;
+    const b = later.rect;
+    const comparable = a && b && (a.source || null) === (b.source || null);
+    if (comparable && ['x', 'y', 'width', 'height'].some((key) => Math.abs(a[key] - b[key]) > tolerance)) {
+      changes.push(`${name} moved or resized (${a.width}×${a.height} at ${a.x},${a.y} → ${b.width}×${b.height} at ${b.x},${b.y})`);
+    } else if (earlier.props !== later.props) {
+      changes.push(`${name} has different settings`);
+    }
+    if (changes.length >= 20) break;
+  }
+  return changes;
+}