@basein/runner 0.3.27 → 0.3.28

package/dist/bin/scenario-edit.js

@@ -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
@@ -47,6 +48,7 @@ export const SCENARIO_EDIT_SUBCOMMANDS = new Set([
     "edits",
     "undo",
     "calc",
+    "learning",
     "editing",
 ]);
 /**
@@ -73,8 +75,9 @@ const USAGE = {
         '                          [--freeze | --unfreeze] [--note "why"] [--force --note "why"] [--revision <n>] [--json]\n' +
         '       bir scenario edit <runId|scnId> --param <name> --kind target|setting [--note "why"] [--revision <n>] [--json]',
     edits: "usage: bir scenario edits <runId|scnId> [--json]",
-    undo: 'usage: bir scenario undo <runId|scnId> [--edit <sedit_id|pedit_id|scor_id> | --step <n> | --param <name>] [--force --note "why"] [--json]',
+    undo: 'usage: bir scenario undo <runId|scnId> [--edit <sedit_id|pedit_id|scor_id|simp_id> | --step <n> | --param <name>] [--force --note "why"] [--json]',
     calc: "usage: bir scenario calc <runId|scnId> [--force [--discard-edits]]",
+    learning: "usage: bir scenario learning <runId|scnId> [--runs <n>] [--stop] [--again] [--json]",
     editing: "usage: bir scenario editing on|off|status",
 };
 export async function scenarioEditCommand(args, deps) {
@@ -91,10 +94,12 @@ export async function scenarioEditCommand(args, deps) {
             return undo(args, deps);
         case "calc":
             return calc(args, deps);
+        case "learning":
+            return learning(args, deps);
         case "editing":
             return editing(args, deps);
         default:
-            deps.out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|replay> …");
+            deps.out("usage: bir scenario <list|show|calc|check|edit|edits|undo|editing|learning|replay> …");
             return 2;
     }
 }
@@ -124,6 +129,13 @@ async function show(args, deps) {
     }
     if (args.step === undefined) {
         out(jsonText(reply.body));
+        // Under the plan, the learning phase in one line (the service's
+        // learningPhase.md LP9) — for a person. Never with --json: scripts and
+        // the `bir` MCP server read this output as JSON, which carries the same
+        // facts as `learning`.
+        const line = args.json ? undefined : learningOfShown(reply.body);
+        if (line)
+            out(line);
         return 0;
     }
     const served = reply.body;
@@ -618,17 +630,18 @@ function refusal(out, report, opening, hint) {
 }
 /**
  * The service's history: step edits, and — from a service that has them —
- * kind changes and corrections (autocorrect.md AC7). An older service sends
- * neither list, and there is nothing of them to print.
+ * kind changes, corrections (autocorrect.md AC7) and the learning phase's
+ * changes (learningPhase.md LP9). An older service sends none of those lists,
+ * and there is nothing of them to print.
  */
 function historyOf(body) {
     const b = body;
+    const entries = (list) => Array.isArray(list) ? list.filter((c) => typeof c?.id === "string" && typeof c?.createdAt === "string") : [];
     return {
         edits: Array.isArray(b?.edits) ? b.edits : [],
         paramEdits: Array.isArray(b?.paramEdits) ? b.paramEdits : [],
-        corrections: Array.isArray(b?.corrections)
-            ? b.corrections.filter((c) => typeof c?.id === "string" && typeof c?.createdAt === "string")
-            : [],
+        corrections: entries(b?.corrections),
+        learning: entries(b?.learning),
     };
 }
 async function fetchEdits(scenarioId, deps) {
@@ -656,16 +669,16 @@ async function listEdits(args, deps) {
         out(jsonText(reply.body));
         return 0;
     }
-    const { edits, paramEdits, corrections } = historyOf(reply.body);
-    if (edits.length === 0 && paramEdits.length === 0 && corrections.length === 0) {
+    const { edits, paramEdits, corrections, learning } = historyOf(reply.body);
+    if (edits.length === 0 && paramEdits.length === 0 && corrections.length === 0 && learning.length === 0) {
         out(`No hand edits of ${target}.`);
         return 0;
     }
     // Ids are printed whole: they are what `undo --edit` takes. The detail line
     // is indented rather than aligned under the date, which a 42-character id
     // would push past most terminals' width. One list, newest first: a step's
-    // edits, a parameter's kind changes and the service's corrections of the
-    // plan are walked back by the same `undo`.
+    // edits, a parameter's kind changes, the service's corrections of the plan
+    // and its learning phase's changes are walked back by the same `undo`.
     const noteOf = (note) => (note ? `  "${note.replace(/\s+/g, " ")}"` : "");
     const rows = [
         ...edits.map((e) => ({
@@ -683,6 +696,11 @@ async function listEdits(args, deps) {
             line: `${c.id}  ${when(c.createdAt)}  correction  ${String(c.state).padEnd(8)} revision ${c.chainRevisionBefore ?? "?"} → ${c.chainRevisionAfter ?? "—"}`,
             detail: correctionSummary(c),
         })),
+        ...learning.map((c) => ({
+            at: c.createdAt,
+            line: `${c.id}  ${when(c.createdAt)}  learning  ${String(c.state).padEnd(STATE_WIDTH)} revision ${c.revisionBefore ?? "?"} → ${c.revisionAfter ?? "—"}`,
+            detail: learningEditSummary(c),
+        })),
     ].sort((x, y) => (x.at < y.at ? 1 : x.at > y.at ? -1 : 0));
     for (const r of rows) {
         out(r.line);
@@ -828,13 +846,15 @@ export function newestUndoableCorrection(corrections) {
 }
 const isParamEditId = (id) => id.startsWith("pedit_");
 const isCorrectionId = (id) => id.startsWith("scor_");
+/** A change a learning phase made (the service's learningPhase.md LP9). */
+const isLearningId = (id) => id.startsWith("simp_");
 async function undo(args, deps) {
     const { out } = deps;
     const target = args.positionals[1];
     if (!target)
         return usageError(deps, "undo");
-    if (args.edit !== undefined && !/^(sedit|pedit|scor)_[\w-]+$/.test(args.edit)) {
-        return usageError(deps, "undo", `--edit takes a sedit_…, pedit_… or scor_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
+    if (args.edit !== undefined && !/^(sedit|pedit|scor|simp)_[\w-]+$/.test(args.edit)) {
+        return usageError(deps, "undo", `--edit takes a sedit_…, pedit_… or scor_… id, or a learning change's simp_… id, as \`bir scenario edits\` prints it; got ${args.edit}.`);
     }
     const picks = [args.edit, args.step, args.param].filter((v) => v !== undefined).length;
     if (picks > 1) {
@@ -872,11 +892,18 @@ async function undo(args, deps) {
         ];
         const pick = candidates.sort((x, y) => (x.at < y.at ? 1 : x.at > y.at ? -1 : 0))[0];
         if (!pick) {
+            // A learning phase's change is the service's, and is taken back by its
+            // id alone (learningPhase.md LP9): a plain undo leaves it be, and says
+            // how, when one is in use.
+            const learned = args.step === undefined && args.param === undefined ? newestUsedLearning(listed.learning) : undefined;
             return localFailure(args, deps, "nothing_to_undo", args.step !== undefined
                 ? `Nothing to undo: step ${args.step} of ${target} has no hand edit that can be undone.`
                 : args.param !== undefined
                     ? `Nothing to undo: parameter ${args.param} of ${target} has no kind change that can be undone.`
-                    : `Nothing to undo: ${target} has no hand edit that can be undone.`);
+                    : `Nothing to undo: ${target} has no hand edit that can be undone.` +
+                        (learned
+                            ? ` Its learning phase's change ${learned.id} (${learned.state}) is taken back by its id: bir scenario undo ${target} --edit ${learned.id}`
+                            : ""));
         }
         editId = pick.id;
     }
@@ -907,6 +934,8 @@ async function undo(args, deps) {
         return paramUndone(reply.body, editId, target, args, deps);
     if (isCorrectionId(editId))
         return correctionUndone(reply.body, editId, target, deps);
+    if (isLearningId(editId))
+        return learningUndone(reply.body, editId, target, deps);
     if (answer?.report)
         renderReport(out, answer.report, { brief: true, undo: true });
     if (refused && answer?.report) {
@@ -964,6 +993,250 @@ function paramUndone(answer, editId, target, args, deps) {
     deps.out(`  One further back: bir scenario undo ${target}${further}`);
     return 0;
 }
+/** A whole count the service sent, or null for anything else. */
+const count = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.round(value) : null;
+const runsWord = (n) => `${n} run${n === 1 ? "" : "s"}`;
+/** One line of the service's text: no line breaks, no runs of spaces. */
+const oneLine = (text) => (typeof text === "string" ? text.replace(/\s+/g, " ").trim() : "");
+/**
+ * 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 function learningLine(l, changes, waiting) {
+    if (!l || (l.state !== "learning" && l.state !== "done" && l.state !== "stopped"))
+        return "No learning phase";
+    const evaluated = count(l.evaluated) ?? 0;
+    if (l.state === "done")
+        return `Learning done after ${runsWord(evaluated)}`;
+    if (l.state === "stopped")
+        return `Learning stopped after ${runsWord(evaluated)}`;
+    const parts = [`Learning: ${evaluated} of ${count(l.runs) ?? "?"} runs evaluated`];
+    const trial = l.trial && typeof l.trial === "object" ? l.trial : undefined;
+    if (trial) {
+        const at = changes ? changes.findIndex((c) => c?.id === trial.changeId) : -1;
+        const needed = count(trial.needed);
+        parts.push(`${at >= 0 ? `change ${at + 1}` : "a change"} on trial` +
+            (needed !== null ? ` (${count(trial.done) ?? 0} of ${runsWord(needed)})` : ""));
+    }
+    const wait = count(waiting);
+    if (wait)
+        parts.push(`${wait} change${wait === 1 ? "" : "s"} waiting for you`);
+    return parts.join(" · ");
+}
+/** "cost 40% under the original", from a ratio to the original; undefined for none. */
+function ratioWords(what, ratio) {
+    if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio < 0)
+        return undefined;
+    const pct = Math.round(Math.abs(1 - ratio) * 100);
+    if (pct === 0)
+        return `${what} the same as the original`;
+    return `${what} ${pct}% ${ratio < 1 ? "under" : "over"} the original`;
+}
+/**
+ * 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 function measuresLine(m) {
+    if (!m || typeof m !== "object")
+        return undefined;
+    const parts = [];
+    const evaluated = count(m.evaluated);
+    const successful = count(m.successful);
+    if (evaluated !== null && evaluated > 0 && successful !== null)
+        parts.push(`Successful ${successful} of ${evaluated}`);
+    const cost = ratioWords("cost", m.costRatio);
+    if (cost)
+        parts.push(cost);
+    const time = ratioWords("time", m.speedRatio);
+    if (time)
+        parts.push(time);
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+/** The width a learning change's state is padded to, beside its id, in `learning` (and `edits`). */
+const STATE_WIDTH = 12;
+/** The scenario's learning line for `show`: from `scenario.learning`, when the service sent one. */
+function learningOfShown(body) {
+    const scenario = body?.scenario;
+    const brief = scenario?.learning;
+    if (!brief || typeof brief !== "object")
+        return undefined;
+    if (brief.state !== "learning" && brief.state !== "done" && brief.state !== "stopped")
+        return undefined;
+    const view = scenario?.learningView;
+    return learningLine(brief, Array.isArray(view?.changes) ? view.changes : undefined, brief.waiting);
+}
+/**
+ * The learning phase as a person reads it: its line, the three measures of
+ * the revision the plan is at, the problems the last evaluated run showed,
+ * and the changes — each with its id, which `bir scenario undo --edit` takes.
+ */
+function renderLearning(out, view, target) {
+    const changes = Array.isArray(view.changes) ? view.changes.filter((c) => c && typeof c.id === "string") : [];
+    const waiting = changes.filter((c) => c.state === "proposed").length;
+    out(learningLine(view, changes, waiting));
+    if (view.state !== "learning" && view.state !== "done" && view.state !== "stopped") {
+        out(view.mode === "off"
+            ? "  The service's learning phase is switched off (SCENARIO_LEARNING=off): no plan learns."
+            : `  To start one: bir scenario learning ${target} --again [--runs <n>]`);
+        return;
+    }
+    const revision = count(view.revision);
+    const measures = measuresLine(view.measures?.current);
+    out(`  ${revision !== null ? `Revision ${revision}` : "Now"}: ${measures ?? "no run of it evaluated yet"}`);
+    const problems = Array.isArray(view.problems) ? view.problems.filter((p) => p && typeof p.text === "string") : [];
+    if (problems.length > 0) {
+        out("  Found in the last run:");
+        for (const p of problems) {
+            const step = count(p.step);
+            out(`    ${p.code ?? "?"}  ${oneLine(p.text)}${step !== null ? ` (step ${step})` : ""}`);
+        }
+    }
+    if (changes.length > 0) {
+        out("  Changes:");
+        for (const c of changes) {
+            const decision = oneLine(c.decision);
+            out(`    ${c.id}  ${String(c.state ?? "?").padEnd(STATE_WIDTH)} ${String(c.aim ?? "?").padEnd(10)} ${oneLine(c.summary)}` +
+                (decision ? ` — ${decision}` : ""));
+        }
+        if (waiting > 0)
+            out('  A proposed change is tried when you press "Use" on the recording page.');
+    }
+}
+/** The second line of a learning change in `edits`: what it did, what for, and what became of it. */
+export function learningEditSummary(c) {
+    const parts = [];
+    const summary = oneLine(c.summary);
+    if (summary)
+        parts.push(summary);
+    if (c.aim)
+        parts.push(`aims at ${c.aim === "successful" ? "successful runs" : c.aim}`);
+    switch (c.state) {
+        case "proposed":
+            parts.push('shown, not used yet — "Use" on the recording page tries it');
+            break;
+        case "trial":
+            parts.push("on trial: the next runs decide whether it is kept");
+            break;
+        case "kept":
+            parts.push("kept");
+            break;
+        case "taken_back":
+            parts.push("taken back");
+            break;
+        case "failed_check":
+            parts.push("not used: its check failed");
+            break;
+        case "dismissed":
+            parts.push("dismissed");
+            break;
+        case "replaced":
+            parts.push("replaced by a recalculation");
+            break;
+        default:
+            if (c.state)
+                parts.push(String(c.state));
+    }
+    return parts.join("; ");
+}
+/** The learning change a plain `undo` would name, when nothing else can be undone: the newest in use. */
+function newestUsedLearning(learning) {
+    return [...learning]
+        .filter((c) => c.state === "trial" || c.state === "kept")
+        .sort((x, y) => (x.createdAt < y.createdAt ? 1 : x.createdAt > y.createdAt ? -1 : 0))[0];
+}
+/** A learning change taken back: the plan as it was before it, and where the phase stands now. */
+function learningUndone(answer, editId, target, deps) {
+    const change = answer?.change;
+    const revision = answer?.chainRevision ?? change?.revisionAfter;
+    deps.out(`The plan is back as it was before learning change ${change?.id ?? editId} (revision ${revision ?? "?"}).`);
+    const summary = oneLine(change?.summary);
+    if (summary)
+        deps.out(`  It was: ${summary}`);
+    deps.out(`  The learning phase now: bir scenario learning ${target}`);
+    return 0;
+}
+/**
+ * `bir scenario learning <id>` (the service's learningPhase.md LP9): the plan's
+ * learning phase — from its calculation until N of its runs were evaluated,
+ * in which the service improves it one change at a time. Without a flag it
+ * only reads. `--runs <n>` sets N (1–50), `--stop` ends the phase now,
+ * `--again` starts a new one (of `--runs` runs, when given). Each change is
+ * the service's; this prints what it answers, in words, or unchanged with
+ * `--json`.
+ */
+async function learning(args, deps) {
+    const { out } = deps;
+    const target = args.positionals[1];
+    if (!target)
+        return usageError(deps, "learning");
+    if (args.stop && (args.runs !== undefined || args.again)) {
+        return usageError(deps, "learning", "--stop ends the learning phase, and --runs and --again are for one that goes on; give one of them.");
+    }
+    if (args.runs !== undefined && (!Number.isInteger(args.runs) || args.runs < 1 || args.runs > 50)) {
+        return usageError(deps, "learning", `--runs takes a number from 1 to 50: how many evaluated runs the learning phase lasts; got ${args.runs}.`);
+    }
+    const body = args.stop
+        ? { stop: true }
+        : args.again
+            ? { again: true, ...(args.runs !== undefined ? { runs: args.runs } : {}) }
+            : args.runs !== undefined
+                ? { runs: args.runs }
+                : undefined;
+    // A read is two requests for a `run_` id — which scenario, then its phase —
+    // inside one bound, as `edits` reads; a change has no such bound.
+    const clock = new ReadClock();
+    const resolved = await resolveTarget(target, args, deps, body ? undefined : clock);
+    if ("code" in resolved)
+        return resolved.code;
+    const path = `/scenarios/${seg(resolved.id)}/learning`;
+    const reply = body ? await deps.service("POST", path, body) : await clock.within(deps.service("GET", path));
+    if ("error" in reply || reply.status !== 200)
+        return explainLearning(reply, args, deps, target, Boolean(body));
+    if (args.json) {
+        out(jsonText(reply.body));
+        return 0;
+    }
+    const view = reply.body?.learning;
+    if (!view || typeof view !== "object") {
+        out("The service answered without the learning phase.");
+        return 1;
+    }
+    renderLearning(out, view, target);
+    return 0;
+}
+/**
+ * The learning routes' refusals in words (contract: 400 `invalid_input`; 409
+ * `not_ready`, `builtin`, `learning_off`); everything else as {@link explain}
+ * says it. A 404 without the service's own code is a service older than the
+ * learning phase.
+ */
+function explainLearning(reply, args, deps, target, change) {
+    const verb = change ? "Not changed" : "Could not read the learning phase";
+    if (!("error" in reply) && !args.json) {
+        const code = reply.body?.error;
+        if (reply.status === 404 && code !== "not_found") {
+            deps.out(`${verb}: the service does not know the learning phase yet — it is older than this runner.`);
+            return 1;
+        }
+        if (code === "builtin") {
+            deps.out(`${verb} (builtin): a built-in plan (Update bir, Remove bir) has no learning phase.`);
+            return 1;
+        }
+        if (code === "learning_off") {
+            deps.out(`${verb} (learning_off): the service's learning phase is switched off (SCENARIO_LEARNING=off), so no plan learns.`);
+            return 1;
+        }
+    }
+    return explain(reply, args, deps, {
+        verb,
+        target,
+        notFound: `No such scenario, or it is not yours: ${target}.`,
+    });
+}
 // ── calc ──────────────────────────────────────────────────────────────────────
 /**
  * `calc` lives here because of one answer: a recalculation rebuilds every
@@ -1176,6 +1449,8 @@ function explain(reply, args, deps, e) {
     const aboutParam = e.param !== undefined || (e.editId?.startsWith("pedit_") ?? false);
     // A correction (autocorrect.md AC7) is about the whole plan.
     const aboutCorrection = e.editId?.startsWith("scor_") ?? false;
+    // So is a learning phase's change (learningPhase.md LP9).
+    const aboutLearning = e.editId?.startsWith("simp_") ?? false;
     if (reply.status === 404) {
         out(e.notFound ??
             `${e.verb} (not_found): no such scenario, step or edit — or it is not yours. Only a scenario's owner can see or change it.`);
@@ -1216,18 +1491,38 @@ function explain(reply, args, deps, e) {
             return 1;
         case "revision_changed": {
             const now = typeof body.chainRevision === "number" ? ` — it is at revision ${body.chainRevision} now` : "";
-            out(aboutParam
-                ? `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}\`), then try again.`
-                : `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
+            out(aboutLearning
+                ? `${e.verb} (revision_changed): the plan changed since it was read${now}. \`bir scenario edits ${target}\` lists what changed it; then try again.`
+                : aboutParam
+                    ? `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}\`), then try again.`
+                    : `${e.verb} (revision_changed): the plan changed since it was read${now}. Show it again (\`bir scenario show ${target}${stepFlag}\`), check again, then save again.`);
             return 1;
         }
+        case "not_latest_change": {
+            // A learning change is taken back exactly — the whole plan from before
+            // it — so only while no later change stands on it (learningPhase.md LP6).
+            const b = body;
+            const latest = typeof b.latestChangeId === "string" ? b.latestChangeId : typeof b.latestEditId === "string" ? b.latestEditId : undefined;
+            if (latest) {
+                out(`${e.verb} (not_latest_change): the plan has changed since ${e.editId ?? "that change"} — ${latest} changed it after. Take back the newer one first, then this one:`);
+                out(`  bir scenario undo ${target} --edit ${latest}`);
+                out(`  bir scenario undo ${target} --edit ${e.editId ?? "<this change>"}`);
+            }
+            else {
+                out(`${e.verb} (not_latest_change): the plan has changed since ${e.editId ?? "that change"}. Take back the newer change first — \`bir scenario edits ${target}\` lists them, newest first.`);
+            }
+            return 1;
+        }
+        case "not_used":
+            out(`${e.verb} (not_used): ${e.editId ?? "that change"} was never used — it is proposed, dismissed or failed its check — so the plan never ran it, and there is nothing to take back.`);
+            return 1;
         case "not_latest_edit": {
             // Undo walks back (D9), so this is a real way through now: undoing the
             // newer entry puts the step back as this one left it, and then this one
             // can be undone. It used to loop, when undo only toggled (C23).
             const latest = typeof body.latestEditId === "string" ? body.latestEditId : "<the newer edit>";
-            out(aboutCorrection
-                ? `${e.verb} (not_latest_edit): the plan has changed since that correction — ${latest} changed it after. Undo the newer one first, then this one:`
+            out(aboutCorrection || aboutLearning
+                ? `${e.verb} (not_latest_edit): the plan has changed since that ${aboutLearning ? "change" : "correction"} — ${latest} changed it after. Undo the newer one first, then this one:`
                 : `${e.verb} (not_latest_edit): the ${aboutParam ? "parameter" : "step"} has changed since that edit — ${latest} changed it after. Undo the newer one first, then this one:`);
             out(`  bir scenario undo ${target} --edit ${latest}`);
             out(`  bir scenario undo ${target} --edit ${e.editId ?? "<this edit>"}`);
@@ -1235,8 +1530,8 @@ function explain(reply, args, deps, e) {
         }
         case "already_undone": {
             const by = typeof body.revertedById === "string" ? body.revertedById : undefined;
-            if (aboutCorrection) {
-                out(`${e.verb} (already_undone): ${e.editId ?? "that correction"} was taken back already; \`bir scenario edits ${target}\` lists what the plan has now.`);
+            if (aboutCorrection || aboutLearning) {
+                out(`${e.verb} (already_undone): ${e.editId ?? (aboutLearning ? "that change" : "that correction")} was taken back already; \`bir scenario edits ${target}\` lists what the plan has now.`);
                 return 1;
             }
             out(`${e.verb} (already_undone): ${e.editId ?? "that edit"} was undone already${by ? `, by ${by}` : ""}. To redo it, undo that undo:`);
@@ -1246,7 +1541,7 @@ function explain(reply, args, deps, e) {
         case "edit_replaced":
             out(aboutParam
                 ? `${e.verb} (edit_replaced): a recalculation dropped that parameter after the change. It stays in \`bir scenario edits\`, but there is nothing left to undo.`
-                : `${e.verb} (edit_replaced): a recalculation replaced the plan after that ${aboutCorrection ? "correction" : "edit"}. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
+                : `${e.verb} (edit_replaced): a recalculation replaced the plan after that ${aboutCorrection ? "correction" : aboutLearning ? "change" : "edit"}. It stays in \`bir scenario edits\`, but there is nothing left to undo.`);
             return 1;
         case "rate_limited": {
             const ms = typeof body.retryAfterMs === "number" ? body.retryAfterMs : undefined;

package/dist/control/server.d.ts

@@ -995,6 +995,25 @@ export declare class ControlServer {
      * to now otherwise.
      */
     private costSince;
+    /**
+     * Where a turn's tokens end, for its reports' `turn` (the service's
+     * learningPhase.md LP11): `until`, the next turn's mark, when that turn has
+     * begun; a mark taken now otherwise, as {@link costSince} reads the
+     * transcript now. Undefined for another host, which has no transcript, and
+     * when the transcript cannot be read. Never throws.
+     */
+    private tokensEnd;
+    /**
+     * The model calls and tokens of one report's window, for its `turn` (the
+     * service's learningPhase.md LP11): the window its cost is read for, from
+     * `from` to `end` — the plan's own retire, or the next plan's arm — and
+     * otherwise to `to` ({@link tokensEnd}). Another host's run has the tokens
+     * it handed over and no count of its calls, and only `whole`: for the
+     * report that bills the run, when one report does. Undefined when nothing
+     * can be said — no mark, no transcript — and then the report's `turn` says
+     * null. Never throws.
+     */
+    private turnUsage;
     private reportExecution;
     /**
      * The plan's own calls of the turn, whole, as an answered turn's report

package/dist/control/server.js

@@ -31,7 +31,7 @@ import { BIR_CALL_ID, fingerprint, newCallId, parseQualifiedName, qualifyToolNam
 import { StepIndexAllocator } from "./ordering.js";
 import { pidAlive } from "./discovery.js";
 import { pinCompatible } from "./pin-guard.js";
-import { agentDayOf, answerBeforePrompt, contextForToolUse, intentForToolUse, markTranscriptUsage, promptCount, recentToolResults, sessionTranscriptPath, settledLastAssistantText, settledTextAfterToolUse, settledTurnEnd, thinkingForToolUse, usageBetween, usageSince, } from "./transcript.js";
+import { agentDayOf, answerBeforePrompt, callsBetween, contextForToolUse, intentForToolUse, markTranscriptUsage, promptCount, recentToolResults, sessionTranscriptPath, settledLastAssistantText, settledTextAfterToolUse, settledTurnEnd, thinkingForToolUse, usageBetween, usageSince, } from "./transcript.js";
 import { isHousekeepingCall } from "../record/housekeeping.js";
 import { readsOnlyCall } from "../replay/reads-only.js";
 import { asSent, userText } from "../record/prompt-text.js";
@@ -709,6 +709,22 @@ function priceUsage(usage) {
         ...(rateUnknown.length > 0 ? { rateUnknown } : {}),
     };
 }
+/**
+ * The tokens of a usage list — the one its cost was priced from — under the
+ * names an execution report's `turn` gives them (the service's
+ * learningPhase.md LP11): every cache write, the 1-hour ones among them, in
+ * `cacheWriteTokens`.
+ */
+function turnTokens(usage) {
+    const sum = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    for (const u of usage) {
+        sum.inputTokens += u.inputTokens;
+        sum.outputTokens += u.outputTokens;
+        sum.cacheReadTokens += u.cacheReadTokens;
+        sum.cacheWriteTokens += u.cacheCreationTokens;
+    }
+    return sum;
+}
 /**
  * What `/health` answers as `hostFields`: how much of another host's protocol
  * this recorder understands. An adapter reads it to know which fields it may
@@ -3280,6 +3296,51 @@ export class ControlServer {
             return { usd: 0, measured: false };
         return priceUsage(until ? usageBetween(mark, until) : usageSince(session.transcriptPath, mark));
     }
+    /**
+     * Where a turn's tokens end, for its reports' `turn` (the service's
+     * learningPhase.md LP11): `until`, the next turn's mark, when that turn has
+     * begun; a mark taken now otherwise, as {@link costSince} reads the
+     * transcript now. Undefined for another host, which has no transcript, and
+     * when the transcript cannot be read. Never throws.
+     */
+    tokensEnd(session, until) {
+        if (otherHost(session))
+            return undefined;
+        if (until)
+            return until;
+        try {
+            return markTranscriptUsage(session.transcriptPath);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * The model calls and tokens of one report's window, for its `turn` (the
+     * service's learningPhase.md LP11): the window its cost is read for, from
+     * `from` to `end` — the plan's own retire, or the next plan's arm — and
+     * otherwise to `to` ({@link tokensEnd}). Another host's run has the tokens
+     * it handed over and no count of its calls, and only `whole`: for the
+     * report that bills the run, when one report does. Undefined when nothing
+     * can be said — no mark, no transcript — and then the report's `turn` says
+     * null. Never throws.
+     */
+    turnUsage(session, run, from, end, to, whole) {
+        try {
+            if (otherHost(session)) {
+                if (!whole || !run.hostUsage?.length)
+                    return undefined;
+                return { modelCalls: null, ...turnTokens(run.hostUsage) };
+            }
+            const last = end ?? to;
+            if (from === undefined || last === undefined)
+                return undefined;
+            return { modelCalls: callsBetween(from, last) ?? null, ...turnTokens(usageBetween(from, last)) };
+        }
+        catch {
+            return undefined;
+        }
+    }
     reportExecution(session, run, durationMs, cost, 
     /** The run was closed before its task ended for the caller (another host only). */
     cutShort = false, 
@@ -3296,6 +3357,11 @@ export class ControlServer {
         // Another host hands over one number for the whole run. It cannot be
         // split between two plans, so with more than one neither is measured.
         const unsplit = otherHost(session) && states.length > 1;
+        // Where the turn's tokens end, read once for every report's `turn` (LP11):
+        // the next turn's mark when that turn has begun, the transcript as it is
+        // now otherwise — as the cost was read a moment ago. Only for a turn that
+        // has a report to send it with.
+        const tokensTo = states.length > 0 || run.lateMatch ? this.tokensEnd(session, until) : undefined;
         // The plan ran to its end and the agent redid the task in a repeat the
         // service took (newestRun.md N7): the prompt plan's report says so, with
         // the repeat's id and the agent's own calls in it (autocorrect.md AC1).
@@ -3382,6 +3448,8 @@ export class ControlServer {
                 redoneBy: state === prompt && state.ranToEnd === true ? redoneBy : undefined,
                 chainDeriveUsd,
                 booksOwnSaving: booksOwn(state),
+                // The model calls and tokens of the same window as the cost above.
+                usage: this.turnUsage(session, run, state.armedBy === "intent" ? state.usageMark : run.usageMark, end, tokensTo, state.armedBy !== "intent" && !unsplit),
             });
             if (!report)
                 return;
@@ -3416,7 +3484,15 @@ export class ControlServer {
                     .catch(() => "")
                     .then((answer) => {
                     const calls = answer ? this.answerCallsOf(state.scenarioId, kept) : [];
-                    this.queue.push(() => recorder.reportExecution(answer ? { ...report, answer, ...(calls.length > 0 ? { answerCalls: calls } : {}) } : report));
+                    this.queue.push(() => recorder.reportExecution(answer
+                        ? {
+                            ...report,
+                            answer,
+                            ...(calls.length > 0 ? { answerCalls: calls } : {}),
+                            // How long the answer is, whole: the report carries 8 KiB of it (LP11).
+                            ...(report.turn ? { turn: { ...report.turn, answerChars: answer.length } } : {}),
+                        }
+                        : report));
                 });
                 this.holdSeal(run, sent);
                 return;
@@ -3438,6 +3514,8 @@ export class ControlServer {
                 siblings: [...states, late],
                 runId: run.runId,
                 cutShort: cutShort || undefined,
+                // The turn's own tokens only when its cost is this report's too.
+                usage: alone ? this.turnUsage(session, run, run.usageMark, undefined, tokensTo, !unsplit) : undefined,
             });
             if (report)
                 this.queue.push(() => recorder.reportExecution(report));

package/dist/control/transcript.d.ts

@@ -217,6 +217,15 @@ export interface ModelUsage extends RateFlags {
  * of pricing, under the model's name with its rate key after it.
  */
 export type UsageMark = Map<string, ModelUsage>;
+/**
+ * The model calls between two marks of one transcript, `from` the earlier:
+ * assistant messages, each counted once by its `message.id` as its tokens are
+ * ({@link totalUsage}), the sub-agents' files included — the calls behind the
+ * tokens {@link usageBetween} gives for the same two marks. No `mark` counts
+ * from the start, as there. Clamped at 0, as the tokens are, for a transcript
+ * rewritten between the two. Undefined when either mark was not made here.
+ */
+export declare function callsBetween(mark: UsageMark | undefined, now: UsageMark): number | undefined;
 /**
  * Snapshot cumulative usage at the moment a run starts.
  *