@itmetsam/samurai-framework 0.22.4 → 0.22.6

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

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

package/dist/agent/generate-kind.js

@@ -0,0 +1,45 @@
+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";
+/** The run of `runAgent`: typed steps go into a spec file */
+export const generateKind = {
+    file: (options) => options.file,
+    sink: (options, { baseURL, emit }) => new StepRecorder({
+        file: options.file,
+        create: options.create,
+        test: options.test,
+        baseURL,
+        planFile: options.planFile,
+        onStep: (event, code, source) => emit({
+            type: "step",
+            event,
+            ...(code !== undefined && { code }),
+            source,
+        }),
+    }),
+    opened: (steps, url) => {
+        if (steps.count === 0)
+            steps.observe({ type: "goto", url });
+    },
+    tools: (context) => createTools(context),
+    prompt: (input, options) => buildSystemPrompt({
+        ...input,
+        ...(options.plan !== undefined && { hasPlan: true }),
+    }),
+    opening: (options, first) => {
+        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,
+        steps: sink,
+        snapshots,
+        ...(baseURL !== undefined && { baseURL }),
+    }),
+};

package/dist/agent/index.d.ts

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

package/dist/agent/index.js

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

package/dist/agent/plan/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/guard.d.ts

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

package/dist/agent/plan/guard.js

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+/** 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>;

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

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync } 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("/");
+    }
+}

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

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

package/dist/agent/plan/prompt.js

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

package/dist/agent/plan/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

@@ -0,0 +1,5 @@
+/**
+ * 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;