@basein/runner 0.3.27 → 0.3.28

package/README.md

@@ -423,6 +423,19 @@ bir scenario edit  scn_… --param database --kind setting --note "why"   # use
 bir scenario undo  scn_… --param database                  # take that back
 ```
 
+**The learning phase.** Not yet released. A new plan is in its learning phase
+until 10 of its runs were evaluated (1 to 50, per plan). In it the service tries
+one change at a time and keeps it only when the plan got better: successful
+runs first, then cost, then speed. `bir scenario show` ends with where it
+stands; `bir scenario edits` lists its changes under their `simp_` ids
+([the guide's §9.3](docs/calculatedReplayGuide.md)):
+
+```bash
+bir scenario learning scn_…                                # runs evaluated, the measures now, the changes tried
+bir scenario learning scn_… --runs 20                      # learn for 20 runs; --stop ends it, --again starts anew
+bir scenario undo     scn_… --edit simp_…                  # take back a change the learning phase made
+```
+
 ---
 
 ## Two things to know before you turn it on

package/dist/bin/bir-scenario.js

@@ -596,7 +596,8 @@ const SCENARIO_TOOLS = [
         description: "List a calculated scenario's hand edits, newest first — step edits and parameter kind changes: step or " +
             "parameter, note, revision, and whether each was forced, undone or replaced by a recalculation — and the " +
             "corrections the service made from a run the agent redid (scor_ ids): what each added, tested or changed, " +
-            "and whether it is used.",
+            "and whether it is used — and the changes its learning phase made (simp_ ids): what each changed and why, " +
+            "and whether it is on trial, kept or taken back.",
         inputSchema: {
             type: "object",
             properties: { target: TARGET },
@@ -746,14 +747,15 @@ const SCENARIO_TOOLS = [
             "one further back. The service checks a step's undo like a save and refuses it when a later step or the final " +
             "answer would break — `force` with a `note` undoes it anyway. To redo, undo the undo: pass its id as `edit` (the " +
             "answer names it). A scor_ id takes back a correction the service made: the plan goes back exactly as it was " +
-            "before it, and is held — not used — until it is corrected again or let go on the recording page.",
+            "before it, and is held — not used — until it is corrected again or let go on the recording page. A simp_ id " +
+            "takes back a change the plan's learning phase made, by its id only: the plan goes back exactly as it was before it.",
         inputSchema: {
             type: "object",
             properties: {
                 target: TARGET,
                 edit: {
                     type: "string",
-                    description: "The sedit_, pedit_ or scor_ id to undo, as scenario_edits lists it. Not with `step` or `param`.",
+                    description: "The sedit_, pedit_, scor_ or simp_ id to undo, as scenario_edits lists it. Not with `step` or `param`.",
                 },
                 step: {
                     ...STEP,
@@ -779,8 +781,8 @@ const SCENARIO_TOOLS = [
                 throw new BadArguments("`edit`, `step` and `param` each pick what to undo; give one of them");
             }
             if (a.edit !== undefined && a.edit !== null) {
-                if (typeof a.edit !== "string" || !/^(sedit|pedit|scor)_[\w-]+$/.test(a.edit)) {
-                    throw new BadArguments("`edit` must be a sedit_…, pedit_… or scor_… id");
+                if (typeof a.edit !== "string" || !/^(sedit|pedit|scor|simp)_[\w-]+$/.test(a.edit)) {
+                    throw new BadArguments("`edit` must be a sedit_…, pedit_… or scor_… id, or a learning change's simp_… id");
                 }
                 if (a.step !== undefined && a.step !== null) {
                     throw new BadArguments("`edit` names one entry and `step` picks one; give one of them");

package/dist/bin/bir.js

@@ -123,10 +123,16 @@ Commands:
                                     a target must be named by the prompt or the plan is
                                     declined; a setting uses its recorded value when the
                                     prompt names none (needs --note)
-  scenario edits <runId|scnId>      a scenario's hand edits, newest first
+  scenario edits <runId|scnId>      a scenario's hand edits, corrections and learning changes,
+                                    newest first
   scenario undo <runId|scnId> [--edit <id> | --step <n> | --param <name>] [--force --note "why"]
                                     take back the newest edit (of step n, or parameter name);
                                     run it again to go one further back; undo an undo's id to redo
+  scenario learning <runId|scnId> [--runs <n>] [--stop] [--again]
+                                    a plan's learning phase: runs evaluated, the measures of its
+                                    revision now, what the last run showed, the changes tried
+                                    (--runs: how many runs it lasts, 1–50; --stop: end it now;
+                                    --again: start a new one)
   scenario editing on|off|status    whether this project's bir MCP server offers the tools
                                     that read and change a scenario (restart Claude Code after);
                                     \`bir setup\` turns it on, and an off stays off
@@ -159,7 +165,7 @@ Options:
   --port <n>        install/setup: control-server port to write into the hook URLs
                     (default: this project's, else the lowest free one from ${DEFAULT_CONTROL_PORT})
   --json            machine-readable output for status / doctor / scenario / investigate
-                    (scenario check|edit|edits|undo: the service's answer, unchanged)
+                    (scenario check|edit|edits|undo|learning: the service's answer, unchanged)
   --dry             replay against recorded outputs only; run no real tools
   --force           scenario calc: recalculate in place · scenario edit: save although
                     the check refused it (needs --note; only for a recording that was wrong)
@@ -171,12 +177,17 @@ Options:
   --unfreeze        scenario check|edit: ask to remove that mark; the check decides
   --note <text>     scenario edit|undo: why, kept in the history (required with --force)
   --revision <n>    scenario edit|undo: only if the plan is still at this chainRevision
-  --edit <id>       scenario undo: the sedit_, pedit_ or scor_ id to undo (default: the newest
-                    that can be); a scor_ id puts back the plan from before that correction
+  --edit <id>       scenario undo: the sedit_, pedit_, scor_ or simp_ id to undo (default: the newest
+                    that can be); a scor_ id puts back the plan from before that correction,
+                    a simp_ id the plan from before that learning change
   --param <name>    scenario edit: the parameter whose kind changes · scenario undo: its newest change
   --kind <kind>     scenario edit --param: target (a prompt must name it) or setting (its
                     recorded value is used when a prompt names none; needs --note)
   --discard-edits   scenario calc --force: recalculate a plan with hand edits, replacing them
+  --runs <n>        scenario learning: how many evaluated runs the learning phase lasts (1–50);
+                    with --again, how many the new one lasts
+  --stop            scenario learning: end the learning phase now
+  --again           scenario learning: start a new learning phase
   --no-browser      login: print the link and code, open nothing (SSH, headless)
   --token <value>   login: redeem a one-time setup token from the console (no browser)
   --password        login: use the old email/password prompt (deprecated)
@@ -222,6 +233,8 @@ function parseArgs(argv) {
         freeze: false,
         unfreeze: false,
         discardEdits: false,
+        stop: false,
+        again: false,
         here: false,
         all: false,
         quick: false,
@@ -402,6 +415,21 @@ function parseArgs(argv) {
                 if (!args.kind)
                     usage(2);
                 break;
+            case "--runs": {
+                // Digits only, as --step: the range (1–50) is scenario-edit.ts's to
+                // explain in words.
+                const raw = argv[++i] ?? "";
+                if (!/^\d+$/.test(raw))
+                    usage(2);
+                args.runs = Number(raw);
+                break;
+            }
+            case "--stop":
+                args.stop = true;
+                break;
+            case "--again":
+                args.again = true;
+                break;
             case "--here":
                 args.here = true;
                 break;
@@ -3622,6 +3650,9 @@ async function scenarioCommand(args) {
             discardEdits: args.discardEdits,
             param: args.param,
             kind: args.kind,
+            runs: args.runs,
+            stop: args.stop,
+            again: args.again,
         }, {
             cwd: process.cwd(),
             out,
@@ -3640,7 +3671,7 @@ async function scenarioCommand(args) {
     if (sub === "replay") {
         return replayCommand({ ...args, scenarioId: args.scenarioId ?? target });
     }
-    out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|replay> …");
+    out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|learning|replay> …");
     return 2;
 }
 /**

package/dist/bin/scenario-edit.d.ts

@@ -8,8 +8,9 @@
  *                      [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>]
  *   bir scenario edit  <runId|scnId> --param <name> --kind target|setting [--note "why"] [--revision <n>]
  *   bir scenario edits <runId|scnId>
- *   bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id> | --step <n> | --param <name>] [--force --note "why"]
+ *   bir scenario undo  <runId|scnId> [--edit <sedit_id|pedit_id|scor_id|simp_id> | --step <n> | --param <name>] [--force --note "why"]
  *   bir scenario calc  <runId|scnId> [--force [--discard-edits]]
+ *   bir scenario learning <runId|scnId> [--runs <n>] [--stop] [--again]
  *   bir scenario editing on|off|status
  *
  * WHY THIS IS A CLIENT AND NOTHING MORE. Whether a change may be saved is
@@ -214,6 +215,12 @@ export interface ScenarioEditArgs {
     param?: string;
     /** `edit --kind target|setting`, with `--param`. Checked here, so any word reaches the usage line. */
     kind?: string;
+    /** `learning --runs <n>`: how many evaluated runs the plan's learning phase lasts (1–50). */
+    runs?: number;
+    /** `learning --stop`: end the learning phase now. */
+    stop?: boolean;
+    /** `learning --again`: start a new learning phase (of `runs`, when given). */
+    again?: boolean;
 }
 /** The `bir scenario` words this module answers; `list` and `replay` stay in bir.ts. */
 export declare const SCENARIO_EDIT_SUBCOMMANDS: ReadonlySet<string>;
@@ -295,5 +302,99 @@ export declare function newestUndoableParam(paramEdits: ParamEditEntry[], param?
  * when `--step` or `--param` narrows the undo to a step or a parameter.
  */
 export declare function newestUndoableCorrection(corrections: CorrectionEntry[]): CorrectionEntry | undefined;
+/** What a learning-phase change aims to make better (the service's learningPhase.md). */
+export type LearningAim = "successful" | "cost" | "speed";
+/** The three measures of one revision of a plan: successful runs, cost, speed. */
+export interface LearningMeasures {
+    evaluated: number;
+    successful: number;
+    successShare: number | null;
+    /** Median cost ÷ the original cost, over the successful measured runs. */
+    costRatio: number | null;
+    /** Median time ÷ the original time, over the successful runs. */
+    speedRatio: number | null;
+}
+/** A problem the service's rules found in a run (P1–P10). */
+export interface LearningProblem {
+    code: string;
+    aim: LearningAim | string;
+    /** One plain sentence. */
+    text: string;
+    step: number | null;
+}
+/** One change of a plan in its learning phase: `simp_` + uuid. Only what is printed is read. */
+export interface LearningChange {
+    id: string;
+    createdAt: string;
+    aim: LearningAim | string;
+    /** One sentence: what changed and why. */
+    summary: string;
+    state: "proposed" | "trial" | "kept" | "taken_back" | "failed_check" | "dismissed" | "replaced" | string;
+    revisionBefore?: number;
+    revisionAfter?: number | null;
+    /** One sentence with the numbers, once it was kept or taken back. */
+    decision?: string | null;
+}
+/** `GET /scenarios/:id/learning`'s `learning`: the phase, its measures, its problems and its changes. */
+export interface LearningView {
+    scenarioId?: string;
+    /** Null: the plan never had a learning phase. */
+    state: "learning" | "done" | "stopped" | null;
+    mode?: "off" | "count" | "observe" | "on" | string;
+    phase?: number;
+    runs: number;
+    evaluated: number;
+    revision?: number;
+    trial: {
+        changeId: string;
+        needed: number;
+        done: number;
+    } | null;
+    measures?: {
+        current: LearningMeasures | null;
+        start: LearningMeasures | null;
+    };
+    changes?: LearningChange[];
+    problems?: LearningProblem[];
+}
+/** A scenario's `learning`, as `GET /scenarios/:id` serves it beside the plan. */
+export interface LearningBrief {
+    state: "learning" | "done" | "stopped";
+    runs: number;
+    evaluated: number;
+    trial: {
+        changeId: string;
+        needed: number;
+        done: number;
+    } | null;
+    /** Changes proposed and waiting for the owner. */
+    waiting: number;
+}
+/** A learning-phase change in `GET /scenarios/:id/edits`'s `learning`. */
+export interface LearningEditEntry {
+    id: string;
+    createdAt: string;
+    state: LearningChange["state"];
+    aim: LearningAim | string;
+    summary: string;
+    revisionBefore: number;
+    revisionAfter: number | null;
+}
+/**
+ * The learning phase in one line (the service's learningPhase.md LP1, LP9):
+ * "Learning: 4 of 10 runs evaluated · change 2 on trial (1 of 2 runs)",
+ * "Learning done after 10 runs", "Learning stopped after 4 runs", or "No
+ * learning phase". `changes`, when known, give the change on trial its
+ * number, oldest first; `waiting`, the changes that wait for their owner.
+ */
+export declare function learningLine(l: Partial<Pick<LearningView, "state" | "runs" | "evaluated" | "trial">> | null | undefined, changes?: ReadonlyArray<Partial<LearningChange>>, waiting?: number | null): string;
+/**
+ * A revision's three measures in one line, leaving out what is not known:
+ * "Successful 4 of 6 · cost 40% under the original · time 35% under the
+ * original". Undefined when none is.
+ */
+export declare function measuresLine(m: Partial<LearningMeasures> | null | undefined): string | undefined;
+/** The second line of a learning change in `edits`: what it did, what for, and what became of it. */
+export declare function learningEditSummary(c: LearningEditEntry): string;
 export {};
 //# sourceMappingURL=scenario-edit.d.ts.map