@itmetsam/samurai-framework 0.22.4 → 0.22.5

package/dist/agent/generate-kind.d.ts

@@ -0,0 +1,5 @@
+import { StepRecorder } from "./recording.js";
+import type { RunKind } from "./run-kind.js";
+import type { AgentOptions } from "./types.js";
+/** The run of `runAgent`: typed steps go into a spec file */
+export declare const generateKind: RunKind<AgentOptions, StepRecorder>;

package/dist/agent/generate-kind.js

@@ -0,0 +1,40 @@
+import { resultSecrets } from "../recorder/session-secrets.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { StepRecorder } from "./recording.js";
+import { personRecording } from "./take-over.js";
+import { createTools } from "./tools/index.js";
+/** The run of `runAgent`: typed steps go into a spec file */
+export const generateKind = {
+    file: (options) => options.file,
+    sink: (options, { baseURL, emit }) => new StepRecorder({
+        file: options.file,
+        create: options.create,
+        test: options.test,
+        baseURL,
+        onStep: (event, code, source) => emit({
+            type: "step",
+            event,
+            ...(code !== undefined && { code }),
+            source,
+        }),
+    }),
+    opened: (steps, url) => {
+        if (steps.count === 0)
+            steps.observe({ type: "goto", url });
+    },
+    tools: (context) => createTools(context),
+    prompt: (input, options) => buildSystemPrompt({
+        ...input,
+        ...(options.plan !== undefined && { hasPlan: true }),
+    }),
+    opening: (options, first) => options.plan !== undefined
+        ? `Goal: ${options.goal}\n\nPlan (written earlier by another agent; follow it, but check each step on the live page):\n${options.plan.trim()}\n\n${first}`
+        : `Goal: ${options.goal}\n\n${first}`,
+    secrets: (steps) => resultSecrets(steps.events, []),
+    person: ({ page, sink, snapshots, baseURL }) => personRecording({
+        page,
+        steps: sink,
+        snapshots,
+        ...(baseURL !== undefined && { baseURL }),
+    }),
+};

package/dist/agent/index.d.ts

@@ -1,11 +1,19 @@
+import type { AgentOptions, AgentSession, PlanOptions, PlanSession } from "./types.js";
 export { DEFAULT_LIMITS, resolveLimits, type AgentLimits } from "./limits.js";
 export { assertModelObject, type AgentModel } from "./model.js";
+export { readPlan } from "./plan/read-plan.js";
 export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
-export type { AgentEndReason, AgentEvent, AgentOptions, AgentResult, AgentSession, } from "./types.js";
-import type { AgentOptions, AgentSession } from "./types.js";
+export type { AgentEndReason, AgentEvent, AgentOptions, AgentResult, AgentSession, PlanOptions, PlanResult, PlanSession, } from "./types.js";
 /**
  * Starts the agent on a goal. The model is an AI SDK model object; the run opens a browser, writes typed steps
  * into the spec file as they succeed, and ends with an `ended` event whatever happens. Throws at once for a model
- * that is a string. Needs the optional packages `ai` and `zod`.
+ * that is a string. Needs the optional packages `ai` and `zod`. With `plan` (the text of a plan from `runPlan`)
+ * the agent follows that plan, checking each step on the live page.
  */
 export declare function runAgent(options: AgentOptions): AgentSession;
+/**
+ * Starts the planning agent on a goal: it explores the page and writes a Markdown plan into `out`, a step at a
+ * time, for `runAgent`'s `plan` option. The page is read-only: every request that is not a GET is stopped. Same
+ * events and `ended` event as `runAgent`, plus `plan-step`. Needs the optional packages `ai` and `zod`.
+ */
+export declare function runPlan(options: PlanOptions): PlanSession;

package/dist/agent/index.js

@@ -1,12 +1,23 @@
+import { startPlan } from "./plan/run.js";
+import { startAgent } from "./run.js";
 export { DEFAULT_LIMITS, resolveLimits } from "./limits.js";
 export { assertModelObject } from "./model.js";
+export { readPlan } from "./plan/read-plan.js";
 export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
-import { startAgent } from "./run.js";
 /**
  * Starts the agent on a goal. The model is an AI SDK model object; the run opens a browser, writes typed steps
  * into the spec file as they succeed, and ends with an `ended` event whatever happens. Throws at once for a model
- * that is a string. Needs the optional packages `ai` and `zod`.
+ * that is a string. Needs the optional packages `ai` and `zod`. With `plan` (the text of a plan from `runPlan`)
+ * the agent follows that plan, checking each step on the live page.
  */
 export function runAgent(options) {
     return startAgent(options);
 }
+/**
+ * Starts the planning agent on a goal: it explores the page and writes a Markdown plan into `out`, a step at a
+ * time, for `runAgent`'s `plan` option. The page is read-only: every request that is not a GET is stopped. Same
+ * events and `ended` event as `runAgent`, plus `plan-step`. Needs the optional packages `ai` and `zod`.
+ */
+export function runPlan(options) {
+    return startPlan(options);
+}

package/dist/agent/plan/guard.d.ts

@@ -0,0 +1,7 @@
+import type Page from "../../browser/page.js";
+/**
+ * Makes the page read-only for the planner: every request that is not a `GET`, `HEAD` or `OPTIONS` is aborted
+ * before it leaves the browser (form submits, `fetch`, XHR, beacons), and `onBlocked` hears what it was. A `GET`
+ * that changes data and a WebSocket message are not covered. Other origins are the origin policy's business.
+ */
+export declare function installPlanGuard(page: Pick<Page, "route">, onBlocked: (what: string) => void): Promise<void>;

package/dist/agent/plan/guard.js

@@ -0,0 +1,32 @@
+/** Methods that read: they pass. `OPTIONS` is the CORS preflight, which carries no data of the page */
+const READS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** "POST /api/feedback": the method and the path, without the query (it can hold values) */
+function describeRequest(method, url) {
+    try {
+        return `${method} ${new URL(url).pathname}`;
+    }
+    catch {
+        return method;
+    }
+}
+/**
+ * Makes the page read-only for the planner: every request that is not a `GET`, `HEAD` or `OPTIONS` is aborted
+ * before it leaves the browser (form submits, `fetch`, XHR, beacons), and `onBlocked` hears what it was. A `GET`
+ * that changes data and a WebSocket message are not covered. Other origins are the origin policy's business.
+ */
+export async function installPlanGuard(page, onBlocked) {
+    await page.route("**/*", async (route) => {
+        const request = route.request();
+        const { method, url } = request;
+        if (READS.has(method.toUpperCase())) {
+            await route.continue();
+            return;
+        }
+        onBlocked(describeRequest(method.toUpperCase(), url));
+        // An aborted form submit leaves Chrome on its error page; an empty 204 answer to a navigation keeps the page
+        if (request.resourceType === "document" || request.navigation !== null)
+            await route.fulfill({ status: 204 });
+        else
+            await route.abort();
+    });
+}

package/dist/agent/plan/plan-file.d.ts

@@ -0,0 +1,59 @@
+/** A plan file may not be larger than this (bytes), for the planner and for `generate --plan` */
+export declare const MAX_PLAN_BYTES: number;
+interface PlanStep {
+    text: string;
+    expect?: string;
+}
+/** A plan as `parsePlan` reads it; every part but the steps may be missing in a hand-written file */
+interface ParsedPlan {
+    title: string;
+    goal: string;
+    start: string;
+    steps: PlanStep[];
+    seen: string[];
+    notDone: string[];
+    questions: string[];
+}
+/**
+ * A plan file being written. The whole file is written again after every call, so it is valid Markdown with its
+ * four headings whenever the run stops. Texts are masked and made one line long.
+ */
+declare class PlanFile {
+    readonly file: string;
+    private readonly goal;
+    private start;
+    private readonly steps;
+    private readonly seenItems;
+    private readonly notDoneItems;
+    private readonly questionItems;
+    constructor(file: string, goal: string, start: string);
+    /** The title, which is also what the run reports as the name of the test */
+    get title(): string;
+    get count(): number;
+    private render;
+    /** Writes the file; refuses, and keeps the file as it was, when it would pass the size limit */
+    private save;
+    private add;
+    /** Appends a step and returns its number */
+    addStep(text: string, expect?: string): number;
+    /** Names the page the plan starts on, once the browser is there */
+    setStart(url: string): void;
+    seen(text: string): void;
+    notDone(text: string): void;
+    question(text: string): void;
+    /** Writes the first version of the file */
+    create(): void;
+}
+export type { PlanFile };
+/** Starts a plan file: the headings are written at once. An existing file is an error unless `force` is set */
+export declare function createPlan(input: {
+    goal: string;
+    start: string;
+    out: string;
+    force?: boolean;
+}): PlanFile;
+/**
+ * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * and `None.` placeholders are fine. Only the `## Steps` heading is needed.
+ */
+export declare function parsePlan(text: string): ParsedPlan;

package/dist/agent/plan/plan-file.js

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { projectDir } from "../../config/config.js";
+import { maskText } from "../../config/mask.js";
+/** A plan file may not be larger than this (bytes), for the planner and for `generate --plan` */
+export const MAX_PLAN_BYTES = 32 * 1024;
+const NONE = "None.";
+const TITLE_LENGTH = 80;
+/** One line, masked: a new line in a text must not be able to start a heading or a step */
+function oneLine(text) {
+    return maskText(text).replace(/\s+/g, " ").trim();
+}
+function bullets(items) {
+    return items.length > 0
+        ? items.map((item) => `- ${item}`).join("\n")
+        : `- ${NONE}`;
+}
+/**
+ * A plan file being written. The whole file is written again after every call, so it is valid Markdown with its
+ * four headings whenever the run stops. Texts are masked and made one line long.
+ */
+class PlanFile {
+    constructor(file, goal, start) {
+        this.file = file;
+        this.goal = goal;
+        this.start = start;
+        this.steps = [];
+        this.seenItems = [];
+        this.notDoneItems = [];
+        this.questionItems = [];
+    }
+    /** The title, which is also what the run reports as the name of the test */
+    get title() {
+        const first = this.goal.slice(0, TITLE_LENGTH).trim();
+        return first.length < this.goal.length ? `${first}…` : first;
+    }
+    get count() {
+        return this.steps.length;
+    }
+    render() {
+        const steps = this.steps.map((step, i) => `${i + 1}. ${step.text}${step.expect !== undefined ? `\n   Expect: ${step.expect}` : ""}`);
+        return [
+            `# Plan: ${this.title}`,
+            "",
+            `Goal: ${this.goal}`,
+            `Start: ${this.start}`,
+            "",
+            "## Steps",
+            "",
+            steps.length > 0 ? steps.join("\n") : `- ${NONE}`,
+            "",
+            "## Seen on the page",
+            "",
+            bullets(this.seenItems),
+            "",
+            "## Not done",
+            "",
+            bullets(this.notDoneItems),
+            "",
+            "## Open questions",
+            "",
+            bullets(this.questionItems),
+            "",
+        ].join("\n");
+    }
+    /** Writes the file; refuses, and keeps the file as it was, when it would pass the size limit */
+    save() {
+        const text = this.render();
+        if (Buffer.byteLength(text) > MAX_PLAN_BYTES)
+            throw new Error(`the plan file is full (${MAX_PLAN_BYTES / 1024} KB); finish with what it holds, or shorten the next entry`);
+        mkdirSync(path.dirname(this.file), { recursive: true });
+        writeFileSync(this.file, text);
+    }
+    add(list, text) {
+        list.push(oneLine(text));
+        try {
+            this.save();
+        }
+        catch (error) {
+            list.pop();
+            throw error;
+        }
+    }
+    /** Appends a step and returns its number */
+    addStep(text, expect) {
+        const step = { text: oneLine(text) };
+        const wanted = expect === undefined ? "" : oneLine(expect);
+        if (wanted !== "")
+            step.expect = wanted;
+        this.steps.push(step);
+        try {
+            this.save();
+        }
+        catch (error) {
+            this.steps.pop();
+            throw error;
+        }
+        return this.steps.length;
+    }
+    /** Names the page the plan starts on, once the browser is there */
+    setStart(url) {
+        this.start = oneLine(url);
+        this.save();
+    }
+    seen(text) {
+        this.add(this.seenItems, text);
+    }
+    notDone(text) {
+        this.add(this.notDoneItems, text);
+    }
+    question(text) {
+        this.add(this.questionItems, text);
+    }
+    /** Writes the first version of the file */
+    create() {
+        this.save();
+    }
+}
+/** Starts a plan file: the headings are written at once. An existing file is an error unless `force` is set */
+export function createPlan(input) {
+    const file = path.resolve(projectDir(), input.out);
+    if (existsSync(file) && input.force !== true)
+        throw new Error(`createPlan(): ${file} already exists; pass force (--force) to replace it`);
+    const plan = new PlanFile(file, oneLine(input.goal), oneLine(input.start));
+    plan.create();
+    return plan;
+}
+const HEADING = /^##\s+(.*?)\s*$/;
+const STEP = /^\s*\d+\.\s+(.*)$/;
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const EXPECT = /^\s+Expect:\s*(.*)$/i;
+const FIELD = /^(Goal|Start):\s*(.*)$/i;
+function sectionOf(heading) {
+    const name = heading.toLowerCase();
+    if (name === "steps")
+        return "steps";
+    if (name.startsWith("seen"))
+        return "seen";
+    if (name === "not done")
+        return "notDone";
+    if (name.startsWith("open question"))
+        return "questions";
+    return "other";
+}
+/**
+ * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * and `None.` placeholders are fine. Only the `## Steps` heading is needed.
+ */
+export function parsePlan(text) {
+    const plan = {
+        title: "",
+        goal: "",
+        start: "",
+        steps: [],
+        seen: [],
+        notDone: [],
+        questions: [],
+    };
+    let section;
+    let hasSteps = false;
+    for (const line of text.split(/\r?\n/)) {
+        const heading = HEADING.exec(line);
+        if (heading) {
+            section = sectionOf(heading[1]);
+            if (section === "steps")
+                hasSteps = true;
+            continue;
+        }
+        if (line.trim() === "")
+            continue;
+        if (section === undefined) {
+            const title = /^#\s+(?:Plan:\s*)?(.*)$/i.exec(line);
+            const field = FIELD.exec(line);
+            if (title && plan.title === "")
+                plan.title = title[1].trim();
+            else if (field)
+                plan[field[1].toLowerCase()] = field[2].trim();
+            continue;
+        }
+        if (section === "other")
+            continue;
+        if (section === "steps") {
+            const last = plan.steps[plan.steps.length - 1];
+            const step = STEP.exec(line);
+            const expect = EXPECT.exec(line);
+            if (step)
+                plan.steps.push({ text: step[1].trim() });
+            else if (last && expect)
+                last.expect = expect[1].trim();
+            else if (last && !BULLET.test(line) && /^\s/.test(line))
+                last.text = `${last.text} ${line.trim()}`;
+            continue;
+        }
+        const item = BULLET.exec(line)?.[1]?.trim();
+        if (item !== undefined && item !== NONE)
+            plan[section].push(item);
+    }
+    if (!hasSteps)
+        throw new Error('parsePlan(): the plan has no "## Steps" heading');
+    return plan;
+}

package/dist/agent/plan/plan-kind.d.ts

@@ -0,0 +1,5 @@
+import type { RunKind } from "../run-kind.js";
+import type { PlanOptions } from "../types.js";
+import { PlanRecorder } from "./recorder.js";
+/** The run of `runPlan`: steps go into a Markdown plan, and the page cannot change data */
+export declare const planKind: RunKind<PlanOptions, PlanRecorder>;

package/dist/agent/plan/plan-kind.js

@@ -0,0 +1,28 @@
+import { maskText } from "../../config/mask.js";
+import { installPlanGuard } from "./guard.js";
+import { createPlan } from "./plan-file.js";
+import { buildPlanPrompt } from "./prompt.js";
+import { PlanRecorder } from "./recorder.js";
+import { createPlanTools } from "./tools.js";
+/** The run of `runPlan`: steps go into a Markdown plan, and the page cannot change data */
+export const planKind = {
+    file: (options) => options.out,
+    sink: (options, { baseURL, emit }) => new PlanRecorder(createPlan({
+        goal: options.goal,
+        start: options.url ?? baseURL ?? "",
+        out: options.out,
+        ...(options.force !== undefined && { force: options.force }),
+    }), (n, text) => emit({ type: "plan-step", n, text })),
+    opened: (plan, url) => plan.setStart(url),
+    tools: (context, plan) => createPlanTools(context, plan),
+    prompt: (input) => buildPlanPrompt(input),
+    opening: (options, first) => `Goal: ${options.goal}\n\n${first}`,
+    secrets: () => [],
+    guard: (page, plan) => installPlanGuard(page, (what) => plan.block(what)),
+    person: ({ snapshots }) => ({
+        // The person's clicks write nothing: only the agent writes the plan. It is told the page may have changed
+        begin: () => Promise.resolve(),
+        end: async () => `The person used the browser while you were stopped. The page may have changed; this is the page now:\n\n${maskText((await snapshots.take()).text)}\n\nYour last call was not run. Call it again only if it is still needed.`,
+        dispose: () => Promise.resolve(),
+    }),
+};

package/dist/agent/plan/prompt.d.ts

@@ -0,0 +1,3 @@
+import { type PromptInput } from "../prompt.js";
+/** The planner's system prompt: explore and describe, never submit, write steps another agent can follow */
+export declare function buildPlanPrompt(input: PromptInput): string;

package/dist/agent/plan/prompt.js

@@ -0,0 +1,37 @@
+import { DATA_RULES, instructionsSection, } from "../prompt.js";
+/** The planner's system prompt: explore and describe, never submit, write steps another agent can follow */
+export function buildPlanPrompt(input) {
+    const secrets = input.secrets.length > 0 ? input.secrets.join(", ") : "none are available";
+    const sections = [
+        `You plan browser tests for SAMURAI, a test framework over WebDriver BiDi. You drive a real browser with the tools below to find out how a page works, and you write a plan: numbered steps, in plain language, that another agent can follow without the page in front of it. That agent writes the test from your plan; you write no test code.`,
+        `## How to work
+- State a short plan in one or two sentences first, then act.
+- Call snapshot to read the page. It lists elements as [e12] role "name" with their state; use those references (e12) as the target of act. References are valid until the next snapshot, so take a new one after the page changes.
+- Do one thing at a time: one tool call at a time, and wait for its answer before the next call.
+- After you did something with act or navigate and saw that it worked, write it with step(text, expect?). Name elements the way snapshot shows them: role and accessible name, for example: Click "Create account" (button). Never use internal ids or references (e12) in a step; they change. In expect, say what the page showed afterwards.
+- A step is written only after you did it on the live page. Do not write steps for things you did not try.
+- Use seen for what a test writer needs to know that is not a step (the headings, the form fields, the validation messages), and notDone for everything you did not do or could not see.
+- Never invent credentials, addresses or data. If you need something you do not have, call question with a short question (and options when there are a few); the answer is for your steps.
+- When the plan covers the goal, call finish with a short summary. If you cannot go on, call finish and say why.`,
+        `## You never submit
+- The page you drive is read-only: the framework blocks every request that is not a GET, so a form submit, a save, a delete or a payment does nothing, and the tool answer says blocked. This is so that planning cannot change real data.
+- Fill forms and open pages to see what they do, but do not try to get around the block. Write the click that would submit as "Not done" (notDone) and say what you expect it to do, if the page tells you.
+- A link or button that only reads is fine. Nothing here stops a page that changes data with a plain GET, so do not open pages whose names say they delete, log out or buy.`,
+        `## Tools
+- snapshot: the page as text.
+- navigate(url): open a URL or a path. Allowed without asking: ${input.origins.length > 0 ? input.origins.join(", ") : "none"}. Any other site asks the person and may be refused.
+- act(kind, target, value?): click, fill, select, check, uncheck, hover, dblclick, clear, press. It writes nothing to the plan.
+- step(text, expect?): write a step you did. Refused when you did nothing since the last step.
+- seen(text), notDone(text): notes for the test writer.
+- question(question, options?): ask the person; it is kept in the plan.
+- finish(summary).`,
+        `## Secrets and data
+- You see the names of secrets, never their values: ${secrets}. Password fields show •••• in snapshots. Write a secret in a step as secrets.NAME (for example secrets.PASSWORD), never a value. You cannot type a secret: describe the step and write it as secrets.NAME.
+- Environment variables are env.NAME. Never put a value you were told or saw for a password, token or key in the plan.`,
+        DATA_RULES,
+    ];
+    const project = instructionsSection(input.instructions);
+    if (project)
+        sections.push(project);
+    return sections.join("\n\n");
+}

package/dist/agent/plan/read-plan.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reads a plan for `generate --plan`: the text goes to the agent as it is. A missing file, a file over 32 KB and a
+ * file without a `## Steps` heading are errors that name the file.
+ */
+export declare function readPlan(file: string): string;

package/dist/agent/plan/read-plan.js

@@ -0,0 +1,28 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { projectDir } from "../../config/config.js";
+import { MAX_PLAN_BYTES, parsePlan } from "./plan-file.js";
+/**
+ * Reads a plan for `generate --plan`: the text goes to the agent as it is. A missing file, a file over 32 KB and a
+ * file without a `## Steps` heading are errors that name the file.
+ */
+export function readPlan(file) {
+    const full = path.resolve(projectDir(), file);
+    let size;
+    try {
+        size = statSync(full).size;
+    }
+    catch {
+        throw new Error(`readPlan(): ${full} cannot be read`);
+    }
+    if (size > MAX_PLAN_BYTES)
+        throw new Error(`readPlan(): ${full} is ${Math.ceil(size / 1024)} KB, over the ${MAX_PLAN_BYTES / 1024} KB limit`);
+    const text = readFileSync(full, "utf8");
+    try {
+        parsePlan(text);
+    }
+    catch (error) {
+        throw new Error(`readPlan(): ${full}: ${error.message.replace(/^parsePlan\(\): /, "")}`);
+    }
+    return text;
+}

package/dist/agent/plan/recorder.d.ts

@@ -0,0 +1,30 @@
+import type { Observation, RecorderEvent } from "../../recorder/normalise.js";
+import type { RunSink } from "../run-kind.js";
+import type { PlanFile } from "./plan-file.js";
+/**
+ * What a planning run keeps: the plan file, whether something was done on the page since the last step, and the
+ * requests the guard stopped. `observe` is how the shared tools (`act`, `navigate`) report what they did; they
+ * write nothing, a plan step is the agent's own words (`step`).
+ */
+export declare class PlanRecorder implements RunSink {
+    private readonly plan;
+    private readonly onStep;
+    private acted;
+    private blocked;
+    constructor(plan: PlanFile, onStep: (n: number, text: string) => void);
+    get count(): number;
+    get file(): string;
+    get testName(): string;
+    observe(_observation: Observation): RecorderEvent[];
+    undo(_count: number): number;
+    /** Records a step the agent has done on the live page; refused when it did nothing since the last step */
+    addStep(text: string, expect?: string): number;
+    setStart(url: string): void;
+    seen(text: string): void;
+    notDone(text: string): void;
+    question(text: string): void;
+    /** The guard stopped a request */
+    block(what: string): void;
+    /** What was stopped since the last call, once */
+    takeBlocked(): string[];
+}

package/dist/agent/plan/recorder.js

@@ -0,0 +1,60 @@
+/**
+ * What a planning run keeps: the plan file, whether something was done on the page since the last step, and the
+ * requests the guard stopped. `observe` is how the shared tools (`act`, `navigate`) report what they did; they
+ * write nothing, a plan step is the agent's own words (`step`).
+ */
+export class PlanRecorder {
+    constructor(plan, onStep) {
+        this.plan = plan;
+        this.onStep = onStep;
+        this.acted = false;
+        this.blocked = new Set();
+    }
+    get count() {
+        return this.plan.count;
+    }
+    get file() {
+        return this.plan.file;
+    }
+    get testName() {
+        return this.plan.title;
+    }
+    observe(_observation) {
+        this.acted = true;
+        return [];
+    }
+    undo(_count) {
+        return 0;
+    }
+    /** Records a step the agent has done on the live page; refused when it did nothing since the last step */
+    addStep(text, expect) {
+        if (!this.acted)
+            throw new Error("nothing was done since the last step; act first");
+        const n = this.plan.addStep(text, expect);
+        this.acted = false;
+        this.onStep(n, text);
+        return n;
+    }
+    setStart(url) {
+        this.plan.setStart(url);
+    }
+    seen(text) {
+        this.plan.seen(text);
+    }
+    notDone(text) {
+        this.plan.notDone(text);
+    }
+    question(text) {
+        this.plan.question(text);
+    }
+    /** The guard stopped a request */
+    block(what) {
+        this.blocked.add(what);
+    }
+    /** What was stopped since the last call, once */
+    takeBlocked() {
+        const list = [...this.blocked];
+        this.blocked = new Set();
+        return list;
+    }
+}

package/dist/agent/plan/run.d.ts

@@ -0,0 +1,8 @@
+import { type RunDeps } from "../run.js";
+import type { PlanOptions, PlanSession } from "../types.js";
+/**
+ * Starts a planning run: the agent explores the page and writes a Markdown plan into `out` after each step it
+ * records. It never submits: every request that is not a GET is stopped. The same events and the same `ended`
+ * event as `runAgent`, plus `plan-step`. Throws at once for a model that is a string.
+ */
+export declare function startPlan(options: PlanOptions, deps?: RunDeps): PlanSession;

package/dist/agent/plan/run.js

@@ -0,0 +1,10 @@
+import { startAgent } from "../run.js";
+import { planKind } from "./plan-kind.js";
+/**
+ * Starts a planning run: the agent explores the page and writes a Markdown plan into `out` after each step it
+ * records. It never submits: every request that is not a GET is stopped. The same events and the same `ended`
+ * event as `runAgent`, plus `plan-step`. Throws at once for a model that is a string.
+ */
+export function startPlan(options, deps = {}) {
+    return startAgent(options, deps, planKind);
+}

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

@@ -0,0 +1,4 @@
+import { type AgentTool, type ToolContext } from "../tools/context.js";
+import type { PlanRecorder } from "./recorder.js";
+/** The planner's tools, bound to a run: the shared ones that read and act, and the ones that write the plan */
+export declare function createPlanTools(context: ToolContext, plan: PlanRecorder): AgentTool[];