@gakim-digital/dexter-bridge 0.12.1 → 0.13.0

package/src/taskEvidence.js

@@ -0,0 +1,245 @@
+// Shared task-plan and post-mutation evidence gate for design harnesses.
+// Framer keeps its interaction checks and calls the decision helpers.
+// Webflow uses the ledger; whether to look at a screenshot is the model's call.
+
+export function missingEvidenceChecks({
+  mutationCalls,
+  hasPlan,
+  requiredChecks = [],
+  unavailable = [],
+  completed,
+}) {
+  if (mutationCalls === 0) return [];
+  const missing = [];
+  if (!hasPlan) missing.push('task-plan');
+  for (const check of requiredChecks) {
+    if (unavailable.includes(check)) continue;
+    if (!completed(check)) missing.push(check);
+  }
+  return missing;
+}
+
+export function evidenceStillDue({
+  hasPlan,
+  mutationCalls,
+  reading,
+  missing = [],
+}) {
+  if (!(hasPlan && mutationCalls > 0 && reading)) return [];
+  return missing;
+}
+
+function uniqueStrings(values) {
+  return [...new Set(
+    (Array.isArray(values) ? values : [])
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  )];
+}
+
+function toolError(code, message) {
+  return Object.assign(new Error(message), { code, statusCode: 400 });
+}
+
+export function createEvidenceLedger({
+  checks,
+  domains,
+  labels = {},
+  messages = {},
+} = {}) {
+  const allowedChecks = new Set(checks || []);
+  const allowedDomains = new Set(domains || []);
+  let operationSequence = 0;
+  let lastMutationSequence = 0;
+  let lastInspectionSequence = 0;
+  let mutationCalls = 0;
+  let taskPlan = null;
+  const verificationEvidence = new Map();
+  let lastMutationAt = null;
+  let lastInspectionAt = null;
+  const toolCalls = [];
+
+  const synchronized = () =>
+    mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
+  const requiredVerification = () => taskPlan?.verification || [];
+  const requiredChecks = () => [...new Set(['structural', ...requiredVerification()])];
+  const completed = (check) => {
+    if (mutationCalls === 0) return true;
+    if (check === 'structural') return synchronized();
+    return Number(verificationEvidence.get(check) || 0) > lastMutationSequence;
+  };
+  const missing = () => missingEvidenceChecks({
+    mutationCalls,
+    hasPlan: Boolean(taskPlan),
+    requiredChecks: requiredChecks(),
+    completed,
+  });
+
+  function markMutation() {
+    mutationCalls += 1;
+    operationSequence += 1;
+    lastMutationSequence = operationSequence;
+    lastMutationAt = new Date().toISOString();
+    return operationSequence;
+  }
+
+  function markInspection({ verifies = [] } = {}) {
+    operationSequence += 1;
+    lastInspectionSequence = operationSequence;
+    lastInspectionAt = new Date().toISOString();
+    verificationEvidence.set('structural', operationSequence);
+    for (const check of uniqueStrings(verifies)) {
+      if (allowedChecks.has(check) && check !== 'structural') {
+        verificationEvidence.set(check, operationSequence);
+      }
+    }
+    return operationSequence;
+  }
+
+  function requireInspection() {
+    if (lastInspectionSequence === 0) {
+      throw toolError(
+        'WEBFLOW_HARNESS_INSPECTION_REQUIRED',
+        messages.inspectionRequired
+          || 'Inspect the live Webflow site before declaring the task and verification plan.',
+      );
+    }
+  }
+
+  function requirePlan() {
+    if (!taskPlan) {
+      throw toolError(
+        'WEBFLOW_HARNESS_PLAN_REQUIRED',
+        messages.planRequired
+          || 'Inspect the live Webflow site, then call webflow_plan_task before making a change.',
+      );
+    }
+  }
+
+  function declarePlan(raw = {}) {
+    requireInspection();
+    const summary = String(raw.summary || '').trim().slice(0, 1000);
+    const declaredDomains = uniqueStrings(raw.domains).filter((domain) => allowedDomains.has(domain));
+    const declaredChecks = uniqueStrings(raw.verification).filter((check) => allowedChecks.has(check));
+    if (summary.length < 10 || declaredDomains.length === 0) {
+      throw toolError(
+        'WEBFLOW_HARNESS_PLAN_INVALID',
+        messages.planInvalid
+          || 'Describe the understood task and declare at least one task domain.',
+      );
+    }
+    taskPlan = {
+      summary,
+      domains: uniqueStrings([...(taskPlan?.domains || []), ...declaredDomains]),
+      verification: uniqueStrings(['structural', ...(taskPlan?.verification || []), ...declaredChecks]),
+    };
+    return {
+      plan: {
+        summary: taskPlan.summary,
+        domains: [...taskPlan.domains],
+        verification: [...taskPlan.verification],
+      },
+      beforeFinishing: `After your final change, and before returning, produce: ${requiredChecks().map((check) => labels[check] || check).join('; ')}.`,
+    };
+  }
+
+  function noteCall(call) {
+    toolCalls.push(call);
+  }
+
+  function evidenceForRead(reading) {
+    return evidenceStillDue({
+      hasPlan: Boolean(taskPlan),
+      mutationCalls,
+      reading,
+      missing: missing(),
+    });
+  }
+
+  function verification() {
+    return {
+      ownedBy: 'harness',
+      required: mutationCalls > 0,
+      completed: missing().length === 0,
+      structuralCompleted: synchronized(),
+      taskPlan: taskPlan
+        ? {
+            summary: taskPlan.summary,
+            domains: [...taskPlan.domains],
+            verification: [...taskPlan.verification],
+          }
+        : null,
+      requiredChecks: requiredChecks(),
+      completedChecks: requiredChecks().filter(completed),
+      missingChecks: missing(),
+      lastMutationAt,
+      lastInspectionAt,
+    };
+  }
+
+  function finalize(completion) {
+    if (completion?.status !== 'completed' || mutationCalls === 0) return completion;
+    if (verification().completed) return completion;
+    const described = missing().map((check) => labels[check] || `post-mutation ${check} verification`);
+    const reason = `The harness ended before completing ${described.join(' and ')}.`;
+    return {
+      ...completion,
+      status: 'failed',
+      summary: String(completion?.summary || '').trim() || 'The requested changes were applied.',
+      checks: [
+        ...(Array.isArray(completion?.checks) ? completion.checks : []),
+        {
+          command: 'Harness-owned final verification',
+          status: 'failed',
+          output: reason,
+        },
+      ],
+      blockedReason: null,
+    };
+  }
+
+  function repairPrompt() {
+    const current = verification();
+    if (current.completed || mutationCalls === 0) return null;
+    const steps = (current.missingChecks || []).map((check) => labels[check] || check);
+    return [
+      messages.repairLead || 'Continue the same Webflow task from its current site state.',
+      'Do not redo successful work.',
+      `Before returning, ${steps.join(' and ')}.`,
+      'Then return the required JSON outcome.',
+    ].join(' ');
+  }
+
+  function unblockedFailurePrompt(completion, lastGateFailed) {
+    if (completion?.status !== 'failed' || mutationCalls > 0 || lastGateFailed) return null;
+    return [
+      'You returned failed without changing the Webflow site, and no tool refused the work.',
+      'Nothing in this run is blocking you and there is no time limit.',
+      'Continue the same task from the current site: plan it, apply the change, verify it, then return the required JSON outcome.',
+      'Return failed or blocked only for a concrete blocker you can name.',
+    ].join(' ');
+  }
+
+  return {
+    markMutation,
+    markInspection,
+    requirePlan,
+    declarePlan,
+    noteCall,
+    evidenceForRead,
+    verification,
+    finalize,
+    repairPrompt,
+    unblockedFailurePrompt,
+    mutationCount: () => mutationCalls,
+    plan: () => (taskPlan
+      ? {
+          summary: taskPlan.summary,
+          domains: [...taskPlan.domains],
+          verification: [...taskPlan.verification],
+        }
+      : null),
+    calls: () => toolCalls.map((call) => ({ ...call })),
+  };
+}