@itmetsam/samurai-framework 0.22.3 → 0.22.5

package/dist/agent/snapshot-script.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Function declaration, called as `(options)` with `{ maxChars, secretFields }`. Writes the page as text (see
+ * `Snapshotter.take`) and remembers the elements it numbered, so `RESOLVE_SCRIPT` can find them again. Secret
+ * values are replaced here, in the page: they never reach the framework.
+ */
+export declare const SNAPSHOT_SCRIPT: string;
+/**
+ * Function declaration, called as `({ ref, focused, secretFields })` with the number of a reference, or `focused`
+ * for the element that has focus. Answers `{ status: "ok", target, candidates, secret, dotted, role, name }`, or a status
+ * that says why the reference does not resolve: `none` (no snapshot in this document), `unknown`, `older` (it was
+ * in an earlier snapshot), `gone` (removed since), `nofocus`.
+ */
+export declare const RESOLVE_SCRIPT: string;
+/**
+ * Function declaration, called as `({ secretFields })`. Answers the first of the caller's selectors that matches a
+ * visible field showing a value in plain text (a password input draws dots and does not count), else "".
+ */
+export declare const SECRET_ON_SCREEN_SCRIPT: string;

package/dist/agent/snapshot-script.js

@@ -0,0 +1,163 @@
+import { ACCESSIBLE_NAME_JS } from "../locator/accessible-name.js";
+import { CANDIDATES_JS } from "../recorder/candidates.js";
+/** Name of the page-global that holds the references of the latest snapshot */
+const STORE_KEY = "samurai.agent.refs";
+/**
+ * Page-side: `isSecret(el, selectors)` is true for a field whose value must never leave the page: a password
+ * input, a one-time code or card field (by `autocomplete`), or an element matching one of the caller's selectors.
+ */
+const SECRET_JS = String.raw `
+  const isSecret = (el, selectors) => {
+    if (el.localName === "input" && (el.getAttribute("type") || "").toLowerCase() === "password") return true;
+    if (/password|one-time-code|cc-/i.test(el.getAttribute("autocomplete") || "")) return true;
+    for (const selector of selectors) {
+      try { if (el.matches(selector)) return true; } catch (error) { /* a bad selector hides nothing */ }
+    }
+    return false;
+  };`;
+/**
+ * Function declaration, called as `(options)` with `{ maxChars, secretFields }`. Writes the page as text (see
+ * `Snapshotter.take`) and remembers the elements it numbered, so `RESOLVE_SCRIPT` can find them again. Secret
+ * values are replaced here, in the page: they never reach the framework.
+ */
+export const SNAPSHOT_SCRIPT = String.raw `(options) => {
+  ${ACCESSIBLE_NAME_JS}
+  ${SECRET_JS}
+  const KEY = Symbol.for("${STORE_KEY}");
+  const store = window[KEY] || (window[KEY] = { next: 1, ids: new WeakMap(), map: new Map() });
+  store.map = new Map();
+  const SHOWN = new Set(["button", "link", "textbox", "searchbox", "combobox", "listbox", "checkbox", "radio", "switch",
+    "slider", "spinbutton", "tab", "menuitem", "menuitemcheckbox", "menuitemradio", "option", "treeitem",
+    "heading", "img", "navigation", "main", "banner", "contentinfo", "region", "form", "dialog", "alertdialog", "alert",
+    "status", "table", "list", "listitem", "row", "cell", "columnheader", "rowheader", "gridcell", "article", "tablist",
+    "menu", "toolbar", "progressbar"]);
+  // Their text is their name: nothing inside is listed again
+  const LEAF = new Set(["button", "link", "heading", "checkbox", "radio", "option", "switch", "tab", "menuitem",
+    "menuitemcheckbox", "menuitemradio", "treeitem"]);
+  const SKIPPED = new Set(["script", "style", "noscript", "template", "head", "svg"]);
+  const cut = (text, max) => (text.length > max ? text.slice(0, max - 1) + "…" : text);
+  const quote = (text) => '"' + text.replace(/"/g, '\\"') + '"';
+  const lines = [];
+  let size = 0;
+  let omitted = 0;
+  const add = (line) => {
+    if (size + line.length + 1 > options.maxChars) { omitted++; return false; }
+    lines.push(line);
+    size += line.length + 1;
+    return true;
+  };
+  const refOf = (el) => {
+    let id = store.ids.get(el);
+    if (id === undefined) { id = store.next++; store.ids.set(el, id); }
+    return id;
+  };
+  const checkedOf = (el, role) => {
+    if (!["checkbox", "radio", "switch", "menuitemcheckbox"].includes(role)) return "";
+    const aria = el.getAttribute("aria-checked");
+    if (aria === "mixed" || el.indeterminate) return " mixed";
+    return (el.checked === true || aria === "true") ? " checked" : " unchecked";
+  };
+  const valueOf = (el, role) => {
+    if (!["textbox", "searchbox", "spinbutton", "combobox", "slider", "listbox"].includes(role)) return "";
+    let value = "";
+    if (el.localName === "select") value = Array.from(el.selectedOptions).map((o) => o.label || o.textContent).join(", ");
+    else if (typeof el.value === "string") value = el.value;
+    if (value === "") return "";
+    return " value=" + quote(isSecret(el, options.secretFields) ? "••••" : cut(squash(value), 80));
+  };
+  const statesOf = (el, role) => {
+    let out = checkedOf(el, role);
+    if (el.disabled === true || el.getAttribute("aria-disabled") === "true") out += " disabled";
+    if (el.getAttribute("aria-expanded") === "true") out += " expanded";
+    if (el.getAttribute("aria-expanded") === "false") out += " collapsed";
+    if (el.selected === true || el.getAttribute("aria-selected") === "true") out += " selected";
+    if (el.getAttribute("aria-pressed") === "true") out += " pressed";
+    if (el.required === true || el.getAttribute("aria-required") === "true") out += " required";
+    if (el.readOnly === true) out += " readonly";
+    if (el === document.activeElement) out += " focused";
+    if (role === "heading") out += " level=" + (Number(el.getAttribute("aria-level")) || Number(el.localName.slice(1)) || 1);
+    return out;
+  };
+  const ownText = (el) => squash(Array.from(el.childNodes).filter((n) => n.nodeType === 3).map((n) => n.nodeValue).join(" "));
+  const visit = (el, depth) => {
+    if (el.nodeType !== 1 || SKIPPED.has(el.localName)) return;
+    if (el.getAttribute("aria-hidden") === "true" || el.hidden) return;
+    const style = getComputedStyle(el);
+    if (style.display === "none") return;
+    const visible = style.visibility !== "hidden" && style.visibility !== "collapse";
+    const role = roleOf(el);
+    const clickable = el.hasAttribute("onclick") || (el.hasAttribute("tabindex") && Number(el.getAttribute("tabindex")) >= 0);
+    let indent = depth;
+    if (visible) {
+      let line = "";
+      if (SHOWN.has(role)) {
+        const name = cut(accessibleName(el) || ownText(el), 100);
+        line = role + (name ? " " + quote(name) : "") + valueOf(el, role) + statesOf(el, role);
+      } else if (clickable) {
+        line = "clickable " + quote(cut(accessibleName(el) || squash(el.textContent || ""), 100)) + statesOf(el, role);
+      } else if (!["input", "select", "textarea"].includes(el.localName)) {
+        const text = ownText(el);
+        if (text) line = "text " + quote(cut(text, 160));
+      }
+      if (line) {
+        const id = refOf(el);
+        if (add("  ".repeat(depth) + "[e" + id + "] " + line)) store.map.set(id, el);
+        indent = depth + 1;
+      }
+    }
+    if (LEAF.has(role)) return;
+    for (const child of el.children) visit(child, indent);
+  };
+  if (document.body) visit(document.body, 0);
+  const text = lines.join("\n");
+  return { text, omitted, count: store.map.size, url: location.href, title: document.title };
+}`;
+/**
+ * Function declaration, called as `({ ref, focused, secretFields })` with the number of a reference, or `focused`
+ * for the element that has focus. Answers `{ status: "ok", target, candidates, secret, dotted, role, name }`, or a status
+ * that says why the reference does not resolve: `none` (no snapshot in this document), `unknown`, `older` (it was
+ * in an earlier snapshot), `gone` (removed since), `nofocus`.
+ */
+export const RESOLVE_SCRIPT = String.raw `(options) => {
+  const KEY = Symbol.for("${STORE_KEY}");
+  const store = window[KEY];
+  const accessible = (() => { ${ACCESSIBLE_NAME_JS}; return { accessibleName, roleOf }; })();
+  const candidates = (() => { ${CANDIDATES_JS}; return { candidatesOf }; })();
+  ${SECRET_JS}
+  let el;
+  if (options.focused) {
+    el = document.activeElement;
+    if (!el || el === document.body || el === document.documentElement) return { status: "nofocus" };
+  } else {
+    if (!store) return { status: "none" };
+    el = store.map.get(options.ref);
+    if (!el) return { status: options.ref >= store.next ? "unknown" : "older" };
+    if (!el.isConnected) return { status: "gone" };
+  }
+  return {
+    status: "ok",
+    target: el,
+    candidates: candidates.candidatesOf(el),
+    secret: isSecret(el, options.secretFields),
+    dotted: el.localName === "input" && (el.getAttribute("type") || "").toLowerCase() === "password",
+    role: accessible.roleOf(el),
+    name: accessible.accessibleName(el),
+  };
+}`;
+/**
+ * Function declaration, called as `({ secretFields })`. Answers the first of the caller's selectors that matches a
+ * visible field showing a value in plain text (a password input draws dots and does not count), else "".
+ */
+export const SECRET_ON_SCREEN_SCRIPT = String.raw `(options) => {
+  for (const selector of options.secretFields) {
+    let found = [];
+    try { found = Array.from(document.querySelectorAll(selector)); } catch (error) { continue; }
+    for (const el of found) {
+      if (el.getClientRects().length === 0 || getComputedStyle(el).visibility === "hidden") continue;
+      if (el.localName === "input" && (el.getAttribute("type") || "").toLowerCase() === "password") continue;
+      const shown = typeof el.value === "string" ? el.value : (el.textContent || "");
+      if (shown.trim() !== "") return selector;
+    }
+  }
+  return "";
+}`;

package/dist/agent/snapshot.d.ts

@@ -0,0 +1,54 @@
+import type Page from "../browser/page.js";
+import type Locator from "../locator/locator.js";
+import type { LocatorSpec } from "../steps/model.js";
+/** A reference does not point at an element of the latest snapshot; the text says why and what to do */
+export declare class SnapshotRefError extends Error {
+    constructor(message: string);
+}
+/** The page as text for the model */
+export interface Snapshot {
+    /** Header, then one line per element: `[e12] button "Save" disabled` */
+    text: string;
+    /** Elements that got a reference */
+    elements: number;
+    /** Lines that did not fit the size cap */
+    omitted: number;
+}
+/** An element of the latest snapshot, ready to act on */
+export interface Located {
+    ref: string;
+    /** The locators the typed step is written with */
+    spec: LocatorSpec;
+    locator: Locator;
+    /** `textbox "Email"`, for messages */
+    description: string;
+    /** A password or a field the caller marked secret: its value is never shown or typed by the model */
+    secret: boolean;
+    /** The page itself draws the value as dots (a password input), so even a screenshot does not show it */
+    dotted: boolean;
+}
+export interface SnapshotOptions {
+    /** CSS selectors of fields to treat as secret, besides password inputs. @default none */
+    secretFields?: readonly string[];
+    /** The size cap of the text in characters. @default 16000 */
+    maxChars?: number;
+}
+/**
+ * Takes snapshots of a page and resolves their references. A reference (`e12`) stays the same for an element
+ * while it lives and is valid until the next snapshot; after that, only the elements the new snapshot lists
+ * resolve. A navigation to a new document starts over.
+ */
+export declare class Snapshotter {
+    private readonly page;
+    private readonly secretFields;
+    private readonly maxChars;
+    constructor(page: Page, options?: SnapshotOptions);
+    take(): Promise<Snapshot>;
+    /** The first caller-marked selector that matches a visible field showing its value in plain text, else undefined */
+    secretOnScreen(): Promise<string | undefined>;
+    /** The element behind `ref`, with the best locator that matches only it. Throws `SnapshotRefError` */
+    locate(ref: string): Promise<Located>;
+    /** The element that has focus now (what `useSecret` fills). Throws `SnapshotRefError` when nothing is focused */
+    locateFocused(): Promise<Located>;
+    private locateWith;
+}

package/dist/agent/snapshot.js

@@ -0,0 +1,95 @@
+import { rankLocator } from "../recorder/ranking.js";
+import { locatorFromSpec } from "../steps/build.js";
+import { RESOLVE_SCRIPT, SECRET_ON_SCREEN_SCRIPT, SNAPSHOT_SCRIPT, } from "./snapshot-script.js";
+/** A reference does not point at an element of the latest snapshot; the text says why and what to do */
+export class SnapshotRefError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SnapshotRefError";
+    }
+}
+/** The size cap when none is given */
+const DEFAULT_MAX_CHARS = 16_000;
+/**
+ * Takes snapshots of a page and resolves their references. A reference (`e12`) stays the same for an element
+ * while it lives and is valid until the next snapshot; after that, only the elements the new snapshot lists
+ * resolve. A navigation to a new document starts over.
+ */
+export class Snapshotter {
+    constructor(page, options = {}) {
+        this.page = page;
+        this.secretFields = options.secretFields ?? [];
+        this.maxChars = options.maxChars ?? DEFAULT_MAX_CHARS;
+    }
+    async take() {
+        const found = await this.page.evaluate(SNAPSHOT_SCRIPT, {
+            maxChars: this.maxChars,
+            secretFields: this.secretFields,
+        });
+        const header = `url: ${found.url}\ntitle: ${found.title}\n`;
+        const marker = found.omitted > 0
+            ? `\n… [snapshot truncated: ${found.omitted} more elements not shown]`
+            : "";
+        return {
+            text: header + found.text + marker,
+            elements: found.count,
+            omitted: found.omitted,
+        };
+    }
+    /** The first caller-marked selector that matches a visible field showing its value in plain text, else undefined */
+    async secretOnScreen() {
+        if (this.secretFields.length === 0)
+            return undefined;
+        const found = await this.page.evaluate(SECRET_ON_SCREEN_SCRIPT, { secretFields: this.secretFields });
+        return found === "" ? undefined : found;
+    }
+    /** The element behind `ref`, with the best locator that matches only it. Throws `SnapshotRefError` */
+    async locate(ref) {
+        const match = /^e(\d+)$/.exec(ref.trim());
+        if (!match)
+            throw new SnapshotRefError(`"${ref}" is not a snapshot reference; references look like e12 and come from a snapshot`);
+        const label = `e${Number(match[1])}`;
+        return this.locateWith(label, { ref: Number(match[1]) });
+    }
+    /** The element that has focus now (what `useSecret` fills). Throws `SnapshotRefError` when nothing is focused */
+    async locateFocused() {
+        return this.locateWith("the focused field", { focused: true });
+    }
+    async locateWith(label, which) {
+        const found = await this.page.evaluate(RESOLVE_SCRIPT, {
+            ...which,
+            secretFields: this.secretFields,
+        });
+        if (found.status !== "ok")
+            throw new SnapshotRefError(refProblem(label, found.status));
+        const spec = await rankLocator(this.page, found.target, found.candidates);
+        if (!spec)
+            throw new SnapshotRefError(`${label} has no locator that matches only that element; take a new snapshot`);
+        return {
+            ref: label,
+            spec,
+            locator: locatorFromSpec(this.page, spec),
+            description: describe(found.role, found.name),
+            secret: found.secret,
+            dotted: found.dotted,
+        };
+    }
+}
+function describe(role, name) {
+    const kind = role === "" ? "element" : role;
+    return name === "" ? kind : `${kind} "${name}"`;
+}
+function refProblem(label, status) {
+    switch (status) {
+        case "none":
+            return `${label} cannot be used: no snapshot has been taken of this page yet (the page is new or has reloaded); take a snapshot first`;
+        case "unknown":
+            return `${label} does not exist; use a reference from the latest snapshot`;
+        case "older":
+            return `${label} was in an earlier snapshot but is not in the latest one: the page changed; take a new snapshot`;
+        case "gone":
+            return `${label} is no longer on the page (it was removed after the snapshot); take a new snapshot`;
+        case "nofocus":
+            return "no field has focus; click the field first";
+    }
+}

package/dist/agent/take-over.d.ts

@@ -0,0 +1,19 @@
+import type Page from "../browser/page.js";
+import type { StepRecorder } from "./recording.js";
+import type { TakeOverHooks } from "./session.js";
+import type { Snapshotter } from "./snapshot.js";
+export interface PersonRecording extends TakeOverHooks {
+    /** Ends a recording that is still open (the run ended while the person had the browser) */
+    dispose(): Promise<void>;
+}
+/**
+ * While the person drives, the framework's own recorder watches the same page and writes what they do into the
+ * spec after the agent's steps, so nothing they record is lost. On hand back the recorder stops, the agent's
+ * recording carries on after the last step, and the agent is told what happened and shown the page as it is.
+ */
+export declare function personRecording(input: {
+    page: Page;
+    steps: StepRecorder;
+    snapshots: Snapshotter;
+    baseURL?: string;
+}): PersonRecording;

package/dist/agent/take-over.js

@@ -0,0 +1,49 @@
+import { maskText } from "../config/mask.js";
+import { stepToSource } from "../steps/emit.js";
+/**
+ * While the person drives, the framework's own recorder watches the same page and writes what they do into the
+ * spec after the agent's steps, so nothing they record is lost. On hand back the recorder stops, the agent's
+ * recording carries on after the last step, and the agent is told what happened and shown the page as it is.
+ */
+export function personRecording(input) {
+    const { page, steps, snapshots } = input;
+    let recorder;
+    const written = new Map();
+    const close = async () => {
+        const open = recorder;
+        recorder = undefined;
+        if (!open)
+            return;
+        await open.stop().catch(() => undefined);
+        steps.rebase();
+    };
+    return {
+        async begin() {
+            written.clear();
+            recorder = await page.record({
+                at: steps.count,
+                initialGoto: false,
+                ...(input.baseURL !== undefined && { baseURL: input.baseURL }),
+                onEvent: (event) => {
+                    steps.external(event);
+                    if (event.op === "remove")
+                        written.delete(event.index);
+                    else
+                        written.set(event.index, stepToSource(event.step));
+                },
+            });
+        },
+        async end() {
+            await close();
+            const mine = [...written.entries()]
+                .sort(([a], [b]) => a - b)
+                .map(([, code]) => code);
+            const did = mine.length > 0
+                ? `They added ${mine.length} ${mine.length === 1 ? "step" : "steps"} to the test: ${mine.join(" ")}`
+                : "They added no steps";
+            const page_ = maskText((await snapshots.take()).text);
+            return `The person used the browser while you were stopped. ${did}. The page may have changed; this is the page now:\n\n${page_}\n\nYour last call was not run. Call it again only if it is still needed.`;
+        },
+        dispose: close,
+    };
+}

package/dist/agent/tools/act.d.ts

@@ -0,0 +1,2 @@
+import { type ToolContext } from "./context.js";
+export declare const act: (context: ToolContext) => import("./context.js").AgentTool;

package/dist/agent/tools/act.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { writtenText } from "../recording.js";
+import { leftAllowedOrigins } from "./origin-guard.js";
+import { defineTool } from "./context.js";
+const KINDS = [
+    "click",
+    "fill",
+    "select",
+    "check",
+    "uncheck",
+    "hover",
+    "dblclick",
+    "clear",
+    "press",
+];
+/** The kinds that need a `value`, and what it is */
+const VALUE_OF = {
+    fill: "the text to type",
+    select: "the option's value or visible text",
+    press: 'the key, for example "Enter" or "Control+A"',
+};
+const PAST = {
+    click: "Clicked",
+    fill: "Filled",
+    select: "Selected an option of",
+    check: "Checked",
+    uncheck: "Unchecked",
+    hover: "Hovered",
+    dblclick: "Double-clicked",
+    clear: "Cleared",
+    press: "Pressed a key on",
+};
+async function perform(kind, value, { locator }, timeout) {
+    const options = { timeout };
+    switch (kind) {
+        case "click":
+            return locator.click(options);
+        case "fill":
+            return locator.fill(value, options);
+        case "select":
+            await locator.selectOption(value, options);
+            return;
+        case "check":
+            return locator.check(options);
+        case "uncheck":
+            return locator.uncheck(options);
+        case "hover":
+            return locator.hover(options);
+        case "dblclick":
+            return locator.dblclick(options);
+        case "clear":
+            return locator.clear(options);
+        case "press":
+            return locator.press(value, options);
+    }
+}
+/** The observation the recorder's normaliser turns into the step for this action */
+function observationFor(kind, value, located) {
+    const { spec: locator, ref: key } = located;
+    switch (kind) {
+        case "click":
+            return { type: "click", key, locator, textEntry: false };
+        case "check":
+        case "uncheck":
+            return {
+                type: "click",
+                key,
+                locator,
+                textEntry: false,
+                checked: kind === "check",
+            };
+        case "fill":
+            return { type: "input", key, locator, value };
+        case "select":
+            return { type: "select", key, locator, option: value };
+        case "press":
+            return { type: "press", key, locator, pressed: value };
+        case "hover":
+        case "dblclick":
+        case "clear":
+            return { type: "action", kind, locator };
+    }
+}
+export const act = defineTool({
+    name: "act",
+    description: "Do one thing to an element of the latest snapshot: click, fill (type text), select (an option of a dropdown), " +
+        "check, uncheck, hover, dblclick, clear or press (a key). Each success is written to the test as a step; " +
+        "a failure writes nothing. Take a new snapshot after the page changes.",
+    inputSchema: z.object({
+        kind: z.enum(KINDS),
+        target: z
+            .string()
+            .describe("A reference from the latest snapshot, for example e12"),
+        value: z
+            .string()
+            .optional()
+            .describe("fill: the text; select: the option; press: the key"),
+    }),
+    async execute({ kind, target, value }, context) {
+        const needs = VALUE_OF[kind];
+        if (needs !== undefined &&
+            (value === undefined || (kind !== "fill" && value === "")))
+            return { ok: false, error: `act(): ${kind} needs a value: ${needs}` };
+        if (needs === undefined && value !== undefined)
+            return { ok: false, error: `act(): ${kind} takes no value` };
+        const located = await context.snapshots.locate(target);
+        if (kind === "fill" && located.secret)
+            return {
+                ok: false,
+                error: `act(): ${located.ref} (${located.description}) holds a secret; focus it with a click and use useSecret, or ask the person`,
+            };
+        const text = value ?? "";
+        const before = await context.page.url();
+        await perform(kind, text, located, context.actionTimeout);
+        const problem = await leftAllowedOrigins(context, before);
+        if (problem)
+            return { ok: false, error: `act(): ${problem}` };
+        const events = context.steps.observe(observationFor(kind, text, located));
+        return {
+            ok: true,
+            message: `${PAST[kind]} ${located.ref} (${located.description}).${writtenText(events)}`,
+        };
+    },
+});

package/dist/agent/tools/ask.d.ts

@@ -0,0 +1 @@
+export declare const ask: (context: import("./context.js").ToolContext) => import("./context.js").AgentTool;

package/dist/agent/tools/ask.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { defineTool } from "./context.js";
+export const ask = defineTool({
+    name: "ask",
+    description: "Ask the person a question and wait for the answer. This is the only way to get what you do not know " +
+        "(a username, which of two options they want, permission). Do not guess; ask.",
+    inputSchema: z.object({
+        question: z.string().min(1),
+        options: z
+            .array(z.string().min(1))
+            .max(8)
+            .optional()
+            .describe("Answers to pick from, when there are a few"),
+    }),
+    async execute({ question, options }, context) {
+        const answer = await context.ask(question, options);
+        return { ok: true, message: `The person answered: ${answer}` };
+    },
+});

package/dist/agent/tools/context.d.ts

@@ -0,0 +1,70 @@
+import type { z } from "zod";
+import type Page from "../../browser/page.js";
+import type { Snapshotter } from "../snapshot.js";
+import type { AgentEvent } from "../types.js";
+import type { OriginPolicy } from "./origins.js";
+import type { Observation, RecorderEvent } from "../../recorder/normalise.js";
+/** Secrets the agent may use: it knows the names; values are read here and go no further than the page */
+interface SecretAccess {
+    readonly allowed: readonly string[];
+    /** The value of a secret in the run's environment; undefined when it has none */
+    get(name: string): string | undefined;
+}
+/** What the shared tools need from the run's record of what was done: a spec writer, or the planner's tally */
+export interface ToolSink {
+    /** Takes note of one thing done on the page and returns the events it wrote (none when nothing is written) */
+    observe(observation: Observation): RecorderEvent[];
+    /** Takes the last `count` steps back and returns how many went */
+    undo(count: number): number;
+}
+/** What the tools of one run share */
+export interface ToolContext {
+    page: Page;
+    snapshots: Snapshotter;
+    steps: ToolSink;
+    origins: OriginPolicy;
+    secrets: SecretAccess;
+    /** The model takes images, so `screenshot` works */
+    vision: boolean;
+    /** Time (ms) an action or an assertion waits for the element. @default 5000 */
+    actionTimeout: number;
+    /** Asks the person and waits for the answer */
+    ask(question: string, options?: string[]): Promise<string>;
+    /** Records the agent's closing summary; the loop ends after the call */
+    finish(summary: string): void;
+    emit(event: AgentEvent): void;
+    /** A secret was typed into a field the page shows in plain text: screenshots would show it */
+    secretOnScreen: boolean;
+}
+/** What a tool answers the model with. A failure is a result too: the model reads it and tries something else */
+export type ToolResult = {
+    ok: true;
+    message: string;
+    /** For a vision model */
+    image?: {
+        mediaType: "image/png";
+        data: string;
+    };
+} | {
+    ok: false;
+    error: string;
+};
+/** A tool as the loop uses it: the model-facing description and schema, and `run` for one call */
+export interface AgentTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodType;
+    /** Validates `args`, runs the tool and answers; never throws. Secret values are removed from the answer */
+    run(args: unknown): Promise<ToolResult>;
+}
+interface ToolSpec<S extends z.ZodType, C extends ToolContext> {
+    name: string;
+    description: string;
+    inputSchema: S;
+    execute(input: z.infer<S>, context: C): Promise<ToolResult>;
+}
+/** The first lines of an error message: enough for the model, without a long call log */
+export declare function shortMessage(error: unknown, max?: number): string;
+/** A tool bound to a run. Wraps `execute` so every tool validates, reports and fails the same way */
+export declare function defineTool<S extends z.ZodType, C extends ToolContext = ToolContext>(spec: ToolSpec<S, C>): (context: C) => AgentTool;
+export {};

package/dist/agent/tools/context.js

@@ -0,0 +1,42 @@
+import { maskDeep } from "../../config/mask.js";
+/** The first lines of an error message: enough for the model, without a long call log */
+export function shortMessage(error, max = 500) {
+    const text = (error instanceof Error ? error.message : String(error)).trim();
+    const lines = text.split("\n").filter((line) => line.trim() !== "");
+    const joined = lines.slice(0, 4).join(" ");
+    return joined.length > max ? `${joined.slice(0, max)}…` : joined;
+}
+/** A tool bound to a run. Wraps `execute` so every tool validates, reports and fails the same way */
+export function defineTool(spec) {
+    return (context) => ({
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+        async run(args) {
+            context.emit({
+                type: "tool-call",
+                tool: spec.name,
+                args: maskDeep(args),
+            });
+            const parsed = spec.inputSchema.safeParse(args);
+            if (!parsed.success) {
+                const problems = parsed.error.issues
+                    .map((issue) => `${issue.path.join(".") || "arguments"}: ${issue.message}`)
+                    .join("; ");
+                return maskDeep({
+                    ok: false,
+                    error: `${spec.name}(): invalid arguments (${problems})`,
+                });
+            }
+            try {
+                return maskDeep(await spec.execute(parsed.data, context));
+            }
+            catch (error) {
+                return maskDeep({
+                    ok: false,
+                    error: `${spec.name}(): ${shortMessage(error)}`,
+                });
+            }
+        },
+    });
+}