@itmetsam/samurai-framework 0.22.6 → 0.22.7

package/dist/agent/index.d.ts

@@ -1,8 +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 { parsePlan, type ParsedPlan } from "./plan/plan-file.js";
-export { defaultPlanFile } from "./plan/plan-path.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,8 +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 { parsePlan } from "./plan/plan-file.js";
-export { defaultPlanFile } from "./plan/plan-path.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/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;
@@ -14,12 +15,35 @@ interface ParsedPlan {
     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.
@@ -52,7 +76,7 @@ declare class PlanFile {
     /** Writes the first version of the file */
     create(): void;
 }
-export type { PlanFile, ParsedPlan };
+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;

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

@@ -16,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.
@@ -48,37 +90,19 @@ class PlanFile {
         }
     }
     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");
+        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(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);
     }
@@ -167,6 +191,7 @@ export function parsePlan(text) {
         seen: [],
         notDone: [],
         questions: [],
+        questionList: [],
         answers: [],
     };
     let section;
@@ -215,13 +240,18 @@ export function parsePlan(text) {
         const asked = plan.questions[plan.questions.length - 1];
         if (answer) {
             const text = answer[1].trim();
-            if (asked !== undefined && text !== "")
+            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

@@ -6,3 +6,8 @@ export declare function slugOf(goal: string): string;
  * 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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+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";
@@ -44,3 +44,19 @@ export async function defaultPlanFile(goal) {
                 .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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.22.6",
+  "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": {