pi-browser-harness 0.13.0 → 0.14.0

package/src/recipes/save-tool.ts

@@ -0,0 +1,247 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr } from "../util/tool";
+import { applyParams, compileSteps, isNoEffectScript, latestTask, siteOf } from "./compile";
+import { type JournalEntry, activeJournal } from "./journal";
+import { RECIPE_NAME, type Recipe, type RecipeStep, stringifyRecipe } from "./recipe";
+import { type StoredRecipe, findRecipe, recipeRoots, saveRecipe } from "./store";
+import { printable, trustWritten } from "./trust";
+import { describeStep, runRecipe } from "./replay";
+
+const SaveArgs = Type.Object({
+  name: Type.String({ pattern: RECIPE_NAME.source, description: "Recipe name, lowercase words joined by '-' (e.g. 'vendor-invoices-export')" }),
+  params: Type.Optional(
+    Type.Record(Type.String({ pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$" }), Type.String(), {
+      description: "Values from this run that change between runs, by param name: { month: '2026-09' }. Each value becomes {{name}} in the steps.",
+    }),
+  ),
+  project: Type.Optional(Type.Boolean({ description: "Save under the project's .pi/browser-recipes instead of the user's recipe folder" })),
+  repair_step: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Repair an existing recipe after a failed replay: replace this step through the end with what you did since the failure. Use the step number the failure reported. The repaired recipe is replayed before it is written, so finish the task from the page where it failed, without detours.",
+    }),
+  ),
+});
+
+// The user sees exactly what will be written, then any notes on it; without a UI the agent's call is the
+// confirmation.
+export const confirmAndSave = async (
+  ctx: ExtensionContext,
+  root: string,
+  recipe: Recipe,
+  title: string,
+  notes = "",
+): Promise<Result<StoredRecipe, ToolErr>> => {
+  if (ctx.hasUI) {
+    const yes = await ctx.ui.confirm(title, `${stringifyRecipe(recipe)}${notes === "" ? "" : `\n${notes}`}`);
+    if (!yes) return err({ kind: "invalid_state", message: "The user declined to save the recipe; nothing was written." });
+  }
+  const saved = await saveRecipe(root, recipe);
+  if (!saved.success) return err({ kind: "io_error", message: saved.error });
+  await trustWritten(saved.data, ctx.cwd);
+  return ok(saved.data);
+};
+
+const fragileNote = (recipe: Recipe): string => {
+  const steps = recipe.steps.flatMap((s, i) => (s.fragile === true ? [i + 1] : []));
+  return steps.length === 0 ? "" : `\nFragile steps (located by coordinates, may break on layout changes): ${steps.join(", ")}`;
+};
+
+const leftOutNote = (entries: ReadonlyArray<JournalEntry>): string => {
+  const n = entries.filter(isNoEffectScript).length;
+  const reads = entries.filter((e) => e.ok && e.read === true && !e.replayable).length;
+  const scripts =
+    n === 0
+      ? ""
+      : `\nLeft out ${n} browser_execute_js call${n === 1 ? "" : "s"} that changed nothing on the page; a replay does not return what they read. If the task needs it, read it with browser_http_get or browser_read_page instead and save again.`;
+  const unkept =
+    reads === 0
+      ? ""
+      : `\nLeft out ${reads} read${reads === 1 ? "" : "s"} that used request headers or a tab id, which a recipe does not keep.`;
+  return `${scripts}${unkept}`;
+};
+
+const MAX_QUOTED = 120;
+
+// Page text in the dialog is quoted on one line and cut short: a newline in it could forge lines of the dialog,
+// and a long one could push the recipe out of view.
+const quoted = (text: string): string => `"${printable(text.length > MAX_QUOTED ? `${text.slice(0, MAX_QUOTED)}…` : text)}"`;
+
+const PLACEHOLDER = /\{\{[a-zA-Z_][a-zA-Z0-9_]*(?:\|[a-z]+)?\}\}/g;
+
+// Text a step matches that the recorded run's page showed, which another run's page may not: a wait for page text
+// with no param in it, and an element name holding a param next to other words. Saving cannot prove a recipe fits
+// other values, so these are shown for the user and the agent to judge, not refused.
+export const runSpecificText = (steps: ReadonlyArray<RecipeStep>): ReadonlyArray<string> =>
+  steps.flatMap((s, i) => {
+    const at = `step ${i + 1}`;
+    const text = s.args["text"];
+    const waits = s.action === "wait_for" && typeof text === "string" && text.match(PLACEHOLDER) === null ? [`${at}: waits for the text ${quoted(text)}`] : [];
+    const names = [...(s.locator !== undefined && "name" in s.locator ? [s.locator.name] : []), ...(s.expect?.appeared ?? []).map((a) => a.name)];
+    const mixed = names.filter((n) => n.match(PLACEHOLDER) !== null && n.replace(PLACEHOLDER, "").trim() !== "");
+    return [...waits, ...mixed.map((n) => `${at}: ${printable(describeStep(s))} matches ${quoted(n)}`)];
+  });
+
+const specificNote = (steps: ReadonlyArray<RecipeStep>): string => {
+  const found = runSpecificText(steps);
+  return found.length === 0
+    ? ""
+    : `These steps match text from this run's page, which another run's page may not show; replace them with steps that do not depend on it if so:\n${found.join("\n")}\n`;
+};
+
+const isFailureMarker = (e: JournalEntry, name: string): boolean =>
+  e.tool === "browser_run_recipe" && !e.ok && e.recipe?.name === name;
+
+const stringParams = (args: JournalEntry["args"]): Record<string, string> =>
+  Object.fromEntries(Object.entries(args).flatMap(([k, v]) => (typeof v === "string" ? [[k, v]] : [])));
+
+// Steps 1..N-1 stay; N..end become what the agent did after the failed replay, templated with that run's params.
+// A param the agent did not retype is not an error: the earlier steps still use it.
+export const repairSteps = (
+  recipe: Recipe,
+  entries: ReadonlyArray<JournalEntry>,
+  step: number,
+): Result<{ readonly steps: ReadonlyArray<RecipeStep>; readonly note: string; readonly params: Readonly<Record<string, string>> }, string> => {
+  let at = -1;
+  for (let i = entries.length - 1; i >= 0 && at < 0; i--) {
+    const e = entries[i];
+    if (e !== undefined && isFailureMarker(e, recipe.name)) at = i;
+  }
+  const marker = entries[at];
+  if (marker === undefined) return err(`no failed replay of ${recipe.name} in this session's journal`);
+  if (marker.recipe?.step !== step) return err(`the last failed replay of ${recipe.name} stopped at step ${marker.recipe?.step ?? "?"}, not ${step}`);
+  const after = entries.slice(at + 1).filter((e) => e.source === "agent");
+  const kept = recipe.steps.slice(0, step - 1);
+  // Each kept new_tab opens a tab and each kept close_tab closes one; only a tab still open may be closed again.
+  const openTabs = kept.reduce((n, s) => (s.action === "new_tab" ? n + 1 : s.action === "close_tab" ? Math.max(0, n - 1) : n), 0);
+  const compiled = compileSteps(after, openTabs);
+  if (!compiled.success) return err(`cannot repair from what was done after the failure: ${compiled.error}`);
+  const declared = Object.fromEntries(Object.entries(stringParams(marker.args)).filter(([k]) => k in recipe.params));
+  const templated = applyParams(compiled.data, declared);
+  const steps = templated.success ? templated.data : compiled.data;
+  return ok({ steps: [...kept, ...steps], note: leftOutNote(after), params: stringParams(marker.args) });
+};
+
+// Actions that only load or read a page, or wait, and so cannot send data however they were recorded.
+const READS_ONLY: ReadonlySet<string> = new Set([
+  "navigate",
+  "new_tab",
+  "go_back",
+  "go_forward",
+  "wait_for",
+  "wait_for_load",
+  "scroll",
+  "focus",
+  "close_tab",
+  "http_get",
+  "read_page",
+]);
+
+// What running a step again would repeat beyond the page itself. In a recipe saved before steps were marked, any
+// other step may have sent data, so it is listed too: the gate fails closed.
+const sideEffectsOf = (recipe: Recipe): ReadonlyArray<string> =>
+  recipe.steps.flatMap((s, i) => {
+    const unmarked = recipe.writesTracked !== true && !READS_ONLY.has(s.action) && s.writes !== true;
+    const effects = [
+      ...(s.action === "upload_file" ? ["uploads a file"] : []),
+      ...(s.action === "download" ? ["changes where downloads go"] : []),
+      ...(s.expect?.download === true ? ["starts a download"] : []),
+      ...(s.writes === true ? ["sends data to the site"] : []),
+      ...(unmarked ? ["may send data to the site: saved before this was tracked"] : []),
+    ];
+    return effects.length > 0 ? [`step ${i + 1}: ${describeStep(s)} (${effects.join(", ")})`] : [];
+  });
+
+// A repair is built from whatever the agent did after the failure, detours included, so it is replayed from step 1
+// before it is written. A replay repeats side effects, so when the steps have any the user decides; with no UI to
+// ask, the repair is written unchecked and says so.
+const checkRepair = async (
+  client: BrowserClient,
+  ctx: ExtensionContext,
+  recipe: Recipe,
+  params: Readonly<Record<string, string>>,
+  signal: AbortSignal | undefined,
+): Promise<Result<string, string>> => {
+  const effects = sideEffectsOf(recipe);
+  if (effects.length > 0) {
+    const why = `a check runs every step again, including:\n${effects.join("\n")}`;
+    if (!ctx.hasUI) return ok(`Not checked by a replay: ${why}\nRun the recipe to check it.`);
+    const go = await ctx.ui.confirm(`Check the repaired recipe "${recipe.name}" by running it?`, `${why}\n\nChoose No to save it without the check.`);
+    if (!go) return ok("Not checked by a replay: the user chose not to run its steps again.");
+  }
+  const outcome = await runRecipe({ client, extensionCtx: ctx, recipe, params, record: false, ...(signal !== undefined ? { signal } : {}) });
+  if (!outcome.ok) {
+    const f = outcome.failure;
+    return err(
+      `repair not saved: a replay of the repaired recipe stopped at step ${f.step} (${f.action}): ${f.reason}. The steps after the failure did not redo the task from where it stopped. Run the recipe again with browser_run_recipe for a fresh failure, finish the task from that page with browser tools, then repair from the step it reports.`,
+    );
+  }
+  return ok(`Checked: a replay of all ${outcome.steps} steps passed.`);
+};
+
+export const saveRecipeTool = defineBrowserTool({
+  name: "browser_save_recipe",
+  label: "Save Browser Recipe",
+  description:
+    "Save the browser task you just finished as a named, replayable recipe. Compiles the page-changing calls and the reads (browser_http_get, browser_read_page of a url) of your most recent browser task from the session journal, turns the given param values into {{params}}, shows the recipe to the user to confirm, and writes a YAML file. A replay returns what the reads fetched; a browser_execute_js that only read the page is left out. Saving over an existing name keeps the previous version.",
+  promptSnippet: "Save the last browser task as a replayable recipe",
+  promptGuidelines: [
+    "After finishing a multi-step browser task the user is likely to repeat (an export, a report, a routine check), offer once to save it as a recipe: propose a name and which typed or selected values are params. Do not offer again for the same task.",
+    "Params are values that change between runs and that you typed, selected or put in a URL — a month, a search term, an id. Never make a button label or page text a param.",
+  ],
+  parameters: SaveArgs,
+  concurrency: "parallel",
+  ensureAlive: false,
+  async handler(args, { client, extensionCtx, signal }) {
+    const journal = activeJournal();
+    if (journal === undefined) return err({ kind: "invalid_state", message: "No browser journal is active in this session." });
+    if (args.repair_step !== undefined) {
+      const stored = await findRecipe(extensionCtx.cwd, args.name);
+      if (!stored.success) return err({ kind: "invalid_args", message: stored.error });
+      const repaired = repairSteps(stored.data.recipe, await journal.entries(), args.repair_step);
+      if (!repaired.success) return err({ kind: "invalid_state", message: repaired.error });
+      const recipe: Recipe = {
+        ...stored.data.recipe,
+        steps: repaired.data.steps,
+        lastRun: { at: new Date().toISOString(), result: "ok", repairedStep: args.repair_step },
+      };
+      const checked = await checkRepair(client, extensionCtx, recipe, repaired.data.params, signal);
+      if (!checked.success) return err({ kind: "invalid_state", message: checked.error });
+      const notes = specificNote(recipe.steps);
+      const saved = await confirmAndSave(extensionCtx, stored.data.root, recipe, `Repair recipe "${args.name}" from step ${args.repair_step}?`, notes);
+      if (!saved.success) return saved;
+      const r = saved.data.recipe;
+      return ok({
+        text: `Repaired recipe ${r.name}: steps ${args.repair_step}–${r.steps.length} replaced, now v${r.version}; previous version kept in .history/.\n${checked.data}${fragileNote(r)}${repaired.data.note}${notes === "" ? "" : `\n${notes.trimEnd()}`}`,
+        details: { name: r.name, version: r.version, path: saved.data.path, steps: r.steps.length },
+      });
+    }
+    const task = latestTask(await journal.entries());
+    const compiled = compileSteps(task);
+    if (!compiled.success) return err({ kind: "invalid_state", message: compiled.error });
+    const params = args.params ?? {};
+    const steps = applyParams(compiled.data, params);
+    if (!steps.success) return err({ kind: "invalid_args", message: `${steps.error}${leftOutNote(task)}` });
+    const recipe: Recipe = {
+      name: args.name,
+      site: siteOf(task),
+      version: 1,
+      params: Object.fromEntries(Object.entries(params).map(([k, v]) => [k, { type: "string", example: v }])),
+      steps: steps.data,
+      recorded: { at: new Date().toISOString(), session: extensionCtx.sessionManager.getSessionId() },
+      writesTracked: true,
+    };
+    const roots = recipeRoots(extensionCtx.cwd);
+    const notes = specificNote(recipe.steps);
+    const saved = await confirmAndSave(extensionCtx, args.project === true ? roots.project : roots.user, recipe, `Save recipe "${args.name}"?`, notes);
+    if (!saved.success) return saved;
+    const r = saved.data.recipe;
+    return ok({
+      text: `Saved recipe ${r.name} v${r.version} (${r.steps.length} steps) to ${saved.data.path}${fragileNote(r)}${leftOutNote(task)}${notes === "" ? "" : `\n${notes.trimEnd()}`}`,
+      details: { name: r.name, version: r.version, path: saved.data.path, steps: r.steps.length },
+    });
+  },
+});

package/src/recipes/store.ts

@@ -0,0 +1,103 @@
+import { copyFile, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, resolve, sep } from "node:path";
+import { agentDir } from "../profile/paths";
+import { type Result, err, ok } from "../util/result";
+import { type LastRun, RECIPE_SITE, type Recipe, parseRecipe, stringifyRecipe } from "./recipe";
+
+export type StoredRecipe = { readonly recipe: Recipe; readonly path: string; readonly root: string };
+
+export const recipeRoots = (cwd: string): { readonly project: string; readonly user: string } => ({
+  project: join(cwd, ".pi", "browser-recipes"),
+  user: join(agentDir(), "browser-recipes"),
+});
+
+const readStored = async (root: string, path: string): Promise<Result<StoredRecipe, string>> => {
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch {
+    return err(`no recipe file at ${path}`);
+  }
+  const parsed = parseRecipe(text);
+  if (!parsed.success) return err(`${path}: ${parsed.error}`);
+  return ok({ recipe: parsed.data, path, root });
+};
+
+const filesUnder = async (root: string): Promise<ReadonlyArray<string>> => {
+  const sites = await readdir(root).catch(() => []);
+  const out: string[] = [];
+  for (const site of sites) {
+    const names = await readdir(join(root, site)).catch(() => []);
+    for (const n of names) if (n.endsWith(".yaml")) out.push(join(root, site, n));
+  }
+  return out;
+};
+
+// Project recipes shadow user recipes of the same name.
+export const listRecipes = async (cwd: string): Promise<ReadonlyArray<StoredRecipe>> => {
+  const { project, user } = recipeRoots(cwd);
+  const seen = new Set<string>();
+  const out: StoredRecipe[] = [];
+  for (const root of [project, user]) {
+    for (const path of await filesUnder(root)) {
+      const stored = await readStored(root, path);
+      if (!stored.success || seen.has(stored.data.recipe.name)) continue;
+      seen.add(stored.data.recipe.name);
+      out.push(stored.data);
+    }
+  }
+  return out;
+};
+
+export const findRecipe = async (cwd: string, name: string): Promise<Result<StoredRecipe, string>> => {
+  const { project, user } = recipeRoots(cwd);
+  for (const root of [project, user]) {
+    for (const path of await filesUnder(root)) {
+      if (!path.endsWith(`/${name}.yaml`)) continue;
+      return readStored(root, path);
+    }
+  }
+  return err(`no recipe named "${name}"; call browser_run_recipe with no name to list saved recipes`);
+};
+
+const writeAtomic = async (path: string, text: string): Promise<void> => {
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, text, "utf8");
+    await rename(tmp, path);
+  } catch (e) {
+    await unlink(tmp).catch(() => undefined);
+    throw e;
+  }
+};
+
+// A save over an existing recipe keeps the old file under .history and bumps the version (R5).
+export const saveRecipe = async (root: string, recipe: Recipe): Promise<Result<StoredRecipe, string>> => {
+  const dir = join(root, recipe.site);
+  if (!RECIPE_SITE.test(recipe.site) || !resolve(dir).startsWith(resolve(root) + sep)) {
+    return err(`refusing to save recipe ${recipe.name}: site "${recipe.site}" is not a host name`);
+  }
+  const path = join(dir, `${recipe.name}.yaml`);
+  try {
+    await mkdir(dir, { recursive: true });
+    const existing = await readStored(root, path);
+    let version = recipe.version;
+    if (existing.success) {
+      const history = join(dir, ".history");
+      await mkdir(history, { recursive: true });
+      await copyFile(path, join(history, `${recipe.name}.v${existing.data.recipe.version}.yaml`));
+      version = existing.data.recipe.version + 1;
+    }
+    const saved: Recipe = { ...recipe, version };
+    await writeAtomic(path, stringifyRecipe(saved));
+    return ok({ recipe: saved, path, root });
+  } catch (e) {
+    return err(`could not save recipe to ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+};
+
+// Records the outcome of a replay without bumping the version; a run is not a new recipe.
+export const recordRun = async (stored: StoredRecipe, lastRun: LastRun): Promise<void> => {
+  await writeAtomic(stored.path, stringifyRecipe({ ...stored.recipe, lastRun })).catch(() => undefined);
+};

package/src/recipes/trust.ts

@@ -0,0 +1,172 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { agentDir } from "../profile/paths";
+import { isRecord } from "../util/guards";
+import { type Result, err, ok } from "../util/result";
+import { describeStep, fill, fillArgs, hostOf } from "./replay";
+import type { Recipe } from "./recipe";
+import { type StoredRecipe, recipeRoots } from "./store";
+
+// A project recipe's absolute path -> sha256 of the file bytes the user approved, and `${path}#params` -> sha256 of the
+// param-decided values (see paramScope) the user last approved for it.
+type TrustStore = Readonly<Record<string, string>>;
+
+const trustFile = (): string => join(agentDir(), "browser-harness", "trusted-recipes.json");
+
+const sha256 = (data: Uint8Array | string): string => createHash("sha256").update(data).digest("hex");
+
+const paramsKey = (path: string): string => `${resolve(path)}#params`;
+
+const readStore = async (): Promise<TrustStore> => {
+  try {
+    const raw: unknown = JSON.parse(await readFile(trustFile(), "utf8"));
+    if (!isRecord(raw)) return {};
+    return Object.fromEntries(Object.entries(raw).flatMap(([k, v]) => (typeof v === "string" ? [[k, v]] : [])));
+  } catch {
+    return {};
+  }
+};
+
+export const isTrusted = async (path: string, bytes: Uint8Array, scope?: string): Promise<boolean> => {
+  const store = await readStore();
+  return store[resolve(path)] === sha256(bytes) && (scope === undefined || store[paramsKey(path)] === sha256(scope));
+};
+
+export const trust = async (path: string, bytes: Uint8Array, scope?: string): Promise<void> => {
+  const file = trustFile();
+  const next: TrustStore = {
+    ...(await readStore()),
+    [resolve(path)]: sha256(bytes),
+    ...(scope !== undefined ? { [paramsKey(path)]: sha256(scope) } : {}),
+  };
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, file);
+  } catch (e) {
+    await unlink(tmp).catch(() => undefined);
+    throw e;
+  }
+};
+
+const isProject = (stored: StoredRecipe, cwd: string): boolean => stored.root === recipeRoots(cwd).project;
+
+// The harness's own writes to a project recipe (a save, a repair, last_run) never make the user approve it again.
+export const trustWritten = async (stored: StoredRecipe, cwd: string): Promise<void> => {
+  if (!isProject(stored, cwd)) return;
+  const bytes = await readFile(stored.path).catch(() => undefined);
+  if (bytes !== undefined) await trust(stored.path, bytes).catch(() => undefined);
+};
+
+// A URL template whose text before its first {{param}} already ends the origin cannot be sent elsewhere by a param.
+const FIXED_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*[/?#]/i;
+const steersOrigin = (template: string): boolean => {
+  const at = template.indexOf("{{");
+  return at !== -1 && !FIXED_ORIGIN.test(template.slice(0, at));
+};
+
+// An opaque origin ("null", as for file: URLs) names nothing, so the whole URL stands in for it.
+const originOf = (url: string): string => {
+  try {
+    const origin = new URL(url).origin;
+    return origin === "null" ? url : origin;
+  } catch {
+    return url;
+  }
+};
+
+// What this run's params decide outside the page: each origin a param can change and each local path a param fills.
+// Undefined when params decide none of it, so such a recipe is approved once per file, whatever the values.
+const paramScope = (recipe: Recipe, params: Readonly<Record<string, string>>): string | undefined => {
+  const parts = recipe.steps.flatMap((s) => [
+    ...[s.args["url"], s.expect?.url].flatMap((u) => (typeof u === "string" && steersOrigin(u) ? [originOf(fill(u, params))] : [])),
+    ...[s.args["filePath"], s.args["downloadPath"]].flatMap((p) => (typeof p === "string" && p.includes("{{") ? [fill(p, params)] : [])),
+  ]);
+  return parts.length > 0 ? JSON.stringify(parts) : undefined;
+};
+
+const ESCAPES: Readonly<Record<string, string>> = { "\n": "\\n", "\r": "\\r", "\t": "\\t" };
+// A param value is the caller's text: a raw newline or terminal escape in it could forge lines of the dialog.
+// eslint-disable-next-line no-control-regex -- matching control characters is the point
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+export const printable = (s: string): string => s.replace(CONTROL, (c) => ESCAPES[c] ?? `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+
+const shownUrl = (url: string): string => {
+  const origin = originOf(url);
+  return origin === url ? url : `${url} (origin ${origin})`;
+};
+
+// What a project recipe can do outside the page: where it goes, which local files it sends, what it downloads. Shown
+// with this run's params filled in, since a {{placeholder}} hides exactly what the user is approving.
+// Hosts on this machine or its private network: a read sent there can reach services the internet cannot.
+const PRIVATE_V4 = /^(?:127\.|10\.|192\.168\.|169\.254\.|0\.|172\.(?:1[6-9]|2\d|3[01])\.)/;
+export const isPrivateHost = (host: string): boolean => {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return (
+    h === "localhost" ||
+    h.endsWith(".localhost") ||
+    h.endsWith(".local") ||
+    h.endsWith(".internal") ||
+    PRIVATE_V4.test(h) ||
+    h === "::1" ||
+    h === "::" ||
+    /^f[cd][0-9a-f]{2}:/.test(h) ||
+    h.startsWith("fe80:") ||
+    h.startsWith("::ffff:")
+  );
+};
+
+const READ_VERBS: ReadonlyMap<string, string> = new Map([
+  ["http_get", "fetch outside the browser"],
+  ["read_page", "read in a tab of its own"],
+]);
+
+const approvalBody = (stored: StoredRecipe, params: Readonly<Record<string, string>>, scoped: boolean): string => {
+  const { recipe } = stored;
+  const lines = recipe.steps.flatMap((s, i) => {
+    const at = `  step ${i + 1}:`;
+    const args = fillArgs(s.args, params);
+    const url = args["url"];
+    const file = args["filePath"];
+    const lands = s.expect?.url !== undefined ? fill(s.expect.url, params) : undefined;
+    if (s.action === "navigate" && typeof url === "string") return [`${at} navigate to ${shownUrl(url)}`];
+    if (s.action === "new_tab" && typeof url === "string") return [`${at} open a new tab at ${shownUrl(url)}`];
+    const verb = READ_VERBS.get(s.action);
+    if (verb !== undefined && typeof url === "string") {
+      const host = hostOf(url);
+      const local = host !== undefined && isPrivateHost(host) ? " (a local or private-network address)" : "";
+      return [`${at} ${verb} ${shownUrl(url)}${local}`];
+    }
+    if (s.action === "upload_file" && typeof file === "string") return [`${at} upload ${file}`];
+    if (s.action === "download") return [`${at} ${describeStep(s)}${typeof args["downloadPath"] === "string" ? ` to ${args["downloadPath"]}` : ""}`];
+    if (lands !== undefined && hostOf(lands) !== recipe.site) return [`${at} ${describeStep(s)}, landing on ${shownUrl(lands)}`];
+    return [];
+  });
+  const note = scoped ? ["", "Approval covers these values; a run with other values asks again."] : [];
+  return [`File: ${stored.path}`, `Site: ${recipe.site}`, ...(lines.length > 0 ? ["", ...lines] : []), ...note, "", `${recipe.steps.length} steps`]
+    .map(printable)
+    .join("\n");
+};
+
+// A recipe from the project's .pi/browser-recipes was written by whoever wrote the repo and replays with no model in
+// the loop, so its exact bytes, and the values its params give to URLs' origins and file paths, must be approved
+// before it runs. Recipes under the agent dir are the user's own.
+export const approveProjectRecipe = async (
+  ctx: ExtensionContext,
+  stored: StoredRecipe,
+  params: Readonly<Record<string, string>>,
+): Promise<Result<void, string>> => {
+  if (!isProject(stored, ctx.cwd)) return ok(undefined);
+  const name = stored.recipe.name;
+  const bytes = await readFile(stored.path).catch(() => undefined);
+  if (bytes === undefined) return err(`recipe ${name} could not be read at ${stored.path}`);
+  const scope = paramScope(stored.recipe, params);
+  if (await isTrusted(stored.path, bytes, scope)) return ok(undefined);
+  if (!ctx.hasUI) return err(`recipe ${name} is a project recipe that has not been approved; run it once in an interactive session to approve it`);
+  if (!(await ctx.ui.confirm(`Run project recipe ${name}?`, approvalBody(stored, params, scope !== undefined)))) return err(`recipe ${name} not run: not approved`);
+  await trust(stored.path, bytes, scope);
+  return ok(undefined);
+};

package/src/registry.ts

@@ -24,6 +24,8 @@ import { executeJsTool, runScriptTool } from "./domains/js";
 import { setupTool } from "./domains/setup";
 import { webSearchTool } from "./domains/search/web-search";
 import { readPageTool } from "./domains/readpage/read-page";
+import { saveRecipeTool } from "./recipes/save-tool";
+import { runRecipeTool } from "./recipes/run-tool";
 
 export const ALL_TOOLS: ReadonlyArray<BrowserTool> = [
   setupTool,
@@ -68,6 +70,8 @@ export const ALL_TOOLS: ReadonlyArray<BrowserTool> = [
   runScriptTool,
   webSearchTool,
   readPageTool,
+  saveRecipeTool,
+  runRecipeTool,
 ];
 
 export type RegistryError = {

package/src/util/js-source.ts

@@ -0,0 +1,28 @@
+import { parse } from "acorn";
+import { isRecord } from "./guards";
+
+const FUNCTION_NODES: ReadonlySet<string> = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
+
+// True when a return statement sits in the program body itself, not inside a function it defines.
+const hasTopLevelReturn = (node: unknown): boolean => {
+  if (Array.isArray(node)) return node.some(hasTopLevelReturn);
+  if (!isRecord(node) || typeof node["type"] !== "string") return false;
+  if (node["type"] === "ReturnStatement") return true;
+  if (FUNCTION_NODES.has(node["type"])) return false;
+  return Object.values(node).some((v) => typeof v === "object" && v !== null && hasTopLevelReturn(v));
+};
+
+// The source Runtime.evaluate should run for what the model wrote. A top-level `return`, anywhere in the body,
+// makes it a function body, so it runs inside an async function. The call is awaited in the source itself: in REPL
+// mode awaitPromise waits only for the REPL's own completion, so a returned promise would come back unresolved
+// (serialized as {}). Anything else, including source that does not parse, is sent as written, so the page reports
+// its own error.
+export const pageExpression = (src: string): string => {
+  let program: unknown;
+  try {
+    program = parse(src, { ecmaVersion: "latest", allowReturnOutsideFunction: true, allowAwaitOutsideFunction: true });
+  } catch {
+    return src;
+  }
+  return isRecord(program) && hasTopLevelReturn(program["body"]) ? `await (async () => {\n${src}\n})()` : src;
+};

package/src/util/tool.ts

@@ -12,7 +12,7 @@ import type {
 import { type Component, Text } from "@mariozechner/pi-tui";
 import { daemonSocketMayExist } from "../daemon/spawn";
 import type { BrowserClient } from "../client";
-import { type Result, err } from "./result";
+import { type Result, err, ok } from "./result";
 
 // Details are stored by pi as JSON and handed back on replay, so a renderer only ever reads them.
 export type DeepReadonly<T> = T extends ReadonlyArray<infer U>
@@ -141,6 +141,23 @@ const detailsGuard = <D extends TSchema>(schema: D | undefined): ((v: unknown) =
 const notConnected = (message: string): Result<never, ToolErr> =>
   err({ kind: "not_connected", message });
 
+export type CallOutcome = { readonly ok: boolean; readonly error?: string };
+
+// Watches a tool call from outside the tool (the recipe journal). Returns the function that receives the call's
+// outcome and may return a note for the end of a successful result, or undefined to skip the call. Errors it throws
+// are swallowed by runHandler.
+export type CallObserver = (call: {
+  readonly name: string;
+  readonly concurrency: ToolConcurrency;
+  readonly args: unknown;
+  readonly client: BrowserClient;
+}) => Promise<((outcome: CallOutcome) => Promise<string | undefined>) | undefined>;
+
+let callObserver: CallObserver | undefined;
+export const setCallObserver = (o: CallObserver | undefined): void => {
+  callObserver = o;
+};
+
 const runHandler = async <S extends TSchema, D extends TSchema>(
   def: BrowserToolDefinition<S, D>,
   client: BrowserClient,
@@ -164,16 +181,21 @@ const runHandler = async <S extends TSchema, D extends TSchema>(
       return err({ kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" });
     }
   }
+  const finish = await callObserver?.({ name: def.name, concurrency: def.concurrency, args, client }).catch(() => undefined);
   try {
-    return await def.handler(args, {
+    const result = await def.handler(args, {
       client,
       signal,
       onUpdate: (u) => onUpdate?.(okResult(u)),
       extensionCtx,
     });
+    const note = await finish?.(result.success ? { ok: true } : { ok: false, error: result.error.message }).catch(() => undefined);
+    return result.success && note !== undefined ? ok({ ...result.data, text: `${result.data.text}\n\n${note}` }) : result;
   } catch (e) {
     // A throw is a bug in the handler, not a tool outcome; it still has to reach the model as an error.
-    return err({ kind: "internal", message: e instanceof Error ? e.message : String(e) });
+    const message = e instanceof Error ? e.message : String(e);
+    await finish?.({ ok: false, error: message }).catch(() => undefined);
+    return err({ kind: "internal", message });
   } finally {
     release?.();
   }