@basein/runner 0.3.9 → 0.3.11

package/dist/control/transcript.d.ts

@@ -44,6 +44,10 @@ export declare function forgetTranscripts(): void;
  * learned from a tool, not from the user (segmented.md R-PARAM-2).
  *
  * "This prompt" is everything after the last user-role line that carries text.
+ * That is only true once the prompt is in the transcript, and at the prompt
+ * hook it is not yet: asked there, this returns the *previous* prompt's
+ * results. So the prompt hook does not ask (control/server.ts,
+ * `recentResultsFor`) — a prompt just submitted has no results anyway.
  * A transcript compacted mid-turn yields whatever follows that line, which may
  * be nothing; a transcript with no user prompt at all (a run opened by a proxy
  * step) yields nothing. Results with `is_error: true` are kept: a failure is

package/dist/control/transcript.js

@@ -410,6 +410,10 @@ export function forgetTranscripts() {
  * learned from a tool, not from the user (segmented.md R-PARAM-2).
  *
  * "This prompt" is everything after the last user-role line that carries text.
+ * That is only true once the prompt is in the transcript, and at the prompt
+ * hook it is not yet: asked there, this returns the *previous* prompt's
+ * results. So the prompt hook does not ask (control/server.ts,
+ * `recentResultsFor`) — a prompt just submitted has no results anyway.
  * A transcript compacted mid-turn yields whatever follows that line, which may
  * be nothing; a transcript with no user prompt at all (a run opened by a proxy
  * step) yields nothing. Results with `is_error: true` are kept: a failure is

package/dist/proxy/session.js

@@ -716,6 +716,7 @@ export class ProxySession {
             this.recorder = await this.buildRecorder();
             this.runId = this.recorder.startRun("", {
                 recorder: "baseinstrunner",
+                runnerVersion: packageVersion(),
                 tier: "standalone",
                 host: { app: process.env.BIR_HOST_APP ?? "unknown", version: process.env.BIR_HOST_VERSION },
                 wrappedServers: [this.serverName],

package/dist/record/housekeeping.d.ts

@@ -68,8 +68,14 @@ export declare const RUN_SCENARIO_TOOL = "mcp__bir__run_scenario";
  * Whether one call is host housekeeping: never recorded as a step, never a
  * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
  * a `Bash` call's `command` is read from it.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Its tool names are
+ * its own: a tool it calls `TodoWrite` or `Bash` is the application's work and
+ * is recorded like any other. Only the runner's own `bir` server stays
+ * housekeeping there. (A host with bookkeeping tools of its own does not
+ * report them at all.)
  */
-export declare function isHousekeepingCall(toolName: string, toolInput?: unknown): boolean;
+export declare function isHousekeepingCall(toolName: string, toolInput?: unknown, otherHost?: boolean): boolean;
 /**
  * {@link isBirOnlyCommand} for PowerShell, whose rules differ enough that the
  * Bash reader would get it wrong: a backslash is a path separator, not an

package/dist/record/housekeeping.js

@@ -76,12 +76,20 @@ export const RUN_SCENARIO_TOOL = `${SCENARIO_SERVER_PREFIX}run_scenario`;
  * Whether one call is host housekeeping: never recorded as a step, never a
  * divergence from a plan. `toolInput` is what the hook saw (`tool_input`); only
  * a `Bash` call's `command` is read from it.
+ *
+ * `otherHost` is a session whose host is not Claude Code. Its tool names are
+ * its own: a tool it calls `TodoWrite` or `Bash` is the application's work and
+ * is recorded like any other. Only the runner's own `bir` server stays
+ * housekeeping there. (A host with bookkeeping tools of its own does not
+ * report them at all.)
  */
-export function isHousekeepingCall(toolName, toolInput) {
-    if (HOUSEKEEPING_TOOLS.has(toolName))
-        return true;
+export function isHousekeepingCall(toolName, toolInput, otherHost = false) {
     if (toolName.startsWith(SCENARIO_SERVER_PREFIX))
         return toolName !== RUN_SCENARIO_TOOL;
+    if (otherHost)
+        return false;
+    if (HOUSEKEEPING_TOOLS.has(toolName))
+        return true;
     if (toolName === "Bash" || toolName === "PowerShell") {
         const command = toolInput?.command;
         if (typeof command !== "string")

package/dist/record/recorder.d.ts

@@ -11,10 +11,31 @@ export interface StartRunOptions {
         scenarioId: string;
         stepIndex: number;
     };
+    /**
+     * The run's `framework`, when the session named a host that is not Claude
+     * Code: its `app`, or `app:scope` (`langchain`, `langchain:billing`). The
+     * service keeps a plan inside the host that recorded it by this text.
+     * Omitted, the recorder's own framework is sent, as before.
+     */
+    framework?: string;
 }
 export interface RunMetrics {
     costUsd?: number;
     durationMs?: number;
+    /**
+     * Why the run ended before its turn did, when it did. Sent as the run's
+     * `error`, cleaned and cut like any text; such a run has no final answer.
+     */
+    error?: string;
+    /**
+     * The caller's word on whether steps of this run were lost. Present only
+     * for a run whose finish may carry the service's `incomplete` mark: the
+     * recorder adds the step sends it lost itself, and sends the mark when
+     * either says so. A run that carries it is never calculated.
+     */
+    incomplete?: {
+        lossy: boolean;
+    };
 }
 /** How long a caller is prepared to wait for {@link Recorder.flush}. */
 export interface FlushOptions {
@@ -148,6 +169,13 @@ export interface RunMatch {
     verified?: MatchVerdict;
     /** The frozen name, beside the runtime `intent` the plan runs on (R-INTENT-12). */
     intentName?: string;
+    /**
+     * Why there is a match and no scenario to run, when the service says:
+     * `switched_off`, `repairing`, or `runner_update_required` — this runner is
+     * older than the plan needs (util/service-headers.ts). Absent or null on an
+     * ordinary hand-out, and from an older service.
+     */
+    withheld?: string | null;
 }
 /** Optional capability: `null` means "fresh run, keep recording". */
 export interface MatchAware {
@@ -206,6 +234,12 @@ export interface IntentMatchRequest {
     acceptSegments?: boolean;
     /** Always true from this runner (R-CALL-28). */
     supportsCalls?: boolean;
+    /**
+     * The host the turn runs in, as its runs' `framework` says it (see
+     * {@link StartRunOptions.framework}). Left out for Claude Code, which is
+     * what a missing value means to the service.
+     */
+    framework?: string;
 }
 /** Which text a step's intent came from. */
 export type IntentSourceName = "text" | "thinking" | "tool";

package/dist/record/remote-recorder.d.ts

@@ -215,6 +215,12 @@ export declare class RemoteRecorder implements Recorder, RecorderHealthReporter
     /** Backfill a step's `context` (the model's reasoning) after the fact. */
     backfillContext(runId: string, stepId: string, context: string): void;
     finishRun(runId: string, finalOutput?: string, metrics?: RunMetrics): void;
+    /**
+     * The service's mark for a run that is not whole, or undefined for one that
+     * is. Read when the finish is sent, not when it was queued: a step dropped
+     * or refused in between is as lost as one before.
+     */
+    private incompleteOf;
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *

package/dist/record/remote-recorder.js

@@ -50,6 +50,7 @@ import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { credentialsPath, describeBody, isAuthResponse, issuedFor, loadCredentials, saveCredentials, } from "../auth/client.js";
 import { errText, logDetail, logEvery, logLine } from "../util/log.js";
+import { serviceHeaders } from "../util/service-headers.js";
 import { isUnhealthyStatus, serviceHealth, serviceTimeoutMs, timeoutSignal, } from "../util/service-health.js";
 import { redactJsonText, redactText } from "./redact.js";
 import { capJsonText, capText, DEFAULT_MAX_PAYLOAD_BYTES, preCut, REPORT_PAYLOAD_MAX_BYTES, } from "./truncate.js";
@@ -465,7 +466,8 @@ export class RemoteRecorder {
                 try {
                     const body = await this.request("POST", "/recordings/runs", JSON.stringify({
                         id,
-                        framework: this.framework,
+                        // The session's own host, when it named one that is not Claude Code.
+                        framework: options?.framework ?? this.framework,
                         input: out(prompt),
                         metadata,
                         // A fragment (fallbk.md D7). Omitted, not null, so an older service
@@ -649,12 +651,30 @@ export class RemoteRecorder {
     }
     finishRun(runId, finalOutput, metrics) {
         const output = pend(finalOutput, TEXT_CAPS.answer);
-        this.enqueueRun(runId, "finish", sizeOf(output), () => this.post(`/recordings/runs/${runId}/finish`, {
+        // An exception's text, more often than not: it can hold a password or a
+        // user's data, so it is cleaned and cut like every other text sent.
+        const error = pend(metrics?.error, TEXT_CAPS.reportError);
+        const asked = metrics?.incomplete;
+        this.enqueueRun(runId, "finish", sizeOf(output, error), () => 
+        // `error` and `incomplete` are omitted, not nulled, when absent, so the
+        // finish of an ordinary run is the body it has always been.
+        this.post(`/recordings/runs/${runId}/finish`, {
             finalOutput: out(output),
+            error: out(error),
             originalCostUsd: metrics?.costUsd,
             originalMs: metrics?.durationMs,
+            incomplete: asked ? this.incompleteOf(runId, asked.lossy) : undefined,
         }));
     }
+    /**
+     * The service's mark for a run that is not whole, or undefined for one that
+     * is. Read when the finish is sent, not when it was queued: a step dropped
+     * or refused in between is as lost as one before.
+     */
+    incompleteOf(runId, lossy) {
+        const lostSteps = this.runs.get(runId)?.lostSteps ?? 0;
+        return lossy || lostSteps > 0 ? { lostSteps, lossy } : undefined;
+    }
     /**
      * Report what a matched turn cost (docs/calculatedReplay.md §11.2).
      *
@@ -805,6 +825,7 @@ export class RemoteRecorder {
             lastUsed: Date.now(),
             failed: 0,
             dropped: 0,
+            lostSteps: 0,
         };
         return entry;
     }
@@ -1038,8 +1059,11 @@ export class RemoteRecorder {
         // A matched turn records nothing by design: nothing was lost.
         if (why !== "not_created") {
             this.droppedSends += 1;
-            if (run)
+            if (run) {
                 run.dropped += 1;
+                if (job.kind === "step")
+                    run.lostSteps += 1;
+            }
         }
         if (job.kind === "finish" && run && job.runId)
             this.summarize(job.runId, run);
@@ -1071,6 +1095,8 @@ export class RemoteRecorder {
         const status = err instanceof ServiceError ? err.status : undefined;
         if (run && job.runId) {
             run.failed += 1;
+            if (job.kind === "step")
+                run.lostSteps += 1;
             if (job.kind === "create") {
                 // A definite refusal means there is no run; an ambiguous failure (a
                 // timeout, a 5xx) may have created it, and the first step will say.
@@ -1369,6 +1395,7 @@ export class RemoteRecorder {
                     headers: {
                         ...(body !== undefined ? { "content-type": "application/json" } : {}),
                         ...(opts.anonymous ? {} : { authorization: `Bearer ${token}` }),
+                        ...serviceHeaders(),
                     },
                     body,
                     signal,
@@ -1596,7 +1623,7 @@ export class RemoteRecorder {
         try {
             res = await fetch(`${this.baseUrl}/auth/refresh`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...serviceHeaders() },
                 body: JSON.stringify({ refreshToken: this.session.refreshToken }),
                 signal,
             });

package/dist/record/switchable-recorder.js

@@ -70,6 +70,7 @@ const INTERNAL = new Set([
     "entryFor",
     "execute",
     "healthyNow",
+    "incompleteOf",
     "laneIsIdle",
     "markDead",
     "mayHotWait",

package/dist/replay/controller.d.ts

@@ -16,6 +16,7 @@ import { type ReplayMode, type StepReach } from "./coverage.js";
 import { deriveParameters, type DeriveContext } from "./derive.js";
 import { ProxyWorkQueue } from "./executor.js";
 import { ScenarioReplayPlan } from "./plan.js";
+import { type HostSinks } from "./safety.js";
 import { SourceRunOutputs } from "./source-run.js";
 import { type FlatStop } from "./flatten.js";
 import { type ExecutionOutcome, type ExecutionStepResult, type FallbackKind, type SerializedScenario, type SerializedScenarioStep } from "./types.js";
@@ -99,6 +100,57 @@ export interface PostToolOptions {
     uncertain?: boolean;
     /** The call was never sent: its upstream was already gone. Nothing of it happened. */
     notSent?: boolean;
+    /**
+     * A host that is not Claude Code stopped the step itself, and says so: the
+     * tool never ran and the host wrote its result (`rejected` — a person said
+     * no or answered in its place, or a call limit blocked it), or it ran with
+     * arguments a person chose (`edited`). Neither is a fault of the plan: the
+     * step is recorded `skipped`, never `failed`, and the plan hands over.
+     */
+    hostStop?: HostStop;
+}
+/** How a host that is not Claude Code stopped a planned step (see {@link PostToolOptions.hostStop}). */
+export type HostStop = "rejected" | "edited";
+/**
+ * What the control server knows of a session whose host is not Claude Code —
+ * a LangChain application, say — handed to {@link ReplayController.arm} and
+ * kept on the plan's state.
+ *
+ * In such a host the tools are the application's own and only it can run
+ * them: it steps through the plan by asking for each step's arguments, and
+ * its tool names carry none of Claude Code's meanings (`Bash`, `Read`,
+ * `TodoWrite`, an `mcp__` prefix). Most of what replay decides by a tool's
+ * name is decided where there is no session to ask, so the fact travels with
+ * the plan.
+ */
+export interface HostContext {
+    /** The host's `app`, for the audit lines (`langchain`). */
+    app: string;
+    /**
+     * The sinks the host declared for its own tools. Always present, empty or
+     * not: being there is what tells the safety rules whose names these are
+     * (safety.ts, `HostSinks`).
+     */
+    sinks: HostSinks;
+    /**
+     * The run's adapter did not ask for a plan with its prompt: it only
+     * records. A match is then declined at gate 2, under its own code.
+     */
+    recordsOnly?: boolean;
+}
+/**
+ * An armed plan as data, for a host that steps through it itself. The same
+ * steps the directive lists — those the plan will run — by their position.
+ */
+export interface PlanData {
+    scenarioId: string | null;
+    mode: ReplayMode;
+    steps: Array<{
+        stepIndex: number;
+        toolName: string;
+    }>;
+    /** Only when the plan stops before its end: the first step that will not run. */
+    stopAt?: number;
 }
 /**
  * The longest a direct run may take by its budgets, end to end.
@@ -431,12 +483,38 @@ export interface ReplayState {
      * is waiting on the service, and obeys its breaker (util/service-health.ts).
      */
     deriveOnService?: boolean;
+    /**
+     * Set when the session's host is not Claude Code (see {@link HostContext}).
+     * Such a plan is always `steer` with every step `live`, and nothing here
+     * runs a step of it or reads a Claude Code meaning into a tool's name.
+     */
+    host?: HostContext;
+    /**
+     * The host stopped a planned step itself ({@link PostToolOptions.hostStop}).
+     * It decides what the report may claim: after `rejected` the task ended
+     * early, so the turn is no measure of it; after either, its cost is no
+     * sample of what the task costs unaided.
+     */
+    hostStop?: HostStop;
 }
 /**
  * Why a match did not arm. One code per gate of the ladder, so the caller can
  * act on a decline without parsing the sentence that explains it.
  */
-export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key";
+export type DeclineCode = "replay_disabled" | "not_ready" | "flatten_failed" | "known_bad_first_step" | "nondeterministic_first_step" | "unusable_first_step" | "coverage" | "missing_target" | "no_derive_key"
+/** The service handed over no plan: this runner is too old for it. */
+ | "runner_update_required"
+/** The session's host only records: its adapter asked for no plan with the prompt. */
+ | "host_records_only"
+/** The plan names a tool the host's agent does not hold. */
+ | "host_tool_missing"
+/**
+ * No gate said no: the plan was good, and late. Not ready when the prompt
+ * had to be answered (`arm_timeout`), or ready just after it had been
+ * (`arm_unannounced`). Set by the control server, where a prompt's wait
+ * ends, so the report can say why a matched turn was not steered.
+ */
+ | "arm_timeout" | "arm_unannounced";
 /** What `PreToolUse` should do about this call. */
 export type PreToolAction = 
 /** Pin the arguments and let the real tool run. */
@@ -515,8 +593,46 @@ export declare class ReplayController {
      * Always returns a state — a declined match still has a ticket to redeem and a
      * baseline sample to contribute, and losing that is how a savings ledger ends
      * up with a denominator nobody measured.
+     *
+     * `host` is given for a session whose host is not Claude Code, and is kept
+     * on the state (see {@link HostContext}).
+     */
+    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext, host?: HostContext): Promise<ReplayState>;
+    /**
+     * The armed plan as data: the steps it will run, in order, and where it
+     * stops when that is before its end. For a host that steps through the plan
+     * itself and must not have to pick the tool names out of a directive
+     * written for a model — a reworded sentence would break every adapter in
+     * the field. Built from the same entries the directive lists.
+     */
+    planData(state: ReplayState): PlanData | undefined;
+    /**
+     * Take back a plan that armed and has run nothing, as a decline.
+     *
+     * For what `arm` could not know: which tools the agent of another host
+     * holds. Such a host shows its tools only when its model is about to be
+     * called, with the first request for a step, and a plan that names a tool
+     * the agent lacks cannot be finished there. It ends before any step runs,
+     * booked like any gate's decline: `not_steered` under `code`, no step
+     * marked failed or missing — either would count against a plan that is
+     * not at fault. Returns false, changing nothing, once a step has run.
+     */
+    declineArmed(state: ReplayState, code: DeclineCode, why: string): boolean;
+    /**
+     * Hand a live plan over for something its host did, not the plan: the
+     * model made a call of its own while the plan was live (`own_call`), the
+     * run was closed with the plan still live (`closed`), or the host was
+     * answered without a step's arguments because they were not ready in time
+     * (`late`).
+     *
+     * Only for a host that is not Claude Code, where a call the plan did not
+     * hand out is by definition the model's own — it is never pinned and never
+     * answered with a bundle. No step is marked failed, so nothing is counted
+     * against the plan; the outcome is `fell_back` when a step ran and `failed`
+     * when none did, as for every hand-over. The note is the caller's to
+     * deliver ({@link takeNote}). Returns false when there was no live plan.
      */
-    arm(match: RunMatchLike, prompt: string, wrapped: ReadonlySet<string>, armedBy?: "prompt" | "intent", ctx?: DeriveContext): Promise<ReplayState>;
+    hostHandOver(state: ReplayState, why: "own_call" | "closed" | "late"): boolean;
     /**
      * The directive to inject via `additionalContext`, or undefined when declined.
      *
@@ -559,8 +675,12 @@ export declare class ReplayController {
      * Deliver text to the model in place of the tool call it was about to make:
      * as genuine command output for `Bash`, as the denial reason otherwise — the
      * two channels a divergence bundle already uses.
+     *
+     * `otherHost` is a session whose host is not Claude Code: a tool it calls
+     * `Bash` is its own, and its command is never rewritten. The text is always
+     * the refusal reason there.
      */
-    deliverInstead(text: string, toolName: string): PreToolAction;
+    deliverInstead(text: string, toolName: string, otherHost?: boolean): PreToolAction;
     /**
      * `PreToolUse`, while a plan is active.
      *
@@ -639,6 +759,13 @@ export declare class ReplayController {
      * moves from `failed` to `fell_back` when it is the first that did.
      */
     private lateThread;
+    /**
+     * Record a step its host stopped ({@link PostToolOptions.hostStop}) as
+     * `skipped`, in plain words, and remember the stop for the report. Never
+     * `failed`: the service counts failures against the plan. And not counted
+     * in `stepsPinned`: the plan's own call did not run.
+     */
+    private hostStopped;
     /** Whether a pinned call's output is threaded from the proxy's report (§7.2). */
     threadsFromProxy(state: ReplayState, toolUseId: string): boolean;
     /**
@@ -685,6 +812,13 @@ export declare class ReplayController {
         siblings?: readonly ReplayState[];
         /** The control server's own run id for this turn — journal-only, never sent. */
         runId?: string;
+        /**
+         * The run was closed before its task ended for the caller — it failed,
+         * went quiet, or stopped with the plan still live. Its cost is no
+         * measure of the task: reported unmeasured, and never a sample of the
+         * usual cost.
+         */
+        cutShort?: boolean;
     }): ExecutionReport | undefined;
     /**
      * The step a failed replay is fairly blamed on: the first whose own logic
@@ -893,6 +1027,8 @@ export interface RunMatchLike {
     verified?: MatchVerdict;
     /** The frozen name, beside the runtime intent the plan runs on (R-INTENT-12). */
     intentName?: string;
+    /** Why the service handed over no plan, when it says. Read for `runner_update_required`. */
+    withheld?: string | null;
 }
 /**
  * The old rule, for a service that sends no `stop`: the position of the first