surf-cli 2.8.0 → 2.10.0

package/native/perplexity-client.cjs

@@ -5,14 +5,16 @@
  * Similar approach to the ChatGPT client.
  */
 
+const { abortableDelay, raceAbort, throwIfAborted } = require("./abort.cjs");
+
 const PERPLEXITY_URL = "https://www.perplexity.ai/";
 
 // ============================================================================
 // Helpers
 // ============================================================================
 
-function delay(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
+function delay(ms, signal) {
+  return abortableDelay(ms, signal);
 }
 
 function buildClickDispatcher() {
@@ -371,7 +373,27 @@ async function submitPrompt(cdp, inputCdp) {
 // Response Handling
 // ============================================================================
 
-async function waitForResponse(cdp, timeoutMs = 120000) {
+function extractPerplexityResponseText() {
+  const selectors = [
+    '[id^="markdown-content"]',
+    '[data-testid="answer"]',
+    'article',
+    '.prose',
+  ];
+
+  for (const selector of selectors) {
+    const elements = Array.from(document.querySelectorAll(selector));
+    for (let i = elements.length - 1; i >= 0; i--) {
+      const text = elements[i].innerText?.trim() || '';
+      if (text) return text;
+    }
+  }
+
+  return '';
+}
+
+async function waitForResponse(cdp, timeoutMs = 120000, signal) {
+  throwIfAborted(signal);
   const deadline = Date.now() + timeoutMs;
   let previousText = '';
   let stableCycles = 0;
@@ -386,17 +408,16 @@ async function waitForResponse(cdp, timeoutMs = 120000) {
     if (url && url.includes('/search/')) {
       break;
     }
-    await delay(200);
+    await delay(200, signal);
   }
   
   // Wait a bit for the response area to render
-  await delay(1000);
+  await delay(1000, signal);
   
   // Now poll for response completion
   while (Date.now() < deadline) {
     const snapshot = await evaluate(cdp, `(function() {
-      const prose = document.querySelector('.prose');
-      const text = prose ? prose.innerText : '';
+      const text = (${extractPerplexityResponseText.toString()})();
       const hasStop = !!document.querySelector('button[aria-label*=stop], button[aria-label*=Stop]');
       const hasCopy = !!document.querySelector('button[aria-label*=copy], button[aria-label*=Copy]');
       const hasRelated = document.body.innerText.indexOf('Related') > -1;
@@ -412,7 +433,7 @@ async function waitForResponse(cdp, timeoutMs = 120000) {
     })()`);
     
     if (!snapshot) {
-      await delay(300);
+      await delay(300, signal);
       continue;
     }
     
@@ -437,7 +458,7 @@ async function waitForResponse(cdp, timeoutMs = 120000) {
     const hasCompletionIndicators = snapshot.hasActions || snapshot.hasRelated || snapshot.hasFollowUp;
     const isDone = !snapshot.generating && (hasCompletionIndicators || isStable);
     
-    if (isDone && currentText.length > 20) {
+    if (isDone && currentText.trim().length > 0) {
       // Clean up the response text
       let cleanText = currentText;
       
@@ -454,11 +475,11 @@ async function waitForResponse(cdp, timeoutMs = 120000) {
       };
     }
     
-    await delay(300);
+    await delay(300, signal);
   }
   
   // Timeout - return whatever we have
-  if (previousText.length > 20) {
+  if (previousText.trim().length > 0) {
     return {
       text: previousText,
       sources: 0,
@@ -485,13 +506,15 @@ async function query(options) {
     cdpEvaluate,
     cdpCommand,
     log = () => {},
+    signal,
   } = options;
+  throwIfAborted(signal);
   
   const startTime = Date.now();
   log("Starting Perplexity query");
   
   // Create tab
-  const tabInfo = await createTab();
+  const tabInfo = await raceAbort(createTab, signal);
   log(`createTab returned: ${JSON.stringify(tabInfo)}`);
   const { tabId } = tabInfo || {};
   
@@ -500,8 +523,8 @@ async function query(options) {
   }
   log(`Created tab ${tabId}`);
   
-  const cdp = (expr) => cdpEvaluate(tabId, expr);
-  const inputCdp = (method, params) => cdpCommand(tabId, method, params);
+  const cdp = (expr) => raceAbort(() => cdpEvaluate(tabId, expr), signal);
+  const inputCdp = (method, params) => raceAbort(() => cdpCommand(tabId, method, params), signal);
   
   try {
     // Wait for page load
@@ -522,6 +545,7 @@ async function query(options) {
         const selectedMode = await selectMode(cdp, mode);
         log(`Mode: ${selectedMode}`);
       } catch (e) {
+        if (signal?.aborted) throw e;
         log(`Mode selection failed: ${e.message}`);
       }
     }
@@ -532,6 +556,7 @@ async function query(options) {
         const selectedModel = await selectModel(cdp, model);
         log(`Model: ${selectedModel}`);
       } catch (e) {
+        if (signal?.aborted) throw e;
         log(`Model selection failed: ${e.message}`);
       }
     }
@@ -545,7 +570,7 @@ async function query(options) {
     log("Submitted, waiting for response...");
     
     // Wait for response
-    const response = await waitForResponse(cdp, timeout);
+    const response = await waitForResponse(cdp, timeout, signal);
     log(`Response: ${response.text.length} chars, ${response.sources} sources${response.partial ? ' (partial)' : ''}`);
     
     return {
@@ -558,8 +583,12 @@ async function query(options) {
       tookMs: Date.now() - startTime,
     };
   } finally {
-    await closeTab(tabId).catch(() => {});
+    try {
+      await closeTab(tabId);
+    } catch (error) {
+      log(`Failed to close Perplexity tab ${tabId}: ${error?.message || error}`);
+    }
   }
 }
 
-module.exports = { query, PERPLEXITY_URL };
+module.exports = { query, PERPLEXITY_URL, waitForResponse, extractPerplexityResponseText };

package/native/playbook-authoring.cjs

@@ -0,0 +1,44 @@
+const fs = require("fs");
+const path = require("path");
+const { readRecent } = require("./activity-journal.cjs");
+const { writeNetworkExport } = require("./network-export.cjs");
+const { getPrivateStateRoot, readPrivateJson } = require("./private-state.cjs");
+const { draftFromRecord, readRecord, recordsRoot } = require("./playbook-records.cjs");
+const { savePlaybook, validateOp } = require("./playbooks.cjs");
+const { commandMetadata, promoteRedactedStepArgs } = require("./workflow-definition.cjs");
+
+function suggestions({ since = "1h", root } = {}) {
+  const events = readRecent({ since, root });
+  const counts = new Map();
+  for (const event of events.filter((entry) => entry.type === "tool.issued")) counts.set(event.command, (counts.get(event.command) || 0) + 1);
+  return [...counts.entries()].map(([command, count]) => ({ command, count })).sort((a, b) => b.count - a.count || a.command.localeCompare(b.command));
+}
+
+function saveFromRecent({ site, op: opId, since = "1h", scope = "user", cwd, home, root }) {
+  const events = readRecent({ since, root }).filter((event) => event.type === "tool.issued");
+  if (events.length === 0) throw new Error("no recent Surf activity to save");
+  if (events.some((event) => ["page-write", "unknown"].includes(commandMetadata(event.command).effect))) {
+    throw new Error("recent activity includes write-capable commands; use an explicit record and review its draft before saving");
+  }
+  const promoted = promoteRedactedStepArgs(events.map((event) => ({ tool: event.command, args: event.argsRedacted || {} })));
+  const op = { id: opId, description: "Drafted from recent Surf activity", effect: "read", args: promoted.args, run: [{ using: "workflow", steps: promoted.steps }], provenance: { recentSince: since } };
+  validateOp(op, { origins: [] });
+  return savePlaybook({ manifest: { id: site, name: site, version: "1.0.0", origins: [] }, op, scope, cwd, home });
+}
+
+function saveFromRecord({ recordId, scope = "user", cwd, home, root = getPrivateStateRoot() }) {
+  const record = readRecord(recordId, root);
+  if (!record) throw new Error(`record not found: ${recordId}`);
+  const draftPath = path.join(recordsRoot(root), recordId, "draft", "op.json");
+  const op = fs.existsSync(draftPath) ? readPrivateJson(draftPath, null, { root }) : draftFromRecord(recordId, root);
+  validateOp(op, { origins: record.origin ? [record.origin] : [] });
+  return savePlaybook({ manifest: { id: record.site, name: record.site, version: "1.0.0", origins: record.origin ? [record.origin] : [] }, op, scope, cwd, home });
+}
+
+function exportRecordHar(recordId, output, root = getPrivateStateRoot()) {
+  const trace = readPrivateJson(path.join(recordsRoot(root), recordId, "network", "trace.json"), null, { root });
+  if (!trace) throw new Error(`record ${recordId} has no network trace`);
+  return writeNetworkExport(path.resolve(output), trace.entries, "har");
+}
+
+module.exports = { exportRecordHar, saveFromRecent, saveFromRecord, suggestions };

package/native/playbook-cli.cjs

@@ -0,0 +1,157 @@
+const path = require("path");
+const { openClientTransport } = require("./client-transport.cjs");
+const { resolveRequestDeadlineMs } = require("./host-sessions.cjs");
+const { exportRecordHar, saveFromRecent, saveFromRecord, suggestions } = require("./playbook-authoring.cjs");
+const { deriveClient, exportClient, verifyClient } = require("./playbook-client.cjs");
+const { exportPlaybookDirectory, importPlaybookDirectory, listPlaybooks, resolvePlaybook } = require("./playbooks.cjs");
+
+function parseCommandArgs(argv) {
+  const positional = [];
+  const options = {};
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const name = value.slice(2);
+    const next = argv[index + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      options[name] = /^-?\d+(?:\.\d+)?$/.test(next) ? Number(next) : next;
+      index++;
+    } else options[name] = true;
+  }
+  return { positional, options };
+}
+
+function unwrapResponse(response) {
+  if (response.error) throw new Error(response.error.content?.[0]?.text || JSON.stringify(response.error));
+  const text = response.result?.content?.[0]?.text;
+  if (text === undefined) return response.result;
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+async function requestHost(endpoint, tool, args, options = {}) {
+  const transport = await openClientTransport(endpoint, { requestTimeoutMs: options.timeoutMs || 11 * 60 * 1000 });
+  try {
+    const request = { type: "tool_request", method: "execute_tool", params: { tool, args }, id: `playbook-${Date.now()}-${Math.random()}` };
+    if (options.tabId) request.tabId = options.tabId;
+    return unwrapResponse(await transport.request(request, options.timeoutMs || 11 * 60 * 1000));
+  } finally {
+    await transport.close();
+  }
+}
+
+function runSpec(argv) {
+  const direct = argv[0] === "use";
+  const offset = direct ? 1 : 2;
+  const parsed = parseCommandArgs(argv.slice(offset));
+  const [playbook, op] = parsed.positional;
+  if (!playbook || !op) throw new Error(direct ? "Usage: surf use <playbook> <op> [--arg value]" : "Usage: surf pb run <playbook> <op> [--arg value]");
+  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in"]);
+  const args = Object.fromEntries(Object.entries(parsed.options).filter(([name]) => !reserved.has(name)));
+  return { playbook, op, args, options: parsed.options };
+}
+
+function resolveRunTimeout(spec, cwd) {
+  const explicit = Number(spec.args.timeout);
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  try {
+    const playbook = resolvePlaybook(spec.playbook, { cwd, pinBuiltIn: spec.options["pin-built-in"] === true });
+    const op = playbook.ops.get(spec.op);
+    const value = Number(op?.args?.timeout?.default);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function playbookCommandNeedsBrowser(argv) {
+  if (argv[0] === "use") return true;
+  const subcommand = argv[1];
+  if (subcommand === "run") return true;
+  return subcommand === "record" && ["start", "stop", "discard"].includes(argv[2]);
+}
+
+async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
+  if (!["playbook", "pb", "use"].includes(argv[0])) return { handled: false };
+  if (argv[0] === "use" || argv[1] === "run") {
+    const spec = runSpec(argv);
+    const timeout = resolveRunTimeout(spec, cwd);
+    const args = {
+      playbook: spec.playbook,
+      op: spec.op,
+      args: spec.args,
+      projectDir: cwd,
+      ...(timeout ? { timeout } : {}),
+      write: spec.options.write === true,
+      repeat: spec.options.repeat === true,
+      retryAttempt: spec.options["retry-attempt"],
+      overrideInDoubt: spec.options["override-in-doubt"] === true,
+      pinBuiltIn: spec.options["pin-built-in"] === true,
+    };
+    const value = await requestHost(endpoint, "playbook.run", args, {
+      tabId: spec.options["tab-id"],
+      timeoutMs: resolveRequestDeadlineMs("playbook.run", args),
+    });
+    return { handled: true, value, json: spec.options.json === true };
+  }
+  const command = argv[1];
+  const parsed = parseCommandArgs(argv.slice(2));
+  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>" };
+  if (endpoint?.kind === "remote" && ["list", "show", "ops"].includes(command)) throw new Error(`playbook ${command} is local-only with --remote because runs resolve on the browser host`);
+  if (command === "list") return { handled: true, value: listPlaybooks({ cwd }), json: parsed.options.json === true };
+  if (command === "show") {
+    const playbook = resolvePlaybook(parsed.positional[0], { cwd });
+    return { handled: true, value: { id: playbook.id, name: playbook.name, version: playbook.version, description: playbook.description, origins: playbook.origins, provenance: playbook.provenance, ops: [...playbook.ops.keys()] }, json: parsed.options.json === true };
+  }
+  if (command === "ops") {
+    const playbook = resolvePlaybook(parsed.positional[0], { cwd });
+    return { handled: true, value: [...playbook.ops.values()].map((op) => ({ id: op.id, description: op.description || "", effect: op.effect, strategies: op.run.map((strategy) => strategy.using) })), json: parsed.options.json === true };
+  }
+  if (command === "record") {
+    const action = parsed.positional[0];
+    const tool = `playbook.record.${action}`;
+    let args = {};
+    if (action === "start") args = { site: parsed.positional[1], op: parsed.options.op, watch: parsed.options.watch === true, network: parsed.options.network === true, includeInputValues: parsed.options["include-input-values"] === true };
+    else if (action === "mark") args = { label: parsed.positional.slice(1).join(" ") };
+    else if (action === "stop") args = { draft: parsed.options.draft === true };
+    else if (!["status", "pause", "resume", "discard"].includes(action)) throw new Error("Unknown record command");
+    const value = await requestHost(endpoint, tool, args, { tabId: parsed.options["tab-id"] });
+    return { handled: true, value, json: parsed.options.json === true };
+  }
+  if (command === "suggest") return { handled: true, value: suggestions({ since: parsed.options.since || "1h" }), json: parsed.options.json === true };
+  if (command === "save") {
+    let value;
+    if (parsed.options["from-record"]) value = saveFromRecord({ recordId: parsed.options["from-record"], scope: parsed.options.project ? "project" : "user", cwd });
+    else if (parsed.options["from-recent"] || parsed.positional[0]) value = saveFromRecent({ site: parsed.positional[0], op: parsed.options.op, since: parsed.options["from-recent"] === true ? "1h" : parsed.options["from-recent"] || "1h", scope: parsed.options.project ? "project" : "user", cwd });
+    else throw new Error("save requires --from-record <id> or <site> --op <name> --from-recent");
+    return { handled: true, value, json: parsed.options.json === true };
+  }
+  if (command === "client") {
+    const action = parsed.positional[0];
+    if (action === "derive") return { handled: true, value: deriveClient(parsed.positional[1], parsed.options.op, parsed.options.out, { recordId: parsed.options["from-record"], requestId: parsed.options["request-id"] }), json: parsed.options.json === true };
+    if (action === "export") {
+      const playbook = parsed.positional[1];
+      const resolved = resolvePlaybook(playbook, { cwd });
+      const op = parsed.options.op || [...resolved.ops.keys()][0];
+      return { handled: true, value: exportClient(playbook, op, parsed.options.out, { cwd }), json: parsed.options.json === true };
+    }
+    if (action === "verify") return { handled: true, value: await verifyClient(parsed.positional[1], { live: parsed.options.live === true ? true : undefined }), json: parsed.options.json === true };
+    throw new Error("Unknown client command");
+  }
+  if (command === "trace" && parsed.positional[0] === "export") {
+    if (!parsed.options["from-record"] || !parsed.options.har) throw new Error("trace export requires --from-record <id> --har <path>");
+    return { handled: true, value: exportRecordHar(parsed.options["from-record"], path.resolve(parsed.options.har)), json: parsed.options.json === true };
+  }
+  if (command === "export") return { handled: true, value: exportPlaybookDirectory(parsed.positional[0], { out: parsed.options.out, cwd }), json: parsed.options.json === true };
+  if (command === "import") return { handled: true, value: importPlaybookDirectory(parsed.positional[0], { scope: parsed.options.project ? "project" : "user", cwd }), json: parsed.options.json === true };
+  throw new Error(`Unknown playbook command: ${command}`);
+}
+
+function formatPlaybookOutput(value, json = false) {
+  if (json || typeof value !== "string") return JSON.stringify(value, null, 2);
+  return value;
+}
+
+module.exports = { formatPlaybookOutput, handlePlaybookCli, playbookCommandNeedsBrowser };

package/native/playbook-client.cjs

@@ -0,0 +1,259 @@
+const fs = require("fs");
+const http = require("http");
+const path = require("path");
+const { execFile } = require("child_process");
+const { atomicWriteFile, atomicWriteJson, ensurePrivateDir, getPrivateStateRoot, readPrivateJson } = require("./private-state.cjs");
+const { resolveOp } = require("./playbooks.cjs");
+const { readRecord, recordsRoot } = require("./playbook-records.cjs");
+const { assertNoEmbeddedSecrets, assertUrlHasNoEmbeddedSecrets, safeHeaders } = require("./redaction.cjs");
+const { version: PACKAGE_VERSION } = require("../package.json");
+
+function absoluteEndpointUrl(url, origins = []) {
+  if (typeof url !== "string" || !url) throw new Error("client projection requires an endpoint URL");
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error("client projection endpoint must use HTTP(S)");
+    return parsed.toString();
+  } catch (error) {
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url)) throw error;
+  }
+  if (!Array.isArray(origins) || origins.length !== 1) {
+    throw new Error("client projection requires an absolute endpoint URL or exactly one declared origin");
+  }
+  const resolved = new URL(url, origins[0]);
+  if (resolved.protocol !== "http:" && resolved.protocol !== "https:") throw new Error("client projection endpoint must use HTTP(S)");
+  return resolved.toString();
+}
+
+function networkStrategy(op) {
+  const strategy = op.run.find((candidate) => candidate.using === "network");
+  if (!strategy) throw new Error(`op ${op.id} has no validated network strategy`);
+  return strategy;
+}
+
+function clientSource() {
+  return `#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const directory = path.dirname(fileURLToPath(import.meta.url));
+const manifest = JSON.parse(fs.readFileSync(path.join(directory, "surf-client.json"), "utf8"));
+const args = {};
+for (let i = 2; i < process.argv.length; i++) {
+  if (!process.argv[i].startsWith("--")) continue;
+  const name = process.argv[i].slice(2);
+  const next = process.argv[i + 1];
+  args[name] = next && !next.startsWith("--") ? (i++, next) : true;
+}
+const template = (value) => typeof value === "string"
+  ? value.replace(/\\{\\{([a-zA-Z0-9._-]+)\\}\\}/g, (_, name) => {
+      if (args[name] === undefined) throw new Error(\`missing argument --\${name}\`);
+      return String(args[name]);
+    })
+  : Array.isArray(value) ? value.map(template)
+  : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, template(item)]))
+  : value;
+const endpoint = template(manifest.endpoint);
+const url = new URL(process.env.SURF_CLIENT_ENDPOINT_URL || endpoint.url);
+for (const [name, value] of Object.entries(endpoint.query || {})) url.searchParams.set(name, String(value));
+const headers = { ...(endpoint.headers || {}) };
+for (const input of manifest.authInputs || []) {
+  const value = process.env[input.env];
+  if (input.required && !value) throw new Error(\`missing auth environment variable \${input.env}\`);
+  if (value && input.header) headers[input.header] = value;
+}
+const response = await fetch(url, {
+  method: endpoint.method,
+  headers,
+  ...(endpoint.body === undefined ? {} : { body: typeof endpoint.body === "string" ? endpoint.body : JSON.stringify(endpoint.body) }),
+});
+const text = await response.text();
+if (!response.ok) throw new Error(\`HTTP \${response.status}: \${text.slice(0, 500)}\`);
+let bodyJson;
+try { bodyJson = JSON.parse(text); } catch {}
+let output = manifest.extract ? {
+  status: response.status,
+  ok: response.ok,
+  url: response.url,
+  headers: Object.fromEntries(response.headers.entries()),
+  body: text,
+  bodyJson,
+} : bodyJson ?? text;
+if (manifest.extract?.jsonPath) {
+  output = bodyJson ?? output;
+  for (const part of manifest.extract.jsonPath.replace(/^\\$\\.?/, "").split(".").filter(Boolean)) output = output?.[part];
+}
+if (manifest.extract?.field) output = output?.[manifest.extract.field];
+process.stdout.write(output === undefined ? "" : typeof output === "string" ? output : JSON.stringify(output, null, 2));
+process.stdout.write("\\n");
+`;
+}
+
+function generateClient({ playbookId, op, strategy, provenance, out, allowWrite = false, origins = [] }) {
+  if (op.effect === "write" && !allowWrite) throw new Error("write-capable client projection requires explicit review");
+  if (typeof out !== "string" || !out) throw new Error("client projection requires --out <directory>");
+  const directory = path.resolve(out);
+  const request = strategy.request;
+  const endpoint = {
+    method: request.method || "GET",
+    url: absoluteEndpointUrl(request.url, origins),
+    query: request.query || {},
+    headers: safeHeaders(request.headers),
+    ...(request.body !== undefined ? { body: request.body } : {}),
+  };
+  assertNoEmbeddedSecrets(endpoint);
+  assertUrlHasNoEmbeddedSecrets(endpoint.url);
+  if (fs.existsSync(directory) && fs.lstatSync(directory).isSymbolicLink()) throw new Error(`refusing symbolic link: ${directory}`);
+  ensurePrivateDir(directory, directory);
+  const manifest = {
+    version: 1,
+    generator: { name: "surf-cli", version: PACKAGE_VERSION },
+    source: provenance,
+    playbook: playbookId,
+    op: op.id,
+    effect: op.effect,
+    endpoint,
+    extract: strategy.extract || null,
+    authInputs: Array.isArray(request.authInputs) ? request.authInputs.map((input) => ({ env: input.env, header: input.header, required: input.required !== false })) : [],
+    verification: strategy.verify || null,
+    verificationCommand: "surf pb client verify .",
+    noEmbeddedSecrets: true,
+  };
+  atomicWriteJson(path.join(directory, "surf-client.json"), manifest, { root: directory });
+  atomicWriteFile(path.join(directory, "client.mjs"), clientSource(), { root: directory, encoding: "utf8" });
+  atomicWriteJson(path.join(directory, "package.json"), { private: true, type: "module", scripts: { start: "node client.mjs" } }, { root: directory });
+  return { directory, manifest };
+}
+
+function exportClient(playbookId, opId, out, options = {}) {
+  const { playbook, op } = resolveOp(playbookId, opId, options);
+  return generateClient({ playbookId, op, strategy: networkStrategy(op), provenance: { type: "playbook", id: playbook.id, op: op.id, ...playbook.provenance }, out, allowWrite: options.allowWrite, origins: op.origins || playbook.origins });
+}
+
+function findRecord(site, op, root = getPrivateStateRoot()) {
+  const base = recordsRoot(root);
+  if (!fs.existsSync(base)) return null;
+  return fs.readdirSync(base).filter((name) => name.startsWith("rec-")).map((name) => readRecord(name, root)).filter((record) => record?.site === site && record?.op === op).sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt)))[0] || null;
+}
+
+function deriveClient(site, opId, out, options = {}) {
+  const root = options.root || getPrivateStateRoot();
+  const record = options.recordId ? readRecord(options.recordId, root) : findRecord(site, opId, root);
+  if (!record) throw new Error(`no record found for ${site} ${opId}`);
+  const trace = readPrivateJson(path.join(recordsRoot(root), record.id, "network", "trace.json"), null, { root });
+  const candidates = (trace?.entries || []).filter((candidate) => ["GET", "HEAD", "OPTIONS", "POST"].includes(candidate.method) && candidate.status >= 200 && candidate.status < 400);
+  const entry = options.requestId
+    ? candidates.find((candidate) => candidate.id === options.requestId || candidate._requestId === options.requestId)
+    : candidates.length === 1 ? candidates[0] : null;
+  if (!options.requestId && candidates.length > 1) throw new Error(`record ${record.id} has multiple read endpoints; pass --request-id`);
+  if (!entry) throw new Error(`record ${record.id} has no validated read endpoint`);
+  const op = { id: opId, effect: "read", run: [] };
+  const url = new URL(entry.url);
+  const query = Object.fromEntries(url.searchParams.entries());
+  url.search = "";
+  const strategy = { using: "network", request: { method: entry.method, url: url.toString(), query, headers: safeHeaders(entry.requestHeaders), ...(entry.requestBody !== undefined ? { body: entry.requestBody } : {}) } };
+  return generateClient({ playbookId: site, op, strategy, provenance: { type: "record", recordId: record.id }, out });
+}
+
+function collectTemplateArgs(value, names = new Set()) {
+  if (typeof value === "string") {
+    for (const match of value.matchAll(/\{\{([a-zA-Z0-9._-]+)\}\}/g)) names.add(match[1]);
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectTemplateArgs(item, names);
+  } else if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectTemplateArgs(item, names);
+  }
+  return names;
+}
+
+function clientArgs(manifest) {
+  return [...collectTemplateArgs(manifest.endpoint)].flatMap((name) => [`--${name}`, "verify"]);
+}
+
+function authEnv(manifest, live) {
+  const env = {};
+  for (const input of manifest.authInputs || []) {
+    if (!input.env) continue;
+    if (live) {
+      if (process.env[input.env] !== undefined) env[input.env] = process.env[input.env];
+    } else env[input.env] = "verify-token";
+  }
+  return env;
+}
+
+function verificationBody(manifest) {
+  if (manifest.extract?.field === "body") return "verified";
+  return JSON.stringify({ ok: true, body: "verified", data: "verified", items: ["verified"] });
+}
+
+function templateForVerify(value) {
+  if (typeof value === "string") return value.replace(/\{\{[a-zA-Z0-9._-]+\}\}/g, "verify");
+  if (Array.isArray(value)) return value.map(templateForVerify);
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, templateForVerify(item)]));
+  return value;
+}
+
+function runClient(resolved, manifest, { env = {}, live = false } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(process.execPath, [path.join(resolved, "client.mjs"), ...clientArgs(manifest)], {
+      cwd: resolved,
+      env: { ...process.env, ...authEnv(manifest, live), ...env },
+      encoding: "utf8",
+      timeout: 30000,
+    }, (error, stdout, stderr) => {
+      if (error) {
+        error.message = stderr || error.message;
+        reject(error);
+      } else resolve(stdout);
+    });
+  });
+}
+
+async function verifyWithLocalServer(resolved, manifest) {
+  const requests = [];
+  const endpoint = templateForVerify(manifest.endpoint);
+  const expectedUrl = new URL(endpoint.url);
+  for (const [name, value] of Object.entries(endpoint.query || {})) expectedUrl.searchParams.set(name, String(value));
+  const expectedPath = `${expectedUrl.pathname}${expectedUrl.search}`;
+  const expectedBody = endpoint.body === undefined ? undefined : typeof endpoint.body === "string" ? endpoint.body : JSON.stringify(endpoint.body);
+  const server = http.createServer((request, response) => {
+    let requestBody = "";
+    request.setEncoding("utf8");
+    request.on("data", (chunk) => { requestBody += chunk; });
+    request.on("end", () => {
+      requests.push({ method: request.method, url: request.url, body: requestBody });
+      const body = verificationBody(manifest);
+      response.writeHead(manifest.verification?.status || 200, { "content-type": body.startsWith("{") ? "application/json" : "text/plain" });
+      response.end(body);
+    });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  try {
+    const address = server.address();
+    const stdout = await runClient(resolved, manifest, {
+      env: { SURF_CLIENT_ENDPOINT_URL: `http://127.0.0.1:${address.port}${expectedPath}` },
+    });
+    if (requests.length === 0) throw new Error("generated client did not call its verification endpoint");
+    const request = requests[0];
+    if (request.method !== endpoint.method) throw new Error(`generated client used ${request.method} instead of ${endpoint.method}`);
+    if (request.url !== expectedPath) throw new Error(`generated client requested ${request.url} instead of ${expectedPath}`);
+    if (expectedBody !== undefined && request.body !== expectedBody) throw new Error("generated client request body did not match the projected endpoint");
+    return { requests: requests.length, stdout: stdout.trim() };
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+async function verifyClient(directory, { live } = {}) {
+  const resolved = path.resolve(directory);
+  const manifest = JSON.parse(fs.readFileSync(path.join(resolved, "surf-client.json"), "utf8"));
+  const source = fs.readFileSync(path.join(resolved, "client.mjs"), "utf8");
+  const serialized = `${JSON.stringify(manifest)}\n${source}`.toLowerCase();
+  if (!manifest.noEmbeddedSecrets || /bearer [a-z0-9._-]+|cookie:\s*[^<]|authorization\s*[:=]\s*["'][^<]/i.test(serialized)) throw new Error("generated client contains embedded credentials");
+  if (!manifest.endpoint?.method || !manifest.endpoint?.url) throw new Error("generated client endpoint is incomplete");
+  absoluteEndpointUrl(manifest.endpoint.url);
+  const execution = live ? { stdout: (await runClient(resolved, manifest, { live: true })).trim() } : await verifyWithLocalServer(resolved, manifest);
+  return { valid: true, playbook: manifest.playbook, op: manifest.op, endpoint: manifest.endpoint, execution };
+}
+
+module.exports = { absoluteEndpointUrl, deriveClient, exportClient, generateClient, verifyClient };