pi-browser-harness 0.13.0 → 0.14.0

package/src/recipes/compile.ts

@@ -0,0 +1,198 @@
+import { type Result, err, ok } from "../util/result";
+import type { JsonObject } from "../util/tool";
+import type { JournalEntry, Locator } from "./journal";
+import { PARAM_FORMS, RECIPE_SITE, type RecipeStep, type StepExpect } from "./recipe";
+import { MESSAGE_ROLES } from "./recordable";
+import { messagePrefix } from "./replay";
+
+const MAX_EXPECT_APPEARED = 3;
+
+const shortName = (tool: string): string => (tool.startsWith("browser_") ? tool.slice("browser_".length) : tool);
+
+// The agent's most recent browser task: every agent entry from the highest run that has one.
+export const latestTask = (entries: ReadonlyArray<JournalEntry>): ReadonlyArray<JournalEntry> => {
+  const agent = entries.filter((e) => e.source === "agent");
+  const last = agent.reduce((max, e) => Math.max(max, e.run), 0);
+  return agent.filter((e) => e.run === last);
+};
+
+// Calls whose effect is the page they land on; the elements of that page say nothing about the step.
+const LOADS_PAGE: ReadonlySet<string> = new Set(["browser_navigate", "browser_new_tab", "browser_go_back", "browser_go_forward", "browser_reload"]);
+
+// What a replay should see after the step. A new URL, a dialog, a download and a status or alert message are each
+// a direct sign the step worked; elements that appeared are used only when there is none of these, since they are
+// often whatever else the page happened to render.
+// A wait changes nothing; whatever appeared while it waited is the page's own doing, and its success is the check.
+const WAITS: ReadonlySet<string> = new Set(["browser_wait_for", "browser_wait_for_load"]);
+
+// Replay compares only a URL's origin and path, so that is all a step keeps: a query or fragment can hold a
+// one-time token (Cloudflare's __cf_chl_rt_tk, a session id) that has no place on disk and means nothing next run.
+export const pageKey = (url: string): string => {
+  try {
+    const u = new URL(url);
+    return u.origin === "null" ? url : `${u.origin}${u.pathname}`;
+  } catch {
+    return url;
+  }
+};
+
+const expectOf = (e: JournalEntry): StepExpect | undefined => {
+  const c = e.change;
+  if (c === undefined || WAITS.has(e.tool)) return undefined;
+  const url = c.url !== undefined && pageKey(c.url) !== pageKey(e.url) ? pageKey(c.url) : undefined;
+  // A page load brings its banners and counters with it, so its messages say nothing about the step. A message
+  // with no words before its first number ("1,151") would match any message of its role, so it is no check.
+  const messages = LOADS_PAGE.has(e.tool) ? [] : c.appeared.filter((a) => MESSAGE_ROLES.has(a.role) && messagePrefix(a.name) !== "");
+  const strong = url !== undefined || c.dialog !== undefined || c.download === true || LOADS_PAGE.has(e.tool);
+  const elements = c.appeared.filter((a) => !MESSAGE_ROLES.has(a.role));
+  const appeared = (messages.length > 0 ? messages : strong ? [] : elements).slice(0, MAX_EXPECT_APPEARED);
+  const expect: StepExpect = {
+    ...(url !== undefined ? { url } : {}),
+    ...(appeared.length > 0 ? { appeared } : {}),
+    ...(c.dialog !== undefined ? { dialog: c.dialog } : {}),
+    ...(c.download === true ? { download: true } : {}),
+  };
+  return Object.keys(expect).length > 0 ? expect : undefined;
+};
+
+const isPoint = (l: Locator | undefined): boolean => l !== undefined && "x" in l;
+
+// Browser settings, not page actions: a replayed download folder would move the user's Chrome downloads for good.
+const SETTINGS: ReadonlySet<string> = new Set(["browser_download"]);
+
+// A script the journal measured to change nothing (see JournalEntry.readOnly): the agent only read the page with it,
+// so replay does not need it and it is left out rather than refusing the save.
+export const isNoEffectScript = (e: JournalEntry): boolean => e.ok && e.tool === "browser_execute_js" && e.readOnly === true;
+
+// `openBefore` counts the tabs that steps before these, kept from a recipe being repaired, opened and left open.
+// A read whose args could not be kept (request headers, a tab id) is left out; so is a read the task repeated
+// exactly later, which the later copy covers.
+export const isLeftOutRead = (e: JournalEntry, i: number, entries: ReadonlyArray<JournalEntry>): boolean =>
+  e.read === true &&
+  (!e.replayable || entries.slice(i + 1).some((l) => l.ok && l.read === true && l.tool === e.tool && JSON.stringify(l.args) === JSON.stringify(e.args)));
+
+export const compileSteps = (entries: ReadonlyArray<JournalEntry>, openBefore = 0): Result<ReadonlyArray<RecipeStep>, string> => {
+  const steps: RecipeStep[] = [];
+  let openTabs = openBefore;
+  for (const [i, e] of entries.entries()) {
+    if (!e.ok || SETTINGS.has(e.tool) || isNoEffectScript(e) || isLeftOutRead(e, i, entries)) continue;
+    if (e.password) return err(`${e.tool} typed into a password field; recipes never type credentials, so this task cannot be saved`);
+    if (!e.replayable) return err(`${e.tool} cannot be replayed; redo the task without it, or leave it out of the recipe`);
+    if (e.tool === "browser_new_tab") openTabs += 1;
+    if (e.tool === "browser_close_tab") {
+      if (openTabs === 0) {
+        return err("browser_close_tab closes a tab the task did not open, so a replay would close the user's tab; leave the tab open, or start the task with browser_new_tab");
+      }
+      openTabs -= 1;
+    }
+    const expect = expectOf(e);
+    if (e.tool === "browser_fill_form") {
+      for (const f of e.fields ?? []) {
+        steps.push({ action: "fill", args: { value: f.value }, ...(f.locator !== undefined ? { locator: f.locator } : {}) });
+      }
+      continue;
+    }
+    const fragile = isPoint(e.locator) || e.tool === "browser_drag_and_drop";
+    steps.push({
+      action: shortName(e.tool),
+      args: e.args,
+      ...(e.locator !== undefined ? { locator: e.locator } : {}),
+      ...(expect !== undefined ? { expect } : {}),
+      ...(fragile ? { fragile: true } : {}),
+      ...(e.wrote === true ? { writes: true } : {}),
+    });
+  }
+  if (steps.length === 0) return err("the agent's last browser task made no page-changing calls to save");
+  return ok(steps);
+};
+
+// The value as typed becomes {{name}}; its URL forms ("Alan_Turing", "Alan+Turing", "Alan%20Turing") become
+// {{name|form}}, so a replay writes the new value the same way.
+const template = (s: string, pairs: ReadonlyArray<readonly [string, string]>): string =>
+  pairs.reduce((acc, [name, value]) => {
+    let out = acc.split(value).join(`{{${name}}}`);
+    for (const [form, apply] of PARAM_FORMS) {
+      const shaped = apply(value);
+      if (shaped !== value) out = out.split(shaped).join(`{{${name}|${form}}}`);
+    }
+    return out;
+  }, s);
+
+const templateArgs = (args: JsonObject, pairs: ReadonlyArray<readonly [string, string]>): JsonObject => {
+  const out: Record<string, JsonObject[string]> = {};
+  for (const [k, v] of Object.entries(args)) out[k] = typeof v === "string" ? template(v, pairs) : v;
+  return out;
+};
+
+const templateLocator = (l: Locator, pairs: ReadonlyArray<readonly [string, string]>): Locator =>
+  "role" in l ? { ...l, name: template(l.name, pairs) } : l;
+
+// The page a step lands on carries the param too: a repo's URL, an account's name in a heading.
+const templateExpect = (e: StepExpect, pairs: ReadonlyArray<readonly [string, string]>): StepExpect => ({
+  ...e,
+  ...(e.url !== undefined ? { url: template(e.url, pairs) } : {}),
+  ...(e.appeared !== undefined ? { appeared: e.appeared.map((a) => ({ ...a, name: template(a.name, pairs) })) } : {}),
+});
+
+const MAX_LISTED_VALUES = 12;
+const MAX_VALUE_CHARS = 100;
+
+// The values a param could be taken from, step by step, so a refused param can be fixed without guessing.
+const valuesIn = (steps: ReadonlyArray<RecipeStep>): string => {
+  const cut = (v: string): string => JSON.stringify(v.length > MAX_VALUE_CHARS ? `${v.slice(0, MAX_VALUE_CHARS)}…` : v);
+  const lines = steps.flatMap((s, i) => [
+    ...Object.entries(s.args).flatMap(([k, v]) => (typeof v === "string" && v !== "" ? [`  step ${i + 1} ${s.action} ${k}: ${cut(v)}`] : [])),
+    ...(s.locator !== undefined && "name" in s.locator ? [`  step ${i + 1} ${s.action} target: ${cut(s.locator.name)}`] : []),
+  ]);
+  if (lines.length === 0) return "No step holds a typed value or URL.";
+  const more = lines.length > MAX_LISTED_VALUES ? [`  … and ${lines.length - MAX_LISTED_VALUES} more`] : [];
+  return [
+    "A param value must appear, exactly as written, in one of these:",
+    ...lines.slice(0, MAX_LISTED_VALUES),
+    ...more,
+  ].join("\n");
+};
+
+// Every occurrence of a param's value becomes {{name}}; longer values go first so "2026-09-01" is not split by "2026-09".
+export const applyParams = (
+  steps: ReadonlyArray<RecipeStep>,
+  params: Readonly<Record<string, string>>,
+): Result<ReadonlyArray<RecipeStep>, string> => {
+  const pairs = [...Object.entries(params)].sort((a, b) => b[1].length - a[1].length);
+  const empty = pairs.find(([, v]) => v === "");
+  if (empty !== undefined) return err(`param ${empty[0]} has an empty value`);
+  const out = steps.map((s) => ({
+    ...s,
+    args: templateArgs(s.args, pairs),
+    ...(s.locator !== undefined ? { locator: templateLocator(s.locator, pairs) } : {}),
+    ...(s.expect !== undefined ? { expect: templateExpect(s.expect, pairs) } : {}),
+  }));
+  for (const [name, value] of pairs) {
+    const placeholder = new RegExp(`\\{\\{${name}(\\|[a-z]+)?\\}\\}`);
+    const used = out.some((s) => placeholder.test(JSON.stringify(s)));
+    if (!used) return err(`param ${name}: the value "${value}" does not appear in the task's steps. ${valuesIn(steps)}`);
+  }
+  return ok(out);
+};
+
+const OPENS_URL: ReadonlySet<string> = new Set(["browser_navigate", "browser_new_tab", "browser_http_get", "browser_read_page"]);
+
+// A call that opens or reads a URL is about that URL; its e.url is the tab it started from, which may be another site.
+const pageOf = (e: JournalEntry): string => {
+  if (!OPENS_URL.has(e.tool)) return e.url;
+  const url = e.args["url"];
+  return typeof url === "string" ? url : (e.change?.url ?? "");
+};
+
+export const siteOf = (entries: ReadonlyArray<JournalEntry>): string => {
+  for (const e of entries) {
+    const url = pageOf(e);
+    try {
+      const host = new URL(url).hostname;
+      if (RECIPE_SITE.test(host)) return host;
+    } catch {
+      // An unparseable URL names no site; try the next entry.
+    }
+  }
+  return "unknown-site";
+};

package/src/recipes/find.ts

@@ -0,0 +1,49 @@
+import type { BrowserClient } from "../client";
+import { refreshRefs } from "../domains/ref-resolve";
+import { type Result, err, ok } from "../util/result";
+import { sleep } from "../util/sleep";
+import type { Locator } from "./journal";
+
+export type TargetArgs = { readonly ref: string } | { readonly selector: string } | { readonly x: number; readonly y: number };
+
+export const FIND_TIMEOUT_MS = 5_000;
+const POLL_MS = 250;
+
+// Chrome's accessible names differ in spacing from one load to the next ("Homepage (g then d)" against
+// "Homepage ( g then d )"), so names are compared with runs of whitespace collapsed and none around brackets.
+const normalName = (name: string): string =>
+  name
+    .replace(/\s+/g, " ")
+    .replace(/\s*([()[\]{}])\s*/g, "$1")
+    .trim();
+
+export const sameName = (a: string, b: string): boolean => normalName(a) === normalName(b);
+
+const nthMatch = (client: BrowserClient, role: string, name: string, nth: number): string | undefined => {
+  let seen = 0;
+  for (const [ref, sig] of client.session().refSignatures()) {
+    if (sig.role !== role || !sameName(sig.name, name)) continue;
+    if (seen === nth) return ref;
+    seen += 1;
+  }
+  return undefined;
+};
+
+// A role+name locator is retried until the element shows up, which replaces the sleeps a recording would need.
+// A css locator or a point passes through: the tools resolve those themselves.
+export const findTarget = async (client: BrowserClient, locator: Locator, signal?: AbortSignal): Promise<Result<TargetArgs, string>> => {
+  if ("css" in locator) return ok({ selector: locator.css });
+  if ("x" in locator) return ok({ x: locator.x, y: locator.y });
+  const deadline = Date.now() + FIND_TIMEOUT_MS;
+  for (;;) {
+    const refreshed = await refreshRefs(client);
+    if (refreshed.success) {
+      const ref = nthMatch(client, locator.role, locator.name, locator.nth);
+      if (ref !== undefined) return ok({ ref });
+    }
+    if (Date.now() >= deadline || signal?.aborted) break;
+    await sleep(POLL_MS, signal);
+  }
+  const which = locator.nth > 0 ? ` (match ${locator.nth + 1})` : "";
+  return err(`no ${locator.role} named "${locator.name}"${which} on the page after ${FIND_TIMEOUT_MS / 1000}s`);
+};

package/src/recipes/journal.ts

@@ -0,0 +1,125 @@
+import { appendFile, mkdir, readdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { agentDir } from "../profile/paths";
+import type { JsonObject } from "../util/tool";
+
+export type Locator =
+  | { readonly role: string; readonly name: string; readonly nth: number }
+  | { readonly css: string }
+  | { readonly x: number; readonly y: number };
+
+export type ObservedChange = {
+  readonly url?: string;
+  readonly appeared: ReadonlyArray<{ readonly role: string; readonly name: string }>;
+  readonly dialog?: string;
+  readonly download?: boolean;
+};
+
+export type JournalFieldEntry = { readonly locator?: Locator; readonly value: string; readonly password: boolean };
+
+// One page-changing call. `args` holds the tool's arguments minus the element handle (ref, selector, x/y),
+// which lives in `locator`; a password value is replaced by "" and flagged, never stored.
+export type JournalEntry = {
+  readonly v: 1;
+  readonly at: string;
+  readonly run: number;
+  readonly source: "agent" | "replay";
+  readonly tool: string;
+  readonly replayable: boolean;
+  readonly args: JsonObject;
+  readonly locator?: Locator;
+  readonly fields?: ReadonlyArray<JournalFieldEntry>;
+  readonly password: boolean;
+  readonly url: string;
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly change?: ObservedChange;
+  // Set on a browser_execute_js that was measured to change nothing: same page, form values, storage and URL, and
+  // no request that could change server state. Saving leaves such a call out.
+  readonly readOnly?: boolean;
+  // A call that only read data for the agent (see READS in recordable.ts); replayable when its args could be kept.
+  readonly read?: boolean;
+  // The tab sent a request that can change server state (a POST, PUT, DELETE...) while the call ran.
+  readonly wrote?: boolean;
+  readonly recipe?: { readonly name: string; readonly step: number };
+};
+
+export type NewEntry = Omit<JournalEntry, "v" | "at" | "run">;
+
+export type Journal = {
+  readonly path: string;
+  readonly beginRun: () => Promise<number>;
+  readonly append: (e: NewEntry) => Promise<void>;
+  readonly entries: () => Promise<ReadonlyArray<JournalEntry>>;
+};
+
+const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+export const journalDir = (): string => join(agentDir(), "browser-harness", "journal");
+
+const isEntry = (v: unknown): v is JournalEntry =>
+  typeof v === "object" && v !== null && "v" in v && v.v === 1 && "run" in v && typeof v.run === "number";
+
+const readEntries = async (path: string): Promise<ReadonlyArray<JournalEntry>> => {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out: JournalEntry[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isEntry(parsed)) out.push(parsed);
+    } catch {
+      // A torn last line from a crash mid-append is skipped, not fatal.
+    }
+  }
+  return out;
+};
+
+const pruneOld = async (dir: string, now: number): Promise<void> => {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!name.endsWith(".jsonl")) continue;
+    const file = join(dir, name);
+    const info = await stat(file).catch(() => undefined);
+    if (info && now - info.mtimeMs > RETENTION_MS) await unlink(file).catch(() => undefined);
+  }
+};
+
+export const createJournal = (dir: string, sessionId: string, now: () => number = Date.now): Journal => {
+  const path = join(dir, `${sessionId}.jsonl`);
+  let run: number | undefined;
+  void pruneOld(dir, now());
+  return {
+    path,
+    beginRun: async () => {
+      if (run === undefined) {
+        const existing = await readEntries(path);
+        run = existing.reduce((max, e) => Math.max(max, e.run), 0);
+      }
+      run += 1;
+      return run;
+    },
+    append: async (e) => {
+      const entry: JournalEntry = { v: 1, at: new Date(now()).toISOString(), run: run ?? 0, ...e };
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      await appendFile(path, `${JSON.stringify(entry)}\n`, { encoding: "utf8", mode: 0o600 });
+    },
+    entries: () => readEntries(path),
+  };
+};
+
+let active: Journal | undefined;
+export const activeJournal = (): Journal | undefined => active;
+export const setActiveJournal = (j: Journal | undefined): void => {
+  active = j;
+};

package/src/recipes/recipe.ts

@@ -0,0 +1,215 @@
+import { parse, stringify } from "yaml";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+import { isRecord } from "../util/guards";
+import type { JsonObject, JsonValue } from "../util/tool";
+import type { Locator } from "./journal";
+import { REPLAYABLE } from "./recordable";
+
+export type StepExpect = {
+  readonly url?: string;
+  readonly appeared?: ReadonlyArray<{ readonly role: string; readonly name: string }>;
+  readonly dialog?: string;
+  readonly download?: boolean;
+};
+
+export type RecipeStep = {
+  readonly action: string;
+  readonly args: JsonObject;
+  readonly locator?: Locator;
+  readonly expect?: StepExpect;
+  readonly fragile?: boolean;
+  // The step sent data to the site when it was recorded, so running it again may repeat that (an order, a message).
+  readonly writes?: boolean;
+};
+
+export type LastRun = { readonly at: string; readonly result: "ok" | "failed"; readonly step?: number; readonly repairedStep?: number };
+
+export type Recipe = {
+  readonly name: string;
+  readonly site: string;
+  readonly version: number;
+  readonly params: Readonly<Record<string, { readonly type: "string"; readonly example: string }>>;
+  readonly steps: ReadonlyArray<RecipeStep>;
+  readonly recorded: { readonly at: string; readonly session: string };
+  readonly lastRun?: LastRun;
+  // Saved by a version that marks each step that sent data (`writes`). Without it, an unmarked step may have.
+  readonly writesTracked?: boolean;
+};
+
+export const RECIPE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// A host (name, IPv4, bracketed IPv6) or unknown-site. The site is a directory under the recipe root, so it may
+// never hold a path separator or be "." or "..".
+export const RECIPE_SITE = /^(?!\.{1,2}$)[a-z0-9._\-[\]:]{1,253}$/;
+// The forms a param's value takes in a URL, by the name a recipe writes after "|": {{topic|underscore}} fills
+// "Grace Hopper" as "Grace_Hopper". A plain {{topic}} is the value as typed.
+export const PARAM_FORMS: ReadonlyMap<string, (value: string) => string> = new Map([
+  ["url", (v: string) => encodeURIComponent(v)],
+  ["plus", (v: string) => encodeURIComponent(v).replace(/%20/g, "+")],
+  ["underscore", (v: string) => v.replace(/ /g, "_")],
+]);
+const PARAM_REF = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)(?:\|([a-z]+))?\}\}/g;
+const LOCATOR_KEYS: ReadonlySet<string> = new Set(["role", "name", "nth", "css", "x", "y"]);
+const STEP_META_KEYS: ReadonlySet<string> = new Set(["expect", "fragile", "writes"]);
+// For these actions x/y are the tool's own coordinates, not where an element is.
+const COORDINATE_ACTIONS: ReadonlySet<string> = new Set(["scroll", "drag_and_drop"]);
+
+// Short action names a recipe may use: every replayable tool except fill_form, which save expands into fills.
+const ACTIONS: ReadonlySet<string> = new Set(
+  [...REPLAYABLE.keys()].filter((t) => t !== "browser_fill_form").map((t) => t.slice("browser_".length)),
+);
+
+const FileSchema = Type.Object({
+  name: Type.String({ pattern: RECIPE_NAME.source }),
+  site: Type.String({ pattern: RECIPE_SITE.source }),
+  version: Type.Integer({ minimum: 1 }),
+  params: Type.Record(Type.String(), Type.Object({ type: Type.Literal("string"), example: Type.String() })),
+  steps: Type.Array(Type.Record(Type.String(), Type.Unknown()), { minItems: 1 }),
+  recorded: Type.Object({ at: Type.String(), session: Type.String() }),
+  writes_tracked: Type.Optional(Type.Boolean()),
+  last_run: Type.Optional(
+    Type.Object({
+      at: Type.String(),
+      result: Type.Union([Type.Literal("ok"), Type.Literal("failed")]),
+      step: Type.Optional(Type.Integer({ minimum: 1 })),
+      repaired_step: Type.Optional(Type.Integer({ minimum: 1 })),
+    }),
+  ),
+});
+const fileValidator = Compile(FileSchema);
+
+export const paramRefs = (value: string): ReadonlyArray<string> => [...value.matchAll(PARAM_REF)].map((m) => m[1] ?? "");
+
+const unknownForm = (value: string): string | undefined =>
+  [...value.matchAll(PARAM_REF)].map((m) => m[2]).find((f) => f !== undefined && !PARAM_FORMS.has(f));
+
+export const fillParams = (s: string, params: Readonly<Record<string, string>>): string =>
+  s.replace(PARAM_REF, (whole, name: string, form: string | undefined) => {
+    const value = params[name];
+    if (value === undefined) return whole;
+    if (form === undefined) return value;
+    return PARAM_FORMS.get(form)?.(value) ?? whole;
+  });
+
+const isJsonScalar = (v: unknown): v is string | number | boolean =>
+  typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+
+const locatorOf = (body: Readonly<Record<string, unknown>>): Locator | undefined => {
+  const { role, name, nth, css, x, y } = body;
+  if (typeof role === "string" && typeof name === "string") return { role, name, nth: typeof nth === "number" ? nth : 0 };
+  if (typeof css === "string") return { css };
+  if (typeof x === "number" && typeof y === "number") return { x, y };
+  return undefined;
+};
+
+const expectOf = (v: unknown): StepExpect | undefined => {
+  if (!isRecord(v)) return undefined;
+  const appeared = Array.isArray(v["appeared"])
+    ? v["appeared"].flatMap((a) => (isRecord(a) && typeof a["role"] === "string" && typeof a["name"] === "string" ? [{ role: a["role"], name: a["name"] }] : []))
+    : undefined;
+  return {
+    ...(typeof v["url"] === "string" ? { url: v["url"] } : {}),
+    ...(appeared !== undefined && appeared.length > 0 ? { appeared } : {}),
+    ...(typeof v["dialog"] === "string" ? { dialog: v["dialog"] } : {}),
+    ...(v["download"] === true ? { download: true } : {}),
+  };
+};
+
+const decodeStep = (raw: Readonly<Record<string, unknown>>, n: number, declared: ReadonlySet<string>): Result<RecipeStep, string> => {
+  const actionKeys = Object.keys(raw).filter((k) => !STEP_META_KEYS.has(k));
+  if (actionKeys.length !== 1) return err(`step ${n}: needs exactly one action, found ${actionKeys.length}`);
+  const action = actionKeys[0] ?? "";
+  if (!ACTIONS.has(action)) return err(`step ${n}: "${action}" is not a replayable action`);
+  const body = raw[action] ?? {};
+  if (!isRecord(body)) return err(`step ${n}: "${action}" must be a map`);
+  const coordinates = COORDINATE_ACTIONS.has(action);
+  const args: Record<string, string | number | boolean> = {};
+  for (const [k, v] of Object.entries(body)) {
+    if (LOCATOR_KEYS.has(k) && !coordinates) continue;
+    if (!isJsonScalar(v)) return err(`step ${n}: "${action}.${k}" must be a string, number or boolean`);
+    args[k] = v;
+  }
+  for (const v of Object.values(body)) {
+    if (typeof v !== "string") continue;
+    const unknown = paramRefs(v).find((p) => !declared.has(p));
+    if (unknown !== undefined) return err(`step ${n}: {{${unknown}}} is not a declared param`);
+    const form = unknownForm(v);
+    if (form !== undefined) return err(`step ${n}: "|${form}" is not a param form; use one of ${[...PARAM_FORMS.keys()].join(", ")}`);
+  }
+  const locator = coordinates ? undefined : locatorOf(body);
+  const expect = expectOf(raw["expect"]);
+  return ok({
+    action,
+    args,
+    ...(locator !== undefined ? { locator } : {}),
+    ...(expect !== undefined ? { expect } : {}),
+    ...(raw["fragile"] === true ? { fragile: true } : {}),
+    ...(raw["writes"] === true ? { writes: true } : {}),
+  });
+};
+
+// Validates the whole file before anything runs; the first problem is reported with its step number.
+export const parseRecipe = (text: string): Result<Recipe, string> => {
+  let raw: unknown;
+  try {
+    raw = parse(text);
+  } catch (e) {
+    return err(`not valid YAML: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!fileValidator.Check(raw)) {
+    const messages = fileValidator.Errors(raw).map((x) => x.message).join("; ");
+    return err(`invalid recipe: ${messages.length > 0 ? messages : "unknown shape"}`);
+  }
+  const declared = new Set(Object.keys(raw.params));
+  const steps: RecipeStep[] = [];
+  for (const [i, s] of raw.steps.entries()) {
+    const decoded = decodeStep(s, i + 1, declared);
+    if (!decoded.success) return decoded;
+    steps.push(decoded.data);
+  }
+  const lr = raw.last_run;
+  return ok({
+    name: raw.name,
+    site: raw.site,
+    version: raw.version,
+    params: raw.params,
+    steps,
+    recorded: raw.recorded,
+    ...(raw.writes_tracked === true ? { writesTracked: true } : {}),
+    ...(lr !== undefined
+      ? { lastRun: { at: lr.at, result: lr.result, ...(lr.step !== undefined ? { step: lr.step } : {}), ...(lr.repaired_step !== undefined ? { repairedStep: lr.repaired_step } : {}) } }
+      : {}),
+  });
+};
+
+const encodeStep = (s: RecipeStep): Record<string, JsonValue> => ({
+  [s.action]: { ...(s.locator ?? {}), ...s.args },
+  ...(s.expect !== undefined && Object.keys(s.expect).length > 0 ? { expect: s.expect } : {}),
+  ...(s.fragile === true ? { fragile: true } : {}),
+  ...(s.writes === true ? { writes: true } : {}),
+});
+
+export const stringifyRecipe = (r: Recipe): string =>
+  stringify(
+    {
+      name: r.name,
+      site: r.site,
+      version: r.version,
+      params: r.params,
+      steps: r.steps.map(encodeStep),
+      recorded: r.recorded,
+      ...(r.writesTracked === true ? { writes_tracked: true } : {}),
+      ...(r.lastRun !== undefined
+        ? {
+            last_run: {
+              at: r.lastRun.at,
+              result: r.lastRun.result,
+              ...(r.lastRun.step !== undefined ? { step: r.lastRun.step } : {}),
+              ...(r.lastRun.repairedStep !== undefined ? { repaired_step: r.lastRun.repairedStep } : {}),
+            },
+          }
+        : {}),
+    },
+    { lineWidth: 0 },
+  );