@gakim-digital/dexter-bridge 0.12.2 → 0.13.0

package/src/webflowTools.js

@@ -0,0 +1,1045 @@
+import crypto from 'node:crypto';
+import { createServer } from 'node:http';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import { createEvidenceLedger } from './taskEvidence.js';
+
+export const WEBFLOW_TEXT_BUDGET_BYTES = 24 * 1024;
+export const WEBFLOW_GUIDANCE_BUDGET_BYTES = 120 * 1024;
+export const WEBFLOW_IDENTICAL_FAILURE_LIMIT = 5;
+export const WEBFLOW_SERVER_FAILURE_LIMIT = 5;
+export const WEBFLOW_WRITE_UNKNOWN = {
+  status: 'unknown',
+  message: 'The write may have landed. Re-read the target before retrying.',
+};
+
+const WEBFLOW_DOMAINS = [
+  'visual',
+  'content',
+  'links',
+  'interactions',
+  'responsive',
+  'data',
+  'structure',
+];
+const WEBFLOW_CHECKS = ['structural', 'links', 'responsive', 'data'];
+const CHECK_LABELS = {
+  'task-plan': 'a harness task and verification plan',
+  structural: 'a final structural read',
+  links: 'a webflow_call read tagged with verifies:["links"]',
+  responsive: 'a webflow_call read tagged with verifies:["responsive"]',
+  data: 'a webflow_call read tagged with verifies:["data"]',
+};
+
+const DROPPED_TOOL_PATTERNS = [
+  /publish/i,
+  /settings/i,
+  /enterprise/i,
+  /member/i,
+  /webflow_cloud|cloud_deploy|\bdeploy\b/i,
+  /campaign/i,
+  /^ask_webflow_ai$/i,
+];
+// These need Webflow's own MCP Bridge App open in the Designer. Dexter's panel
+// replaces them: webflow_context (selection, page, mode) and webflow_snapshot.
+const DESIGNER_SESSION_TOOLS = ['designer_tool', 'element_snapshot_tool'];
+const DESIGNER_SESSION_TOOL_PATTERN = new RegExp(`\\b(${DESIGNER_SESSION_TOOLS.join('|')})\\b`);
+const DESIGNER_SESSION_FAILURE = /unable to connect to webflow designer|designer mcp app/i;
+const DESIGNER_SESSION_MESSAGE = "This Webflow action needs Webflow's own Designer app, which Dexter does not use. Do not ask the user to open a Webflow app or link. Use webflow_context for the current page and selection (each selected element's id is the { component, element } object Webflow's data tools take), webflow_snapshot for screenshots, and the data_* tools to read and edit.";
+
+// Webflow MCP tools reach the harness through webflow_call instead of as native
+// tools: their schemas are ~170k tokens, re-read on every model request.
+// Dexter fills these arguments itself on every call.
+const DEXTER_FILLED_ARGUMENTS = ['siteId', 'session_id', 'agent_id', 'context'];
+const WEBFLOW_CALL_CONTEXT = "Dexter applies the designer's requested change to this Webflow site, reading and editing its elements, styles, and assets in the Designer.";
+const READ_ACTION_PATTERN = /^(get|query|list|search|read|check)_|^guide$/;
+const READ_ONLY_TOOLS = new Set(['webflow_guide_tool', 'get_asset_preview']);
+const PROMPT_GUIDE_SECTIONS = [/^General Rules:/, /^### Important rules for creating elements/];
+// Guide sections for the live-Designer tools Dexter replaces.
+const DESIGNER_SESSION_GUIDE_SECTION = /^(Element Snapshot Tool Usage|Canvas Navigation \(Designer\)):/;
+const SESSION_ISSUANCE = /\[session_id issued[^\]]*\]\s*session_id:\s*(ses_[0-9A-Za-z]+)\s*(?:This is the first-call issuance[^.]*\.)?\s*/g;
+const CATALOG_DESCRIPTION_CHARS = 160;
+const WEBFLOW_HELP_ACTION_LIMIT = 8;
+
+const guidanceCache = new Map();
+
+function toolError(code, message, statusCode = 400) {
+  return Object.assign(new Error(message), { code, statusCode });
+}
+
+function designerSessionError() {
+  return toolError('WEBFLOW_DESIGNER_SESSION_UNAVAILABLE', DESIGNER_SESSION_MESSAGE, 409);
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isBlockedWebflowMcpTool(name) {
+  const tool = String(name || '');
+  if (!tool || tool === 'get_more_tools' || DESIGNER_SESSION_TOOLS.includes(tool)) return true;
+  return DROPPED_TOOL_PATTERNS.some((pattern) => pattern.test(tool));
+}
+
+function isBlockedWebflowAction(action) {
+  return /publish/i.test(action);
+}
+
+function callActions(args) {
+  const items = Array.isArray(args?.actions) ? args.actions : [];
+  return items.flatMap((item) => (isRecord(item) ? Object.keys(item).filter((key) => key !== 'label') : []));
+}
+
+// Webflow calls carry their actions as keys: { actions: [{ query_styles: {...} }] }.
+export function classifyWebflowToolCall(tool, args = {}) {
+  if (READ_ONLY_TOOLS.has(tool)) return 'read';
+  if (/_builder$/.test(tool)) return 'mutation';
+  const actions = callActions(args);
+  if (actions.length === 0) return 'mutation';
+  return actions.every((action) => READ_ACTION_PATTERN.test(action)) ? 'read' : 'mutation';
+}
+
+export function budgetWebflowText(value, maximum = WEBFLOW_TEXT_BUDGET_BYTES) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+  const bytes = Buffer.byteLength(text);
+  if (bytes <= maximum) return text;
+  let end = text.length;
+  while (end > 0 && Buffer.byteLength(text.slice(0, end)) > maximum - 80) {
+    end = Math.floor(end * 0.9);
+  }
+  const kept = text.slice(0, end);
+  const omitted = bytes - Buffer.byteLength(kept);
+  return `${kept}…truncated ${omitted} bytes; narrow the query`;
+}
+
+function clipBytes(text, maximum) {
+  const value = String(text || '');
+  if (Buffer.byteLength(value) <= maximum) return value;
+  let end = value.length;
+  while (end > 0 && Buffer.byteLength(value.slice(0, end)) > maximum) {
+    end -= Math.max(1, Math.floor(end * 0.1));
+  }
+  return value.slice(0, end);
+}
+
+export function assertWebflowHarnessAgent(agentId) {
+  if (agentId === 'opencode') {
+    throw toolError(
+      'WEBFLOW_AGENT_UNSUPPORTED',
+      'OpenCode is not available for Webflow runs. Use Claude Code.',
+    );
+  }
+}
+
+function dexterTool(name, description, inputSchema, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties: inputSchema,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+  };
+}
+
+function dexterDefinitions() {
+  return [
+    dexterTool(
+      'webflow_context',
+      "Read the current Webflow page, selection, and site context from the open Designer. Each selected element has `id`, the { component, element } object Webflow's data tools take, and `nodeId`, which webflow_snapshot takes.",
+      {},
+    ),
+    dexterTool(
+      'webflow_snapshot',
+      "Screenshot specific elements, by the nodeId webflow_context or the data tools report. Webflow renders these screenshots itself, so letter-spacing and word spacing can look tighter than on the live site.",
+      {
+        elementIds: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 4,
+          items: { type: 'string', minLength: 1, maxLength: 200 },
+        },
+        pageId: { type: 'string', maxLength: 200 },
+      },
+      ['elementIds'],
+    ),
+    dexterTool(
+      'webflow_plan_task',
+      'After inspecting the live site and before the first change, declare the task and the evidence you will produce.',
+      {
+        summary: { type: 'string', minLength: 10, maxLength: 1000 },
+        domains: {
+          type: 'array',
+          minItems: 1,
+          uniqueItems: true,
+          items: { type: 'string', enum: WEBFLOW_DOMAINS },
+        },
+        verification: {
+          type: 'array',
+          minItems: 1,
+          uniqueItems: true,
+          items: { type: 'string', enum: WEBFLOW_CHECKS },
+        },
+      },
+      ['summary', 'domains', 'verification'],
+    ),
+    dexterTool(
+      'webflow_read_website',
+      'Read one page of a website the user named. Only sites the user named can be read.',
+      {
+        url: { type: 'string', minLength: 1, maxLength: 2048 },
+        screenshotTop: { type: 'integer', minimum: 0 },
+      },
+      ['url'],
+    ),
+    dexterTool(
+      'webflow_find_images',
+      'Search for real stock photos. Use an attachment or an existing site asset first. Never invent an image URL.',
+      {
+        query: { type: 'string', minLength: 2, maxLength: 200 },
+        count: { type: 'integer', minimum: 1, maximum: 8 },
+        orientation: { type: 'string', enum: ['landscape', 'portrait', 'squarish'] },
+      },
+      ['query'],
+    ),
+    dexterTool(
+      'webflow_upload_image',
+      'Upload an attachment or a stock-image URL into the Webflow site through the open Designer, then use the returned asset.',
+      {
+        source: { type: 'string', enum: ['attachment', 'url'] },
+        attachmentId: { type: 'string', maxLength: 180 },
+        url: { type: 'string', maxLength: 2048 },
+        alt: { type: 'string', maxLength: 300 },
+      },
+      ['source'],
+    ),
+  ];
+}
+
+function gatewayDefinitions(tools) {
+  const tool = { type: 'string', enum: tools };
+  return [
+    dexterTool(
+      'webflow_tool_help',
+      'Show the exact arguments of Webflow tool actions and Webflow\'s usage notes for that tool. Before using an action for the first time, ask for every action you plan to use in one call.',
+      {
+        tool,
+        actions: {
+          type: 'array',
+          maxItems: WEBFLOW_HELP_ACTION_LIMIT,
+          uniqueItems: true,
+          items: { type: 'string', minLength: 1, maxLength: 80 },
+        },
+      },
+      ['tool'],
+    ),
+    dexterTool(
+      'webflow_call',
+      'Run a tool from the Webflow tool catalog with the arguments webflow_tool_help showed. Batch several actions in one call. Dexter fills siteId, session_id, agent_id, context, and action labels, and fills pageId with the current Designer page when you leave it out.',
+      {
+        tool,
+        arguments: { type: 'object', description: 'The tool\'s arguments, such as { "actions": [{ "query_elements": { … } }] }.' },
+        verifies: {
+          type: 'array',
+          uniqueItems: true,
+          items: { type: 'string', enum: ['links', 'responsive', 'data'] },
+          description: 'For a verification read, the checks it provides.',
+        },
+      },
+      ['tool', 'arguments'],
+    ),
+  ];
+}
+
+// Webflow declares draft-07 `$schema`; the Claude API then rejects some tool
+// schemas (data_optimize_tool) that are valid as its required draft 2020-12.
+function schemaOf(tool) {
+  const schema = isRecord(tool.inputSchema)
+    ? tool.inputSchema
+    : isRecord(tool.parameters)
+      ? tool.parameters
+      : { type: 'object', additionalProperties: true };
+  const { $schema, ...rest } = schema;
+  return rest;
+}
+
+function clipSentence(text, maximum) {
+  const value = String(text || '').replace(/\s+/g, ' ').trim();
+  if (value.length <= maximum) return value;
+  const cut = value.slice(0, maximum);
+  return `${cut.slice(0, Math.max(cut.lastIndexOf(' '), 1))}…`;
+}
+
+// The schema the harness's arguments must match: Webflow's, minus what Dexter fills.
+// pageId stays optional: Dexter fills the current page when it is left out.
+function harnessSchema(schema) {
+  const properties = { ...(schema.properties || {}) };
+  for (const field of DEXTER_FILLED_ARGUMENTS) delete properties[field];
+  return {
+    ...schema,
+    properties,
+    required: (schema.required || []).filter((field) => !DEXTER_FILLED_ARGUMENTS.includes(field) && field !== 'pageId'),
+  };
+}
+
+// Action items are validated against their own action's branch, so the
+// top level sees `actions` as a plain array.
+function topLevelSchema(entry) {
+  const schema = harnessSchema(entry.schema);
+  if (!entry.branches.size) return schema;
+  const { items: _items, ...actions } = schema.properties.actions;
+  return { ...schema, properties: { ...schema.properties, actions } };
+}
+
+function catalogEntry(tool) {
+  const schema = schemaOf(tool);
+  const variants = schema.properties?.actions?.items?.anyOf;
+  const actions = new Map();
+  const branches = new Map();
+  for (const variant of Array.isArray(variants) ? variants : []) {
+    const action = Object.keys(variant?.properties || {}).find((key) => key !== 'label');
+    if (!action || isBlockedWebflowAction(action)) continue;
+    actions.set(action, variant.properties[action]);
+    branches.set(action, variant);
+  }
+  return {
+    name: tool.name,
+    description: typeof tool.description === 'string' ? tool.description.trim() : '',
+    schema,
+    actions,
+    branches,
+    guide: [],
+  };
+}
+
+// Ajv reports `data/update_style must …`; name the argument path instead.
+function validationText(errorMessage, root) {
+  return String(errorMessage || 'invalid arguments')
+    .split(', data')
+    .map((part, index) => (index ? `data${part}` : part))
+    .map((part) => part.replace(/^data(\S*) /, (_match, path) => `${root}${path.replace(/\//g, '.')}: `))
+    .join('; ');
+}
+
+function catalogFromList(payload) {
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  return new Map(
+    tools
+      .filter((tool) => typeof tool?.name === 'string' && !isBlockedWebflowMcpTool(tool.name))
+      .map((tool) => [tool.name, catalogEntry(tool)]),
+  );
+}
+
+function catalogText(catalog) {
+  return [...catalog.values()].map((entry) => {
+    const actions = entry.actions.size ? ` Actions: ${[...entry.actions.keys()].join(', ')}.` : '';
+    // Some descriptions list their actions too; the catalog line already does.
+    const description = entry.description.replace(/\s*\bActions?:[\s\S]*$/, '');
+    return `- ${entry.name}: ${clipSentence(description, CATALOG_DESCRIPTION_CHARS)}${actions}`;
+  }).join('\n');
+}
+
+function guideSections(text) {
+  const sections = [];
+  for (const line of String(text || '').split('\n')) {
+    const trimmed = line.trim();
+    const header = trimmed
+      && !trimmed.startsWith('--')
+      && trimmed.length < 140
+      && (trimmed.endsWith(':') || trimmed.startsWith('###'));
+    if (header || sections.length === 0) sections.push({ header: header ? trimmed : '', lines: [] });
+    // Advice to use the live-Designer tools Dexter replaces would send the model to them.
+    if (!header && DESIGNER_SESSION_TOOL_PATTERN.test(line)) continue;
+    sections[sections.length - 1].lines.push(line);
+  }
+  return sections
+    .map((section) => ({ header: section.header, text: section.lines.join('\n').trim() }))
+    .filter((section) => section.text !== section.header);
+}
+
+// Tool sections of Webflow's guide go to the tools they describe (shown by
+// webflow_tool_help); only the general rules stay in the prompt.
+function splitGuide(text, catalog) {
+  const names = [...catalog.keys()].sort((a, b) => b.length - a.length);
+  const pattern = names.length
+    ? new RegExp(`\\b(${names.map((name) => name.replace(/[^a-z0-9_]/gi, '')).join('|')})\\b`, 'g')
+    : null;
+  const general = [];
+  for (const section of guideSections(text)) {
+    if (!section.text || DESIGNER_SESSION_GUIDE_SECTION.test(section.header)) continue;
+    const inHeader = pattern ? [...new Set(section.header.match(pattern) || [])] : [];
+    const inBody = pattern ? section.text.match(pattern) || [] : [];
+    const owners = inHeader.length ? inHeader : inBody.slice(0, 1);
+    for (const owner of owners) catalog.get(owner)?.guide.push(section.text);
+    if (!owners.length || PROMPT_GUIDE_SECTIONS.some((rule) => rule.test(section.header))) {
+      general.push(section.text);
+    }
+  }
+  return general.join('\n\n');
+}
+
+function toolHelp(entry, requested) {
+  const schema = harnessSchema(entry.schema);
+  const unknown = requested.filter((action) => !entry.actions.has(action));
+  if (entry.actions.size && unknown.length) {
+    throw toolError(
+      'WEBFLOW_ACTION_UNKNOWN',
+      `${entry.name} has no action ${unknown.join(', ')}. Actions: ${[...entry.actions.keys()].join(', ')}.`,
+    );
+  }
+  const help = { tool: entry.name, description: entry.description };
+  if (entry.actions.size) {
+    const { actions: _actions, ...rest } = schema.properties;
+    help.arguments = rest;
+    help.required = schema.required;
+    help.actionItem = 'Each actions item is { "<action>": { ...that action\'s arguments } }; Dexter adds the label.';
+    if (requested.length) {
+      help.actions = Object.fromEntries(requested.map((action) => [action, entry.actions.get(action)]));
+    } else {
+      help.availableActions = [...entry.actions.keys()];
+    }
+  } else {
+    help.arguments = schema.properties;
+    help.required = schema.required;
+  }
+  if (schema.properties.pageId) help.pageId = 'Optional. Dexter uses the current Designer page when you leave it out.';
+  if (entry.guide.length) help.guide = entry.guide.join('\n\n');
+  return help;
+}
+
+// Webflow requires a label on every action item and a build_label on builder items.
+function withLabels(tool, args) {
+  if (!Array.isArray(args.actions)) return args;
+  const builder = /_builder$/.test(tool);
+  return {
+    ...args,
+    actions: args.actions.map((item, index) => {
+      if (!isRecord(item)) return item;
+      if (builder) return item.build_label ? item : { build_label: `build_${index + 1}`, ...item };
+      if (item.label) return item;
+      const action = Object.keys(item).find((key) => key !== 'label');
+      return { label: action || `action_${index + 1}`, ...item };
+    }),
+  };
+}
+
+function contentItems(result) {
+  if (Array.isArray(result?.content)) return result.content;
+  if (Array.isArray(result)) return result;
+  return [];
+}
+
+function textFromContent(items) {
+  return items
+    .filter((item) => item?.type === 'text' && typeof item.text === 'string')
+    .map((item) => item.text)
+    .join('\n');
+}
+
+function imagesFromContent(items) {
+  return items
+    .filter((item) => item?.type === 'image' && typeof item.data === 'string' && item.data)
+    .map((item) => ({
+      mimeType: item.mimeType || 'image/png',
+      data: item.data,
+    }));
+}
+
+// Images reach the model as image blocks; their base64 in the text would be read twice.
+function withoutImageData(result) {
+  if (!isRecord(result)) return result;
+  const stripped = { ...result };
+  for (const field of ['images', 'modelImages']) {
+    if (!Array.isArray(result[field])) continue;
+    stripped[field] = result[field].map((image) => {
+      if (!isRecord(image)) return image;
+      const { data: _data, ...rest } = image;
+      return rest;
+    });
+  }
+  return stripped;
+}
+
+function parseToolPayload(result) {
+  const items = contentItems(result);
+  if (items.length > 0) {
+    return {
+      text: textFromContent(items),
+      images: imagesFromContent(items),
+      isError: result?.isError === true,
+    };
+  }
+  if (typeof result === 'string') return { text: result, images: [], isError: false };
+  return { text: JSON.stringify(result ?? {}), images: [], isError: false };
+}
+
+// The MCP SDK reports an HTTP failure as StreamableHTTPError with the status in `code`.
+function statusOf(error) {
+  const status = Number(error?.status || error?.statusCode || (typeof error?.code === 'number' ? error.code : 0));
+  return Number.isFinite(status) ? status : 0;
+}
+
+// Dexter's API holds the Webflow token and answers 403/409 with { error, code } when it refuses a call.
+function proxyRefusal(error) {
+  const status = statusOf(error);
+  if (status !== 403 && status !== 409) return null;
+  let body = null;
+  try {
+    body = JSON.parse(/\{[\s\S]*\}/.exec(String(error?.message || ''))?.[0] || 'null');
+  } catch {
+    body = null;
+  }
+  return toolError(
+    body?.code || 'WEBFLOW_MCP_REFUSED',
+    body?.error || 'Dexter could not reach Webflow for this site.',
+    status,
+  );
+}
+
+function isTimeout(error) {
+  return error?.code === 'TIMEOUT'
+    || error?.code === 'ETIMEDOUT'
+    || error?.name === 'TimeoutError'
+    || /timed out|timeout/i.test(String(error?.message || ''));
+}
+
+function isNetwork(error) {
+  return ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN'].includes(error?.code)
+    || /network|fetch failed|socket/i.test(String(error?.message || ''));
+}
+
+function isServerFailure(error) {
+  const status = statusOf(error);
+  if (status === 406 || status >= 500) return true;
+  return /unable to connect/i.test(String(error?.message || ''));
+}
+
+// Webflow's MCP is reached through Dexter's API, which adds the site's Webflow token server-side.
+async function connectWebflowMcp(endpoint) {
+  const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
+    import('@modelcontextprotocol/sdk/client/index.js'),
+    import('@modelcontextprotocol/sdk/client/streamableHttp.js'),
+  ]);
+  const client = new Client({ name: 'dexter-bridge', version: '0.12.0' });
+  const transport = new StreamableHTTPClientTransport(new URL(endpoint.url), {
+    requestInit: { headers: endpoint.headers || {} },
+  });
+  try {
+    await client.connect(transport);
+  } catch (error) {
+    throw proxyRefusal(error) || error;
+  }
+  return client;
+}
+
+export function createWebflowToolRuntime({
+  assignment,
+  trace,
+  onActivity,
+  mcpEndpoint,
+  callPanelTool,
+  findImages,
+  readWebsite,
+  mcpClient = null,
+} = {}) {
+  const siteId = String(assignment?.context?.webflowSiteId || '').trim();
+  const ledger = createEvidenceLedger({
+    checks: WEBFLOW_CHECKS,
+    domains: WEBFLOW_DOMAINS,
+    labels: CHECK_LABELS,
+  });
+  const requestedTools = Array.isArray(assignment?.toolProtocol?.tools)
+    ? new Set(assignment.toolProtocol.tools)
+    : null;
+  const initialTools = dexterDefinitions().filter((tool) => !requestedTools || requestedTools.has(tool.name));
+  let definitions = initialTools;
+  let catalog = new Map();
+  let webflowSession = 'start';
+  const agentId = `dexter|dexter-bridge|${crypto.randomBytes(4).toString('hex').slice(0, 5)}`;
+  const schemaValidator = new AjvJsonSchemaValidator();
+  const validators = new Map();
+  let connected = mcpClient;
+  let mcpServerVersion = mcpClient?.serverVersion || null;
+  let guidance = { content: '', hash: null };
+  let closed = false;
+  let serial = Promise.resolve();
+  let server = null;
+  let gateway = null;
+  let repeatedFailureFingerprint = null;
+  let repeatedFailureCount = 0;
+  let repeatedFailureStops = 0;
+  let serverFailures = 0;
+  let readCalls = 0;
+  let snapshotCalls = 0;
+  let currentPageId = '';
+  const abortController = new AbortController();
+
+  const reportActivity = (event) => {
+    try {
+      void Promise.resolve(onActivity?.(event)).catch(() => undefined);
+    } catch {
+      // Observability must never interrupt a Webflow operation.
+    }
+  };
+
+  async function ensureClient() {
+    if (connected) return connected;
+    if (!mcpEndpoint?.url) {
+      throw toolError(
+        'WEBFLOW_AUTHORIZATION_REQUIRED',
+        'Connect Webflow before Dexter can edit this site.',
+        409,
+      );
+    }
+    connected = await connectWebflowMcp(mcpEndpoint);
+    mcpServerVersion = connected.getServerVersion?.()?.version || mcpServerVersion;
+    return connected;
+  }
+
+  async function callMcp(name, args, mutation) {
+    const invoke = async () => {
+      const client = await ensureClient();
+      try {
+        return await client.callTool({ name, arguments: args });
+      } catch (error) {
+        throw proxyRefusal(error) || error;
+      }
+    };
+    try {
+      return await invoke();
+    } catch (error) {
+      if (!mutation && isNetwork(error) && error?.webflowRetried !== true) {
+        error.webflowRetried = true;
+        try {
+          return await invoke();
+        } catch (retried) {
+          retried.webflowRetried = true;
+          throw retried;
+        }
+      }
+      throw error;
+    }
+  }
+
+  // Dexter owns the run's site and Webflow's per-call bookkeeping arguments.
+  function filledArguments(entry, args) {
+    const properties = entry.schema.properties || {};
+    const filled = { ...args };
+    if ('siteId' in properties && siteId) filled.siteId = siteId;
+    if ('session_id' in properties) filled.session_id = webflowSession;
+    if ('agent_id' in properties) filled.agent_id = agentId;
+    if ('context' in properties) filled.context = WEBFLOW_CALL_CONTEXT;
+    return filled;
+  }
+
+  // Webflow issues a session id in the first result's text; reuse it and keep it out of the model's view.
+  function withoutSessionIssuance(text) {
+    return String(text || '').replace(SESSION_ISSUANCE, (_match, issued) => {
+      if (webflowSession === 'start') webflowSession = issued;
+      return '';
+    }).trim();
+  }
+
+  async function callWebflowTool(entry, args, mutation) {
+    const parsed = parseToolPayload(await callMcp(entry.name, filledArguments(entry, args), mutation));
+    return { ...parsed, text: withoutSessionIssuance(parsed.text) };
+  }
+
+  function withCurrentPage(entry, args) {
+    if (!('pageId' in (entry.schema.properties || {})) || args.pageId) return args;
+    if (currentPageId) return { ...args, pageId: currentPageId };
+    if (!(entry.schema.required || []).includes('pageId')) return args;
+    throw toolError(
+      'WEBFLOW_PAGE_UNKNOWN',
+      `${entry.name} needs a page. Call webflow_context so Dexter knows the current page, or pass pageId.`,
+    );
+  }
+
+  function validatorFor(key, schema) {
+    if (!validators.has(key)) validators.set(key, schemaValidator.getValidator(schema));
+    return validators.get(key);
+  }
+
+  function invalidCall(entry, problem) {
+    return toolError(
+      'WEBFLOW_CALL_INVALID',
+      `Invalid arguments for ${entry.name}: ${problem}. Call webflow_tool_help with this tool and its actions for the exact arguments.`,
+    );
+  }
+
+  function validateCall(entry, args) {
+    const unknown = entry.actions.size
+      ? callActions(args).filter((action) => !entry.actions.has(action))
+      : [];
+    if (unknown.length) {
+      throw toolError(
+        'WEBFLOW_ACTION_UNKNOWN',
+        `${entry.name} cannot run ${unknown.join(', ')}. Actions: ${[...entry.actions.keys()].join(', ')}.`,
+      );
+    }
+    const validated = validatorFor(entry.name, topLevelSchema(entry))(args);
+    if (!validated.valid) throw invalidCall(entry, validationText(validated.errorMessage, 'arguments'));
+    if (!entry.branches.size || !Array.isArray(args.actions)) return;
+    args.actions.forEach((item, index) => {
+      const named = isRecord(item) ? Object.keys(item).filter((key) => key !== 'label') : [];
+      if (named.length !== 1) throw invalidCall(entry, `actions[${index}]: must hold exactly one action`);
+      const [action] = named;
+      const result = validatorFor(`${entry.name}:${action}`, entry.branches.get(action))(item);
+      if (!result.valid) throw invalidCall(entry, validationText(result.errorMessage, `actions[${index}]`));
+    });
+  }
+
+  function panelImages(result) {
+    const images = [
+      ...(Array.isArray(result?.images) ? result.images : []),
+      ...(Array.isArray(result?.modelImages) ? result.modelImages : []),
+    ];
+    return images
+      .filter((image) => typeof image?.data === 'string' && image.data)
+      .map((image) => ({
+        mimeType: image.mimeType || 'image/png',
+        data: image.data,
+      }));
+  }
+
+  function catalogTool(name) {
+    const entry = catalog.get(String(name || ''));
+    if (!entry) {
+      throw toolError(
+        'WEBFLOW_TOOL_UNKNOWN',
+        `Unknown Webflow tool: ${name}. Tools: ${[...catalog.keys()].join(', ')}.`,
+      );
+    }
+    return entry;
+  }
+
+  async function invokeUnsafe(name, rawArguments = {}) {
+    if (closed) {
+      throw toolError('WEBFLOW_RUNTIME_CLOSED', 'The Webflow runtime is closed.');
+    }
+    if (!isRecord(rawArguments)) {
+      throw toolError('WEBFLOW_TOOL_INPUT_INVALID', 'Webflow tool arguments must be an object.');
+    }
+    const known = definitions.some((tool) => tool.name === name);
+    if (!known) {
+      throw toolError('WEBFLOW_TOOL_UNKNOWN', `Unknown Webflow tool: ${name}`);
+    }
+    const call = name === 'webflow_call' ? catalogTool(rawArguments.tool) : null;
+    const callArguments = call
+      ? withLabels(call.name, isRecord(rawArguments.arguments) ? rawArguments.arguments : {})
+      : null;
+    const mutation = name === 'webflow_upload_image'
+      || (call ? classifyWebflowToolCall(call.name, callArguments) === 'mutation' : false);
+    const category = name === 'webflow_plan_task'
+      ? 'plan'
+      : mutation
+        ? 'mutation'
+        : 'read';
+    const fingerprint = crypto
+      .createHash('sha256')
+      .update(`${name}\n${JSON.stringify(rawArguments)}`)
+      .digest('hex');
+    if (
+      repeatedFailureFingerprint === fingerprint
+      && repeatedFailureCount >= WEBFLOW_IDENTICAL_FAILURE_LIMIT
+    ) {
+      repeatedFailureStops += 1;
+      throw toolError(
+        'WEBFLOW_REPEATED_CALL_LOOP',
+        'The same Webflow tool call has failed five times in a row. Change the approach or report the concrete blocker.',
+      );
+    }
+    const startedAt = Date.now();
+    const toolCall = {
+      name,
+      ...(call ? { webflowTool: call.name, actions: callActions(callArguments) } : {}),
+      category,
+      status: 'failed',
+      durationMs: 0,
+    };
+    ledger.noteCall(toolCall);
+    if (category === 'read') readCalls += 1;
+    reportActivity({
+      kind: 'tool_active',
+      source: 'webflow',
+      name,
+      phase: 'started',
+      message: mutation ? 'Updating the Webflow site' : 'Inspecting the Webflow site',
+    });
+    try {
+      let text = '';
+      let modelImages = [];
+      if (call) {
+        const pagedArguments = withCurrentPage(call, callArguments);
+        validateCall(call, pagedArguments);
+        if (mutation) ledger.requirePlan();
+        let parsed;
+        try {
+          parsed = await callWebflowTool(call, pagedArguments, mutation);
+        } catch (error) {
+          if (DESIGNER_SESSION_FAILURE.test(String(error?.message || ''))) throw designerSessionError();
+          if (!mutation || !isTimeout(error)) throw error;
+          parsed = { text: JSON.stringify(WEBFLOW_WRITE_UNKNOWN), images: [], isError: false };
+        }
+        // Webflow reports a missing Bridge App as a successful result with status:false.
+        if (DESIGNER_SESSION_FAILURE.test(parsed.text)) throw designerSessionError();
+        if (parsed.isError) {
+          throw toolError('WEBFLOW_MCP_TOOL_FAILED', budgetWebflowText(parsed.text || 'Webflow MCP tool failed.'));
+        }
+        text = budgetWebflowText(parsed.text);
+        modelImages = parsed.images;
+        if (mutation) ledger.markMutation();
+        else ledger.markInspection({ verifies: rawArguments.verifies });
+      } else if (name === 'webflow_tool_help') {
+        const requested = Array.isArray(rawArguments.actions) ? rawArguments.actions.map(String) : [];
+        text = JSON.stringify(toolHelp(catalogTool(rawArguments.tool), requested));
+      } else if (name === 'webflow_plan_task') {
+        text = JSON.stringify(ledger.declarePlan(rawArguments));
+      } else if (name === 'webflow_context') {
+        const context = await relayPanel(name, rawArguments);
+        if (context?.page?.id) currentPageId = String(context.page.id);
+        text = JSON.stringify(context);
+        ledger.markInspection();
+      } else if (name === 'webflow_snapshot') {
+        const relayed = await relayPanel(name, rawArguments);
+        modelImages = panelImages(relayed);
+        snapshotCalls += 1;
+        text = JSON.stringify({ ...withoutImageData(relayed), imageCount: modelImages.length });
+        ledger.markInspection();
+      } else if (name === 'webflow_upload_image') {
+        ledger.requirePlan();
+        text = JSON.stringify(await relayPanel(name, rawArguments));
+        ledger.markMutation();
+      } else if (name === 'webflow_find_images') {
+        if (typeof findImages !== 'function') {
+          throw toolError('WEBFLOW_IMAGE_SEARCH_UNAVAILABLE', 'Image search is not available in this run.');
+        }
+        text = JSON.stringify(await findImages({
+          query: rawArguments.query,
+          orientation: rawArguments.orientation,
+          count: rawArguments.count,
+          signal: abortController.signal,
+        }));
+        ledger.markInspection();
+      } else if (name === 'webflow_read_website') {
+        if (typeof readWebsite !== 'function') {
+          throw toolError('WEBFLOW_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,
+          signal: abortController.signal,
+        });
+        modelImages = panelImages(website);
+        text = JSON.stringify(website?.result ?? website ?? {});
+        ledger.markInspection();
+      }
+      repeatedFailureFingerprint = null;
+      repeatedFailureCount = 0;
+      serverFailures = 0;
+      toolCall.status = 'succeeded';
+      toolCall.durationMs = Date.now() - startedAt;
+      const due = ledger.evidenceForRead(category === 'read' || name === 'webflow_snapshot');
+      return {
+        result: text,
+        ...(modelImages.length ? { modelImages } : {}),
+        ...(due.length ? { evidenceStillDue: due } : {}),
+      };
+    } catch (error) {
+      if (repeatedFailureFingerprint === fingerprint) repeatedFailureCount += 1;
+      else {
+        repeatedFailureFingerprint = fingerprint;
+        repeatedFailureCount = 1;
+      }
+      if (isServerFailure(error)) {
+        serverFailures += 1;
+        if (serverFailures >= WEBFLOW_SERVER_FAILURE_LIMIT) {
+          throw toolError(
+            'WEBFLOW_MCP_UNAVAILABLE',
+            'Webflow MCP kept failing (server error or connection). Stop and report the blocker instead of retrying the same call.',
+            503,
+          );
+        }
+      }
+      toolCall.durationMs = Date.now() - startedAt;
+      toolCall.errorCode = error?.code || 'WEBFLOW_TOOL_FAILED';
+      toolCall.errorMessage = budgetWebflowText(String(error?.message || 'Webflow tool failed.'), 300);
+      trace?.warn?.('webflow_tool_failed', {
+        name,
+        code: error?.code,
+        message: error?.message,
+      });
+      throw error;
+    }
+  }
+
+  async function relayPanel(name, args) {
+    if (typeof callPanelTool !== 'function') {
+      throw toolError('PANEL_NOT_CONNECTED', 'The Webflow panel is not connected to this run.', 409);
+    }
+    const payload = await callPanelTool({
+      callId: crypto.randomUUID(),
+      name,
+      arguments: args,
+      signal: abortController.signal,
+    });
+    // The relay's own failure is top-level; the panel's failure is nested in result.
+    const result = payload?.ok === false ? payload : payload?.result ?? payload;
+    if (result?.ok === false) {
+      throw toolError(
+        result.error?.code || 'PANEL_TOOL_FAILED',
+        result.error?.message || 'The Webflow panel could not run that tool.',
+        409,
+      );
+    }
+    return result;
+  }
+
+  function invoke(name, args = {}) {
+    const operation = serial.then(() => invokeUnsafe(name, args));
+    serial = operation.catch(() => undefined);
+    return operation;
+  }
+
+  async function preflight() {
+    const client = await ensureClient();
+    catalog = catalogFromList(await client.listTools());
+    const guide = catalog.get('webflow_guide_tool');
+    // The guide is loaded here, split between the prompt and webflow_tool_help.
+    catalog.delete('webflow_guide_tool');
+    const parts = [];
+    if (guide) parts.push(splitGuide((await callWebflowTool(guide, {}, false)).text, catalog));
+    definitions = [...initialTools, ...(catalog.size ? gatewayDefinitions([...catalog.keys()]) : [])];
+    if (catalog.size) {
+      parts.push(`Webflow tool catalog. Call these through webflow_call; get exact arguments from webflow_tool_help first:\n${catalogText(catalog)}`);
+    }
+    const content = clipBytes(parts.filter(Boolean).join('\n\n'), WEBFLOW_GUIDANCE_BUDGET_BYTES);
+    const hash = content
+      ? crypto.createHash('sha256').update(content).digest('hex')
+      : null;
+    const cached = guidanceCache.get(siteId);
+    guidance = cached?.hash === hash && hash
+      ? cached
+      : { content, hash };
+    if (siteId && hash) guidanceCache.set(siteId, guidance);
+    return { unresolvedTargets: [] };
+  }
+
+  async function startGateway() {
+    if (gateway) return gateway;
+    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, 'WEBFLOW_GATEWAY_NOT_FOUND', 'Webflow tool endpoint not found.');
+        return;
+      }
+      if (request.headers.authorization !== `Bearer ${token}`) {
+        fail(401, 'WEBFLOW_GATEWAY_UNAUTHORIZED', 'Invalid Webflow 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 || 'WEBFLOW_TOOL_FAILED',
+            error?.message || 'Webflow tool failed.',
+          );
+        }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    gateway = { url: `http://127.0.0.1:${address.port}/tool`, token };
+    return gateway;
+  }
+
+  return {
+    get definitions() {
+      return definitions;
+    },
+    get toolNames() {
+      return definitions.map((tool) => tool.name);
+    },
+    preflight,
+    loadProjectGuidance: async () => ({ content: guidance.content, inventory: '' }),
+    configurePromptContext() {},
+    invoke,
+    startGateway,
+    directWorkspace: true,
+    hasPendingChanges: () => false,
+    sourceHash: () => null,
+    inspect: async () => {
+      await serial;
+      return {
+        synchronized: ledger.verification().structuralCompleted,
+        changed: ledger.mutationCount() > 0,
+        verification: ledger.verification(),
+      };
+    },
+    synchronize: async () => ({ synchronized: true }),
+    finalizeCompletion: (completion) => ledger.finalize(completion),
+    verificationRepairPrompt: () => ledger.repairPrompt(),
+    unblockedFailurePrompt: (completion) => {
+      const lastGate = [...ledger.calls()].reverse().find((call) => call.category === 'plan' || call.category === 'mutation');
+      return ledger.unblockedFailurePrompt(completion, lastGate?.status === 'failed');
+    },
+    summary: () => ({
+      siteId,
+      toolCalls: ledger.calls(),
+      mutationCalls: ledger.mutationCount(),
+      readCalls,
+      snapshotCalls,
+      snapshotsTaken: snapshotCalls,
+      guidanceHash: guidance.hash,
+      mcpToolCount: catalog.size,
+      mcpServerVersion,
+      toolCallCount: ledger.calls().length,
+      verification: ledger.verification(),
+      loopProtection: {
+        identicalFailureLimit: WEBFLOW_IDENTICAL_FAILURE_LIMIT,
+        blockedCalls: repeatedFailureStops,
+        serverFailureLimit: WEBFLOW_SERVER_FAILURE_LIMIT,
+        serverFailures,
+      },
+    }),
+    fatalInfrastructureError: () => null,
+    waitForFatalInfrastructure: () => new Promise(() => undefined),
+    close: async ({ waitForPending = true } = {}) => {
+      closed = true;
+      abortController.abort();
+      if (waitForPending) await serial.catch(() => undefined);
+      if (connected?.close && connected !== mcpClient) {
+        await connected.close().catch(() => undefined);
+      }
+      if (server) {
+        if (!waitForPending) server.closeAllConnections?.();
+        await new Promise((resolve) => server.close(() => resolve()));
+        server = null;
+      }
+    },
+  };
+}
+
+export function __resetWebflowToolRuntimeForTests() {
+  guidanceCache.clear();
+}