@basein/runner 0.3.9 → 0.3.10

package/dist/control/server.d.ts

@@ -83,7 +83,58 @@ export interface HookPayload {
      * only. See {@link ControlServer.offSessions}.
      */
     bir_off?: unknown;
+    /**
+     * Which host the session runs in. An adapter sends it with every request,
+     * so a recorder that restarted in the middle of a run still learns it; the
+     * session keeps the first one (see {@link hostOf}).
+     */
+    host?: {
+        app?: unknown;
+        version?: unknown;
+        adapter?: unknown;
+        scope?: unknown;
+    };
+    /**
+     * With `/session/prompt`: the adapter can step through a plan, and asks
+     * for one. An adapter that only records never sends it, and no plan is
+     * started for its run.
+     */
+    replay?: unknown;
+    /** With `/session/prompt`: the host's tools whose input is run, or written into a file. */
+    sinks?: {
+        command?: unknown;
+        write?: unknown;
+    };
+    /** With `/tool/pre`: what the model wrote before the call. */
+    context?: unknown;
+    /** With `/tool/pre`: what the model reasoned before the call. */
+    thinking?: unknown;
+    /**
+     * The adapter's own call for a step of the plan, not the model's: on the
+     * `/tool/pre` that asks for the step's arguments, and on the `/tool/post`
+     * that brings its result.
+     */
+    scripted?: unknown;
+    /** With the first scripted `/tool/pre` of a run: the tools the agent holds. */
+    tools?: unknown;
+    /** With a scripted `/tool/post`: the host stopped the step itself (`rejected`, `edited`). */
+    host_stop?: unknown;
+    /** With `/session/stop`: the run's final answer. */
+    final_answer?: unknown;
+    /** With `/session/stop`: the tokens the run's model calls used, per model, under Claude's own names. */
+    usage?: unknown;
+    /** With `/session/stop`: the run failed, and why. */
+    failed?: unknown;
+    /** With `/session/stop`: the recording is not the whole run, and why. */
+    incomplete?: unknown;
 }
+/**
+ * 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
+ * rely on — with 1 it records; from 2 it may also ask for a plan and step
+ * through it, because the checks a replay in another host needs are here.
+ */
+export declare const HOST_FIELDS = 2;
 export interface ControlServerOptions {
     recorder: Recorder;
     /**
@@ -296,6 +347,13 @@ export declare class ControlServer {
      * SessionStart.
      */
     private readonly offSessions;
+    /**
+     * Sessions of another host that named a scope the recorder cannot keep as
+     * it is (see {@link badScope}) → when last heard. Nothing of such a session
+     * is recorded or replayed: every hook of it is answered `{}`. Kept apart
+     * from {@link sessions}, so it never holds a run or takes a proxy's step.
+     */
+    private readonly refusedSessions;
     /**
      * Proxy ids that registered with *this* recorder (UPG-7). A poll from any
      * other id is a proxy from before this recorder started — a 0.2.12 proxy
@@ -434,6 +492,18 @@ export declare class ControlServer {
     private sessionOff;
     /** Mark `sessionId` off (see {@link sessionOff}), sealing whatever it had open. */
     private markSessionOff;
+    /**
+     * Whether this hook belongs to a session of another host whose scope the
+     * recorder cannot keep as it is (see {@link badScope}), and so is answered
+     * `{}` unprocessed — every hook of it, like a session that is off. One
+     * line says so, once for the session.
+     *
+     * A session that already has a host keeps it: a later payload cannot turn
+     * a run that is being recorded into one that is not.
+     */
+    private hostRefused;
+    /** Flag every run open right now as having lost steps (see `RunState.lossy`). */
+    private markOpenRunsLossy;
     /** Whether `sessionId` is a session started with `BIR_OFF=1`. */
     private isSessionOff;
     /** The route's hook deadline, or undefined when `route` is not a hook this recorder serves. */
@@ -492,7 +562,12 @@ export declare class ControlServer {
     reap(now?: number): void;
     /** Drop a session and everything keyed on it. Its last run was sealed and drained already. */
     private forgetSession;
-    /** Open a run for `session`, or return the open one. */
+    /**
+     * Open a run for `session`, or return the open one.
+     *
+     * `asked` is what the prompt that opens the run asked for, in a session of
+     * another host: whether its adapter wants a plan (`HookPayload.replay`).
+     */
     private ensureRun;
     private runMetadata;
     /**
@@ -589,6 +664,41 @@ export declare class ControlServer {
     private refreshDeliveryTool;
     /** `arming`, never rejecting: a broken arm is logged and is no plan at all. */
     private armOrLog;
+    /**
+     * Whether `run` only records: a run of another host whose adapter did not
+     * ask for a plan with its prompt. Treated as a run with replay off in the
+     * three places that ask (`onPrompt`, `armFromMatch`, `tryIntentMatch`).
+     *
+     * An adapter that only records never sends `replay`. Without this the
+     * recorder would start a plan for every prompt that matches one, read the
+     * model's own calls against it, and book a replay nobody ran. A run another
+     * hook opened carries no flag either, and only records.
+     */
+    private recordsOnly;
+    /**
+     * What {@link ReplayController.arm} is told of `session` when its host is
+     * not Claude Code, and undefined when it is.
+     */
+    private hostContext;
+    /**
+     * The earlier tool results the reading of new values may look at: this
+     * prompt's own, from the transcript — and so none for a plan that is
+     * started at the prompt (segmented.md R-PARAM-2a).
+     *
+     * `at` is where the plan is being started, and at the prompt a transcript
+     * has nothing to give. The prompt was only just submitted, so it has no
+     * results of its own; and the transcript does not hold it yet, so what the
+     * transcript calls "this prompt's results" are still the *previous*
+     * prompt's. They used to be sent as this task's, and they answered for it:
+     * a second prompt that named one person ran on the person the first
+     * prompt's results were full of.
+     *
+     * A session of another host has no transcript, and a plan starts there at
+     * the prompt only: none either. Its adapter used to hand the conversation's
+     * earlier results over with the prompt (`recent_results`) — the same
+     * mistake, made on purpose. An adapter that still sends them is not read.
+     */
+    private recentResultsFor;
     /**
      * The prompt hook answered without a directive: retire any prompt-armed plan
      * of `run` that could still steer. `armFromMatch` arms one live only while
@@ -616,6 +726,9 @@ export declare class ControlServer {
      * routinely left half-open, which is what happened in practice.
      *
      * Idempotent: the second caller sees `finished` and does nothing.
+     *
+     * `reason` says why the run is closed. It decides something only in a
+     * session of another host (see {@link CloseReason}).
      */
     private sealRun;
     /**
@@ -640,7 +753,14 @@ export declare class ControlServer {
      * false` and zero rather than a number that is confidently wrong.
      */
     private runCost;
-    /** Transcript cost since `mark`; unmeasured (and zero) without one. */
+    /**
+     * What a run of another host cost, from the tokens its adapter handed over
+     * with the stop. Measured only when at least one entry has tokens and every
+     * model in the list has a price; with no usage at all, not measured — and
+     * one `run.unmeasured` line says which.
+     */
+    private hostCost;
+    /** Transcript cost since `mark`; unmeasured (and zero) without one, or with a model that has no price. */
     private costSince;
     private reportExecution;
     /**
@@ -691,6 +811,68 @@ export declare class ControlServer {
      * still running when the deadline passes — see {@link replayOverran}.
      */
     private onToolPre;
+    /**
+     * `/tool/pre` in a session whose host is not Claude Code — a LangChain
+     * application, say (the service's integratioLangChane.md). Two kinds of
+     * request, told apart by `scripted`:
+     *
+     *  - **The adapter asks for the plan's next step** (`scripted: true`). It
+     *    is answering in the model's place and wants the step's arguments; the
+     *    host then runs its own tool with them. See {@link onScriptedPre}.
+     *  - **The model's own call.** Recorded, never pinned. See {@link onOwnPre}.
+     *
+     * ONLY A PROMPT OPENS A RUN for such a host. A hook that finds none open
+     * opens none and answers `{}`: the run failed and its adapter closed it,
+     * or the two-hour limit sealed it, or the recorder restarted under it. What
+     * arrives afterwards — the application going on from its checkpoint, a
+     * retry middleware trying the call again — must not become a second
+     * recording with an empty prompt.
+     */
+    private onHostToolPre;
+    /**
+     * The adapter of another host asks for the plan's next step. The answer
+     * either pins the call — `allow`, with the step's computed arguments — or
+     * carries no pin, which ends the plan for the adapter. It then says why:
+     *
+     *  - `noPlan`: the recorder holds no live plan for the run. It ran to its
+     *    end, was handed over, or the recorder restarted while the run waited
+     *    for a person. Nothing is recorded: no call follows this request.
+     *  - `declined`: the plan names a tool the agent does not hold.
+     *  - a refusal whose reason is the hand-over note, when the plan stopped
+     *    in this very request.
+     */
+    private onScriptedPre;
+    /**
+     * The first tool the plan will call that the agent does not hold, or
+     * undefined when it holds them all — or did not say which it holds.
+     */
+    private missingHostTool;
+    /**
+     * The model's own call, in a session of another host: any `/tool/pre`
+     * without `scripted`.
+     *
+     * NEVER PINNED, and never answered with a bundle. In Claude Code a call to
+     * the plan's next tool is pinned, because there the model is the one who
+     * makes the plan's calls. Here the adapter makes them, so a call the model
+     * made is the model's whatever tool it names: answered with the plan's
+     * arguments, the tool would run with arguments the model never wrote, and
+     * the model would read a result that does not belong to the call it sees.
+     *
+     * A plan that is still live is handed over. The call runs as the model
+     * wrote it — the note is not given in its place — and the note goes out
+     * with this call's `/tool/post`. The recording of the model's own work
+     * after the hand-over (the fragment) opens with this very call: opened one
+     * call later, the call that left the plan would be in no recording.
+     */
+    private onOwnPre;
+    /**
+     * What the model wrote and reasoned before a call, as its host handed it
+     * over with the call — the values {@link intentForToolUse} and
+     * {@link thinkingForToolUse} read from a transcript, under the same switch:
+     * a source `BIR_INTENT_SOURCES` turned off is not taken from the payload
+     * either. `context` is the written text only; thinking rides apart.
+     */
+    private hostWords;
     /** This run's plan, when it is armed, still live, and announced to the model. */
     private livePlan;
     /** Whether a `run_scenario` pre for `state` is still waiting for its `/scenario/run`. */
@@ -888,6 +1070,22 @@ export declare class ControlServer {
      */
     private onAgent;
     private onStop;
+    /**
+     * Keep what another host handed over with its stop — on the run, not on the
+     * session: a later prompt of the session opens a new run, which must not
+     * inherit an answer or a cost. Returns why the run is closed.
+     *
+     *  - `final_answer`, `usage`: the answer and the tokens (see `sealRun`,
+     *    `hostCost`).
+     *  - `incomplete`: the recording is not the whole run — the adapter lost
+     *    calls, a person changed one, or one was answered in its tool's place.
+     *    The run is flagged lossy, so its finish carries the service's mark; the
+     *    mark has no place for a text, which goes to the log only.
+     *  - `failed`: the run failed. It is closed with that text as its error
+     *    and no final answer. An exception's text can hold a password or a
+     *    user's data: it is cleaned and cut like every text that is sent.
+     */
+    private noteHostStop;
     /**
      * `SessionEnd` — `/clear`, exit, logout. Answered at once: the host is
      * waiting on it to exit, and this process outlives the session, so the run