@basein/runner 0.3.27 → 0.3.28

package/docs/calculatedReplayGuide.md

@@ -784,8 +784,9 @@ bir scenario edit  <runId|scnId> --step <n> [--input-logic <file|->] [--output-l
                    [--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|scor_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]     (§9.3)
 bir scenario editing on|off|status
 ```
 
@@ -1128,6 +1129,10 @@ How undo works:
   `bir scenario undo` takes back a correction in use when it is the newest change. `--step` never
   picks one: a correction changes the whole plan. A recalculation is refused on a corrected plan
   as on an edited one (`Not recalculated: the plan carries correction scor_…`).
+- **A change of the plan's learning phase** (built 2026-11-13, not yet released; §9.3).
+  `bir scenario edits` lists it under its `simp_` id, and `bir scenario undo <id> --edit simp_…`
+  puts back the whole plan from before it. Only by its id: a plain `bir scenario undo` never takes
+  one back, and when nothing else can be undone it names the change in use and the command.
 
 #### What a save changes
 
@@ -1346,6 +1351,73 @@ Parameter database: target → setting (revision 4). Undo: bir scenario undo scn
 | Claude Code asks before each `bir` tool | No `mcp__bir` in `permissions.allow`: the project was wired by `bir install`, or the rule was taken out | `bir setup` here adds it (`bir doctor` says when it is missing) |
 | The `bir` server lists no tools at all | The runner is off here (`bir off`, `bir off --here`, or `BIR_OFF=1` where Claude Code started) | `bir on` (or `bir on --here`), and the server tells the open session its list changed. For `BIR_OFF=1`, start Claude Code without it |
 
+### 9.3 The learning phase — `bir scenario learning`
+
+> Built 2026-11-13, **not yet released**: it needs the next `@basein/runner` version and a service
+> deploy. The design is `learningPhase.md` in the BaseIn repository (LP9, LP11).
+
+A new plan is in its **learning phase** from the moment it is calculated until 10 of its runs were
+evaluated. You can change the number for each plan, from 1 to 50. In that time the service scores
+every run, looks for what to improve, and tries one change at a time. It keeps a change only when
+the plan got better by the three measures — successful runs first, then cost, then speed — and
+otherwise takes it back exactly.
+
+**Do this**
+
+```
+bir scenario learning <runId|scnId>                        # where the learning phase stands
+bir scenario learning <runId|scnId> --runs <n>             # it lasts n evaluated runs (1–50)
+bir scenario learning <runId|scnId> --stop                 # end it now
+bir scenario learning <runId|scnId> --again [--runs <n>]   # start a new one
+```
+
+**You should see**
+
+```
+Learning: 4 of 10 runs evaluated · change 2 on trial (1 of 2 runs)
+  Revision 7: Successful 4 of 6 · cost 40% under the original · time 35% under the original
+  Found in the last run:
+    P3  The summary reads 2 values no step makes (task_id, due_date). (step 4)
+  Changes:
+    simp_0b6f…  kept         cost       The summary emits only the values the answer reads. — Kept: cost 0.62 → 0.41 of the original over 2 runs, every run successful.
+    simp_7d2e…  trial        speed      The owner's lookup is left out: nothing reads it.
+```
+
+- The first line is the phase: `Learning: 4 of 10 runs evaluated`, `Learning done after 10 runs`,
+  `Learning stopped after 4 runs`, or `No learning phase`. A change on trial says how many of its
+  runs are in.
+- The second line is the three measures of the revision the plan is at now. A measure that is not
+  known yet is left out.
+- `Found in the last run` is what the service's rules found in the newest evaluated run, one
+  problem per line (P1 to P10).
+- `Changes` is the phase's changes, oldest first: the id, the state (`proposed`, `trial`, `kept`,
+  `taken_back`, `failed_check`, `dismissed`, `replaced`), what it aims at, what it changed, and the
+  decision with its numbers. A `proposed` change waits for you: **Use** on the recording page tries
+  it.
+- `bir scenario show <id>` ends with the first line (not with `--json`: scripts read that as JSON,
+  and it carries the same facts as `learning`). `bir scenario edits <id>` lists the changes beside
+  your hand edits, and `bir scenario undo <id> --edit simp_…` takes one back (§9.2).
+- `--json` prints the service's answer unchanged. The exit codes are those of §9.2.
+
+The runner also tells the service more about each run, for the learning phase's rules about cost
+and time: the execution report's `turn` says whether the plan ran direct or steered, the turn's
+model calls and tokens, how many characters the plan handed the agent to read, whether that was
+the brief bundle, how long the agent's answer was, and, on a hand-over, where the step stood and
+why it stopped. An older service ignores it.
+
+**If it goes wrong**
+
+| What `bir` says | Why | What to do |
+|---|---|---|
+| `Not changed (builtin)` | Update bir and Remove bir have no learning phase | Nothing |
+| `Not changed (learning_off)` | The service runs with `SCENARIO_LEARNING=off` | Ask whoever runs the service |
+| `Not changed (not_ready)` | The plan is not ready, or a calculation of it is running | Wait for it, then try again |
+| `Not changed (invalid_input)` | The service did not take the request; `bir` prints its details | `--runs` takes 1 to 50 |
+| `the service does not know the learning phase yet` | The service is older than this runner | Wait for the service deploy |
+| `No learning phase` | The plan was in use before the learning phase existed — or it has none at first: a fragment, or another host's plan | For a plan in use from before: `bir scenario learning <id> --again` starts one |
+| `Not undone (not_latest_change)` | A later change of the plan stands on that one | Take back the newer one first: `bir` prints both commands when the service names it, and `bir scenario edits <id>` lists the changes, newest first |
+| `Not undone (not_used)` | The change was never used: it is proposed, dismissed, or failed its check | Nothing to take back |
+
 ---
 
 ## 10. What is built
@@ -1368,6 +1440,7 @@ part of it is not deployed yet.
 | **§6.5** *(the package is not on PyPI; the service's part is not deployed)* | A plan stepped through by the adapter of a host that is not Claude Code: the declines `host_records_only` and `host_tool_missing`, the stops `host_rejected` and `host_edited`, the cost from the adapter's `usage` | [control/server.ts](../src/control/server.ts), [controller.ts](../src/replay/controller.ts), [handover.ts](../src/replay/handover.ts), [safety.ts](../src/replay/safety.ts), [bin/investigate.ts](../src/bin/investigate.ts); the proof: `examples/langchain-proof/` in the repository (not in the npm package) |
 | **Redo and corrections** *(not yet released; the service's autocorrect.md)* | The report's `redoneBy`; a redone repeat opens with the plan's own calls, whole and marked `byPlan`; steps that run only when (contract 2); `scor_` corrections in `bir scenario edits` and `undo`; `bir investigate`'s repeat, verdict, hold and correction lines | [control/server.ts](../src/control/server.ts), [controller.ts](../src/replay/controller.ts), [plan.ts](../src/replay/plan.ts), [scenario-edit.ts](../src/bin/scenario-edit.ts), [investigate.ts](../src/bin/investigate.ts); tests: [step-tests.test.ts](../test/step-tests.test.ts), [newest-run.test.ts](../test/newest-run.test.ts) |
 | **§9.2** *(not yet released)* | `bir scenario show/check/edit/edits/undo/calc/editing`, the `bir` server's scenario tools, `bir` calls never recorded (`editSteps.md` D13) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [bin/bir-scenario.ts](../src/bin/bir-scenario.ts), [record/housekeeping.ts](../src/record/housekeeping.ts); tests: [scenario-edit.test.ts](../test/scenario-edit.test.ts), [bir-scenario.test.ts](../test/bir-scenario.test.ts), [housekeeping.test.ts](../test/housekeeping.test.ts), [replay-server.test.ts](../test/replay-server.test.ts) |
+| **§9.3** *(not yet released; the service's learningPhase.md)* | `bir scenario learning`, the learning line in `show`, `simp_` changes in `edits` and `undo`; the report's `turn` (LP11) | [bin/scenario-edit.ts](../src/bin/scenario-edit.ts), [controller.ts](../src/replay/controller.ts), [control/server.ts](../src/control/server.ts), [control/transcript.ts](../src/control/transcript.ts), [remote-recorder.ts](../src/record/remote-recorder.ts); tests: [scenario-learning.test.ts](../test/scenario-learning.test.ts), [learning-turn.test.ts](../test/learning-turn.test.ts) |
 
 ```bash
 npm test                                                # ~1,000 tests, incl. test/replay.test.ts and test/replay-server.test.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basein/runner",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "A recording MCP proxy: sits between any MCP client and its MCP servers, executes each call on the client's behalf, and records the run as a reusable BaseIn scenario.",
   "type": "module",
   "license": "MIT",