@basein/runner 0.3.9 → 0.3.11

package/dist/util/service-headers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The contract this runner follows. It goes up by one, together with the
+ * service's own number, when the service starts to rely on something a runner
+ * must do — never for a field a runner may ignore.
+ *
+ * - **1** — stops in front of a step that carries `stop`, and reads
+ *   `withheld: "runner_update_required"` on a match.
+ */
+export declare const CONTRACT = 1;
+/** Spread into the `headers` of a request to the service. */
+export declare function serviceHeaders(): Record<string, string>;
+/**
+ * `bir doctor`'s line for a service that hands plans only to a newer runner
+ * than this one: its `/health` names the lowest contract it serves
+ * (`minRunner`). Undefined when this runner is new enough, and when the
+ * service is an older one that names no minimum.
+ */
+export declare function runnerOutdated(service: {
+    minRunner?: number;
+} | undefined, ours?: {
+    contract: number;
+    version: string;
+}): string | undefined;
+//# sourceMappingURL=service-headers.d.ts.map

package/dist/util/service-headers.js

@@ -0,0 +1,47 @@
+/**
+ * The two headers every call to the BaseIn service carries, so the service
+ * knows which runner it is talking to.
+ *
+ * WHY. The service hands every runner the same plan, and a safety mark added to
+ * a plan later works only in a runner that knows it. With these the service can
+ * count the versions in use, and hand no plan to a runner too old for it — the
+ * agent then does the task, and `bir doctor` says to update.
+ *
+ * `x-bir-version` is this package's version. `x-bir-contract` is
+ * {@link CONTRACT}: the newest set of rules this runner follows.
+ *
+ * On every call to the service, signed in or not, and never on a call to
+ * anyone else: not to Anthropic (replay/derive.ts), not to an upstream MCP
+ * server, not to the local control server.
+ */
+import { packageVersion } from "./version.js";
+/**
+ * The contract this runner follows. It goes up by one, together with the
+ * service's own number, when the service starts to rely on something a runner
+ * must do — never for a field a runner may ignore.
+ *
+ * - **1** — stops in front of a step that carries `stop`, and reads
+ *   `withheld: "runner_update_required"` on a match.
+ */
+export const CONTRACT = 1;
+/** Spread into the `headers` of a request to the service. */
+export function serviceHeaders() {
+    return {
+        "x-bir-version": packageVersion(),
+        "x-bir-contract": String(CONTRACT),
+    };
+}
+/**
+ * `bir doctor`'s line for a service that hands plans only to a newer runner
+ * than this one: its `/health` names the lowest contract it serves
+ * (`minRunner`). Undefined when this runner is new enough, and when the
+ * service is an older one that names no minimum.
+ */
+export function runnerOutdated(service, ours = { contract: CONTRACT, version: packageVersion() }) {
+    if (service?.minRunner === undefined || service.minRunner <= ours.contract)
+        return undefined;
+    return (`the BaseIn service hands plans only to a newer runner than this one (${ours.version}): ` +
+        "it still records, but nothing is replayed until it is updated — run `bir update`, " +
+        "then `bir setup` in each project that uses it");
+}
+//# sourceMappingURL=service-headers.js.map

package/docs/BaseInstRunner.md

@@ -411,7 +411,7 @@ the discovery file required on every route):
 | `POST /session/end` | hook | `finishRun` + flush |
 | `POST /proxy/register` | proxy | `{ serverName, pid, cwd }` → `{ runId, sessionId }` |
 | `POST /proxy/step` | proxy | A `ProxyStepReport`; allocates `stepIndex` |
-| `GET /health` | CLI | `bir doctor` |
+| `GET /health` | CLI, adapter | `bir doctor`; the adapter of another host reads `hostFields` (below) |
 
 **Ordering.** `ordering.ts` hands out `stepIndex` from one counter shared by hook
 and proxy reports. Allocation happens at *report* time, not call time, so
@@ -424,6 +424,99 @@ what actually happened.
 `PostToolUse` shape, and `SubagentStart` / `SubagentStop` (which carry `agent_id`)
 to attribute subagent steps correctly.
 
+**A host that is not Claude Code.** The same routes serve an agent that runs
+somewhere else. The one host `bir setup --host` knows is a LangChain
+application: a Python program whose agent is built with LangChain's
+`create_agent` and the package `langchain-basic2202`. The package (the adapter)
+is a LangChain middleware. It runs inside the application, sees every tool call
+itself, and finds the recorder by the folder's discovery file. The folder is set
+up with `bir setup --host langchain`, which gives it a port and a token of its
+own and starts the recorder. It writes no hooks and wraps no server
+([production.md](../production.md) §3.2). The how-to is `langChainGuide.md` in
+the repository's root; it is not in the npm package, and the Python package is
+not on PyPI yet.
+
+Claude Code's hooks are unchanged, and every new field is optional. A session
+whose requests carry `host` with an `app` other than `claude-code` is a session
+of another host. What such a host adds:
+
+| Route | Added | Meaning |
+|---|---|---|
+| every request | `host: { app, version?, adapter?, scope? }` | The host the session runs in. The session keeps the first one it names |
+| `POST /session/prompt` | `replay: true` | The adapter can step through a plan, and asks for one |
+| `POST /session/prompt` | `sinks: { command?: string[], write?: string[] }` | The host's tools whose input is run, or written into a file |
+| `POST /session/prompt` | answer: `plan: { scenarioId, mode, steps: [{ stepIndex, toolName }], stopAt? }` | The plan as data, beside the directive |
+| `POST /tool/pre` | `context: string`, `thinking: string` | What the model wrote, and what it reasoned, before the call |
+| `POST /tool/pre` | `scripted: true` | The adapter asks for the next step's arguments |
+| `POST /tool/pre` | `tools: [{ name }]` | The tools the agent holds, with the first such request of a run |
+| `POST /tool/pre` | answer: `noPlan: true`, or `declined: "host_tool_missing"` | Why a request for a step got none |
+| `POST /tool/post` | `scripted: true` | The result of a call the adapter made for a step of the plan |
+| `POST /tool/post` | `host_stop: "rejected" \| "edited"` | The host stopped the step itself |
+| `POST /session/stop` | `final_answer: string` | The run's final answer |
+| `POST /session/stop` | `usage: [{ model, input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens? }]` | The tokens the run's model calls used, per model |
+| `POST /session/stop` | `failed: string`, `incomplete: string` | The run failed, or its recording is not the whole run, and why |
+| `GET /health` | answer: `hostFields: 2` | How much of this protocol the recorder understands. An adapter reads it before it relies on a field: with 1 it records, from 2 it may also ask for a plan and step through it |
+
+A prompt's `recent_results` (the conversation's earlier tool results, which an
+adapter used to send for the reading of new values) is no longer read. A new
+prompt's values are read from the prompt alone: an earlier turn's results are
+not this task's (the service's segmented.md, R-PARAM-2a).
+
+What the control server does for such a session:
+
+- **The run.** It is created with `framework` set to the app, or `app:scope`
+  (`langchain`, `langchain:billing`), and with the host in `metadata.host`. A
+  Claude Code run is created as before (`framework: "baseinstrunner"`). Only
+  `/session/prompt` opens a run. Any other request that finds none open records
+  nothing and is answered `{}`, or `{ noPlan: true }` when it asked for a step.
+- **The scope.** It keeps plans apart inside one account, and is part of the
+  run's `framework`. It is 1 to 64 characters and is never cut or dropped. A
+  session that names one the recorder cannot keep (empty, longer, or not a
+  text) has every request answered `{}`, and nothing of it is recorded or
+  replayed (`session.host_refused`).
+- **The plan.** One starts only for a prompt that said `replay: true`.
+  Otherwise a match is declined with `host_records_only`. The plan's mode is
+  always `steer`, and the runner runs no step itself: the host runs its own
+  tools. The prompt's answer carries the plan as data (`plan`), because the
+  directive beside it is a text written for a model.
+- **Tool names.** They carry no Claude Code meaning. `Bash`, `Read`,
+  `TodoWrite` or `ToolSearch` are the application's own tools there, and
+  nothing is skipped as housekeeping except the `bir` server's own tools.
+- **A step.** The adapter asks for each one (`scripted: true`). The answer is
+  the step's arguments (`hookSpecificOutput.updatedInput`), or
+  `{ noPlan: true }` when the recorder holds no live plan, or
+  `{ declined: "host_tool_missing" }` when the plan names a tool that is not in
+  `tools`.
+- **The model's own call.** A `/tool/pre` without `scripted` is the model's own
+  call, and is never given the plan's arguments. A plan that is live then is
+  handed over, and the hand-over note comes with that call's `/tool/post`.
+- **A step the host stopped.** `host_stop: "rejected"` means a person said no,
+  or answered in the tool's place, or a call limit blocked the call. `"edited"`
+  means a person changed the call. Either way the step's verdict is `skipped`,
+  not `failed`, and nothing is counted against the plan. After `rejected` the
+  report is `measured: false`; after `edited` the cost stays measured. Both are
+  `baselineEligible: false`.
+- **The cost.** It comes from `usage`, not from a transcript. It is measured
+  only when at least one entry has tokens and every model in the list has a
+  price. With more than one plan in one run, none is measured.
+- **The end.** `failed` closes the run with that text as its `error` (cleaned
+  of secrets, cut) and no final answer. `incomplete` marks the finish
+  `incomplete: { lostSteps, lossy }`; the finish carries that mark too when the
+  recorder itself lost one of the run's step sends. A run sealed after two
+  hours of silence is closed with `error: "turn ended early: idle"`. A run that
+  is closed while its plan is still live has the plan handed over first, so the
+  report says `fell_back` (a step ran) or `failed` (none ran), with
+  `measured: false` and `baselineEligible: false`.
+- **Sinks.** A value that a plan reads from the prompt is checked before it goes
+  into a tool the host declared in `sinks`, or one whose plain name has a
+  command word (`sql`, `query`, `exec`, `shell`, `command`, `script` and `eval`
+  among them).
+
+On the service's side, matching stays inside a host: a run created with
+`framework` `langchain` or `langchain:<scope>` is matched only against
+recordings and plans of that same text. Everything else is Claude Code's pool,
+as before. That part of the service is built and not deployed yet.
+
 **Acceptance:** a Claude Code session running one built-in and one MCP tool
 produces a single run whose steps are in true execution order.
 
@@ -574,6 +667,11 @@ Run `metadata` carries what is new, and what BaseIn-side consumers will need:
 `tier` is the field that stops a Tier 2 partial trace being mistaken for a
 complete one.
 
+A run of a host that is not Claude Code (Phase 5) names that host in
+`metadata.host` (`{ "app": "langchain", … }`), and is created with a `framework`
+of its own: the app, or `app:scope`. Its finish may carry an `error`, and the
+`incomplete` mark.
+
 ---
 
 ## 8. Full-passthrough method map
@@ -618,6 +716,11 @@ observable.
 - Discovery files are mode `0600`.
 - `bir doctor` prints exactly which servers are wrapped, so a proxy can never sit
   in the path invisibly.
+- A recorder started for a folder that is set up for another host and not for
+  Claude Code (Phase 5) gets a small environment, not the whole environment of
+  the window that started it. A plan's step code runs inside the recorder with
+  no sandbox, so a model key or a database password of the application must not
+  reach it. The names it keeps are in [production.md](../production.md) §9.
 
 ---
 
@@ -630,6 +733,7 @@ The governing rule: **the host session must never fail because of BaseInstRunner
 | Control server unreachable at startup | Buffer <= 10 s while retrying, then Tier 2 (passthrough for an entry that may not record here, §0.1). Keep looking every 15 s; bind when a recorder answers |
 | Control server dies mid-session | Log `tier.downgrade`; what follows goes to a Tier 2 run of the proxy's own (at most one per proxy; none where the entry may not record), flagged `lossy`, until a recorder answers again. A bound proxy in an installed project whose recorder died (pid gone, port refusing) starts it again in the background (`bir-hooks revive`); a recorder stopped with `bir down` stays stopped |
 | Recorder HTTP fails | Drop the send, log once per run, continue. Never retry inline: a background send is retried once, and only after a 429/503 or a connection that never reached the service. After a failure, hooks stop waiting on the service for a cool-down (5 s, doubling to 60 s) |
+| The service answers `429`: the account is over one of its limits (these are built in the service, and not deployed yet) | Send the create, the step or the report once more, at most 2 s later, then drop it (`recorder.send_failed` with `HTTP 429`). A dropped step is a hole in its recording, and a run whose create got a `429` runs without its plan. A `429` that the second try did not cure starts the same cool-down. The limits are in [production.md](../production.md) §3.3 |
 | Upstream fails to start, or exits | Answer the requests in flight, then exit with the upstream's status (1 if it had none). The host shows that one server failed, with a reconnect offered, as it would unwrapped. `BIR_PROXY_STAY_UP=1` keeps the proxy up instead, answering every request `MCP server "x" is not available` |
 | A stdio upstream dies mid-call | Return `isError: true` with `MCP server "x" is not available` as content — a tool failure the model can react to, not a protocol error — then exit as above |
 | Remote upstream unreachable or refusing | The proxy stays up and answers each request with a short JSON-RPC error that never echoes the server's body (`upstream unreachable: …`, `upstream requires sign-in (HTTP 401)`). Only connecting is bounded (10 s, `BIR_UPSTREAM_CONNECT_TIMEOUT_MS`); a slow tool is the host's to time out |
@@ -659,6 +763,9 @@ The governing rule: **the host session must never fail because of BaseInstRunner
 6. **Redaction** — assert no fixture secret reaches the recorder.
 7. **Integration** — a real Claude Code session against `fake-upstream`, asserting
    run shape end to end. The only test that catches host-behaviour drift.
+8. **Another host** — `examples/langchain-proof/`, in the repository and not in
+   the npm package: a real LangChain agent against the real recorder, with a
+   stand-in service and a fake model (Phase 5). Its README lists the cases.
 
 ---
 
@@ -683,6 +790,13 @@ ship it before touching the control plane.
    `metadata` enough for the savings pipeline to exclude partial traces from
    baselines? A Tier 2 run has no prompt, so similarity matching on `input` behaves
    differently.
+   *Answered in part.* The service's new build (built, not deployed yet) lets a
+   finish say that the recording is not whole: `incomplete: { lostSteps, lossy }`.
+   A run with an `error`, or with that mark, is never picked for automatic
+   calculation and no longer catches its prompt, unless its owner preferred it
+   or it already has a plan. Today only a run of a host that is not Claude Code
+   (Phase 5) sends either: a Claude Code run that was interrupted or lost steps
+   is finished as before. The runner still sends `tier` in `metadata` only.
 2. **Coexistence with RRepeat.** If both are installed, both record the same session
    into the same service. Should `bir-hooks` detect `rrepeat-hooks` and refuse, or
    should runs carry a `recorder` discriminator and be deduped server-side? §7's