@itmetsam/samurai-framework 0.22.4 → 0.22.6

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

@@ -3,18 +3,25 @@ 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 { StepRecorder } from "../recording.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: StepRecorder;
+    steps: ToolSink;
     origins: OriginPolicy;
     secrets: SecretAccess;
     /** The model takes images, so `screenshot` works */
@@ -50,14 +57,14 @@ export interface AgentTool {
     /** 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> {
+interface ToolSpec<S extends z.ZodType, C extends ToolContext> {
     name: string;
     description: string;
     inputSchema: S;
-    execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>;
+    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>(spec: ToolSpec<S>): (context: ToolContext) => AgentTool;
+export declare function defineTool<S extends z.ZodType, C extends ToolContext = ToolContext>(spec: ToolSpec<S, C>): (context: C) => AgentTool;
 export {};

package/dist/agent/tools/index.js

@@ -5,6 +5,7 @@ import { finish } from "./finish.js";
 import { navigate } from "./navigate.js";
 import { screenshot } from "./screenshot.js";
 import { snapshot } from "./snapshot.js";
+import { undo } from "./undo.js";
 import { useSecret } from "./use-secret.js";
 /** The agent's tools, bound to a run. Nothing else reaches the browser, the spec file or the person */
 export function createTools(context) {
@@ -15,6 +16,7 @@ export function createTools(context) {
         expectTool,
         screenshot,
         useSecret,
+        undo,
         ask,
         finish,
     ].map((tool) => tool(context));

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

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

package/dist/agent/tools/undo.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineTool } from "./context.js";
+export const undo = defineTool({
+    name: "undo",
+    description: "Take the last steps you wrote out of the test, for a step that was a mistake or a detour (a failed attempt, a reset). " +
+        "It only edits the test: the page stays as it is, so take a new snapshot (or reload) before you carry on.",
+    inputSchema: z.object({
+        count: z.number().int().min(1).max(20).optional(),
+    }),
+    async execute({ count }, context) {
+        const wanted = count ?? 1;
+        const removed = context.steps.undo(wanted);
+        if (removed === 0)
+            return {
+                ok: false,
+                error: "undo(): there is no step of yours to remove",
+            };
+        return {
+            ok: true,
+            message: `Removed the last ${removed} step${removed === 1 ? "" : "s"} from the test${removed < wanted ? ` (only ${removed} were yours)` : ""}. The page was not changed.`,
+        };
+    },
+});

package/dist/agent/types.d.ts

@@ -36,6 +36,12 @@ export type AgentEvent =
     inputTokens: number;
     outputTokens: number;
     totalTokens: number;
+}
+/** A planning run recorded step `n` of the plan file */
+ | {
+    type: "plan-step";
+    n: number;
+    text: string;
 } | {
     type: "ended";
     result: AgentResult;
@@ -56,17 +62,12 @@ export interface AgentResult {
     secrets: string[];
     tokens: number;
 }
-export interface AgentOptions extends ProjectOptions {
+/** What every kind of run takes: the model, the goal, the browser and the limits */
+export interface BaseAgentOptions extends ProjectOptions {
     /** The model, as an object from an AI SDK provider package. A string is refused */
     model: AgentModel;
     /** What the test should do, in the person's words */
     goal: string;
-    /** The spec file, absolute or relative to the project folder */
-    file: string;
-    /** Add a test with this title to the file (creating it) instead of writing into an existing one */
-    create?: string;
-    /** The existing test to write into (title or index), as for `recordSpec` */
-    test?: string | number;
     /** Where the browser starts. @default the environment's base URL */
     url?: string;
     browser?: SupportedBrowser;
@@ -86,6 +87,34 @@ export interface AgentOptions extends ProjectOptions {
     signal?: AbortSignal;
     onEvent?: (event: AgentEvent) => void;
 }
+export interface AgentOptions extends BaseAgentOptions {
+    /** The spec file, absolute or relative to the project folder */
+    file: string;
+    /** Add a test with this title to the file (creating it) instead of writing into an existing one */
+    create?: string;
+    /** The existing test to write into (title or index), as for `recordSpec` */
+    test?: string | number;
+    /** The text of a plan written earlier (see `runPlan`): a draft to follow and check on the live page */
+    plan?: string;
+    /**
+     * The plan file the `plan` text came from, relative to the project folder (an absolute path is made relative).
+     * The test is marked with `{ type: "plan", description: <this path> }` in its `annotations` option
+     */
+    planFile?: string;
+}
+/** A planning run: explores the page and writes a Markdown plan, never a spec, and never submits */
+export interface PlanOptions extends BaseAgentOptions {
+    /** The plan file, absolute or relative to the project folder */
+    out: string;
+    /** Overwrite `out` when it exists. @default false */
+    force?: boolean;
+}
+/** How a planning run ended: `file` is the plan, `steps` the plan steps */
+export type PlanResult = Omit<AgentResult, "test">;
+/** A planning run in progress; the same controls as an `AgentSession` */
+export type PlanSession = Omit<AgentSession, "result"> & {
+    readonly result: Promise<PlanResult>;
+};
 /** A run in progress */
 export interface AgentSession {
     readonly events: AsyncIterable<AgentEvent>;

package/dist/cli/agent-run.d.ts

@@ -0,0 +1,43 @@
+import { type ParsedCommandLine } from "./args.js";
+import type { AgentResult, AgentSession } from "../agent/index.js";
+import type { Io } from "./io.js";
+/** The agent entry, loaded when `generate` or `plan` runs: it needs the optional packages `ai` and `zod` */
+export type AgentEntry = typeof import("../agent/index.js");
+export interface AgentCommandDeps {
+    loadAgent?: () => Promise<AgentEntry>;
+}
+/**
+ * What `generate` and `plan` share: the flags both read (browser, origins, secrets, limits, ...), the model and
+ * the notice of which provider receives the pages. Throws a usage error for a bad flag.
+ */
+export declare function prepareAgentRun({ values }: ParsedCommandLine, io: Io, deps: AgentCommandDeps, command: string): Promise<{
+    agent: typeof import("../agent/index.js");
+    model: import("../agent/model.js").AgentModel;
+    options: {
+        signal?: AbortSignal | undefined;
+        limits?: {
+            maxSteps: number;
+        } | undefined;
+        secretFields?: string[] | undefined;
+        secrets?: string[] | undefined;
+        allowedOrigins?: string[] | undefined;
+        headless?: boolean | undefined;
+        port?: number | undefined;
+        browser?: import("../types/browser.js").SupportedBrowser | undefined;
+        url?: string | undefined;
+        environment?: string | undefined;
+        timeout?: number | undefined;
+        expectTimeout?: number | undefined;
+    };
+}>;
+/**
+ * Prints a run's events (or each as a JSON line) and answers its questions in the terminal. Returns the exit code:
+ * 0 for a run that finished, 1 for any other end. `summarise` prints the closing text of the command.
+ */
+export declare function followRun(session: Pick<AgentSession, "events" | "answer" | "stop"> & {
+    result: Promise<{
+        reason: string;
+    }>;
+}, io: Io, json: boolean, summarise: (result: AgentResult) => void): Promise<number>;
+/** The opening words of the closing text: "Done" or how the run stopped */
+export declare function endingOf(reason: string): string;

package/dist/cli/agent-run.js

@@ -0,0 +1,132 @@
+import { parseRunnerFlags, parseRunOverrides, } from "./args.js";
+async function loadAgentEntry(command) {
+    try {
+        return await import("../agent/index.js");
+    }
+    catch (error) {
+        if (error.code === "ERR_MODULE_NOT_FOUND")
+            throw new Error(`samurai ${command} needs the packages ai and zod, and a provider package for your model; run: npm install ai zod @ai-sdk/anthropic (or @ai-sdk/openai, @ai-sdk/openai-compatible)`);
+        throw error;
+    }
+}
+function origin(raw) {
+    try {
+        return new URL(raw).origin;
+    }
+    catch {
+        throw new Error(`--yes-origin: "${raw}" is not a URL such as https://shop.example`);
+    }
+}
+/** The model the run uses: `--model`, else `SAMURAI_AI_MODEL`, else the config's `ai.model` */
+async function chosenModel(agent, flag, env) {
+    const spec = flag ?? (await agent.defaultModelSpec(env));
+    if (!spec)
+        throw new Error("No model: pass --model provider:name (anthropic, openai or openai-compatible), set SAMURAI_AI_MODEL, or set ai.model in samurai.config.ts");
+    return {
+        spec,
+        model: await agent.modelFromSpec(spec, { projectDir: process.cwd(), env }),
+    };
+}
+/**
+ * What `generate` and `plan` share: the flags both read (browser, origins, secrets, limits, ...), the model and
+ * the notice of which provider receives the pages. Throws a usage error for a bad flag.
+ */
+export async function prepareAgentRun({ values }, io, deps, command) {
+    const maxSteps = values["max-steps"] === undefined ? undefined : Number(values["max-steps"]);
+    if (maxSteps !== undefined && (!Number.isInteger(maxSteps) || maxSteps < 1))
+        throw new Error(`--max-steps must be a whole number from 1, got "${values["max-steps"]}"`);
+    const flags = parseRunnerFlags(values);
+    if (flags.browsers && flags.browsers.length > 1)
+        throw new Error("--browser: the agent uses one browser");
+    const allowedOrigins = (values["yes-origin"] ?? []).map(origin);
+    const agent = await (deps.loadAgent ?? (() => loadAgentEntry(command)))();
+    const { spec, model } = await chosenModel(agent, values.model, io.env);
+    if (values.json !== true)
+        io.out(`Model ${spec.slice(0, spec.indexOf(":"))}: the pages the agent reads are sent to that provider.\n`);
+    return {
+        agent,
+        model,
+        options: {
+            ...parseRunOverrides(values, io.env),
+            ...(values.url !== undefined && { url: values.url }),
+            ...(flags.browsers && { browser: flags.browsers[0] }),
+            ...(flags.port !== undefined && { port: flags.port }),
+            ...(flags.headless !== undefined && { headless: flags.headless }),
+            ...(allowedOrigins.length > 0 && { allowedOrigins }),
+            ...(values.secret && { secrets: values.secret }),
+            ...(values["secret-field"] && { secretFields: values["secret-field"] }),
+            ...(maxSteps !== undefined && { limits: { maxSteps } }),
+            ...(io.signal && { signal: io.signal }),
+        },
+    };
+}
+function summaryOf(args) {
+    const text = JSON.stringify(args ?? {});
+    return text.length > 100 ? `${text.slice(0, 99)}…` : text;
+}
+/**
+ * Prints a run's events (or each as a JSON line) and answers its questions in the terminal. Returns the exit code:
+ * 0 for a run that finished, 1 for any other end. `summarise` prints the closing text of the command.
+ */
+export async function followRun(session, io, json, summarise) {
+    let unanswerable;
+    for await (const event of session.events) {
+        if (json)
+            io.out(`${JSON.stringify(event)}\n`);
+        switch (event.type) {
+            case "plan":
+                if (!json)
+                    io.out(`${event.text}\n`);
+                break;
+            case "tool-call":
+                if (!json)
+                    io.out(`  · ${event.tool} ${summaryOf(event.args)}\n`);
+                break;
+            case "step":
+                if (!json && event.code !== undefined)
+                    io.out(`  ${event.event.op === "insert" ? "+" : "~"} ${event.code}\n`);
+                break;
+            case "plan-step":
+                if (!json)
+                    io.out(`  + ${event.n}. ${event.text}\n`);
+                break;
+            case "question": {
+                const originQuestion = event.options?.join("/") === "allow/deny";
+                if (io.prompt && !json) {
+                    io.out(`? ${event.question}${event.options ? ` (${event.options.join("/")})` : ""}\n`);
+                    void io
+                        .prompt("> ")
+                        .then((answer) => session.answer(event.id, answer))
+                        .catch(() => undefined); // the run ended while the question was open
+                }
+                else if (originQuestion) {
+                    session.answer(event.id, "deny");
+                }
+                else {
+                    unanswerable = event.question;
+                    session.stop();
+                }
+                break;
+            }
+            case "ended":
+                if (!json)
+                    summarise(event.result);
+                break;
+            default:
+                break;
+        }
+    }
+    if (unanswerable !== undefined)
+        io.err(`The agent asked "${unanswerable}" and nobody can answer: stdin is not a terminal${json ? " (or --json is set)" : ""}. Run it in a terminal, or put the answer in the goal.\n`);
+    return (await session.result).reason === "finished" ? 0 : 1;
+}
+const ENDINGS = {
+    stopped: "Stopped.",
+    "step-limit": "Stopped at the step limit (--max-steps).",
+    "token-limit": "Stopped at the token limit.",
+    "time-limit": "Stopped at the time limit.",
+};
+/** The opening words of the closing text: "Done" or how the run stopped */
+export function endingOf(reason) {
+    return reason === "finished" ? "Done" : (ENDINGS[reason] ?? reason);
+}

package/dist/cli/args.d.ts

@@ -24,6 +24,9 @@ export declare function parseCommandLine(argv: string[]): {
         test?: string | undefined;
         at?: string | undefined;
         new?: string | undefined;
+        plan?: string | undefined;
+        out?: string | undefined;
+        force?: boolean | undefined;
         url?: string | undefined;
         model?: string | undefined;
         "max-steps"?: string | undefined;

package/dist/cli/args.js

@@ -19,6 +19,9 @@ const FLAGS = {
     test: { type: "string" },
     at: { type: "string" },
     new: { type: "string" },
+    plan: { type: "string" },
+    out: { type: "string" },
+    force: { type: "boolean" },
     url: { type: "string" },
     model: { type: "string" },
     "max-steps": { type: "string" },

package/dist/cli/generate.d.ts

@@ -1,10 +1,6 @@
-import { type ParsedCommandLine } from "./args.js";
+import { type AgentCommandDeps } from "./agent-run.js";
+import type { ParsedCommandLine } from "./args.js";
 import type { Io } from "./io.js";
-/** The agent entry, loaded when `generate` runs: it needs the optional packages `ai` and `zod` */
-type AgentEntry = typeof import("../agent/index.js");
-export interface GenerateDeps {
-    loadAgent?: () => Promise<AgentEntry>;
-}
+export type GenerateDeps = AgentCommandDeps;
 /** `samurai generate "<goal>"`: lets the AI agent write a test and prints what it does. Returns the exit code */
-export declare function generateCommand({ values, positionals }: ParsedCommandLine, io: Io, deps?: GenerateDeps): Promise<number>;
-export {};
+export declare function generateCommand(parsed: ParsedCommandLine, io: Io, deps?: GenerateDeps): Promise<number>;

package/dist/cli/generate.js

@@ -1,138 +1,47 @@
-import { parseRunnerFlags, parseRunOverrides, } from "./args.js";
-const USAGE_LINE = 'Usage: samurai generate "<goal>" --file <spec> [--new <title>] [--test <name|index>] [--url <url>] [--model <provider:name>] [--max-steps <n>] [--yes-origin <origin>] [--secret <NAME>] [--json]';
-async function loadAgent() {
-    try {
-        return await import("../agent/index.js");
-    }
-    catch (error) {
-        if (error.code === "ERR_MODULE_NOT_FOUND")
-            throw new Error("samurai generate needs the packages ai and zod, and a provider package for your model; run: npm install ai zod @ai-sdk/anthropic (or @ai-sdk/openai, @ai-sdk/openai-compatible)");
-        throw error;
-    }
-}
-function origin(raw) {
-    try {
-        return new URL(raw).origin;
-    }
-    catch {
-        throw new Error(`--yes-origin: "${raw}" is not a URL such as https://shop.example`);
-    }
-}
-/** The model the run uses: `--model`, else `SAMURAI_AI_MODEL`, else the config's `ai.model` */
-async function chosenModel(agent, flag, env) {
-    const spec = flag ?? (await agent.defaultModelSpec(env));
-    if (!spec)
-        throw new Error("No model: pass --model provider:name (anthropic, openai or openai-compatible), set SAMURAI_AI_MODEL, or set ai.model in samurai.config.ts");
-    return {
-        spec,
-        model: await agent.modelFromSpec(spec, { projectDir: process.cwd(), env }),
-    };
-}
+import { endingOf, followRun, prepareAgentRun, } from "./agent-run.js";
+const USAGE_LINE = 'Usage: samurai generate "<goal>" --file <spec> [--new <title>] [--test <name|index>] [--plan <plan.md>] [--url <url>] [--model <provider:name>] [--max-steps <n>] [--yes-origin <origin>] [--secret <NAME>] [--json]';
 /** `samurai generate "<goal>"`: lets the AI agent write a test and prints what it does. Returns the exit code */
-export async function generateCommand({ values, positionals }, io, deps = {}) {
+export async function generateCommand(parsed, io, deps = {}) {
+    const { values, positionals } = parsed;
     const goal = positionals[0];
     if (!goal)
         throw new Error(`Which goal? ${USAGE_LINE}`);
     const files = values.file ?? [];
     if (files.length !== 1)
         throw new Error(`Give exactly one --file <spec>. ${USAGE_LINE}`);
-    const maxSteps = values["max-steps"] === undefined ? undefined : Number(values["max-steps"]);
-    if (maxSteps !== undefined && (!Number.isInteger(maxSteps) || maxSteps < 1))
-        throw new Error(`--max-steps must be a whole number from 1, got "${values["max-steps"]}"`);
-    const flags = parseRunnerFlags(values);
-    if (flags.browsers && flags.browsers.length > 1)
-        throw new Error("--browser: the agent uses one browser");
     const test = values.test === undefined
         ? undefined
         : /^\d+$/.test(values.test)
             ? Number(values.test)
             : values.test;
-    const allowedOrigins = (values["yes-origin"] ?? []).map(origin);
-    const agent = await (deps.loadAgent ?? loadAgent)();
-    const { spec, model } = await chosenModel(agent, values.model, io.env);
-    const json = values.json === true;
-    if (!json)
-        io.out(`Model ${spec.slice(0, spec.indexOf(":"))}: the pages the agent reads are sent to that provider.\n`);
+    const { agent, model, options } = await prepareAgentRun(parsed, io, deps, "generate");
+    const plan = values.plan === undefined ? undefined : readPlanFlag(agent, values.plan);
     const session = agent.runAgent({
-        ...parseRunOverrides(values, io.env),
+        ...options,
         model,
         goal,
         file: files[0],
         ...(test !== undefined && { test }),
         ...(values.new !== undefined && { create: values.new }),
-        ...(values.url !== undefined && { url: values.url }),
-        ...(flags.browsers && { browser: flags.browsers[0] }),
-        ...(flags.port !== undefined && { port: flags.port }),
-        ...(flags.headless !== undefined && { headless: flags.headless }),
-        ...(allowedOrigins.length > 0 && { allowedOrigins }),
-        ...(values.secret && { secrets: values.secret }),
-        ...(values["secret-field"] && { secretFields: values["secret-field"] }),
-        ...(maxSteps !== undefined && { limits: { maxSteps } }),
-        ...(io.signal && { signal: io.signal }),
+        ...(plan !== undefined && { plan, planFile: values.plan }),
     });
-    let unanswerable;
-    for await (const event of session.events) {
-        if (json)
-            io.out(`${JSON.stringify(event)}\n`);
-        switch (event.type) {
-            case "plan":
-                if (!json)
-                    io.out(`${event.text}\n`);
-                break;
-            case "tool-call":
-                if (!json)
-                    io.out(`  · ${event.tool} ${summaryOf(event.args)}\n`);
-                break;
-            case "step":
-                if (!json && event.code !== undefined)
-                    io.out(`  ${event.event.op === "insert" ? "+" : "~"} ${event.code}\n`);
-                break;
-            case "question": {
-                const originQuestion = event.options?.join("/") === "allow/deny";
-                if (io.prompt && !json) {
-                    io.out(`? ${event.question}${event.options ? ` (${event.options.join("/")})` : ""}\n`);
-                    void io
-                        .prompt("> ")
-                        .then((answer) => session.answer(event.id, answer))
-                        .catch(() => undefined); // the run ended while the question was open
-                }
-                else if (originQuestion) {
-                    session.answer(event.id, "deny");
-                }
-                else {
-                    unanswerable = event.question;
-                    session.stop();
-                }
-                break;
-            }
-            case "ended":
-                if (!json)
-                    summarise(io, event.result);
-                break;
-            default:
-                break;
-        }
-    }
-    if (unanswerable !== undefined)
-        io.err(`The agent asked "${unanswerable}" and nobody can answer: stdin is not a terminal${json ? " (or --json is set)" : ""}. Run it in a terminal, or put the answer in the goal.\n`);
-    return (await session.result).reason === "finished" ? 0 : 1;
+    return followRun(session, io, values.json === true, (result) => summarise(io, result));
 }
-function summaryOf(args) {
-    const text = JSON.stringify(args ?? {});
-    return text.length > 100 ? `${text.slice(0, 99)}…` : text;
+/** The text of `--plan <file>`; a file that cannot be used is a usage error that names it */
+function readPlanFlag(agent, file) {
+    try {
+        return agent.readPlan(file);
+    }
+    catch (error) {
+        throw new Error(`--plan: ${error.message.replace(/^readPlan\(\): /, "")}`);
+    }
 }
-const ENDINGS = {
-    stopped: "Stopped.",
-    "step-limit": "Stopped at the step limit (--max-steps).",
-    "token-limit": "Stopped at the token limit.",
-    "time-limit": "Stopped at the time limit.",
-};
 function summarise(io, result) {
     const base = `"${result.test}" has ${result.steps} ${result.steps === 1 ? "step" : "steps"} in ${result.file}.`;
     if (result.reason === "error")
         io.err(`\nThe run failed: ${result.error ?? "unknown error"}\n${base}\n`);
     else
-        io.out(`\n${result.reason === "finished" ? "Done" : (ENDINGS[result.reason] ?? result.reason)} ${base}\n${result.summary ? `${result.summary}\n` : ""}`);
+        io.out(`\n${endingOf(result.reason)} ${base}\n${result.summary ? `${result.summary}\n` : ""}`);
     if (result.secrets.length > 0)
         io.out(`Set ${result.secrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
     io.out(`${result.tokens} tokens used. Review the steps before you run the test.\n`);

package/dist/cli/main.js

@@ -5,6 +5,7 @@ import { browsersCommand } from "./browsers.js";
 import { flowCommand } from "./flow.js";
 import { generateCommand } from "./generate.js";
 import { initProject } from "./init.js";
+import { planCommand } from "./plan.js";
 import { recordCommand } from "./record.js";
 import { USAGE } from "./usage.js";
 import { frameworkVersion } from "./version.js";
@@ -39,6 +40,8 @@ export async function main(argv, io) {
         }
         if (command === "generate")
             return await generateCommand({ values, positionals }, io);
+        if (command === "plan")
+            return await planCommand({ values, positionals }, io);
         if (command === "record")
             return await recordCommand({ values, positionals }, io);
         if (command !== "run" && command !== "list") {

package/dist/cli/plan.d.ts

@@ -0,0 +1,6 @@
+import { type AgentCommandDeps } from "./agent-run.js";
+import type { ParsedCommandLine } from "./args.js";
+import type { Io } from "./io.js";
+export type PlanDeps = AgentCommandDeps;
+/** `samurai plan "<goal>"`: without `--out` the plan goes to `<plansDir>/<slug-of-goal>.plan.md`. Lets the AI agent explore the page and write a test plan, without submitting anything */
+export declare function planCommand(parsed: ParsedCommandLine, io: Io, deps?: PlanDeps): Promise<number>;

package/dist/cli/plan.js

@@ -0,0 +1,31 @@
+import { endingOf, followRun, prepareAgentRun, } from "./agent-run.js";
+const USAGE_LINE = 'Usage: samurai plan "<goal>" [--out <plan.md>] [--force] [--url <url>] [--model <provider:name>] [--max-steps <n>] [--yes-origin <origin>] [--secret <NAME>] [--json]';
+/** `samurai plan "<goal>"`: without `--out` the plan goes to `<plansDir>/<slug-of-goal>.plan.md`. Lets the AI agent explore the page and write a test plan, without submitting anything */
+export async function planCommand(parsed, io, deps = {}) {
+    const { values, positionals } = parsed;
+    const goal = positionals[0];
+    if (!goal)
+        throw new Error(`Which goal? ${USAGE_LINE}`);
+    const { agent, model, options } = await prepareAgentRun(parsed, io, deps, "plan");
+    const out = values.out === undefined || values.out === ""
+        ? await agent.defaultPlanFile(goal)
+        : values.out;
+    if (values.out === undefined && values.json !== true)
+        io.out(`The plan will be written to ${out}\n`);
+    const session = agent.runPlan({
+        ...options,
+        model,
+        goal,
+        out,
+        ...(values.force === true && { force: true }),
+    });
+    return followRun(session, io, values.json === true, (result) => summarise(io, result));
+}
+function summarise(io, result) {
+    const base = `The plan in ${result.file} has ${result.steps} ${result.steps === 1 ? "step" : "steps"}.`;
+    if (result.reason === "error")
+        io.err(`\nThe run failed: ${result.error ?? "unknown error"}\n${base}\n`);
+    else
+        io.out(`\n${endingOf(result.reason)} ${base}\n${result.summary ? `${result.summary}\n` : ""}`);
+    io.out(`${result.tokens} tokens used. Read the plan, fix what is wrong, then: samurai generate "<goal>" --plan ${result.file} --file <spec>\n`);
+}

package/dist/cli/usage.d.ts

@@ -1 +1 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai generate \"<goal>\"   Let an AI agent write a test into a spec file (needs ai, zod and a provider)\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups; repeat it for several\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n  --retries <n>               Run a failing test again up to n times, each with a fresh browser\n                              (or SAMURAI_RETRIES; default 0)\n  --shard <current/total>     Run one slice of the selected tests, to split a run over machines:\n                              --shard=2/4 runs the second of four. Whole files (and serial\n                              blocks) go to one shard; an empty shard succeeds\n\nOptions for record (also --env, --port, --json; always with a window):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\nOptions for generate (also --env, --browser, --port, --headless, --json):\n  --file <spec>               The spec file to write into (required, once)\n  --new <title>               Add a test with this title (creates the file if needed)\n  --test <name|index>         Write into this test; not needed when the file has one\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  --model <provider:name>     anthropic, openai or openai-compatible, for example\n                              anthropic:claude-sonnet-4-5. Default: SAMURAI_AI_MODEL, then the\n                              config's ai.model. Keys: ANTHROPIC_API_KEY, OPENAI_API_KEY,\n                              SAMURAI_AI_API_KEY (+ SAMURAI_AI_BASE_URL for openai-compatible)\n  --max-steps <n>             Most model calls in the run (default 40)\n  --yes-origin <origin>       A site the agent may open without asking; repeatable\n  --secret <NAME>             A secret the agent may type (it never sees the value); repeatable\n  --secret-field <css>        A field whose value is never shown to the model; repeatable\n  Questions are asked in the terminal; without one (or with --json) an unknown site is refused\n  and any other question ends the run.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed (generate: the agent finished), 1 when a test failed (generate: it ended at a limit, was stopped or failed), 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai plan \"<goal>\"       Let an AI agent explore a page and write a test plan (Markdown); it submits nothing\n  samurai generate \"<goal>\"   Let an AI agent write a test into a spec file (needs ai, zod and a provider)\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups; repeat it for several\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n  --retries <n>               Run a failing test again up to n times, each with a fresh browser\n                              (or SAMURAI_RETRIES; default 0)\n  --shard <current/total>     Run one slice of the selected tests, to split a run over machines:\n                              --shard=2/4 runs the second of four. Whole files (and serial\n                              blocks) go to one shard; an empty shard succeeds\n\nOptions for record (also --env, --port, --json; always with a window):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\nOptions for plan (also --env, --browser, --port, --headless, --json and the model, limit and\norigin options of generate below):\n  --out <plan.md>             The plan file to write; written after every step. Without it: <plansDir>/<goal-slug>.plan.md\n  --force                     Replace --out when it exists\n  The page is read-only while planning: every request that is not a GET is blocked.\n\nOptions for generate (also --env, --browser, --port, --headless, --json):\n  --file <spec>               The spec file to write into (required, once)\n  --plan <plan.md>            A plan from samurai plan: the agent follows it and checks each step\n  --new <title>               Add a test with this title (creates the file if needed)\n  --test <name|index>         Write into this test; not needed when the file has one\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  --model <provider:name>     anthropic, openai or openai-compatible, for example\n                              anthropic:claude-sonnet-4-5. Default: SAMURAI_AI_MODEL, then the\n                              config's ai.model. Keys: ANTHROPIC_API_KEY, OPENAI_API_KEY,\n                              SAMURAI_AI_API_KEY (+ SAMURAI_AI_BASE_URL for openai-compatible)\n  --max-steps <n>             Most model calls in the run (default 40)\n  --yes-origin <origin>       A site the agent may open without asking; repeatable\n  --secret <NAME>             A secret the agent may type (it never sees the value); repeatable\n  --secret-field <css>        A field whose value is never shown to the model; repeatable\n  Questions are asked in the terminal; without one (or with --json) an unknown site is refused\n  and any other question ends the run.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed (generate, plan: the agent finished), 1 when a test failed (generate, plan: it ended at a limit, was stopped or failed), 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";

package/dist/cli/usage.js

@@ -5,6 +5,7 @@ Usage:
   samurai run [options]       Run the tests (the default command)
   samurai list [options]      List the tests without running them
   samurai record <spec>       Open a browser and record what you do into a spec file
+  samurai plan "<goal>"       Let an AI agent explore a page and write a test plan (Markdown); it submits nothing
   samurai generate "<goal>"   Let an AI agent write a test into a spec file (needs ai, zod and a provider)
   samurai init [folder]       Scaffold a project: config, an example test, .env.example
   samurai flow <command>      List, check and run the flows in ./flows (see below)
@@ -42,8 +43,15 @@ Options for record (also --env, --port, --json; always with a window):
   --url <url>                 Page to start on (default: the environment's baseURL)
   Stop with Ctrl+C or by closing the browser window.
 
+Options for plan (also --env, --browser, --port, --headless, --json and the model, limit and
+origin options of generate below):
+  --out <plan.md>             The plan file to write; written after every step. Without it: <plansDir>/<goal-slug>.plan.md
+  --force                     Replace --out when it exists
+  The page is read-only while planning: every request that is not a GET is blocked.
+
 Options for generate (also --env, --browser, --port, --headless, --json):
   --file <spec>               The spec file to write into (required, once)
+  --plan <plan.md>            A plan from samurai plan: the agent follows it and checks each step
   --new <title>               Add a test with this title (creates the file if needed)
   --test <name|index>         Write into this test; not needed when the file has one
   --url <url>                 Page to start on (default: the environment's baseURL)
@@ -61,7 +69,7 @@ Options for generate (also --env, --browser, --port, --headless, --json):
   -h, --help                  Show this help
   -v, --version               Show the version
 
-Exit code: 0 when every test passed (generate: the agent finished), 1 when a test failed (generate: it ended at a limit, was stopped or failed), 2 for a usage or configuration error.
+Exit code: 0 when every test passed (generate, plan: the agent finished), 1 when a test failed (generate, plan: it ended at a limit, was stopped or failed), 2 for a usage or configuration error.
 
 samurai flow:
   list                        The flows in ./flows