@parcha/agentrun-kernel 0.0.0-stage → 0.1.0-beta.29

package/dist/runner.js

@@ -0,0 +1,547 @@
+// A DSL node on any harness: createHarnessRunner turns an AgentAdapter into exactly the interpreter's `runNode`, so a
+// DSL host and serve run a node on a harness adapter (Codex first) the way createPiRunner runs it on Pi. The
+// node's record arrives through an injected `submit` tool whose input is the node's schema under `value`
+// (submitParameters, the envelope both runners use); a review that does not accept it is the tool's result, in the
+// same session. Every paid request passes the runner first: the turn cap, then the host's `beforeRequest` (its budget),
+// each of which may refuse it. Under recovery a session is keyed by its step's sessionId: a delivered record is answered
+// from the session's records, and a session cut off inside a turn is resumed by the adapter, spending nothing again.
+import { randomUUID } from "node:crypto";
+import { Compile } from "typebox/compile";
+import { submitParameters } from "@parcha/agentrun-dsl";
+import { HarnessRunError, SessionFenced } from "./errors.js";
+/** The tool the runner injects; a host tool may not take its name. */
+export const SUBMIT_TOOL = "submit";
+/** Why a review rejected a candidate, as the model reads it: its message, or, for none (no message, or a blank one),
+ *  that it gave no reason. Always a string, so a rejection never lets the candidate through (Pi's runner reads a review
+ *  the same way). A long one reaches the model through the host's one bound on a result (HOST_RESULT_MAX_CHARS). */
+const reviewRejection = (message) => {
+    const said = message === undefined || message === null ? "" : String(message);
+    return said.trim() ? said : "the review rejected it without saying why";
+};
+/** A held figure as a host gives it or a record keeps it: a finite amount, 0 or more, else none. */
+const heldFigure = (value) => (typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined);
+/** `total` with `cost` added: unknown once either is. */
+const spent = (total, cost) => (total === null || cost === undefined ? null : total + cost);
+/** The records the runner keeps beside the adapter's own, in each session. */
+/** `request` is written before a paid request leaves, `turn` when it has answered with its usage: a request a crash cut off
+ *  keeps its `request` and has no `turn`. */
+export const RUNNER_RECORDS = { request: "runner.request", response: "runner.response", turn: "runner.turn", submit: "runner.submit", accepted: "runner.accepted" };
+const positive = (value, name) => {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+};
+/** Turns in a row that may end with no paid request and no accepted submission before a node ends `no_progress`. The
+ *  turn limit counts paid requests only, so without this bound a harness whose turns never reach its model (a cached or
+ *  refused answer, a misconfigured model) would be sent turns forever, on microtasks no timer can interrupt. */
+export const NO_PROGRESS_TURNS = 3;
+/** The runner's booking of paid model requests, for a host that drives an adapter session itself (a chat run): the same
+ *  records (`runner.request` before a request leaves, `runner.turn` with its cost when it answers), the same turn limit
+ *  and `beforeRequest`, the same events. `createHarnessRunner` is built on it. */
+export async function modelPortFor(writer, options) {
+    return bookingFor(writer, { ...options, records: options.records ?? (await writer.read()) });
+}
+function bookingFor(writer, options) {
+    const node = { key: options.key, label: options.label ?? options.key, ...(options.executionPath === undefined ? {} : { executionPath: options.executionPath }) };
+    const limit = options.maxTurns ?? null;
+    const append = options.append ?? ((records) => writer.append(records));
+    const emit = (event) => options.onEvent?.({ ...event, ...node });
+    // A turn is a paid request that left: counted from the records written before each one left, so a request a crash cut
+    // off still counts against the turn cap. What it cost is unknown: the session's spend counts it at the figure its
+    // host held for it, on its record, and is unknown from then on when there is none.
+    const requests = options.records.filter((r) => r.kind === RUNNER_RECORDS.request).map((r) => (r.data ?? {}));
+    const inherited = requests.map((data, i) => data.turn ?? i + 1);
+    let turns = inherited.length;
+    /** What the host held for each request, by turn: what it counts at when its own cost never comes in. */
+    const held = new Map();
+    /** What the host counts each request of this process at if its client stops it part way (Admission.stoppedUsd). */
+    const stoppedAt = new Map();
+    requests.forEach((data, i) => {
+        const figure = heldFigure(data.heldUsd);
+        if (figure !== undefined)
+            held.set(inherited[i], figure);
+    });
+    // Which of them were answered: each runner.turn names its own turn (one written before turns were named answers the
+    // earliest still open, as answers then came in order).
+    const answered = new Set();
+    let spentUsd = 0;
+    for (const r of options.records) {
+        if (r.kind !== RUNNER_RECORDS.turn)
+            continue;
+        const data = r.data;
+        const turn = data.turn ?? inherited.find((t) => !answered.has(t)) ?? 0;
+        answered.add(turn);
+        // A cost that never came in: at the figure its answer was booked at (a stopped request's), else what was held for it.
+        spentUsd = spent(spentUsd, data.usd === null ? (heldFigure(data.heldUsd) ?? held.get(turn)) : (data.usd ?? 0));
+    }
+    for (const turn of inherited)
+        if (!answered.has(turn))
+            spentUsd = spent(spentUsd, held.get(turn));
+    // The ids each request's response gave it, kept as its headers arrived: a request cut off after them reached the provider.
+    const responses = new Map();
+    for (const r of options.records) {
+        if (r.kind !== RUNNER_RECORDS.response)
+            continue;
+        const data = r.data;
+        if (typeof data.turn === "number" && data.providerIds)
+            responses.set(data.turn, data.providerIds);
+    }
+    // This process's requests in flight, oldest first: the turn each was admitted as, and its model.
+    const open = [];
+    // Response ids whose own write was refused, marked `late`: the booking's next write of its own (the next runner.request,
+    // or a runner.turn) carries them first, so a request this process cuts by dying after that still keeps its ids. One a
+    // runner.turn writes with the ids is dropped, never written twice. A process that dies before writing for its booking
+    // again loses them: the request is then booked once, cut, at an unknown cost, with no ids.
+    let carry = [];
+    const write = async (records, covers = () => false) => {
+        const taken = carry;
+        carry = [];
+        try {
+            await append([...taken.filter((r) => !covers(r)), ...records]);
+        }
+        catch (error) {
+            carry = [...taken, ...carry];
+            throw error;
+        }
+    };
+    // Admissions run one at a time (the turn limit, the host's check and the durable write), so two requests asked for at
+    // once can't both pass a limit only one fits; the requests themselves still run side by side once admitted.
+    let admitting = Promise.resolve();
+    // A paid request whose cost couldn't be recorded stops the booking itself, whether or not the host gave it a stop.
+    let failed;
+    const end = (reason, message) => options.stop ? options.stop(reason, message) : new HarnessRunError(reason, turns, 0, { maxTurns: limit, ...(message === undefined ? {} : { message }) });
+    const admit = async ({ model, inputTokensMax, outputTokensAsked, outputTokensLeast }) => {
+        const stopped = options.stopped?.() ?? failed;
+        if (stopped)
+            throw stopped;
+        const pausing = options.draining?.();
+        if (pausing)
+            throw pausing;
+        if (limit !== null && turns >= limit)
+            throw end("turn_limit");
+        const verdict = await options.beforeRequest?.({ ...node, model, turn: turns + 1, maxTurns: limit, ...(options.budgetUsd === undefined ? {} : { budgetUsd: options.budgetUsd }), spentUsd, inFlight: open.map((f) => ({ ...f })), inputTokensMax,
+            ...(outputTokensAsked === undefined ? {} : { outputTokensAsked }), ...(outputTokensLeast === undefined ? {} : { outputTokensLeast }) });
+        if (verdict && "refuse" in verdict)
+            throw end("refused", verdict.refuse);
+        const hold = verdict && "holdUsd" in verdict ? heldFigure(verdict.holdUsd) : undefined;
+        // The output limit the host admits it with goes into its body. A limit that is no whole number of tokens above 0 (a
+        // fraction, 0, a negative, NaN) can't be sent, so the request is refused before anything is written: dropping it would
+        // send the request with no limit at all. Only a verdict with no limit sends the request with none.
+        const limited = verdict && "outputTokensMax" in verdict ? verdict.outputTokensMax : undefined;
+        if (limited !== undefined && !(Number.isSafeInteger(limited) && limited > 0))
+            throw end("refused", `the request was not sent: its output limit (${String(limited)}) is not a whole number of tokens above 0`);
+        // A stop or a pause that came while the host was checking: nothing was written for this request, so it is refused, not
+        // sent. After the write below it is committed (refusing it then would leave a recorded request that was never sent).
+        const late = options.stopped?.() ?? failed ?? options.draining?.();
+        if (late)
+            throw late;
+        // Durable before the request leaves: admitted, then sent. It counts as a turn once its record is written (admissions
+        // run one at a time), so a write that fails refuses the request and costs no turn.
+        const turn = turns + 1;
+        await write([{ kind: RUNNER_RECORDS.request, data: { turn, model, ...(hold === undefined ? {} : { heldUsd: hold }) } }]);
+        turns = turn;
+        if (hold !== undefined)
+            held.set(turn, hold);
+        const stoppedUsd = verdict && "stoppedUsd" in verdict && typeof verdict.stoppedUsd === "function" ? verdict.stoppedUsd : undefined;
+        if (stoppedUsd)
+            stoppedAt.set(turn, stoppedUsd);
+        // A stop that came while the record was written: the request has not left. It is booked withdrawn, at $0, so no
+        // later process books it as cut at an unknown price; if that write fails, it is booked cut, which is never less.
+        // Its record is written, so it costs a turn of the cap, never money.
+        const stoppedNow = options.stopped?.();
+        if (stoppedNow) {
+            answered.add(turn);
+            // Through the booking's own write: a response's ids still waiting to be carried go with the withdrawal.
+            await write([{ kind: RUNNER_RECORDS.turn, data: { turn, usd: 0, unsent: true } }]).catch(() => undefined);
+            throw stoppedNow;
+        }
+        open.push({ turn, model, inputTokensMax, ...(limited === undefined ? {} : { outputTokensMax: limited }) });
+        emit({ type: "request_start", turn, model });
+        return { turn, ...(limited === undefined ? {} : { outputTokensMax: limited }) };
+    };
+    const models = {
+        beforeRequest: (request) => {
+            const admitted = admitting.then(() => admit(request));
+            admitting = admitted.catch(() => { });
+            return admitted;
+        },
+        responded: async (ids, ticket) => {
+            const turn = ticket?.turn ?? open[0]?.turn ?? turns;
+            try {
+                await append([{ kind: RUNNER_RECORDS.response, data: { turn, providerIds: ids } }]);
+            }
+            catch (error) {
+                // Refused (a commit that timed out, say): the proxy goes on with the answer, and the ids wait for the next write.
+                carry.push({ kind: RUNNER_RECORDS.response, data: { turn, providerIds: ids, late: true } });
+                throw error;
+            }
+        },
+        afterRequest: async (usage, ticket) => {
+            // The turn this request was admitted as (its ticket; without one, the earliest still in flight).
+            const turn = ticket?.turn ?? open[0]?.turn ?? turns;
+            const at = open.findIndex((f) => f.turn === turn);
+            if (at >= 0)
+                open.splice(at, 1);
+            // A cost that never came in (a response cut short): at what the host held for the request, else unknown. One its
+            // client stopped part way at what the host counts it at by what streamed (one token a byte), never more than that.
+            const hold = held.get(turn);
+            const stoppedUsd = stoppedAt.get(turn);
+            stoppedAt.delete(turn);
+            const stopped = usage.usd === null && hold !== undefined && stoppedUsd && typeof usage.stoppedAfterBytes === "number" && usage.stoppedAfterBytes >= 0 ? heldFigure(stoppedUsd(usage.stoppedAfterBytes)) : undefined;
+            const figure = stopped === undefined ? hold : Math.min(hold, stopped);
+            spentUsd = spent(spentUsd, usage.usd === null ? figure : usage.usd);
+            try {
+                // A runner.turn with the ids holds what a carried response record of this turn would: that one is dropped. A
+                // stopped one keeps the figure it counts at (`heldUsd`), so a later process counts it the same.
+                const covers = (r) => usage.providerIds !== undefined && r.data.turn === turn;
+                await write([{ kind: RUNNER_RECORDS.turn, data: { turn, usd: usage.usd, ...tokensOf(usage), ...(usage.estimated ? { estimated: true } : {}), ...(usage.tableUsd === undefined ? {} : { tableUsd: usage.tableUsd }), ...(usage.providerIds ? { providerIds: usage.providerIds } : {}), ...(stopped === undefined ? {} : { heldUsd: figure, stopped: true }) } }], covers);
+            }
+            catch (error) {
+                // A paid request whose cost can't be kept: the attempt stops, saying so, rather than spend on uncounted.
+                if (!options.stopped?.())
+                    failed ??= end("model_error", `harness node stopped: the cost of a paid request could not be recorded: ${String(error?.message ?? error).slice(0, 200)}`);
+                throw error;
+            }
+            answered.add(turn);
+            emit({ type: "request_end", turn, usage });
+        },
+    };
+    // One booking of the cut requests at a time: a call made while one is writing waits for it, never books them again.
+    let cutting;
+    const bookCut = async () => {
+        // A paid request a crash cut off kept its runner.request and has no runner.turn: the provider may have billed it.
+        // Each is booked once, as cut, at an unknown price, and the host is told as for any answered request, so its ledger
+        // shows the possible spend instead of nothing. Booked, it is answered: a later attempt never books it again.
+        // Only requests an earlier process admitted: one this process has in flight is not cut.
+        const numbers = inherited.filter((t) => !answered.has(t));
+        if (numbers.length === 0)
+            return;
+        // A cut request whose response had begun carries the ids it gave: the provider saw it, under them. One with none may
+        // still have reached the provider before any answer; both are booked at an unknown price.
+        const cutOf = (turn) => {
+            const providerIds = responses.get(turn);
+            return providerIds ? { usd: null, cut: true, turn, providerIds } : { usd: null, cut: true, turn };
+        };
+        await append(numbers.map((turn) => ({ kind: RUNNER_RECORDS.turn, data: cutOf(turn) })));
+        for (const turn of numbers)
+            answered.add(turn);
+        // The spend already counts each of them, at its held figure or as unknown: booking them adds nothing.
+        for (const turn of numbers) {
+            const providerIds = responses.get(turn);
+            emit({ type: "request_end", turn, usage: { input: 0, output: 0, cacheRead: 0, usd: null, estimated: true, cut: true, ...(providerIds ? { providerIds } : {}) } });
+        }
+    };
+    return {
+        models,
+        turns: () => turns,
+        spentUsd: () => spentUsd,
+        bookCut() {
+            cutting ??= bookCut().catch((error) => {
+                cutting = undefined;
+                throw error;
+            });
+            return cutting;
+        },
+    };
+}
+/** A booking's tokens as its runner.turn keeps them (`usage`, in pi's shape: `input` excludes cached tokens), or nothing
+ *  when it reports none: a request whose usage was not read is booked with zeros, which are no count. */
+function tokensOf(usage) {
+    const tokens = { input: usage.input, output: usage.output, cacheRead: usage.cacheRead ?? 0, cacheWrite: usage.cacheWrite ?? 0 };
+    return tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite > 0 ? { usage: tokens } : {};
+}
+const NUDGE = "You finished without an accepted submission. Call submit with the complete result; plain text does not deliver it.";
+export function createHarnessRunner(adapter, options) {
+    const maxTurns = options.maxTurns === null ? null : positive(options.maxTurns ?? 8, "maxTurns");
+    const maxSends = positive(options.maxSends ?? 100, "maxSends");
+    const maxSubmissions = options.maxSubmissions === null ? null : positive(options.maxSubmissions ?? 5, "maxSubmissions");
+    const timeoutMs = options.timeoutMs === null ? null : positive(options.timeoutMs ?? 120_000, "timeoutMs");
+    const registered = new Map();
+    for (const tool of options.tools ?? []) {
+        if (tool.name === SUBMIT_TOOL || registered.has(tool.name))
+            throw new Error(`Reserved or duplicate harness tool: ${tool.name}`);
+        registered.set(tool.name, tool);
+    }
+    const store = options.store;
+    /** The nodes running now, each by how it is paused; and whether the runner was stopped. */
+    const running = new Map();
+    let halted = false;
+    const runNode = async (request, pause) => {
+        // Without a step there is no durable identity: a fresh session of the runner's own, never one derived from the
+        // label, which map items and loops repeat.
+        const key = request.step ? `step:${request.step.sessionId}` : `call:${randomUUID()}`;
+        const node = { key, label: request.label, ...(request.executionPath === undefined ? {} : { executionPath: request.executionPath }) };
+        const emit = (event) => options.onEvent?.({ ...event, ...node });
+        const refuse = (message, turns = 0, submissions = 0) => new HarnessRunError("refused", turns, submissions, { message });
+        const signals = [options.signal, request.signal].filter((s) => Boolean(s));
+        if (halted || signals.some((s) => s.aborted))
+            throw new HarnessRunError("aborted", 0, 0);
+        if (request.maxTurns !== undefined) {
+            positive(request.maxTurns, "maxTurns");
+            if (maxTurns !== null && request.maxTurns > maxTurns)
+                throw refuse(`Node "${request.label}" asks max_turns ${request.maxTurns}, above this host's cap of ${maxTurns} turns`);
+        }
+        const limit = request.maxTurns ?? maxTurns;
+        // Absent: every registered tool. An unknown name is refused, never dropped.
+        const requested = request.tools ?? [...registered.keys()];
+        for (const name of requested)
+            if (!registered.has(name))
+                throw refuse(`Node "${request.label}" names the tool ${name}, which this host does not give ${adapter.id} nodes`);
+        // This attempt takes the session before it reads it: from here a process that held it earlier (one whose lease
+        // lapsed while it was still alive) can write nothing more into it, a runner.accepted included.
+        const writer = await store.open(key);
+        // A session that already delivered: its record, and nothing runs.
+        const earlier = request.step ? await writer.read() : [];
+        const delivered = earlier.findLast((r) => r.kind === RUNNER_RECORDS.accepted);
+        if (delivered)
+            return structuredClone(delivered.data.value);
+        const validator = Compile(request.schema);
+        const parameters = submitParameters(request.schema);
+        const envelope = Compile(parameters);
+        let submissions = earlier.filter((r) => r.kind === RUNNER_RECORDS.submit).length;
+        // The session's paid requests, counted and booked by its model port (modelPortFor), made once `append` exists below.
+        let booking;
+        const turnsSoFar = () => booking?.turns() ?? 0;
+        let accepted = false;
+        let submission;
+        let lastTool;
+        let stopped;
+        // A pause in progress: nothing new starts, and the node stops once its session has drained.
+        let draining = false;
+        // Calls the session announced (tool_start) before the pause: they are in flight, not new, and run on through a drain.
+        // A stop with no drain (drainMs 0) lets nothing run on, announced or not.
+        const announced = new Set();
+        let immediate = false;
+        const failure = (reason, message) => new HarnessRunError(reason, turnsSoFar(), submissions, { maxTurns: limit, ...(lastTool === undefined ? {} : { lastTool }), ...(message === undefined ? {} : { message }) });
+        const controller = new AbortController();
+        let rejectStopped;
+        const interrupted = new Promise((_, reject) => { rejectStopped = reject; });
+        void interrupted.catch(() => { });
+        const bounded = (work) => Promise.race([work, interrupted]);
+        const stop = (error) => {
+            stopped ??= error;
+            rejectStopped(stopped);
+            controller.abort(stopped);
+        };
+        const onAbort = () => stop(failure("aborted"));
+        const append = async (records) => {
+            try {
+                await writer.append(records);
+            }
+            catch (error) {
+                // A newer process holds the session: this attempt stops, and what it was writing never counts.
+                if (error instanceof SessionFenced) {
+                    stop(failure("fenced"));
+                    throw stopped;
+                }
+                throw error;
+            }
+        };
+        booking = bookingFor(writer, {
+            ...node, maxTurns: limit, records: earlier, append,
+            ...(request.budgetUsd === undefined ? {} : { budgetUsd: request.budgetUsd }),
+            ...(options.beforeRequest ? { beforeRequest: options.beforeRequest } : {}),
+            onEvent: (event) => emit(event),
+            stopped: () => stopped,
+            draining: () => (draining ? failure("aborted", "harness node pausing: no new paid request") : undefined),
+            stop: (reason, message) => { stop(failure(reason, message)); return stopped; },
+        });
+        const submit = {
+            name: SUBMIT_TOOL,
+            description: "Deliver a result matching the required JSON Schema. Rejection feedback must be corrected in this session.",
+            inputSchema: parameters,
+            replay: "safe",
+            async call(args) {
+                if (accepted)
+                    return { text: "Already accepted; end your turn." };
+                // A stop with no drain takes no answer, though one inside a drain is kept (it is the end of a paid response).
+                if (stopped || (draining && immediate))
+                    return { text: "This session has stopped.", isError: true };
+                submissions += 1;
+                await append([{ kind: RUNNER_RECORDS.submit, data: { n: submissions } }]);
+                const candidate = args?.value;
+                let message;
+                if (!envelope.Check(args))
+                    message = JSON.stringify([...envelope.Errors(args)]);
+                else if (!validator.Check(candidate))
+                    message = JSON.stringify([...validator.Errors(candidate)]);
+                else if (request.review) {
+                    const verdict = await request.review(candidate);
+                    if (!verdict.accepted)
+                        message = reviewRejection(verdict.message);
+                    else if (!validator.Check(candidate))
+                        message = "The reviewed candidate no longer satisfies its output schema";
+                }
+                if (stopped)
+                    return { text: "This session has stopped.", isError: true };
+                if (message !== undefined) {
+                    if (maxSubmissions !== null && submissions >= maxSubmissions)
+                        stop(failure("submission_limit"));
+                    return { text: `Rejected: ${message}. Correct the result and call submit again.`, isError: true };
+                }
+                // Durable before it is acknowledged: a process that dies after this answers the step from the record.
+                await append([{ kind: RUNNER_RECORDS.accepted, data: { value: structuredClone(candidate) } }]);
+                submission = structuredClone(candidate);
+                accepted = true;
+                return { text: "Accepted. End your turn." };
+            },
+        };
+        const guard = (tool) => ({
+            ...tool,
+            call: (args, context) => {
+                if (accepted || stopped)
+                    return Promise.reject(new Error("the session has stopped; tool execution refused"));
+                // A stop with no drain runs nothing more; a drain lets a call announced before it run on.
+                if (draining && immediate)
+                    return Promise.reject(new Error("the session has stopped; this call was not run"));
+                if (draining && !announced.has(context.callId))
+                    return Promise.reject(new Error("the session is pausing; this call was not run"));
+                return tool.call(args, options.sessionDir ? { ...context, sessionDir: options.sessionDir } : context);
+            },
+        });
+        const spec = {
+            ...node,
+            system: [...request.system, 'Only a successful submit tool call delivers the result. Call submit with {"value": YOUR_RESULT}. The schema below describes value, not the envelope.', `Required JSON Schema: ${JSON.stringify(request.schema)}`],
+            tools: [...requested.map((name) => guard(registered.get(name))), submit],
+            context: request.context === "fork" ? "fork" : "fresh",
+            ...(request.tier === undefined ? {} : { tier: request.tier }),
+            ...(request.effort === undefined ? {} : { effort: request.effort }),
+            ...(request.thinking === undefined ? {} : { thinking: request.thinking }),
+        };
+        // Refused at create time, before anything is spent: a fork the adapter cannot make, or anything the adapter refuses.
+        const problems = [
+            ...(spec.context === "fork" && !adapter.capabilities().fork ? [`Node "${request.label}" asks for context: "fork", but ${adapter.id} has no caller transcript to fork. Declare context: "fresh".`] : []),
+            ...adapter.check(spec),
+        ];
+        if (problems.length)
+            throw refuse(problems.join("; "));
+        const models = booking.models;
+        let session;
+        let opening;
+        // Armed here, with nothing between them and the try whose finally releases them: a refusal above never leaves a timer.
+        signals.forEach((s) => s.addEventListener("abort", onAbort, { once: true }));
+        // A stop that landed while the store was read: a listener added to an aborted signal never fires.
+        if (signals.some((s) => s.aborted))
+            onAbort();
+        const timer = timeoutMs === null ? undefined : setTimeout(() => stop(failure("timeout")), timeoutMs);
+        // A pause: nothing new starts, the session drains its calls in flight (an adapter that can't drain stops at once),
+        // then the node stops. One that arrived before this node could be paused stops it here.
+        pause(async (drainMs) => {
+            immediate = drainMs === 0;
+            draining = true;
+            if (session)
+                await session.interrupt({ drainMs }).catch(() => { });
+            stop(failure("aborted"));
+        });
+        if (halted) {
+            draining = true;
+            stop(failure("aborted"));
+        }
+        try {
+            if (stopped)
+                throw stopped;
+            // A paid request a crash cut off is booked once, as cut, at an unknown price, before this attempt sends anything.
+            await bounded(booking.bookCut());
+            if (stopped)
+                throw stopped;
+            session = await bounded(opening = adapter.open(spec, {
+                writer,
+                models,
+                signal: controller.signal,
+                ...(options.sessionDir ? { dir: options.sessionDir(key) } : {}),
+                onEvent: (event) => {
+                    if (event.type === "tool_start") {
+                        lastTool = event.name.slice(0, 64);
+                        if (!draining)
+                            announced.add(event.callId);
+                    }
+                    emit(event);
+                },
+            }));
+            const turnOf = async () => {
+                const end = await bounded(session.turnEnd());
+                if (end.status === "failed" && !accepted)
+                    stop(failure("model_error", end.error));
+            };
+            // Sends have their own count, checked against the same limit (or maxSends when it is null), never added to the paid
+            // requests: one send may make several. They need no record: a crash restarts them, and the recorded requests still
+            // bound the money. Turns that make no paid request also end the node `no_progress` after a few in a row.
+            const sendLimit = limit ?? maxSends;
+            let sends = 0;
+            let idle = 0;
+            const progressed = (before) => {
+                idle = accepted || turnsSoFar() > before ? 0 : idle + 1;
+                if (idle >= NO_PROGRESS_TURNS && !accepted)
+                    stop(failure("no_progress", `harness node stopped: no_progress, ${idle} turns in a row made no paid request and delivered nothing`));
+            };
+            if (session.state === "open_turn") {
+                const before = turnsSoFar();
+                sends += 1;
+                await bounded(session.recover());
+                await turnOf();
+                progressed(before);
+            }
+            let prompt = session.state === "new" ? request.user : NUDGE;
+            while (!accepted && !stopped && !draining && (limit === null || turnsSoFar() < limit) && sends < sendLimit) {
+                const before = turnsSoFar();
+                sends += 1;
+                await bounded(session.send(prompt));
+                await turnOf();
+                progressed(before);
+                prompt = NUDGE;
+            }
+            if (accepted)
+                return submission;
+            if (draining)
+                stop(failure("aborted"));
+            if (stopped)
+                throw stopped;
+            if (limit !== null && turnsSoFar() >= limit)
+                throw failure("turn_limit");
+            // The sends ran out first: say so, since the turns reported are below the limit.
+            throw failure("turn_limit", `harness node stopped: turn_limit, ${sends} turns sent (the cap on sends) made ${turnsSoFar()} paid requests and ${submissions} submissions`);
+        }
+        catch (error) {
+            if (accepted)
+                return submission;
+            if (stopped)
+                throw stopped;
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            signals.forEach((s) => s.removeEventListener("abort", onAbort));
+            if (session) {
+                if (!accepted && stopped)
+                    await session.interrupt().catch(() => { });
+                await session.close().catch(() => { });
+            }
+            else if (opening) {
+                // The node stopped while its session was opening: a session that opens later is stopped and let go, so no harness
+                // process outlives the node.
+                void opening.then(async (late) => {
+                    await late.interrupt().catch(() => { });
+                    await late.close().catch(() => { });
+                }, () => { });
+            }
+        }
+    };
+    const run = (request) => {
+        let drain = async (_drainMs) => { };
+        const node = runNode(request, (pause) => { drain = pause; });
+        running.set(node, (drainMs) => drain(drainMs));
+        void node.then(() => running.delete(node), () => running.delete(node));
+        return node;
+    };
+    return Object.assign(run, {
+        async stop(stopOptions = {}) {
+            const drainMs = stopOptions.drainMs ?? 0;
+            if (!Number.isFinite(drainMs) || drainMs < 0)
+                throw new Error("drainMs must be a non-negative number of milliseconds");
+            halted = true;
+            const nodes = [...running];
+            await Promise.all(nodes.map(([, drain]) => drain(drainMs)));
+            await Promise.allSettled(nodes.map(([node]) => node));
+        },
+    });
+}

package/dist/schema-check-cases.d.ts

@@ -0,0 +1,7 @@
+/** One case: the input schema, and where it is refused (JSON pointers), or `[]` when it may be used. */
+export interface SchemaCheckCase {
+    name: string;
+    schema: unknown;
+    refusedAt: string[];
+}
+export declare const SCHEMA_CHECK_CASES: readonly SchemaCheckCase[];

package/dist/schema-check-cases.js

@@ -0,0 +1,73 @@
+// The cases `toolSchemaProblems` decides, for every adapter's own check() tests: each harness runs the same table, so
+// their columns agree by test. Written for AgentRun.
+const P = { a: { type: "string" }, b: { type: "string" } };
+/** A schema `depth` objects deep, each one property down. */
+const nested = (depth) => {
+    let schema = { type: "string" };
+    for (let i = 0; i < depth; i += 1)
+        schema = { type: "object", properties: { a: schema } };
+    return schema;
+};
+export const SCHEMA_CHECK_CASES = Object.freeze([
+    // The root: an object of arguments, nothing else.
+    { name: "a root with no type", schema: { properties: P, required: ["a"] }, refusedAt: ["/"] },
+    { name: "a root anyOf of objects", schema: { anyOf: [{ type: "object", properties: P }, { type: "object" }] }, refusedAt: ["/"] },
+    { name: "a root of type array", schema: { type: "array", items: { type: "string" } }, refusedAt: ["/"] },
+    { name: 'a root of type ["object", "null"]', schema: { type: ["object", "null"], properties: P }, refusedAt: ["/"] },
+    { name: "a root that is only a $ref", schema: { $ref: "#/$defs/X", $defs: { X: { type: "object", properties: P } } }, refusedAt: ["/"] },
+    { name: "a root that is not a schema object", schema: "object", refusedAt: ["/"] },
+    { name: "no schema at all", schema: undefined, refusedAt: ["/"] },
+    // JSON Schema 2020-12.
+    { name: 'a type of "strng"', schema: { type: "object", properties: { a: { type: "strng" } } }, refusedAt: ["/properties/a/type"] },
+    { name: "a minimum given as a string", schema: { type: "object", properties: { n: { type: "number", minimum: "1" } } }, refusedAt: ["/properties/n/minimum"] },
+    { name: "required not an array", schema: { type: "object", properties: P, required: "a" }, refusedAt: ["/required"] },
+    { name: "tuple items (an array of schemas)", schema: { type: "object", properties: { t: { type: "array", items: [{ type: "string" }, { type: "number" }] } } }, refusedAt: ["/properties/t/items"] },
+    // $schema: a dialect Anthropic's API takes (measured: 2020-12, 2019-09, draft-07, -06, -04), or refused there.
+    { name: "a $schema of draft-07", schema: { $schema: "http://json-schema.org/draft-07/schema#", type: "object", properties: P }, refusedAt: [] },
+    { name: "a $schema of 2020-12", schema: { $schema: "https://json-schema.org/draft/2020-12/schema", type: "object", properties: P }, refusedAt: [] },
+    { name: "a $schema that is not a string", schema: { $schema: 42, type: "object", properties: P }, refusedAt: ["/$schema"] },
+    { name: "a $schema naming no dialect", schema: { $schema: "https://example.com/unknown", type: "object", properties: P }, refusedAt: ["/$schema"] },
+    // A check never throws: a schema so deep the metaschema check overflows is a problem at "/", and so is one deeper still.
+    { name: "a schema 2,000 objects deep (the metaschema check overflows)", schema: nested(2_000), refusedAt: ["/"] },
+    { name: "a schema 5,000 objects deep", schema: nested(5_000), refusedAt: ["/"] },
+    { name: "a schema 100 objects deep", schema: nested(100), refusedAt: [] },
+    // $ref: local followed, remote refused.
+    { name: "a remote $ref by URL", schema: { type: "object", properties: { r: { $ref: "https://example.com/schema.json" } } }, refusedAt: ["/properties/r/$ref"] },
+    { name: "a remote $ref by file", schema: { type: "object", properties: { r: { $ref: "other.json#/x" } } }, refusedAt: ["/properties/r/$ref"] },
+    { name: "a local $ref into $defs", schema: { type: "object", properties: { r: { $ref: "#/$defs/X" } }, $defs: { X: { type: "object", properties: P } } }, refusedAt: [] },
+    {
+        name: "a remote $ref in a schema position deep inside (anyOf in $defs)",
+        schema: { type: "object", properties: { r: { $ref: "#/$defs/X" } }, $defs: { X: { anyOf: [{ $ref: "https://example.com/a.json" }, { type: "null" }] } } },
+        refusedAt: ["/$defs/X/anyOf/0/$ref"],
+    },
+    {
+        name: "a remote $ref in a contentSchema (a schema position)",
+        schema: { type: "object", properties: { payload: { type: "string", contentMediaType: "application/json", contentSchema: { $ref: "https://example.com/payload.json" } } } },
+        refusedAt: ["/properties/payload/contentSchema/$ref"],
+    },
+    // Values, not schemas: a "$ref" key inside default, examples, const or enum is data, and a property named "$ref" is a name.
+    { name: 'a "$ref" inside a default (a value)', schema: { type: "object", properties: { d: { type: "object", default: { $ref: "data-template.json" } } } }, refusedAt: [] },
+    { name: 'a "$ref" inside examples (values)', schema: { type: "object", properties: { d: { type: "object", examples: [{ $ref: "https://example.com/x.json" }] } } }, refusedAt: [] },
+    { name: 'a "$ref" inside a const (a value)', schema: { type: "object", properties: { c: { const: { $ref: "other.json#/y" } } } }, refusedAt: [] },
+    { name: 'a "$ref" inside an enum (values)', schema: { type: "object", properties: { e: { enum: [{ $ref: "z.json" }, null] } } }, refusedAt: [] },
+    { name: 'a property named "$ref" (a name)', schema: { type: "object", properties: { $ref: { type: "string" } } }, refusedAt: [] },
+    // What may be used.
+    { name: "an empty object", schema: { type: "object" }, refusedAt: [] },
+    { name: "an open object", schema: { type: "object", additionalProperties: true }, refusedAt: [] },
+    {
+        name: "a generated schema (titles, defaults, formats, bounds, a nullable union, prefixItems)",
+        schema: {
+            type: "object",
+            title: "Input",
+            properties: {
+                q: { type: "string", title: "Q", minLength: 1, pattern: "^[a-z]+$" },
+                when: { anyOf: [{ type: "string", format: "date-time" }, { type: "null" }], default: null },
+                pair: { type: "array", prefixItems: [{ type: "string" }, { type: "number" }], items: false },
+                n: { type: "integer", minimum: 0, maximum: 4 },
+            },
+            required: ["q"],
+            additionalProperties: false,
+        },
+        refusedAt: [],
+    },
+]);

package/dist/schema-check.d.ts

@@ -0,0 +1,3 @@
+/** Where `schema`, the input schema of the tool `tool`, is refused on every harness, as `<tool>: <JSON pointer>: <why>`;
+ *  empty when it may be used. */
+export declare function toolSchemaProblems(tool: string, schema: unknown): string[];