@itmetsam/samurai-framework 0.22.5 → 0.22.7

package/dist/agent/generate-kind.js

@@ -1,5 +1,6 @@
 import { resultSecrets } from "../recorder/session-secrets.js";
 import { buildSystemPrompt } from "./prompt.js";
+import { questionsSection } from "./plan/questions.js";
 import { StepRecorder } from "./recording.js";
 import { personRecording } from "./take-over.js";
 import { createTools } from "./tools/index.js";
@@ -11,6 +12,7 @@ export const generateKind = {
         create: options.create,
         test: options.test,
         baseURL,
+        planFile: options.planFile,
         onStep: (event, code, source) => emit({
             type: "step",
             event,
@@ -27,9 +29,12 @@ export const generateKind = {
         ...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}`,
+    opening: (options, first) => {
+        if (options.plan === undefined)
+            return `Goal: ${options.goal}\n\n${first}`;
+        const questions = questionsSection(options.plan);
+        return `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${questions === "" ? "" : `${questions}\n\n`}${first}`;
+    },
     secrets: (steps) => resultSecrets(steps.events, []),
     person: ({ page, sink, snapshots, baseURL }) => personRecording({
         page,

package/dist/agent/index.d.ts

@@ -1,6 +1,9 @@
 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 { splitFrontMatter } from "./plan/front-matter.js";
+export { formatPlan, MAX_PLAN_BYTES, parsePlan, type ParsedPlan, type PlanDocument, type PlanQuestion, } from "./plan/plan-file.js";
+export { defaultPlanFile, listPlans } from "./plan/plan-path.js";
 export { readPlan } from "./plan/read-plan.js";
 export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
 export type { AgentEndReason, AgentEvent, AgentOptions, AgentResult, AgentSession, PlanOptions, PlanResult, PlanSession, } from "./types.js";

package/dist/agent/index.js

@@ -2,6 +2,9 @@ import { startPlan } from "./plan/run.js";
 import { startAgent } from "./run.js";
 export { DEFAULT_LIMITS, resolveLimits } from "./limits.js";
 export { assertModelObject } from "./model.js";
+export { splitFrontMatter } from "./plan/front-matter.js";
+export { formatPlan, MAX_PLAN_BYTES, parsePlan, } from "./plan/plan-file.js";
+export { defaultPlanFile, listPlans } from "./plan/plan-path.js";
 export { readPlan } from "./plan/read-plan.js";
 export { defaultModelSpec, ModelSetupError, modelFromSpec, } from "./providers.js";
 /**

package/dist/agent/plan/front-matter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Splits the YAML front matter off a plan: a first line of `---` up to the next line of `---`. Nothing inside is
+ * parsed (the app keeps its own metadata there, and any key is fine). A plan without it is returned as it is; an
+ * opening fence with no closing one throws.
+ */
+export declare function splitFrontMatter(text: string): {
+    front: string;
+    body: string;
+};

package/dist/agent/plan/front-matter.js

@@ -0,0 +1,18 @@
+const FENCE = "---";
+/**
+ * Splits the YAML front matter off a plan: a first line of `---` up to the next line of `---`. Nothing inside is
+ * parsed (the app keeps its own metadata there, and any key is fine). A plan without it is returned as it is; an
+ * opening fence with no closing one throws.
+ */
+export function splitFrontMatter(text) {
+    const lines = text.replace(/^/, "").split("\n");
+    if (lines[0]?.trimEnd() !== FENCE)
+        return { front: "", body: text };
+    const end = lines.findIndex((line, i) => i > 0 && line.trimEnd() === FENCE);
+    if (end < 0)
+        throw new Error(`the front matter block opened with "---" on the first line has no closing "---" line`);
+    return {
+        front: `${lines.slice(0, end + 1).join("\n")}\n`,
+        body: lines.slice(end + 1).join("\n"),
+    };
+}

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

@@ -1,5 +1,6 @@
 /** A plan file may not be larger than this (bytes), for the planner and for `generate --plan` */
 export declare const MAX_PLAN_BYTES: number;
+/** One step of a plan, with what to check after it */
 interface PlanStep {
     text: string;
     expect?: string;
@@ -12,8 +13,37 @@ interface ParsedPlan {
     steps: PlanStep[];
     seen: string[];
     notDone: string[];
+    /** Every open question, answered or not */
     questions: string[];
+    /** Every open question with its answer, if it has one; what `formatPlan` takes back */
+    questionList: PlanQuestion[];
+    /** The questions that have an `Answer:` line, with the answer; a question with an empty answer is not here */
+    answers: {
+        question: string;
+        answer: string;
+    }[];
 }
+/** A plan as `formatPlan` writes it and `parsePlan` reads it back */
+interface PlanDocument {
+    title: string;
+    goal: string;
+    start: string;
+    steps: PlanStep[];
+    seen: string[];
+    notDone: string[];
+    /** An answered question is written with an indented `Answer:` line below it */
+    questions: PlanQuestion[];
+}
+interface PlanQuestion {
+    text: string;
+    answer?: string;
+}
+/**
+ * Writes a plan as Markdown, the format the planner writes and `parsePlan` reads. Every text is masked and made one
+ * line. `front` is a raw front matter block (ending with a new line, as `splitFrontMatter` returns it) placed first.
+ * Throws when the result is larger than `MAX_PLAN_BYTES`.
+ */
+export declare function formatPlan(plan: PlanDocument, front?: string): 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.
@@ -30,6 +60,8 @@ declare class PlanFile {
     /** The title, which is also what the run reports as the name of the test */
     get title(): string;
     get count(): number;
+    /** The front matter the file has now (the app may change it while the plan is written); kept as it is */
+    private frontMatter;
     private render;
     /** Writes the file; refuses, and keeps the file as it was, when it would pass the size limit */
     private save;
@@ -44,7 +76,7 @@ declare class PlanFile {
     /** Writes the first version of the file */
     create(): void;
 }
-export type { PlanFile };
+export type { PlanFile, ParsedPlan, PlanDocument, PlanQuestion };
 /** 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;
@@ -53,7 +85,7 @@ export declare function createPlan(input: {
     force?: boolean;
 }): PlanFile;
 /**
- * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * Reads a plan, the one `createPlan` wrote or one a person edited. A leading front matter block is ignored. 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

@@ -1,7 +1,8 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { projectDir } from "../../config/config.js";
 import { maskText } from "../../config/mask.js";
+import { splitFrontMatter } from "./front-matter.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.";
@@ -15,6 +16,48 @@ function bullets(items) {
         ? items.map((item) => `- ${item}`).join("\n")
         : `- ${NONE}`;
 }
+/**
+ * Writes a plan as Markdown, the format the planner writes and `parsePlan` reads. Every text is masked and made one
+ * line. `front` is a raw front matter block (ending with a new line, as `splitFrontMatter` returns it) placed first.
+ * Throws when the result is larger than `MAX_PLAN_BYTES`.
+ */
+export function formatPlan(plan, front = "") {
+    const steps = plan.steps.map((step, i) => {
+        const expect = step.expect === undefined ? "" : oneLine(step.expect);
+        return `${i + 1}. ${oneLine(step.text)}${expect !== "" ? `\n   Expect: ${expect}` : ""}`;
+    });
+    const questions = plan.questions.map((q) => {
+        const answer = q.answer === undefined ? "" : oneLine(q.answer);
+        return `- ${oneLine(q.text)}${answer !== "" ? `\n  Answer: ${answer}` : ""}`;
+    });
+    const text = [
+        ...(front === "" ? [] : [front.replace(/\n$/, "")]),
+        `# Plan: ${oneLine(plan.title)}`,
+        "",
+        `Goal: ${oneLine(plan.goal)}`,
+        `Start: ${oneLine(plan.start)}`,
+        "",
+        "## Steps",
+        "",
+        steps.length > 0 ? steps.join("\n") : `- ${NONE}`,
+        "",
+        "## Seen on the page",
+        "",
+        bullets(plan.seen.map(oneLine)),
+        "",
+        "## Not done",
+        "",
+        bullets(plan.notDone.map(oneLine)),
+        "",
+        "## Open questions",
+        "",
+        questions.length > 0 ? questions.join("\n") : `- ${NONE}`,
+        "",
+    ].join("\n");
+    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`);
+    return text;
+}
 /**
  * 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.
@@ -37,37 +80,29 @@ class PlanFile {
     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");
+    /** The front matter the file has now (the app may change it while the plan is written); kept as it is */
+    frontMatter() {
+        try {
+            return splitFrontMatter(readFileSync(this.file, "utf8")).front;
+        }
+        catch {
+            return "";
+        }
+    }
+    render(front) {
+        return formatPlan({
+            title: this.title,
+            goal: this.goal,
+            start: this.start,
+            steps: this.steps,
+            seen: this.seenItems,
+            notDone: this.notDoneItems,
+            questions: this.questionItems.map((text) => ({ text })),
+        }, front);
     }
     /** 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`);
+        const text = this.render(this.frontMatter());
         mkdirSync(path.dirname(this.file), { recursive: true });
         writeFileSync(this.file, text);
     }
@@ -129,6 +164,7 @@ const HEADING = /^##\s+(.*?)\s*$/;
 const STEP = /^\s*\d+\.\s+(.*)$/;
 const BULLET = /^\s*[-*]\s+(.*)$/;
 const EXPECT = /^\s+Expect:\s*(.*)$/i;
+const ANSWER = /^\s+Answer:\s*(.*)$/i;
 const FIELD = /^(Goal|Start):\s*(.*)$/i;
 function sectionOf(heading) {
     const name = heading.toLowerCase();
@@ -143,7 +179,7 @@ function sectionOf(heading) {
     return "other";
 }
 /**
- * Reads a plan, the one `createPlan` wrote or one a person edited: blank lines, a missing title, missing sections
+ * Reads a plan, the one `createPlan` wrote or one a person edited. A leading front matter block is ignored. Blank lines, a missing title, missing sections
  * and `None.` placeholders are fine. Only the `## Steps` heading is needed.
  */
 export function parsePlan(text) {
@@ -155,10 +191,19 @@ export function parsePlan(text) {
         seen: [],
         notDone: [],
         questions: [],
+        questionList: [],
+        answers: [],
     };
     let section;
     let hasSteps = false;
-    for (const line of text.split(/\r?\n/)) {
+    let body;
+    try {
+        body = splitFrontMatter(text).body;
+    }
+    catch (error) {
+        throw new Error(`parsePlan(): ${error.message}`);
+    }
+    for (const line of body.split(/\r?\n/)) {
         const heading = HEADING.exec(line);
         if (heading) {
             section = sectionOf(heading[1]);
@@ -191,9 +236,22 @@ export function parsePlan(text) {
                 last.text = `${last.text} ${line.trim()}`;
             continue;
         }
+        const answer = section === "questions" ? ANSWER.exec(line) : null;
+        const asked = plan.questions[plan.questions.length - 1];
+        if (answer) {
+            const text = answer[1].trim();
+            if (asked !== undefined && text !== "") {
+                plan.answers.push({ question: asked, answer: text });
+                plan.questionList[plan.questionList.length - 1].answer = text;
+            }
+            continue;
+        }
         const item = BULLET.exec(line)?.[1]?.trim();
-        if (item !== undefined && item !== NONE)
+        if (item !== undefined && item !== NONE) {
             plan[section].push(item);
+            if (section === "questions")
+                plan.questionList.push({ text: item });
+        }
     }
     if (!hasSteps)
         throw new Error('parsePlan(): the plan has no "## Steps" heading');

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

@@ -0,0 +1,13 @@
+/** Lower-case ascii words of a goal joined by `-`, at most 60 characters; `plan` when nothing is left */
+export declare function slugOf(goal: string): string;
+/**
+ * The file `samurai plan` writes when no `--out` is given: `<plansDir>/<slug-of-goal>.plan.md` below the project
+ * folder, with `-2`, `-3`, ... added until the name is free, so an earlier plan is never replaced. The folder is
+ * created. Returns the path relative to the project folder, with `/` separators.
+ */
+export declare function defaultPlanFile(goal: string): Promise<string>;
+/**
+ * The plan files (`*.plan.md`) below the config's `plansDir`, searched in all sub-folders: paths relative to the
+ * project folder, with `/` separators, sorted. A missing folder gives an empty list.
+ */
+export declare function listPlans(): Promise<string[]>;

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

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { loadRawConfig, projectDir } from "../../config/config.js";
+import { DEFAULT_PLANS_DIR } from "../../config/defaults.js";
+const SLUG_LENGTH = 60;
+/** Lower-case ascii words of a goal joined by `-`, at most 60 characters; `plan` when nothing is left */
+export function slugOf(goal) {
+    const slug = goal
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, SLUG_LENGTH)
+        .replace(/^-+|-+$/g, "");
+    return slug === "" ? "plan" : slug;
+}
+/** The config's `plansDir`; a project without a `samurai.config.ts` (and no config given) uses the default */
+async function plansDirOf() {
+    try {
+        return (await loadRawConfig()).plansDir ?? DEFAULT_PLANS_DIR;
+    }
+    catch (error) {
+        if (existsSync(path.join(projectDir(), "samurai.config.ts")))
+            throw error;
+        return DEFAULT_PLANS_DIR;
+    }
+}
+/**
+ * The file `samurai plan` writes when no `--out` is given: `<plansDir>/<slug-of-goal>.plan.md` below the project
+ * folder, with `-2`, `-3`, ... added until the name is free, so an earlier plan is never replaced. The folder is
+ * created. Returns the path relative to the project folder, with `/` separators.
+ */
+export async function defaultPlanFile(goal) {
+    const dir = await plansDirOf();
+    const folder = path.resolve(projectDir(), dir);
+    mkdirSync(folder, { recursive: true });
+    const slug = slugOf(goal);
+    for (let n = 1;; n++) {
+        const name = `${n === 1 ? slug : `${slug}-${n}`}.plan.md`;
+        if (!existsSync(path.join(folder, name)))
+            return path
+                .relative(projectDir(), path.join(folder, name))
+                .split(path.sep)
+                .join("/");
+    }
+}
+/**
+ * The plan files (`*.plan.md`) below the config's `plansDir`, searched in all sub-folders: paths relative to the
+ * project folder, with `/` separators, sorted. A missing folder gives an empty list.
+ */
+export async function listPlans() {
+    const folder = path.resolve(projectDir(), await plansDirOf());
+    if (!existsSync(folder))
+        return [];
+    return readdirSync(folder, { recursive: true, encoding: "utf8" })
+        .filter((name) => name.endsWith(".plan.md"))
+        .map((name) => path
+        .relative(projectDir(), path.join(folder, name))
+        .split(path.sep)
+        .join("/"))
+        .sort();
+}

package/dist/agent/plan/prompt.js

@@ -21,7 +21,7 @@ export function buildPlanPrompt(input) {
 - 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.
+- step(text, expect?): write a step you did. Refused when every act or navigate so far is already a step.
 - seen(text), notDone(text): notes for the test writer.
 - question(question, options?): ask the person; it is kept in the plan.
 - finish(summary).`,

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

@@ -0,0 +1,5 @@
+/**
+ * The plan's open questions as a prompt section: the answered ones with their answers, then the unanswered ones,
+ * which the agent may `ask` the person. Empty when the plan has none or cannot be read.
+ */
+export declare function questionsSection(planText: string): string;

package/dist/agent/plan/questions.js

@@ -0,0 +1,22 @@
+import { parsePlan } from "./plan-file.js";
+/**
+ * The plan's open questions as a prompt section: the answered ones with their answers, then the unanswered ones,
+ * which the agent may `ask` the person. Empty when the plan has none or cannot be read.
+ */
+export function questionsSection(planText) {
+    let plan;
+    try {
+        plan = parsePlan(planText);
+    }
+    catch {
+        return "";
+    }
+    const answered = new Set(plan.answers.map((entry) => entry.question));
+    const open = plan.questions.filter((question) => !answered.has(question));
+    const parts = [];
+    if (plan.answers.length > 0)
+        parts.push(`Questions the person has answered (use the answers, do not ask again):\n${plan.answers.map((entry) => `- ${entry.question}\n  Answer: ${entry.answer}`).join("\n")}`);
+    if (open.length > 0)
+        parts.push(`Questions still open (call ask if you need the answer, do not guess):\n${open.map((question) => `- ${question}`).join("\n")}`);
+    return parts.join("\n\n");
+}

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

@@ -1,5 +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
+ * Reads a plan for `generate --plan`: the text goes to the agent as it is, without a front matter block. 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

@@ -1,9 +1,10 @@
 import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { projectDir } from "../../config/config.js";
+import { splitFrontMatter } from "./front-matter.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
+ * Reads a plan for `generate --plan`: the text goes to the agent as it is, without a front matter block. 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) {
@@ -20,9 +21,9 @@ export function readPlan(file) {
     const text = readFileSync(full, "utf8");
     try {
         parsePlan(text);
+        return splitFrontMatter(text).body;
     }
     catch (error) {
         throw new Error(`readPlan(): ${full}: ${error.message.replace(/^parsePlan\(\): /, "")}`);
     }
-    return text;
 }

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

@@ -2,14 +2,14 @@ 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
+ * What a planning run keeps: the plan file, how many things were done on the page, 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 done;
     private blocked;
     constructor(plan: PlanFile, onStep: (n: number, text: string) => void);
     get count(): number;
@@ -17,7 +17,7 @@ export declare class PlanRecorder implements RunSink {
     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 */
+    /** Records a step the agent has done on the live page; refused when every action so far is already a step */
     addStep(text: string, expect?: string): number;
     setStart(url: string): void;
     seen(text: string): void;

package/dist/agent/plan/recorder.js

@@ -1,5 +1,5 @@
 /**
- * What a planning run keeps: the plan file, whether something was done on the page since the last step, and the
+ * What a planning run keeps: the plan file, how many things were done on the page, 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`).
  */
@@ -7,7 +7,7 @@ export class PlanRecorder {
     constructor(plan, onStep) {
         this.plan = plan;
         this.onStep = onStep;
-        this.acted = false;
+        this.done = 0;
         this.blocked = new Set();
     }
     get count() {
@@ -20,18 +20,17 @@ export class PlanRecorder {
         return this.plan.title;
     }
     observe(_observation) {
-        this.acted = true;
+        this.done++;
         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 */
+    /** Records a step the agent has done on the live page; refused when every action so far is already a step */
     addStep(text, expect) {
-        if (!this.acted)
-            throw new Error("nothing was done since the last step; act first");
+        if (this.plan.count >= this.done)
+            throw new Error(`all ${this.done} actions so far are already recorded as steps; act first`);
         const n = this.plan.addStep(text, expect);
-        this.acted = false;
         this.onStep(n, text);
         return n;
     }

package/dist/agent/plan/tools.js

@@ -8,7 +8,7 @@ const step = defineTool({
     name: "step",
     description: "Write one step into the plan, after you did it on the live page with act or navigate. Say what to do the way " +
         'snapshot names it (role and name, for example: Click "Create account" (button)), and in expect what showed ' +
-        "afterwards. It is refused when you did nothing since the last step. One step per thing done.",
+        "afterwards. It is refused when every act or navigate so far is already a step. One step per thing done.",
     inputSchema: z.object({
         text: z.string().min(1).max(600),
         expect: z.string().min(1).max(400).optional(),

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

@@ -0,0 +1,8 @@
+/** The plan's path as the annotation names it: relative to the project folder, with `/` separators */
+export declare function planAnnotationPath(planFile: string): string;
+/**
+ * `source` with test `testIndex` marked as made from `planFile`: an annotation `{ type: "plan", description }` in
+ * its options. An existing plan annotation gets the new path in place, the test's other annotations stay, and a
+ * test that already names this plan leaves the source as it is.
+ */
+export declare function linkPlan(source: string, testIndex: number, planFile: string): string;

package/dist/agent/plan-link.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { projectDir } from "../config/config.js";
+import { applyEdit } from "../steps/edit.js";
+import { parseSpec } from "../steps/parse.js";
+/** The plan's path as the annotation names it: relative to the project folder, with `/` separators */
+export function planAnnotationPath(planFile) {
+    const relative = path.isAbsolute(planFile)
+        ? path.relative(projectDir(), planFile)
+        : path.normalize(planFile);
+    return relative.split(path.sep).join("/");
+}
+/**
+ * `source` with test `testIndex` marked as made from `planFile`: an annotation `{ type: "plan", description }` in
+ * its options. An existing plan annotation gets the new path in place, the test's other annotations stay, and a
+ * test that already names this plan leaves the source as it is.
+ */
+export function linkPlan(source, testIndex, planFile) {
+    const note = { type: "plan", description: planAnnotationPath(planFile) };
+    const existing = parseSpec(source)[testIndex]?.annotations ?? [];
+    const at = existing.findIndex((entry) => entry.type === "plan");
+    const annotations = at < 0
+        ? [...existing, note]
+        : existing.map((entry, i) => (i === at ? note : entry));
+    return applyEdit(source, { op: "declare", test: testIndex, annotations });
+}

package/dist/agent/recording.d.ts

@@ -6,6 +6,8 @@ export interface StepRecorderOptions {
     create?: string | undefined;
     /** The existing test to write into, as for `recordSpec` */
     test?: string | number | undefined;
+    /** The plan the test is made from, as `AgentOptions.planFile`: written on the test as a `plan` annotation */
+    planFile?: string | undefined;
     /** Relative URLs are written against this */
     baseURL?: string | undefined;
     /** Called after each event is written, with the statement it produced and the file's new content */

package/dist/agent/recording.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { projectDir } from "../config/config.js";
 import { Normaliser, } from "../recorder/normalise.js";
 import { prepareSpec, readSpec, SpecWriter } from "../recorder/spec-source.js";
+import { linkPlan } from "./plan-link.js";
 import { stepToSource } from "../steps/emit.js";
 /** The statement an event wrote, `undefined` for a removal */
 function codeOf(event) {
@@ -23,6 +24,9 @@ export class StepRecorder {
         const spec = prepareSpec(this.file, readSpec(this.file, options), options);
         this.testName = spec.testName;
         this.writer = new SpecWriter(spec.source, this.file, spec.testIndex);
+        const planFile = options.planFile;
+        if (planFile !== undefined)
+            this.writer.rewrite((source) => linkPlan(source, spec.testIndex, planFile));
         this.steps = spec.at;
         this.first = spec.at;
         this.normaliser = this.fresh();

package/dist/agent/types.d.ts

@@ -96,6 +96,11 @@ export interface AgentOptions extends BaseAgentOptions {
     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 {

package/dist/cli/generate.js

@@ -23,7 +23,7 @@ export async function generateCommand(parsed, io, deps = {}) {
         file: files[0],
         ...(test !== undefined && { test }),
         ...(values.new !== undefined && { create: values.new }),
-        ...(plan !== undefined && { plan }),
+        ...(plan !== undefined && { plan, planFile: values.plan }),
     });
     return followRun(session, io, values.json === true, (result) => summarise(io, result));
 }

package/dist/cli/plan.d.ts

@@ -2,5 +2,5 @@ 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>"`: lets the AI agent explore the page and write a test plan, without submitting anything */
+/** `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

@@ -1,19 +1,22 @@
 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>"`: lets the AI agent explore the page and write a test plan, without submitting anything */
+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}`);
-    if (values.out === undefined || values.out === "")
-        throw new Error(`Give the plan file with --out <plan.md>. ${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.out,
+        out,
         ...(values.force === true && { force: true }),
     });
     return followRun(session, io, values.json === true, (result) => summarise(io, result));

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 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 (required); written after every step\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";
+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

@@ -45,7 +45,7 @@ Options for record (also --env, --port, --json; always with a 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 (required); written after every step
+  --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.
 

package/dist/config/config.js

@@ -8,6 +8,7 @@ import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
 import { validateFullyParallelConfig } from "./fully-parallel.js";
 import { validateWorkersConfig } from "./workers.js";
+import { validatePlansDirConfig } from "./plans-dir.js";
 import { validateWebServerConfig } from "./web-server-options.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
@@ -39,6 +40,7 @@ export function validateConfig(config) {
     validateGroupUse(config);
     validateEnvironmentUse(config);
     validateWebServerConfig(config);
+    validatePlansDirConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/defaults.d.ts

@@ -33,6 +33,8 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const DEFAULT_DOWNLOADS_DIR = "result/downloads";
 /** The files folder, relative to the project */
 export declare const DEFAULT_FILES_DIR = "files";
+/** Where test plans are written, relative to the project */
+export declare const DEFAULT_PLANS_DIR = "plans";
 /** How many times a failing test is run again */
 export declare const DEFAULT_RETRIES = 0;
 /** Which page log entries go in the report: those of failed tests */

package/dist/config/defaults.js

@@ -30,6 +30,8 @@ export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
 export const DEFAULT_DOWNLOADS_DIR = "result/downloads";
 /** The files folder, relative to the project */
 export const DEFAULT_FILES_DIR = "files";
+/** Where test plans are written, relative to the project */
+export const DEFAULT_PLANS_DIR = "plans";
 /** How many times a failing test is run again */
 export const DEFAULT_RETRIES = 0;
 /** Which page log entries go in the report: those of failed tests */

package/dist/config/plans-dir.d.ts

@@ -0,0 +1,3 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Checks the `plansDir` key of a config: a folder inside the project. Throws an Error that names the key */
+export declare function validatePlansDirConfig(config: SamuraiTestConfig): void;

package/dist/config/plans-dir.js

@@ -0,0 +1,11 @@
+import path from "node:path";
+/** Checks the `plansDir` key of a config: a folder inside the project. Throws an Error that names the key */
+export function validatePlansDirConfig(config) {
+    const dir = config.plansDir;
+    if (dir === undefined)
+        return;
+    if (typeof dir !== "string" || dir.trim() === "")
+        throw new Error(`plansDir must be a folder name relative to the project, got ${JSON.stringify(dir)}`);
+    if (path.isAbsolute(dir) || path.normalize(dir).split(path.sep)[0] === "..")
+        throw new Error(`plansDir must be a folder inside the project, got "${dir}"`);
+}

package/dist/config/resolved-config.d.ts

@@ -57,6 +57,7 @@ export interface ResolvedConfig {
     } | null;
     downloadsDir: string;
     filesDir: string;
+    plansDir: string;
     logs: {
         capture: "off" | "failures" | "all";
         failOnPageError: boolean;

package/dist/config/resolved-config.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { browsersFor } from "./browsers-for.js";
 import { importConfigFile, projectConfig, validateConfig } from "./config.js";
-import { DEFAULT_COLLECT_BODIES, DEFAULT_COMMAND_TIMEOUT, DEFAULT_DOWNLOADS_DIR, DEFAULT_FAIL_ON_PAGE_ERROR, DEFAULT_FILES_DIR, DEFAULT_IDLE_TIME, DEFAULT_LOGS_CAPTURE, DEFAULT_MAX_BODY_SIZE, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_RETRIES, DEFAULT_ROUTE_TIMEOUT, DEFAULT_SRC_DIR, DEFAULT_TRACK_NETWORK, DEFAULT_VIEWPORT, DEFAULT_WAIT_UNTIL, } from "./defaults.js";
+import { DEFAULT_COLLECT_BODIES, DEFAULT_COMMAND_TIMEOUT, DEFAULT_DOWNLOADS_DIR, DEFAULT_FAIL_ON_PAGE_ERROR, DEFAULT_FILES_DIR, DEFAULT_PLANS_DIR, DEFAULT_IDLE_TIME, DEFAULT_LOGS_CAPTURE, DEFAULT_MAX_BODY_SIZE, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_RETRIES, DEFAULT_ROUTE_TIMEOUT, DEFAULT_SRC_DIR, DEFAULT_TRACK_NETWORK, DEFAULT_VIEWPORT, DEFAULT_WAIT_UNTIL, } from "./defaults.js";
 import { forbidsOnly } from "./forbid-only.js";
 import { IMPLICIT_ENVIRONMENT, resolveRunSettings, UnknownEnvironmentError, } from "./run-settings.js";
 import { resolveWorkers } from "./workers-option.js";
@@ -72,6 +72,7 @@ export function resolveConfig(config, options) {
         viewport: viewport === null ? null : { ...(viewport ?? DEFAULT_VIEWPORT) },
         downloadsDir: config.downloadsDir ?? DEFAULT_DOWNLOADS_DIR,
         filesDir: config.filesDir ?? DEFAULT_FILES_DIR,
+        plansDir: config.plansDir ?? DEFAULT_PLANS_DIR,
         logs: {
             capture: config.logs?.capture ?? DEFAULT_LOGS_CAPTURE,
             failOnPageError: config.logs?.failOnPageError ?? DEFAULT_FAIL_ON_PAGE_ERROR,

package/dist/recorder/spec-source.d.ts

@@ -34,6 +34,8 @@ export declare class SpecWriter {
     private readonly testIndex;
     readonly events: RecorderEvent[];
     constructor(source: string, file: string, testIndex: number);
+    /** Changes the source with `change` and writes the file when it differs; returns the new content */
+    rewrite(change: (source: string) => string): string;
     /** Applies the event, writes the file and returns the file's new content */
     write(event: RecorderEvent): string;
 }

package/dist/recorder/spec-source.js

@@ -74,6 +74,15 @@ export class SpecWriter {
         this.testIndex = testIndex;
         this.events = [];
     }
+    /** Changes the source with `change` and writes the file when it differs; returns the new content */
+    rewrite(change) {
+        const next = change(this.source);
+        if (next !== this.source) {
+            this.source = next;
+            writeFileSync(this.file, this.source);
+        }
+        return this.source;
+    }
     /** Applies the event, writes the file and returns the file's new content */
     write(event) {
         this.source = applyRecorderEvent(this.source, this.testIndex, event);

package/dist/runner/registry.js

@@ -7,7 +7,7 @@ import { validateUseOptions } from "../config/use-options.js";
 import { currentStepLog, currentTestInfo, infoFor, skipFromCondition, } from "./test-info.js";
 import { runStep } from "./steps.js";
 import { markTests } from "./test-annotations.js";
-import { validateTestIO } from "./test-io.js";
+import { validateTestAnnotations, validateTestIO } from "./test-io.js";
 import { addHook, addUse, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 import { configureSuite } from "./serial.js";
 const registered = [];
@@ -26,7 +26,7 @@ function openDescribe(file, title, fn, modifier, reason, mode) {
     }
 }
 function add({ file, line, column }, title, fn, modifier, extras = {}) {
-    const { reason, inputs, outputs, extension, expectedFail } = extras;
+    const { reason, inputs, outputs, annotations, extension, expectedFail } = extras;
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
@@ -40,6 +40,7 @@ function add({ file, line, column }, title, fn, modifier, extras = {}) {
         ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
         ...(inputs && { inputs }),
         ...(outputs && { outputs }),
+        ...(annotations && { annotations }),
         ...(extension && { extension }),
         ...(expectedFail && { expectedFail }),
     });
@@ -65,6 +66,9 @@ function bodyAndOptions(call, title, second, third) {
         fn: fn,
         ...(reason !== undefined && { reason }),
         ...(options && call.startsWith("test") && validateTestIO(call, options)),
+        ...(options &&
+            call.startsWith("test") &&
+            validateTestAnnotations(call, options)),
     };
 }
 /** `test()` and `test.only()`: a reason only makes sense with skip and fixme */

package/dist/runner/test-info.js

@@ -19,6 +19,7 @@ export class TestInfoImpl {
         const { test } = from;
         this.title = test.titlePath[test.titlePath.length - 1] ?? test.name;
         this.titlePath = [...test.titlePath];
+        this.annotations = (test.annotations ?? []).map((a) => ({ ...a }));
         this.file = test.file;
         if (test.line !== undefined)
             this.line = test.line;

package/dist/runner/test-io.d.ts

@@ -1,4 +1,4 @@
-import type { TestError, TestOptions, TestOutputs } from "../types/test.js";
+import type { TestAnnotation, TestError, TestOptions, TestOutputs } from "../types/test.js";
 import type { OutputSink } from "../wait/output-sink.js";
 /**
  * Checks the `inputs` and `outputs` of a `test()` options object and returns them, leaving out an empty or absent
@@ -8,6 +8,10 @@ export declare function validateTestIO(call: string, options: TestOptions): {
     inputs?: Record<string, string>;
     outputs?: string[];
 };
+/** Checks the `annotations` of a `test()` options object and returns them, or nothing when absent or empty */
+export declare function validateTestAnnotations(call: string, options: TestOptions): {
+    annotations?: TestAnnotation[];
+};
 /**
  * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
  * name the test did not declare throws.

package/dist/runner/test-io.js

@@ -45,6 +45,27 @@ export function validateTestIO(call, options) {
     }
     return result;
 }
+/** Checks the `annotations` of a `test()` options object and returns them, or nothing when absent or empty */
+export function validateTestAnnotations(call, options) {
+    const { annotations } = options;
+    if (annotations === undefined)
+        return {};
+    if (!Array.isArray(annotations))
+        throw new Error(`${call}(): annotations must be an array`);
+    for (const note of annotations) {
+        const entry = note;
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            throw new Error(`${call}(): each annotation must be an object with a type`);
+        if (typeof entry.type !== "string" || entry.type === "")
+            throw new Error(`${call}(): an annotation needs a non-empty type`);
+        if (entry.description !== undefined &&
+            typeof entry.description !== "string")
+            throw new Error(`${call}(): the description of annotation "${entry.type}" must be a string`);
+    }
+    return annotations.length > 0
+        ? { annotations: annotations.map((a) => ({ ...a })) }
+        : {};
+}
 /**
  * The `inputs` fixture: each declared input with the value the run supplies, else its default. Reading a
  * name the test did not declare throws.

package/dist/steps/edit.d.ts

@@ -1,3 +1,4 @@
+import type { TestAnnotation } from "../types/test.js";
 import type { Step, TestInput } from "./model.js";
 export type StepEdit = {
     op: "replace";
@@ -34,7 +35,7 @@ export type StepEdit = {
     test: number;
 }
 /**
- * Sets the test's `inputs` and `outputs` in its options object: a given list replaces that list, one left out
+ * Sets the test's `inputs`, `outputs` and `annotations` in its options object: a given list replaces that list, one left out
  * stays. When both end up empty the options object goes, unless it holds a `reason`
  */
  | {
@@ -42,6 +43,7 @@ export type StepEdit = {
     test: number;
     inputs?: TestInput[];
     outputs?: string[];
+    annotations?: TestAnnotation[];
 };
 /**
  * Applies one edit and returns the new source. Only the touched statement changes, plus the test's parameters

package/dist/steps/edit.js

@@ -158,7 +158,7 @@ export function applyEdit(source, edit) {
             return withStep(source, parsed, edit.step, (text, code) => insertCode(text, parsed, edit.index, code));
         case "declare": {
             let next = source;
-            for (const key of ["inputs", "outputs"]) {
+            for (const key of ["inputs", "outputs", "annotations"]) {
                 const list = edit[key];
                 if (list)
                     next = declareList(next, pickTest(next, edit.test), key, list);

package/dist/steps/model.d.ts

@@ -1,4 +1,4 @@
-import type { Modifier } from "../types/test.js";
+import type { Modifier, TestAnnotation } from "../types/test.js";
 /**
  * One call of a locator expression, as written in a spec: `page.getByRole("button", { name: "Save" })`.
  * A RegExp text or name is tested as written, so it never comes with `exact`, `match` or `ignoreCase`.
@@ -264,6 +264,8 @@ export interface ParsedTest {
     inputs?: TestInput[];
     /** The `outputs` of the test's options object; undefined without the key */
     outputs?: string[];
+    /** The `annotations` of the test's options object; undefined without the key or with an empty list */
+    annotations?: TestAnnotation[];
     /** The range of the test's options object (`test(title, { … }, fn)`), when it has one */
     options?: {
         start: number;

package/dist/steps/parse.js

@@ -137,7 +137,7 @@ export function parseSpecFile(source) {
                 return;
             }
             const { callback, options = {}, range } = args;
-            const { reason, inputs, outputs } = options;
+            const { reason, inputs, outputs, annotations } = options;
             const body = callbackBody(callback);
             if (!body) {
                 unparsed.push(unreadable(node, kind, "not-inline"));
@@ -161,6 +161,7 @@ export function parseSpecFile(source) {
                     ...effectiveMark(mark, describes),
                     ...(inputs && { inputs }),
                     ...(outputs && { outputs }),
+                    ...(annotations && { annotations }),
                     ...(range && { options: range }),
                     titleEnd: node.arguments[0].end,
                 });

package/dist/steps/test-options.d.ts

@@ -1,13 +1,15 @@
 import ts from "typescript";
-import type { Modifier } from "../types/test.js";
+import type { Modifier, TestAnnotation } from "../types/test.js";
 import type { ParsedTest, TestInput } from "./model.js";
 /** What a `test()` or `describe()` options object says, as far as the codec reads it */
 export interface TestOptionsRead {
     reason?: string;
     inputs?: TestInput[];
     outputs?: string[];
+    annotations?: TestAnnotation[];
 }
-type ListKey = "inputs" | "outputs";
+type ListKey = "inputs" | "outputs" | "annotations";
+type ListValue = TestInput[] | string[] | TestAnnotation[];
 /**
  * The options object of a test or describe call: a describe takes only `reason`, a test also `inputs` and
  * `outputs`. Undefined when the object isn't a literal the codec can read, so the call is left unparsed. An
@@ -21,5 +23,5 @@ export declare function readTestOptions(node: ts.Expression, kind: "test" | "des
  * the object, its layout and a `reason`, stays as it is; an unchanged list leaves the source as it is. Throws for
  * names the runtime rejects, before writing
  */
-export declare function declareList(source: string, parsed: ParsedTest, key: ListKey, list: TestInput[] | string[]): string;
+export declare function declareList(source: string, parsed: ParsedTest, key: ListKey, list: ListValue): string;
 export {};

package/dist/steps/test-options.js

@@ -33,6 +33,35 @@ function readOutputs(node) {
         ? names
         : undefined;
 }
+/** `[{ type: "plan", description: "…" }, …]`; undefined for anything but string literals under those two keys */
+function readAnnotations(node) {
+    if (!ts.isArrayLiteralExpression(node))
+        return undefined;
+    const notes = [];
+    for (const element of node.elements) {
+        if (!ts.isObjectLiteralExpression(element))
+            return undefined;
+        const note = {};
+        for (const property of element.properties) {
+            if (!ts.isPropertyAssignment(property))
+                return undefined;
+            const key = keyOf(property.name);
+            const value = stringOf(property.initializer);
+            if (value === undefined)
+                return undefined;
+            if (key === "type")
+                note.type = value;
+            else if (key === "description")
+                note.description = value;
+            else
+                return undefined;
+        }
+        if (note.type === undefined || note.type === "")
+            return undefined;
+        notes.push(note);
+    }
+    return notes;
+}
 /**
  * The options object of a test or describe call: a describe takes only `reason`, a test also `inputs` and
  * `outputs`. Undefined when the object isn't a literal the codec can read, so the call is left unparsed. An
@@ -67,13 +96,27 @@ export function readTestOptions(node, kind, modifier) {
             if (outputs.length > 0)
                 read.outputs = outputs;
         }
+        else if (kind === "test" && key === "annotations") {
+            const annotations = readAnnotations(value);
+            if (!annotations)
+                return undefined;
+            if (annotations.length > 0)
+                read.annotations = annotations;
+        }
         else
             return undefined;
     }
     return read;
 }
 const str = (value) => JSON.stringify(value);
+function annotationToSource(note) {
+    return note.description === undefined
+        ? `{ type: ${str(note.type)} }`
+        : `{ type: ${str(note.type)}, description: ${str(note.description)} }`;
+}
 function listToSource(key, list) {
+    if (key === "annotations")
+        return `[${list.map(annotationToSource).join(", ")}]`;
     if (key === "outputs")
         return `[${list.map(str).join(", ")}]`;
     const entries = list.map(({ name, default: value }) => `${IDENTIFIER.test(name) ? name : str(name)}: ${str(value)}`);
@@ -82,6 +125,12 @@ function listToSource(key, list) {
 const sameList = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /** Throws for a list the runtime's `test()` would reject: a name that isn't valid, a name twice, a default that isn't text */
 function checkList(key, list) {
+    if (key === "annotations") {
+        for (const note of list)
+            if (typeof note.type !== "string" || note.type === "")
+                throw new Error(`applyEdit(): an annotation needs a non-empty type`);
+        return;
+    }
     const kind = key === "inputs" ? "input" : "output";
     const seen = new Set();
     for (const entry of list) {

package/dist/types/config.d.ts

@@ -204,6 +204,12 @@ export interface SamuraiTestConfig {
    * @default "files"
    */
   filesDir?: string;
+  /**
+   * Folder, relative to the project folder, where test plans are kept; `samurai plan "<goal>"` without `--out`
+   * writes `<plansDir>/<slug-of-goal>.plan.md`
+   * @default "plans"
+   */
+  plansDir?: string;
   /**
    * The AI agent (`samurai generate`). `model` is a `provider:name` pair, such as `anthropic:claude-sonnet-4-5`;
    * never a key (keys come from the environment). The `--model` flag and `SAMURAI_AI_MODEL` win over it

package/dist/types/test.d.ts

@@ -170,6 +170,8 @@ export interface TestOptions extends TestDetails {
   inputs?: Record<string, string>;
   /** Names of the text values the test saves for later tests to use */
   outputs?: string[];
+  /** Notes on the test, such as `{ type: "plan", description: "plans/pay.plan.md" }`; the report lists them first */
+  annotations?: TestAnnotation[];
 }
 
 /** Runs before or after each test of a suite, in the test's browser, with the test's fixtures */
@@ -225,6 +227,8 @@ export interface RegisteredTestCase extends TestCaseBase {
   inputs?: Record<string, string>;
   /** The names of the outputs the test declared */
   outputs?: string[];
+  /** The annotations the test declared; every run of the test starts with them */
+  annotations?: TestAnnotation[];
   /** Registered with `test.fail("title", fn)`: expected to fail; `description` is the `{ reason }` given */
   expectedFail?: { description?: string };
   /** The custom fixtures of the `test` it was written with (`test.extend()`); absent for the plain `test` */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.22.5",
+  "version": "0.22.7",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {