surf-cli 2.9.0 → 2.11.0

package/native/workflow-definition.cjs

@@ -0,0 +1,369 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { isSensitiveName, redactSensitiveFields, redactUrlSecrets } = require("./redaction.cjs");
+
+const COMMANDS = {
+  ai: { primaryArg: "query", effect: "read", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  gemini: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  chatgpt: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  "oracle.ask": { primaryArg: "prompt", effect: "page-write", argKinds: { prompt: "user-input" }, sensitiveArgs: ["prompt"] },
+  perplexity: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  grok: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  navigate: { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },
+  go: { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },
+  back: { effect: "navigation" },
+  forward: { effect: "navigation" },
+  reload: { effect: "navigation" },
+  js: { primaryArg: "code", effect: "unknown", recordable: false, argKinds: { code: "code" }, sensitiveArgs: ["code"] },
+  javascript_tool: { primaryArg: "code", effect: "unknown", recordable: false, argKinds: { code: "code" }, sensitiveArgs: ["code"] },
+  click: { effect: "page-write", argKinds: { ref: "element-ref", selector: "selector", x: "number", y: "number" } },
+  key: { primaryArg: "key", effect: "page-write", argKinds: { key: "key" } },
+  submit: { effect: "page-write" },
+  hover: { effect: "read", argKinds: { ref: "element-ref", selector: "selector" } },
+  scroll: { effect: "page-write", argKinds: { direction: "name", scroll_pixels: "number" } },
+  "scroll.top": { effect: "page-write", argKinds: { selector: "selector" } },
+  "scroll.bottom": { effect: "page-write", argKinds: { selector: "selector" } },
+  "scroll.info": { effect: "read", argKinds: { selector: "selector" } },
+  wait: { primaryArg: "duration", effect: "read", recordable: false, argKinds: { duration: "duration" } },
+  health: { primaryArg: "url", effect: "read", argKinds: { url: "url" } },
+  new_tab: { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },
+  "tab.new": { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },
+  switch_tab: { primaryArg: "tab_id", effect: "navigation", argKinds: { tab_id: "tab-id" } },
+  "tab.switch": { primaryArg: "id", effect: "navigation", argKinds: { id: "tab-id" } },
+  close_tab: { primaryArg: "tab_id", effect: "page-write", argKinds: { tab_id: "tab-id" } },
+  "tab.close": { primaryArg: "id", effect: "page-write", argKinds: { id: "tab-id" } },
+  "tab.name": { primaryArg: "name", effect: "page-write", argKinds: { name: "name" } },
+  "tab.unname": { primaryArg: "name", effect: "page-write", argKinds: { name: "name" } },
+  scroll_to_position: { primaryArg: "position", effect: "page-write", argKinds: { position: "position" } },
+  type: { primaryArg: "text", effect: "page-write", argKinds: { selector: "selector", text: "user-input" }, sensitiveArgs: ["text"] },
+  smart_type: { primaryArg: "text", effect: "page-write", argKinds: { selector: "selector", text: "user-input" }, sensitiveArgs: ["text"] },
+  find_and_type: { effect: "page-write", argKinds: { text: "user-input" }, sensitiveArgs: ["text"] },
+  form_input: { effect: "page-write", argKinds: { value: "user-input" }, sensitiveArgs: ["value"] },
+  "cookie.set": { effect: "page-write", argKinds: { value: "secret" }, sensitiveArgs: ["value"] },
+  "emulate.network": { primaryArg: "preset", effect: "page-write", argKinds: { preset: "name" } },
+  "emulate.cpu": { primaryArg: "rate", effect: "page-write", argKinds: { rate: "number" } },
+  search: { primaryArg: "term", effect: "read", argKinds: { term: "user-input" }, sensitiveArgs: ["term"] },
+  "wait.element": { primaryArg: "selector", effect: "read", recordable: false, argKinds: { selector: "selector" } },
+  "wait.url": { primaryArg: "pattern", effect: "read", recordable: false, argKinds: { pattern: "url-pattern" } },
+  zoom: { primaryArg: "level", effect: "page-write", argKinds: { level: "number" } },
+  "history.search": { primaryArg: "query", effect: "read", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  "network.get": { primaryArg: "id", effect: "read", argKinds: { id: "request-id" } },
+  "network.body": { primaryArg: "id", effect: "read", argKinds: { id: "request-id" } },
+  "network.curl": { primaryArg: "id", effect: "read", argKinds: { id: "request-id" } },
+  "network.path": { primaryArg: "id", effect: "read", argKinds: { id: "request-id" } },
+  "page.read": { effect: "read" },
+  "page.text": { effect: "read" },
+  "page.state": { effect: "read" },
+  screenshot: { effect: "read" },
+  "window.new": { primaryArg: "url", effect: "navigation", argKinds: { url: "url" } },
+  "window.focus": { primaryArg: "id", effect: "navigation", argKinds: { id: "window-id" } },
+  "window.close": { primaryArg: "id", effect: "page-write", argKinds: { id: "window-id" } },
+  "locate.role": { primaryArg: "role", effect: "read", argKinds: { role: "role" } },
+  "locate.text": { primaryArg: "text", effect: "read", argKinds: { text: "user-input" }, sensitiveArgs: ["text"] },
+  "locate.label": { primaryArg: "label", effect: "read", argKinds: { label: "user-input" }, sensitiveArgs: ["label"] },
+  "emulate.device": { primaryArg: "device", effect: "page-write", argKinds: { device: "name" } },
+  "frame.js": { primaryArg: "code", effect: "unknown", recordable: false, argKinds: { code: "code" }, sensitiveArgs: ["code"] },
+  "element.styles": { primaryArg: "selector", effect: "read", argKinds: { selector: "selector" } },
+  select: { primaryArg: "selector", effect: "page-write", argKinds: { selector: "selector", values: "user-input" }, sensitiveArgs: ["values"] },
+  "form.fill": { effect: "page-write", argKinds: { data: "user-input" }, sensitiveArgs: ["data"] },
+  "dialog.accept": { effect: "page-write", argKinds: { text: "user-input" }, sensitiveArgs: ["text"] },
+  "dialog.dismiss": { effect: "page-write" },
+  "dialog.info": { effect: "read" },
+};
+
+const ALIASES = {
+  snap: "screenshot",
+  read: "page.read",
+  find: "search",
+  go: "navigate",
+  net: "network",
+  "network.dump": "network.get",
+};
+
+const PRIMARY_ARG_MAP = Object.fromEntries(
+  Object.entries(COMMANDS).filter(([, value]) => value.primaryArg).map(([name, value]) => [name, value.primaryArg]),
+);
+PRIMARY_ARG_MAP.go = "url";
+PRIMARY_ARG_MAP.find = "term";
+
+function commandMetadata(command) {
+  const name = ALIASES[command] || command;
+  const metadata = COMMANDS[name];
+  return {
+    name,
+    primaryArg: metadata?.primaryArg,
+    effect: metadata?.effect || "unknown",
+    recordable: Boolean(metadata) && metadata.recordable !== false,
+    argKinds: metadata?.argKinds || {},
+    sensitiveArgs: metadata?.sensitiveArgs || [],
+  };
+}
+
+function redactCommandArgs(command, args, includeInputValues = false) {
+  const metadata = commandMetadata(command);
+  const redacted = redactSensitiveFields({ ...(args || {}) });
+  for (const name of metadata.sensitiveArgs) {
+    if (!includeInputValues && Object.hasOwn(redacted, name)) redacted[name] = `<${name}>`;
+  }
+  for (const [name, kind] of Object.entries(metadata.argKinds)) {
+    if (kind === "url" && Object.hasOwn(redacted, name)) redacted[name] = redactUrlSecrets(redacted[name]);
+  }
+  for (const name of Object.keys(redacted)) {
+    if (isSensitiveName(name)) redacted[name] = "<redacted>";
+  }
+  return redacted;
+}
+
+function templateRedactedArgs(value, args = {}) {
+  if (typeof value === "string") {
+    const match = value.match(/^<([a-z0-9._-]+)>$/);
+    if (!match) return value;
+    args[match[1]] = { required: true, desc: `Recorded ${match[1]}` };
+    return `{{${match[1]}}}`;
+  }
+  if (Array.isArray(value)) return value.map((item) => templateRedactedArgs(item, args));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, templateRedactedArgs(item, args)]));
+  }
+  return value;
+}
+
+function promoteRedactedStepArgs(steps) {
+  const args = {};
+  return {
+    args,
+    steps: steps.map((step) => ({ ...step, args: templateRedactedArgs(step.args || {}, args) })),
+  };
+}
+
+function tokenize(line) {
+  const tokens = [];
+  let current = "";
+  let inQuote = null;
+  for (const ch of line) {
+    if (inQuote) {
+      if (ch === inQuote) inQuote = null;
+      else current += ch;
+    } else if (ch === '"' || ch === "'") inQuote = ch;
+    else if (ch === " " || ch === "\t") {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+    } else current += ch;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function coerceValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+$/.test(value)) return Number.parseInt(value, 10);
+  if (/^-?\d+\.\d+$/.test(value)) return Number.parseFloat(value);
+  return value;
+}
+
+function parseCommandLine(line) {
+  const tokens = tokenize(line);
+  if (tokens.length === 0) return null;
+  let cmd = ALIASES[tokens[0]] || tokens[0];
+  const args = {};
+  let i = 1;
+  if (i < tokens.length && !tokens[i].startsWith("--")) {
+    const firstArg = tokens[i];
+    if (cmd === "click") {
+      if (/^e\d+$/.test(firstArg)) {
+        args.ref = firstArg;
+        i++;
+      } else if (/^\d+$/.test(firstArg) && /^\d+$/.test(tokens[i + 1] || "")) {
+        args.x = Number.parseInt(firstArg, 10);
+        args.y = Number.parseInt(tokens[i + 1], 10);
+        i += 2;
+      }
+    } else if (cmd === "select") {
+      args.selector = firstArg;
+      i++;
+      const values = [];
+      while (i < tokens.length && !tokens[i].startsWith("--")) values.push(tokens[i++]);
+      if (values.length === 1) args.values = values[0];
+      else if (values.length > 1) args.values = values;
+    } else if (cmd === "scroll") {
+      if (firstArg === "top" || firstArg === "bottom") {
+        cmd = `scroll.${firstArg}`;
+        i++;
+      } else if (["up", "down", "left", "right"].includes(firstArg)) {
+        args.direction = firstArg;
+        i++;
+        if (/^-?\d+$/.test(tokens[i] || "")) args.scroll_pixels = Number.parseInt(tokens[i++], 10);
+      }
+    } else {
+      const primaryKey = PRIMARY_ARG_MAP[cmd];
+      if (primaryKey) {
+        args[primaryKey] = firstArg;
+        i++;
+      }
+    }
+  }
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (!token.startsWith("--")) {
+      i++;
+      continue;
+    }
+    const key = token.slice(2);
+    const next = tokens[i + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = coerceValue(next);
+      i += 2;
+    } else {
+      args[key] = true;
+      i++;
+    }
+  }
+  return { cmd, args };
+}
+
+function parseDoCommands(input) {
+  const hasPipe = input.includes("|");
+  const normalized = hasPipe ? input : input.replace(/\\n/g, "\n");
+  return normalized
+    .split(hasPipe ? "|" : "\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"))
+    .map(parseCommandLine)
+    .filter(Boolean);
+}
+
+function getWorkflowDirs({ cwd = process.cwd(), home = os.homedir() } = {}) {
+  return [
+    { path: path.join(cwd, ".surf", "workflows"), scope: "project" },
+    { path: path.join(home, ".surf", "workflows"), scope: "user" },
+  ];
+}
+
+function resolveWorkflow(nameOrPath, options = {}) {
+  if (nameOrPath.includes("|")) return { type: "inline", content: nameOrPath };
+  if (nameOrPath.includes("/") || nameOrPath.includes("\\") || nameOrPath.endsWith(".json")) {
+    return fs.existsSync(nameOrPath) ? { type: "file", path: nameOrPath } : { type: "not_found", name: nameOrPath };
+  }
+  for (const { path: dir } of getWorkflowDirs(options)) {
+    const filePath = path.join(dir, `${nameOrPath}.json`);
+    if (fs.existsSync(filePath)) return { type: "file", path: filePath };
+  }
+  return { type: "not_found", name: nameOrPath };
+}
+
+function normalizeStep(step) {
+  if (!step || typeof step !== "object" || Array.isArray(step)) throw new Error("workflow step must be an object");
+  if (step.repeat !== undefined || step.each !== undefined) {
+    if (!Array.isArray(step.steps) || step.steps.length === 0) throw new Error("loop must have a non-empty 'steps' array");
+    return {
+      ...step,
+      steps: step.steps.map(normalizeStep),
+      ...(step.until ? { until: normalizeStep(step.until) } : {}),
+    };
+  }
+  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 } : {}) };
+}
+
+function normalizeWorkflow(workflow) {
+  if (!workflow || typeof workflow !== "object" || Array.isArray(workflow)) throw new Error("workflow must be an object");
+  if (!Array.isArray(workflow.steps)) throw new Error("Workflow must have a 'steps' array");
+  if (workflow.steps.length === 0) throw new Error("Workflow has no steps");
+  if (workflow.args !== undefined && (!workflow.args || typeof workflow.args !== "object" || Array.isArray(workflow.args))) {
+    throw new Error("'args' must be an object");
+  }
+  return { ...workflow, args: workflow.args || {}, steps: workflow.steps.map(normalizeStep) };
+}
+
+function validateWorkflowArgs(workflow, providedArgs) {
+  const errors = [];
+  for (const [name, spec] of Object.entries(workflow.args || {})) {
+    if (spec.required && providedArgs[name] === undefined) errors.push(`Missing required argument: --${name}`);
+  }
+  return errors;
+}
+
+function applyArgDefaults(workflow, providedArgs) {
+  const vars = { ...providedArgs };
+  for (const [name, spec] of Object.entries(workflow.args || {})) {
+    if (vars[name] === undefined && spec.default !== undefined) vars[name] = spec.default;
+  }
+  return vars;
+}
+
+function validateWorkflowFile(filePath) {
+  if (!fs.existsSync(filePath)) return { valid: false, error: `File not found: ${filePath}` };
+  try {
+    const workflow = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    normalizeWorkflow(workflow);
+    return { valid: true, workflow };
+  } catch (error) {
+    return { valid: false, error: error instanceof SyntaxError ? `Invalid JSON: ${error.message}` : error.message };
+  }
+}
+
+function listWorkflows(options = {}) {
+  const workflows = [];
+  for (const { path: dir, scope } of getWorkflowDirs(options)) {
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir).filter((name) => name.endsWith(".json"))) {
+      const filePath = path.join(dir, file);
+      try {
+        const content = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        workflows.push({ name: content.name || file.slice(0, -5), description: content.description || "", scope, path: filePath, args: content.args, stepCount: content.steps?.length || 0 });
+      } catch {}
+    }
+  }
+  return workflows;
+}
+
+function getWorkflowInfo(name, options = {}) {
+  const resolved = resolveWorkflow(name, options);
+  if (resolved.type === "not_found") return { error: `Workflow not found: ${name}` };
+  if (resolved.type === "inline") return { error: "Cannot get info for inline workflows" };
+  try {
+    const content = JSON.parse(fs.readFileSync(resolved.path, "utf8"));
+    return { name: content.name || name, description: content.description || "", args: content.args || {}, steps: content.steps || [], path: resolved.path };
+  } catch (error) {
+    return { error: `Failed to parse workflow: ${error.message}` };
+  }
+}
+
+function formatStep(step, indent = 0) {
+  const pad = "  ".repeat(indent);
+  if (step.repeat !== undefined || step.each !== undefined) {
+    const label = step.repeat !== undefined ? `repeat ${step.repeat} times:` : `each ${step.each} as ${step.as || "item"}:`;
+    const lines = [`${pad}${label}`, ...(step.steps || []).map((nested) => formatStep(nested, indent + 1))];
+    if (step.until) lines.push(`${pad}  until: ${step.until.tool || step.until.cmd}`);
+    return lines.join("\n");
+  }
+  const tool = step.tool || step.cmd;
+  const argStr = Object.entries(step.args || {}).map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+  return `${pad}${tool}${argStr ? ` ${argStr}` : ""}${step.as ? ` → ${step.as}` : ""}`;
+}
+
+module.exports = {
+  ALIASES,
+  PRIMARY_ARG_MAP,
+  applyArgDefaults,
+  commandMetadata,
+  formatStep,
+  getWorkflowDirs,
+  getWorkflowInfo,
+  listWorkflows,
+  normalizeStep,
+  normalizeWorkflow,
+  parseCommandLine,
+  parseDoCommands,
+  promoteRedactedStepArgs,
+  redactCommandArgs,
+  resolveWorkflow,
+  tokenize,
+  validateWorkflowArgs,
+  validateWorkflowFile,
+};

package/native/workflow-runtime.cjs

@@ -0,0 +1,225 @@
+const { redactCommandArgs } = require("./workflow-definition.cjs");
+
+const MAX_LOOP_ITERATIONS = 100;
+const AUTO_WAIT_COMMANDS = ["go", "navigate", "click", "key", "form.fill", "submit", "tab.switch", "tab.new", "back", "forward"];
+const AUTO_WAIT_MAP = {
+  navigate: "wait.load",
+  go: "wait.load",
+  click: "wait.dom",
+  key: "wait.dom",
+  "form.fill": "wait.dom",
+  submit: "wait.load",
+  "tab.switch": "wait.load",
+  "tab.new": "wait.load",
+  back: "wait.load",
+  forward: "wait.load",
+};
+
+function shouldAutoWait(cmd) {
+  return AUTO_WAIT_COMMANDS.some((candidate) => cmd === candidate || cmd.startsWith(`${candidate}.`));
+}
+
+function getAutoWaitCommand(cmd) {
+  if (AUTO_WAIT_MAP[cmd] !== undefined) return AUTO_WAIT_MAP[cmd];
+  for (const [prefix, waitCmd] of Object.entries(AUTO_WAIT_MAP)) {
+    if (cmd.startsWith(`${prefix}.`)) return waitCmd;
+  }
+  return null;
+}
+
+function resolveVar(template, vars) {
+  if (typeof template !== "string") return template;
+  const match = template.match(/^%\{(\w+)\}$/);
+  if (match) return vars[match[1]] !== undefined ? vars[match[1]] : template;
+  return template.replace(/%\{(\w+)\}/g, (_, name) => {
+    const value = vars[name];
+    if (value === undefined) return `%{${name}}`;
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+  });
+}
+
+function substituteVars(value, vars) {
+  if (!value || typeof value !== "object") return typeof value === "string" ? resolveVar(value, vars) : value;
+  if (Array.isArray(value)) return value.map((item) => substituteVars(item, vars));
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, substituteVars(item, vars)]));
+}
+
+function extractStepOutput(response) {
+  if (response?.result?.content?.[0]?.text) {
+    const text = response.result.content[0].text;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  if (response?.value !== undefined) return response.value;
+  if (response?.output !== undefined) {
+    try {
+      return JSON.parse(response.output);
+    } catch {
+      return response.output;
+    }
+  }
+  if (response?.result !== undefined) return response.result;
+  return response;
+}
+
+function abortMessage(signal) {
+  if (!signal?.aborted) return null;
+  return signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Workflow aborted");
+}
+
+function assertNotAborted(signal) {
+  const message = abortMessage(signal);
+  if (message) throw new Error(message);
+}
+
+async function executeSingleStep(step, vars, options) {
+  const {
+    autoWait = true,
+    executeTool,
+    includeInputValues = false,
+    onEvent = () => {},
+    signal,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    stepDelay = 100,
+  } = options;
+  if (typeof executeTool !== "function") throw new Error("workflow runtime requires executeTool");
+  const args = substituteVars(step.args || {}, vars);
+  const startedAt = new Date().toISOString();
+  const baseEvent = { command: step.cmd, argsRedacted: redactCommandArgs(step.cmd, args, includeInputValues), startedAt };
+  onEvent({ type: "tool.started", ...baseEvent });
+  try {
+    assertNotAborted(signal);
+    const response = await executeTool(step.cmd, args, { signal });
+    assertNotAborted(signal);
+    if (response?.error) {
+      const error = response.error.content?.[0]?.text || (typeof response.error === "string" ? response.error : JSON.stringify(response.error));
+      onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: error });
+      return { success: false, error };
+    }
+    if (step.as) vars[step.as] = extractStepOutput(response);
+    if (autoWait) {
+      const waitCmd = getAutoWaitCommand(step.cmd);
+      if (waitCmd) {
+        const waitArgs = waitCmd === "wait.load" ? { timeout: 10000 } : { stable: 100, timeout: 5000 };
+        try {
+          await executeTool(waitCmd, waitArgs, { signal });
+        } catch {}
+      }
+    }
+    if (stepDelay > 0) {
+      assertNotAborted(signal);
+      await sleep(stepDelay, signal);
+      assertNotAborted(signal);
+    }
+    onEvent({ type: "tool.completed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: "success" });
+    return { success: true, ...(step.as ? { output: vars[step.as] } : {}) };
+  } catch (error) {
+    const message = error?.message || String(error);
+    onEvent({ type: "tool.failed", ...baseEvent, endedAt: new Date().toISOString(), resultSummary: message });
+    return { success: false, error: message };
+  }
+}
+
+async function executeStep(step, vars, options) {
+  const { onError = "stop" } = options;
+  assertNotAborted(options.signal);
+  if (step.repeat !== undefined) {
+    let max = resolveVar(step.repeat, vars);
+    if (typeof max === "string") max = Number.parseInt(max, 10);
+    if (typeof max !== "number" || Number.isNaN(max)) max = 1;
+    max = Math.min(max, MAX_LOOP_ITERATIONS);
+    if (!Array.isArray(step.steps) || step.steps.length === 0) return { success: false, error: "repeat: steps array required", stepsExecuted: 0 };
+    let stepsExecuted = 0;
+    for (let index = 0; index < max; index++) {
+      const loopVars = { ...vars, _index: index, _iteration: index + 1 };
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, options);
+        stepsExecuted += result.stepsExecuted || 1;
+        if (!result.success && onError === "stop") return { success: false, error: result.error, stepsExecuted };
+      }
+      copyCapturedVars(step.steps, loopVars, vars);
+      if (step.until) {
+        const untilResult = await executeSingleStep(step.until, loopVars, options);
+        stepsExecuted++;
+        if (untilResult.output) break;
+      }
+    }
+    return { success: true, stepsExecuted };
+  }
+  if (step.each !== undefined) {
+    const items = resolveVar(step.each, vars);
+    if (!Array.isArray(items)) return { success: false, error: `each: expected array, got ${typeof items}${items === undefined ? " (undefined)" : ""}`, stepsExecuted: 0 };
+    if (!Array.isArray(step.steps) || step.steps.length === 0) return { success: false, error: "each: steps array required", stepsExecuted: 0 };
+    const itemVar = step.as || "item";
+    let stepsExecuted = 0;
+    for (let index = 0; index < Math.min(items.length, MAX_LOOP_ITERATIONS); index++) {
+      const loopVars = { ...vars, [itemVar]: items[index], _index: index, _iteration: index + 1 };
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, options);
+        stepsExecuted += result.stepsExecuted || 1;
+        if (!result.success && onError === "stop") return { success: false, error: result.error, stepsExecuted };
+      }
+      copyCapturedVars(step.steps, loopVars, vars);
+    }
+    return { success: true, stepsExecuted };
+  }
+  return { ...(await executeSingleStep(step, vars, options)), stepsExecuted: 1 };
+}
+
+function copyCapturedVars(steps, source, target) {
+  for (const step of steps) {
+    const isLoop = step.repeat !== undefined || step.each !== undefined;
+    if (!isLoop && step.as && source[step.as] !== undefined) target[step.as] = source[step.as];
+  }
+}
+
+async function executeWorkflow(steps, options = {}) {
+  const vars = { ...(options.vars || {}), ...(options.context?.vars || {}) };
+  const results = [];
+  let failed = 0;
+  let stepsExecuted = 0;
+  const startTotal = Date.now();
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const startTime = Date.now();
+    const type = step.repeat !== undefined || step.each !== undefined ? "loop" : "tool";
+    options.onProgress?.({ phase: "start", index, total: steps.length, step, type });
+    let result;
+    try {
+      result = await executeStep(step, vars, options);
+    } catch (error) {
+      result = { success: false, error: error?.message || String(error), stepsExecuted: 0 };
+    }
+    const ms = Date.now() - startTime;
+    stepsExecuted += type === "loop" ? result.stepsExecuted || 0 : 1;
+    if (!result.success) {
+      failed++;
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop" } : { cmd: step.cmd }), status: "error", error: result.error, ms });
+      options.onProgress?.({ phase: "fail", index, total: steps.length, step, type, ms, error: result.error });
+      if ((options.onError || "stop") === "stop") {
+        return { status: "failed", completedSteps: type === "loop" ? stepsExecuted : stepsExecuted - 1, totalSteps: steps.length, results, error: result.error, totalMs: Date.now() - startTotal, vars };
+      }
+    } else {
+      results.push({ step: index + 1, ...(type === "loop" ? { type: "loop", stepsExecuted: result.stepsExecuted } : { cmd: step.cmd }), status: "ok", ms });
+      options.onProgress?.({ phase: "ok", index, total: steps.length, step, type, ms, stepsExecuted: result.stepsExecuted });
+    }
+  }
+  return { status: failed > 0 ? "partial" : "completed", completedSteps: stepsExecuted, totalSteps: steps.length, results, failed, totalMs: Date.now() - startTotal, vars };
+}
+
+module.exports = {
+  AUTO_WAIT_COMMANDS,
+  AUTO_WAIT_MAP,
+  MAX_LOOP_ITERATIONS,
+  executeSingleStep,
+  executeStep,
+  executeWorkflow,
+  extractStepOutput,
+  getAutoWaitCommand,
+  resolveVar,
+  shouldAutoWait,
+  substituteVars,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -28,6 +28,7 @@
   },
   "files": [
     "native/",
+    "playbooks/",
     "scripts/",
     "dist/",
     "skills/",

package/playbooks/page/ops/read.json

@@ -0,0 +1,22 @@
+{
+  "id": "read",
+  "description": "Read the current site's root document",
+  "effect": "read",
+  "run": [
+    {
+      "using": "network",
+      "request": { "method": "GET", "url": "/" },
+      "extract": { "field": "body" },
+      "expect": { "truthy": true }
+    },
+    {
+      "using": "workflow",
+      "steps": [
+        { "tool": "page.text", "args": {}, "as": "content" }
+      ],
+      "extract": { "jsonPath": "$.vars.content" },
+      "expect": { "truthy": true }
+    }
+  ],
+  "on": { "drift": { "fallback": "next", "report": true } }
+}

package/playbooks/page/playbook.json

@@ -0,0 +1,7 @@
+{
+  "id": "page",
+  "name": "Current page",
+  "version": "1.0.0",
+  "description": "Read the current browser page with a network fast path and UI fallback",
+  "origins": []
+}