surf-cli 2.19.0 → 2.20.0

package/native/semantic-workflow.cjs

@@ -0,0 +1,398 @@
+const crypto = require("node:crypto");
+const { SEMANTIC_POLICY, find, verify } = require("./semantic-core.cjs");
+const {
+  buildLogicalCandidates,
+  canonicalSameOriginDestination,
+  confirmedActionResponse,
+  expectedIdentity,
+  providerState,
+  semanticObservationFrom,
+} = require("./semantic-cli.cjs");
+
+const WORKFLOW_POLICY = Object.freeze({
+  defaultDeadlineMs: 60_000,
+  maxDeadlineMs: 120_000,
+  defaultProviderCalls: 32,
+  maxProviderCalls: 64,
+  defaultSearchObservations: 12,
+  maxSearchObservations: 32,
+  maxSteps: 32,
+  verificationMs: 5_000,
+  noProgressObservations: 2,
+});
+
+function failure(reason, detail = {}) {
+  return { kind: "failure", status: "blocked", reason, ...detail };
+}
+
+function success(status, detail = {}) {
+  return { kind: "success", status, ...detail };
+}
+
+function parseBoundary(response, label) {
+  if (response?.error) throw Object.assign(new Error(response.error.message || `${label} failed`), { code: response.error.code });
+  if (response?.result?.content) {
+    const text = response.result.content.find((item) => item.type === "text")?.text;
+    try { return JSON.parse(text); } catch { throw new Error(`browser returned an invalid ${label} response`); }
+  }
+  return response;
+}
+
+function samePinnedScope(left, right) {
+  return left.browserEpoch === right.browserEpoch && left.tabId === right.tabId && left.frameId === right.frameId;
+}
+
+function publicBinding(binding) {
+  return { handle: binding.handle, role: binding.candidate.role || null, name: binding.candidate.name || null, type: binding.candidate.type || null };
+}
+
+function scanCoverage(intervals, scrollHeight, truncated, invalidated = false) {
+  const validHeight = Number.isFinite(scrollHeight) && scrollHeight >= 0;
+  const validIntervals = validHeight && intervals.every(({ start, end }) =>
+    Number.isFinite(start) && Number.isFinite(end) && start >= 0 && start <= end && end <= scrollHeight);
+  const merged = [];
+  if (validIntervals) {
+    for (const interval of [...intervals].sort((left, right) => left.start - right.start || left.end - right.end)) {
+      const previous = merged.at(-1);
+      if (previous && interval.start <= previous.end) previous.end = Math.max(previous.end, interval.end);
+      else merged.push({ ...interval });
+    }
+  }
+  const atBottom = validIntervals && intervals.some(({ end }) => end >= scrollHeight);
+  const spansScope = merged.length === 1 && merged[0].start === 0 && merged[0].end >= scrollHeight;
+  return { intervals, atBottom, complete: atBottom && spansScope && !truncated && !invalidated, truncated };
+}
+
+function createSemanticWorkflowRuntime(dependencies) {
+  const { request, evaluate, attemptStore = null, createAttemptStore, now = () => Date.now(), sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = dependencies;
+  if (typeof request !== "function" || typeof evaluate !== "function") throw new TypeError("semantic workflow requires request and evaluate boundaries");
+
+  function createContext(options = {}) {
+    const deadlineMs = options.deadlineMs ?? WORKFLOW_POLICY.defaultDeadlineMs;
+    const maxProviderCalls = options.maxProviderCalls ?? WORKFLOW_POLICY.defaultProviderCalls;
+    if (!Number.isInteger(deadlineMs) || deadlineMs < 1 || deadlineMs > WORKFLOW_POLICY.maxDeadlineMs) throw new Error("invalid semantic workflow deadline");
+    if (!Number.isInteger(maxProviderCalls) || maxProviderCalls < 1 || maxProviderCalls > WORKFLOW_POLICY.maxProviderCalls) throw new Error("invalid semantic provider-call limit");
+    const inputs = { ...(options.inputs || {}) };
+    if (Object.keys(inputs).length > SEMANTIC_POLICY.limits.inputSlots) throw new Error("semantic input-slot limit exceeded");
+    for (const value of Object.values(inputs)) {
+      if (Buffer.byteLength(String(value), "utf8") > SEMANTIC_POLICY.limits.inputValueBytes) throw new Error("semantic input value exceeds its byte limit");
+    }
+    const runId = options.runId || crypto.randomUUID();
+    const workflowDigest = options.workflowDigest || "unknown";
+    return {
+      runId, workflowDigest,
+      deadline: now() + deadlineMs, maxProviderCalls, bindings: new Map(), inputs,
+      limits: { deadlineMs, maxProviderCalls },
+      pinned: null, acquired: false, steps: 0, completedSteps: [],
+      attemptStore: attemptStore || createAttemptStore?.({ runId, workflowDigest }),
+      usage: { providerCalls: 0, inputTokens: 0, outputTokens: 0, partial: false, browserCommands: 0, semanticDecisions: 0, observations: 0 },
+    };
+  }
+
+  const remaining = (context) => Math.max(0, context.deadline - now());
+  async function browser(context, tool, args) {
+    if (remaining(context) < 1) throw Object.assign(new Error("semantic workflow deadline exhausted"), { code: "budget_exhausted" });
+    context.usage.browserCommands++;
+    return request(tool, args, remaining(context), context.pinned);
+  }
+  async function observe(context) {
+    const observation = semanticObservationFrom(await browser(context, "page.read", { semanticObservation: true }));
+    context.usage.observations++;
+    if (!context.pinned) context.pinned = { ...observation.identity };
+    else if (!samePinnedScope(context.pinned, observation.identity)) throw Object.assign(new Error("pinned browser scope changed"), { code: "stale_identity" });
+    return observation;
+  }
+  async function evaluator(context, state, questions, options = {}) {
+    if (++context.usage.providerCalls > context.maxProviderCalls) throw Object.assign(new Error("semantic provider-call budget exhausted"), { code: "budget_exhausted" });
+    if (remaining(context) < 1) throw Object.assign(new Error("semantic workflow deadline exhausted"), { code: "budget_exhausted" });
+    context.usage.semanticDecisions++;
+    const timeoutMs = Math.min(SEMANTIC_POLICY.timeoutMs, remaining(context));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await evaluate(state, questions, { ...options, signal: controller.signal, timeoutMs });
+      context.model = response.model;
+      context.usage.inputTokens += response.usage?.input_tokens || 0;
+      context.usage.outputTokens += response.usage?.output_tokens || 0;
+      return response;
+    } catch (error) {
+      context.usage.partial = true;
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function decide(context, observation, query, target, binding) {
+    const state = providerState(observation);
+    const eligibleRefs = new Set(observation.candidates.filter((candidate) => {
+      if ((target.role && candidate.role !== target.role) || (target.type && candidate.type !== target.type)) return false;
+      if (!binding) return true;
+      return candidate.role === binding.candidate.role &&
+        candidate.type === binding.candidate.type &&
+        candidate.name === binding.candidate.name &&
+        canonicalSameOriginDestination(candidate, observation.identity.fullUrl) ===
+          canonicalSameOriginDestination(binding.candidate, binding.fullUrl);
+    }).map((candidate) => candidate.ref));
+    const candidates = buildLogicalCandidates(observation, state.candidates).flatMap((candidate) => {
+      const concreteCandidates = candidate.concreteCandidates.filter((item) => eligibleRefs.has(item.id));
+      return concreteCandidates.length ? [{ ...candidate, concreteCandidates }] : [];
+    });
+    if (!candidates.length) return null;
+    const result = await find({
+      state: {
+        ...state,
+        candidates: candidates.map(({ id, role, name, type, text }) => ({ id, role, name, type, text })),
+      },
+      goal: query,
+      candidates,
+      evaluate: (s, q, o) => evaluator(context, s, q, o),
+    });
+    return {
+      ...result,
+      candidate: result.candidate?.concreteCandidates[0] || null,
+    };
+  }
+  async function scrollGeometry(context, action, scopeToken, identity) {
+    const value = parseBoundary(await browser(context, "semantic.scrollScope", {
+      action, scopeToken, semanticExpectedIdentity: identity,
+      ...(action === "advance" ? { maxFraction: 0.75 } : {}),
+    }), "scroll scope");
+    if (value?.success !== true || !value.geometry || typeof value.scopeToken !== "string") throw Object.assign(new Error(value?.reason || "scroll scope unavailable"), { code: value?.reason || "unsupported_control" });
+    if (scopeToken && value.scopeToken !== scopeToken) throw Object.assign(new Error("scroll scope changed"), { code: "stale_scroll_scope" });
+    return value;
+  }
+  async function resolve(context, target, write, search = {}) {
+    const binding = target?.binding ? context.bindings.get(target.binding) : null;
+    if (target?.binding && !binding) return { error: failure("invalid_binding") };
+    const query = binding?.query || target?.query;
+    if (typeof query !== "string" || !query.trim()) return { error: failure("validation_failure") };
+    const maximum = search.maxObservations ?? WORKFLOW_POLICY.defaultSearchObservations;
+    if (!Number.isInteger(maximum) || maximum < 1 || maximum > WORKFLOW_POLICY.maxSearchObservations) return { error: failure("validation_failure") };
+    let observation = await observe(context);
+    let scope = await scrollGeometry(context, "inspect", undefined, observation.identity);
+    const inspectedGeometry = scope.geometry;
+    scope = await scrollGeometry(context, "top", scope.scopeToken, observation.identity);
+    const initialObservationStillVisible = inspectedGeometry.intervalStart === scope.geometry.intervalStart &&
+      inspectedGeometry.intervalEnd === scope.geometry.intervalEnd &&
+      inspectedGeometry.scrollHeight === scope.geometry.scrollHeight;
+    const intervals = [];
+    const scopedScrollHeight = scope.geometry.scrollHeight;
+    let noProgress = 0;
+    let truncated = false;
+    let invalidated = false;
+    for (let index = 0; index < maximum; index++) {
+      if (index || !initialObservationStillVisible) observation = await observe(context);
+      truncated ||= Number(observation.omitted?.candidates || 0) + Number(observation.omitted?.chunks || 0) > 0;
+      const geometry = scope.geometry;
+      intervals.push({ start: geometry.intervalStart, end: geometry.intervalEnd });
+      invalidated ||= geometry.scrollHeight !== scopedScrollHeight;
+      const coverage = scanCoverage(intervals, geometry.scrollHeight, truncated, invalidated);
+      const decision = await decide(context, observation, query, target, binding);
+      if (decision?.candidate &&
+          (!target.role || decision.candidate.role === target.role) &&
+          (!target.type || decision.candidate.type === target.type)) {
+        if (!write || decision.decision.probability >= SEMANTIC_POLICY.thresholds.write) {
+          const concrete = observation.candidates.find((item) => item.ref === decision.candidate.id);
+          if (binding) {
+            const priorDestination = canonicalSameOriginDestination(binding.candidate, binding.fullUrl);
+            const nextDestination = canonicalSameOriginDestination(concrete, observation.identity.fullUrl);
+            if (concrete.role !== binding.candidate.role || concrete.type !== binding.candidate.type || concrete.name !== binding.candidate.name || priorDestination !== nextDestination) {
+              return { error: failure("ambiguous_target") };
+            }
+          }
+          return { observation, candidate: concrete, query, decision, coverage };
+        }
+        return { error: failure("low_confidence", { probability: decision.decision.probability, appliedThreshold: SEMANTIC_POLICY.thresholds.write }) };
+      }
+      if (coverage.atBottom) return { error: failure(coverage.complete ? "target_not_found" : "incomplete_search", { coverage }) };
+      if (index + 1 === maximum) return { error: failure("incomplete_search", { coverage }) };
+      const next = await scrollGeometry(context, "advance", scope.scopeToken, observation.identity);
+      const progressed = next.geometry.intervalStart > geometry.intervalStart && next.geometry.intervalStart <= geometry.intervalEnd;
+      noProgress = progressed ? 0 : noProgress + 1;
+      if (noProgress >= WORKFLOW_POLICY.noProgressObservations) return { error: failure("no_progress", { coverage }) };
+      scope = next;
+    }
+    return { error: failure("incomplete_search") };
+  }
+  async function compare(context, observation, candidate, predicate) {
+    return parseBoundary(await browser(context, "semantic.localCompare", {
+      ref: candidate.ref, predicate, semanticExpectedIdentity: expectedIdentity(observation, candidate),
+    }), "local comparison");
+  }
+  function localPredicate(context, predicate) {
+    if (!predicate || typeof predicate !== "object") return predicate;
+    let expected = predicate.expected ?? predicate.equals ?? predicate.contains;
+    if (predicate.input !== undefined) expected = context.inputs[predicate.input];
+    return {
+      kind: predicate.kind === "textExact" ? "textEquals" : predicate.kind,
+      ...(expected !== undefined ? { expected: predicate.kind === "checkedEquals" ? Boolean(expected) : String(expected) } : {}),
+    };
+  }
+  async function verifyPredicate(context, observation, candidate, predicate) {
+    predicate = localPredicate(context, predicate);
+    const until = Math.min(context.deadline, now() + WORKFLOW_POLICY.verificationMs);
+    const fullUrl = observation.identity.fullUrl;
+    do {
+      const result = await compare(context, observation, candidate, predicate);
+      if (result?.success === true && result.matches === true) return true;
+      if (now() >= until) return false;
+      await sleep(Math.min(100, until - now()));
+      const refreshed = await observe(context);
+      if (refreshed.identity.fullUrl !== fullUrl) return false;
+      const matching = refreshed.candidates.filter((item) =>
+        item.role === candidate.role && item.type === candidate.type && item.name === candidate.name);
+      if (matching.length !== 1) return false;
+      observation = refreshed;
+      candidate = matching[0];
+    } while (remaining(context) > 0);
+    return false;
+  }
+  async function verifyExpectation(context, resolved, expectation) {
+    if (expectation?.mode === "semantic") {
+      const observation = await observe(context);
+      const state = providerState(observation);
+      const result = await verify({
+        state,
+        outcome: expectation.claim,
+        evidence: state.chunks,
+        evaluate: (s, q, o) => evaluator(context, s, q, o),
+      });
+      return result.status === "satisfied";
+    }
+    if (expectation?.kind === "urlPath") {
+      const observation = await observe(context);
+      return new URL(observation.identity.fullUrl).pathname === expectation.equals;
+    }
+    if (expectation?.target) {
+      const expectedTarget = await resolve(context, expectation.target, false, { maxObservations: 1 });
+      if (expectedTarget.error) return false;
+      return verifyPredicate(context, expectedTarget.observation, expectedTarget.candidate, expectation);
+    }
+    return verifyPredicate(context, resolved.observation, resolved.candidate, expectation);
+  }
+  async function storeCall(context, name, ...args) {
+    if (!context.attemptStore?.[name]) throw new Error(`attempt store does not implement ${name}`);
+    return context.attemptStore[name](...args);
+  }
+  async function mutate(context, step, resolved, action, predicate, value) {
+    const record = {
+      stepId: step.id,
+      operation: step.op,
+      target: {
+        role: resolved.candidate.role,
+        ...(resolved.candidate.name ? { name: resolved.candidate.name } : {}),
+      },
+      budgets: { remainingMs: remaining(context) },
+    };
+    let attempt;
+    try { attempt = await storeCall(context, "reserve", record); await storeCall(context, "dispatchIntent", attempt.attemptId); }
+    catch { return failure("checkpoint_failure", { write: { state: "not_dispatched", replayAllowed: false } }); }
+    try {
+      const args = action === "fill"
+        ? { data: [{ ref: resolved.candidate.ref, value }], semanticExpectedIdentity: expectedIdentity(resolved.observation, resolved.candidate) }
+        : { ref: resolved.candidate.ref, semanticExpectedIdentity: expectedIdentity(resolved.observation, resolved.candidate) };
+      const response = await browser(context, action === "fill" ? "form.fill" : "click", args);
+      confirmedActionResponse(response);
+    } catch {
+      try { await storeCall(context, "terminal", attempt.attemptId, "outcome_unknown"); }
+      catch { return failure("checkpoint_failure", { write: { state: "dispatch_unknown", replayAllowed: false } }); }
+      return failure("outcome_unknown", { write: { state: "dispatch_unknown", replayAllowed: false } });
+    }
+    let verified;
+    try { verified = predicate ? await verifyExpectation(context, resolved, predicate) : false; }
+    catch (error) {
+      try { await storeCall(context, "terminal", attempt.attemptId, "acknowledged_unverified"); }
+      catch { return failure("checkpoint_failure", { write: { state: "acknowledged_unverified", replayAllowed: false } }); }
+      return failure(error.code || "verification_failed", { write: { state: "acknowledged_unverified", replayAllowed: false } });
+    }
+    try { await storeCall(context, "terminal", attempt.attemptId, verified ? "verified" : "acknowledged_unverified"); }
+    catch { return failure("checkpoint_failure", { write: { state: verified ? "acknowledged_verified" : "acknowledged_unverified", replayAllowed: false } }); }
+    return verified ? success("verified", { write: { state: "acknowledged_verified", replayAllowed: false } }) : failure("assertion_mismatch", { write: { state: "acknowledged_unverified", replayAllowed: false } });
+  }
+
+  async function executeStepInner(step, context) {
+    if (!context || !(context.bindings instanceof Map)) throw new TypeError("invalid semantic workflow context");
+    if (++context.steps > WORKFLOW_POLICY.maxSteps) return failure("budget_exhaustion");
+    if (remaining(context) < 1) return failure("budget_exhaustion");
+    if (!context.acquired && context.attemptStore) { await context.attemptStore.acquire(); context.acquired = true; }
+    try {
+      if (step.op === "find") {
+        const resolved = await resolve(context, step.target, false, step.search);
+        if (resolved.error) return resolved.error;
+        const handle = step.as || step.id;
+        const binding = { handle, query: resolved.query, candidate: resolved.candidate, fullUrl: resolved.observation.identity.fullUrl };
+        context.bindings.set(handle, binding);
+        return success("completed", { binding: publicBinding(binding), coverage: resolved.coverage, probability: resolved.decision.decision.probability });
+      }
+      if (step.op === "open") {
+        const resolved = await resolve(context, step.target, false);
+        if (resolved.error) return resolved.error;
+        const url = canonicalSameOriginDestination(resolved.candidate, resolved.observation.identity.fullUrl);
+        if (!url) return failure("unsupported_control");
+        confirmedActionResponse(await browser(context, "navigate", { url, semanticExpectedIdentity: resolved.observation.identity }));
+        const arrived = await observe(context);
+        return new URL(arrived.identity.fullUrl).href === url ? success("verified") : failure("assertion_mismatch");
+      }
+      if (step.op === "assert" && step.mode === "semantic") {
+        const observation = await observe(context);
+        const state = providerState(observation);
+        const result = await verify({ state, outcome: step.claim, evidence: state.chunks, evaluate: (s, q, o) => evaluator(context, s, q, o) });
+        return result.status === "satisfied" ? success("verified", { probability: result.decision.probability }) : failure("assertion_mismatch", { semanticStatus: result.status });
+      }
+      if (step.op === "assert") {
+        const resolved = await resolve(context, step.target || step.predicate?.target, false, { maxObservations: 1 });
+        if (resolved.error) return resolved.error;
+        return await verifyPredicate(context, resolved.observation, resolved.candidate, step.predicate) ? success("verified") : failure("assertion_mismatch");
+      }
+      const resolved = await resolve(context, step.target, true, step.search);
+      if (resolved.error) return resolved.error;
+      if (step.op === "ensureChecked") {
+        const predicate = { kind: "checkedEquals", expected: step.checked };
+        const comparison = await compare(context, resolved.observation, resolved.candidate, predicate);
+        if (comparison?.success !== true) return failure(comparison?.reason || "unsupported_control");
+        if (comparison.matches === true) return success("skipped_already_satisfied");
+        return await mutate(context, step, resolved, "click", predicate);
+      }
+      if (step.op === "fill") {
+        if (!Object.hasOwn(context.inputs, step.input)) return failure("validation_failure");
+        const value = String(context.inputs[step.input]);
+        const predicate = { kind: "valueEquals", expected: value };
+        const comparison = await compare(context, resolved.observation, resolved.candidate, predicate);
+        if (comparison?.success !== true) return failure(comparison?.reason || "unsupported_control");
+        if (comparison.matches === true) return success("skipped_already_satisfied");
+        return await mutate(context, step, resolved, "fill", predicate, value);
+      }
+      if (step.op === "click") {
+        if (!step.expect) return failure("validation_failure");
+        return await mutate(context, step, resolved, "click", step.expect);
+      }
+      return failure("validation_failure");
+    } catch (error) {
+      return failure(error.code === "budget_exhausted" ? "budget_exhaustion" : (error.code || "provider_error"));
+    }
+  }
+  async function executeStep(step, context) {
+    const result = await executeStepInner(step, context);
+    if (result.kind === "success") context.completedSteps.push(step.id);
+    return result;
+  }
+  async function closeContext(context, terminal = {}) {
+    if (!context?.acquired || !context.attemptStore) return;
+    try {
+      await context.attemptStore.checkpoint({
+        completedSteps: context.completedSteps,
+        reason: terminal.reason || null,
+        budgets: { remainingMs: remaining(context) },
+      });
+    } finally {
+      await context.attemptStore.release({
+        state: terminal.state || (terminal.reason ? "failed" : "completed"),
+        reason: terminal.reason,
+      });
+      context.acquired = false;
+    }
+  }
+  return { closeContext, createContext, executeStep };
+}
+
+module.exports = { WORKFLOW_POLICY, createSemanticWorkflowRuntime };

package/native/tool-scope.cjs

@@ -43,6 +43,7 @@ const TAB_TOOLS = new Set([
   "click", "left_click", "right_click", "double_click", "triple_click", "drag", "hover", "key", "submit",
   "type", "smart_type", "find_and_type", "form_input", "form.fill", "select", "upload", "upload_image",
   "scroll", "scroll.top", "scroll.bottom", "scroll.to", "scroll.info", "scroll_to_position",
+  "semantic.localCompare", "semantic.scrollScope",
   "search", "locate.role", "locate.text", "locate.label", "element.styles",
   "js", "javascript_tool", "eval",
   "wait.element", "wait.url", "wait.network", "wait.dom", "wait.load", "wait.ready", "page.readiness", "health",

package/native/workflow-definition.cjs

@@ -280,7 +280,126 @@ function normalizeStep(step) {
   }
   const cmd = step.tool || step.cmd;
   if (typeof cmd !== "string" || !cmd) throw new Error("workflow step must have a 'tool' field");
-  return { cmd: ALIASES[cmd] || cmd, args: step.args || {}, ...(step.as ? { as: step.as } : {}) };
+  return { cmd: ALIASES[cmd] || cmd, args: step.args || {}, ...(step.id ? { id: step.id } : {}), ...(step.as ? { as: step.as } : {}) };
+}
+
+const SEMANTIC_OPS = new Set(["find", "open", "ensureChecked", "fill", "click", "assert"]);
+const SEMANTIC_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+const SEMANTIC_STEP_FIELDS = new Set(["id", "tool", "args", "as"]);
+const SEMANTIC_ARG_FIELDS = {
+  find: new Set(["op", "target", "search"]),
+  open: new Set(["op", "target", "expect"]),
+  ensureChecked: new Set(["op", "target", "checked", "expect"]),
+  fill: new Set(["op", "target", "input", "expect"]),
+  click: new Set(["op", "target", "expect"]),
+  assert: new Set(["op", "mode", "claim", "bindings", "target", "predicate"]),
+};
+
+function assertClosedObject(value, allowed, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${path}.${key} is not allowed`);
+  }
+}
+
+function assertSemanticName(value, path) {
+  if (typeof value !== "string" || !SEMANTIC_ID.test(value)) {
+    throw new Error(`${path} must be a 1-64 character identifier`);
+  }
+}
+
+function validateTarget(target, path, { queryOnly = false } = {}) {
+  assertClosedObject(target, new Set(["query", "role", "type", "binding"]), path);
+  const hasQuery = typeof target.query === "string" && target.query.length > 0;
+  const hasBinding = typeof target.binding === "string" && target.binding.length > 0;
+  if (hasQuery === hasBinding || (queryOnly && !hasQuery)) {
+    throw new Error(`${path} must contain exactly one of 'query' or 'binding'${queryOnly ? " (query required)" : ""}`);
+  }
+  if (hasBinding && (target.role !== undefined || target.type !== undefined)) {
+    throw new Error(`${path} binding cannot include role or type`);
+  }
+  if (target.role !== undefined && (typeof target.role !== "string" || !target.role)) throw new Error(`${path}.role must be a non-empty string`);
+  if (target.type !== undefined && (typeof target.type !== "string" || !target.type)) throw new Error(`${path}.type must be a non-empty string`);
+}
+
+function validateExpectation(value, path) {
+  assertClosedObject(value, new Set(["kind", "mode", "target", "equals", "contains", "input", "binding", "claim"]), path);
+  const kinds = new Set(["urlPath", "visible", "checkedEquals", "valueEquals", "textExact", "textContains"]);
+  if (value.mode === "semantic") {
+    if (typeof value.claim !== "string" || !value.claim) throw new Error(`${path}.claim must be a non-empty string`);
+  } else if (!kinds.has(value.kind)) throw new Error(`${path}.kind is invalid`);
+  if (value.target !== undefined) validateTarget(value.target, `${path}.target`);
+}
+
+function validateSemanticStep(step, index, priorBindings, ids, policy) {
+  const path = `steps[${index}]`;
+  assertClosedObject(step, SEMANTIC_STEP_FIELDS, path);
+  if (step.tool !== "semantic.step") throw new Error(`${path}.tool must be 'semantic.step'`);
+  assertSemanticName(step.id, `${path}.id`);
+  if (ids.has(step.id)) throw new Error(`${path}.id must be unique`);
+  ids.add(step.id);
+  if (step.as !== undefined) {
+    assertSemanticName(step.as, `${path}.as`);
+    if (priorBindings.has(step.as)) throw new Error(`${path}.as must be unique`);
+  }
+  if (!step.args || typeof step.args !== "object" || Array.isArray(step.args)) throw new Error(`${path}.args must be an object`);
+  const op = step.args.op;
+  if (!SEMANTIC_OPS.has(op)) throw new Error(`${path}.args.op is invalid`);
+  assertClosedObject(step.args, SEMANTIC_ARG_FIELDS[op], `${path}.args`);
+
+  if (op === "find") {
+    validateTarget(step.args.target, `${path}.args.target`, { queryOnly: true });
+    if (step.args.search !== undefined) {
+      assertClosedObject(step.args.search, new Set(["mode", "maxObservations"]), `${path}.args.search`);
+      if (step.args.search.mode !== "scroll") throw new Error(`${path}.args.search.mode must be 'scroll'`);
+      if (step.args.search.maxObservations !== undefined && (!Number.isInteger(step.args.search.maxObservations) || step.args.search.maxObservations < 1 || step.args.search.maxObservations > policy.maxSearchObservations)) {
+        throw new Error(`${path}.args.search.maxObservations must be an integer from 1 to ${policy.maxSearchObservations}`);
+      }
+    }
+  } else if (op !== "assert") validateTarget(step.args.target, `${path}.args.target`);
+
+  if (op === "ensureChecked" && typeof step.args.checked !== "boolean") throw new Error(`${path}.args.checked must be a boolean`);
+  if (op === "fill") assertSemanticName(step.args.input, `${path}.args.input`);
+  if (op === "click" && step.args.expect === undefined) throw new Error(`${path}.args.expect is required`);
+  if (step.args.expect !== undefined) validateExpectation(step.args.expect, `${path}.args.expect`);
+  if (op === "assert") {
+    if (step.args.mode !== "local" && step.args.mode !== "semantic") throw new Error(`${path}.args.mode must be 'local' or 'semantic'`);
+    if (step.args.mode === "semantic" && (typeof step.args.claim !== "string" || !step.args.claim)) throw new Error(`${path}.args.claim must be a non-empty string`);
+    if (step.args.mode === "local") validateExpectation(step.args.predicate, `${path}.args.predicate`);
+    if (step.args.target !== undefined) validateTarget(step.args.target, `${path}.args.target`);
+  }
+
+  const references = [];
+  if (step.args.target?.binding) references.push(step.args.target.binding);
+  if (step.args.expect?.target?.binding) references.push(step.args.expect.target.binding);
+  if (step.args.expect?.binding) references.push(step.args.expect.binding);
+  if (step.args.predicate?.target?.binding) references.push(step.args.predicate.target.binding);
+  if (step.args.predicate?.binding) references.push(step.args.predicate.binding);
+  if (Array.isArray(step.args.bindings)) references.push(...step.args.bindings);
+  else if (step.args.bindings !== undefined) throw new Error(`${path}.args.bindings must be an array`);
+  for (const binding of references) {
+    assertSemanticName(binding, `${path} binding`);
+    if (!priorBindings.has(binding)) throw new Error(`${path} binding '${binding}' must refer to a prior step output`);
+  }
+  if (step.as !== undefined) {
+    priorBindings.add(step.as);
+  }
+}
+
+function validateSemanticWorkflow(workflow) {
+  const { WORKFLOW_POLICY } = require("./semantic-workflow.cjs");
+  assertClosedObject(workflow.semantic, new Set(["version", "deadlineMs", "maxProviderCalls"]), "semantic");
+  if (workflow.semantic.version !== 1) throw new Error("semantic.version must equal 1");
+  if (workflow.steps.length > WORKFLOW_POLICY.maxSteps) throw new Error(`semantic workflows support at most ${WORKFLOW_POLICY.maxSteps} steps`);
+  if (workflow.semantic.deadlineMs !== undefined && (!Number.isInteger(workflow.semantic.deadlineMs) || workflow.semantic.deadlineMs < 1 || workflow.semantic.deadlineMs > WORKFLOW_POLICY.maxDeadlineMs)) {
+    throw new Error(`semantic.deadlineMs must be an integer from 1 to ${WORKFLOW_POLICY.maxDeadlineMs}`);
+  }
+  if (workflow.semantic.maxProviderCalls !== undefined && (!Number.isInteger(workflow.semantic.maxProviderCalls) || workflow.semantic.maxProviderCalls < 1 || workflow.semantic.maxProviderCalls > WORKFLOW_POLICY.maxProviderCalls)) {
+    throw new Error(`semantic.maxProviderCalls must be an integer from 1 to ${WORKFLOW_POLICY.maxProviderCalls}`);
+  }
+  const priorBindings = new Set();
+  const ids = new Set();
+  workflow.steps.forEach((step, index) => validateSemanticStep(step, index, priorBindings, ids, WORKFLOW_POLICY));
 }
 
 function normalizeWorkflow(workflow) {
@@ -290,6 +409,11 @@ function normalizeWorkflow(workflow) {
   if (workflow.args !== undefined && (!workflow.args || typeof workflow.args !== "object" || Array.isArray(workflow.args))) {
     throw new Error("'args' must be an object");
   }
+  const hasSemanticSteps = workflow.steps.some((step) => step?.tool === "semantic.step" || step?.cmd === "semantic.step");
+  if (workflow.semantic !== undefined || hasSemanticSteps) {
+    if (workflow.semantic === undefined) throw new Error("semantic workflows require semantic.version=1");
+    validateSemanticWorkflow(workflow);
+  }
   return { ...workflow, args: workflow.args || {}, steps: workflow.steps.map(normalizeStep) };
 }