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

package/dist/schema-check.js

@@ -0,0 +1,88 @@
+// What every harness adapter refuses in a tool's input schema before a session starts. Written for AgentRun.
+//
+// Three checks, the same on every harness so their columns agree by construction: the root is `{ "type": "object" }`
+// (a tool's input is an object of arguments; on the pinned Claude CLI one tool with any other root loses every tool of
+// the session, the submit tool too); the schema is valid JSON Schema 2020-12 (what Anthropic's API checks, and an
+// invalid schema means nothing on any harness); and no `$ref` leaves the schema (a remote one is fetched by no harness,
+// so the model never sees what it names). A local `$ref` into `$defs` is fine. Each adapter's `check()` calls this
+// first, then adds only its own harness's measured refusals.
+import { Ajv2020 } from "ajv/dist/2020.js";
+let metaschema;
+const isPlain = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const pointer = (path) => path || "/";
+const escape = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+/** The keywords whose value is a schema, a list of schemas, or a map of names to schemas (JSON Schema 2020-12, with the
+ *  older spellings a generator still writes). Every other keyword holds values (default, examples, const, enum, ...). */
+const SCHEMA_ONE = new Set(["items", "additionalItems", "additionalProperties", "contains", "propertyNames", "unevaluatedItems", "unevaluatedProperties", "not", "if", "then", "else", "contentSchema"]);
+const SCHEMA_LISTS = new Set(["allOf", "anyOf", "oneOf", "prefixItems", "items"]);
+const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas", "dependencies"]);
+/** The `$schema` dialects Anthropic's API takes (measured; with or without a trailing "#"). Any other value, or one that
+ *  is not a string, it rejects. A schema is checked as 2020-12 whichever of these it names, as the API does. */
+const DIALECTS = new Set([
+    "https://json-schema.org/draft/2020-12/schema", "https://json-schema.org/draft/2019-09/schema",
+    "http://json-schema.org/draft-07/schema", "http://json-schema.org/draft-06/schema", "http://json-schema.org/draft-04/schema",
+]);
+/** 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 function toolSchemaProblems(tool, schema) {
+    if (!isPlain(schema) || schema.type !== "object") {
+        return [`${tool}: /: the root must be {"type": "object"} (a tool's input is an object of arguments), not ${String(JSON.stringify(isPlain(schema) ? schema.type ?? null : schema) ?? schema).slice(0, 60)}`];
+    }
+    // A schema is sent as JSON: one that is not JSON (a cycle in its objects, a BigInt) is refused before anything walks it.
+    try {
+        JSON.stringify(schema);
+    }
+    catch (error) {
+        return [`${tool}: /: the schema is not JSON (${String(error?.message ?? error).split("\n")[0].slice(0, 80)}); a tool's input schema is sent as JSON`];
+    }
+    const problems = [];
+    const { $schema: dialect, ...body } = schema;
+    if (dialect !== undefined && !(typeof dialect === "string" && DIALECTS.has(dialect.replace(/#$/, "")))) {
+        problems.push(`${tool}: /$schema: ${String(JSON.stringify(dialect)).slice(0, 80)} names no JSON Schema dialect (2020-12, 2019-09, draft-07, -06 or -04)`);
+    }
+    metaschema ??= new Ajv2020({ strict: false, allErrors: true });
+    let valid;
+    try {
+        valid = metaschema.validateSchema(body);
+    }
+    catch (error) {
+        problems.push(`${tool}: /: ${String(error?.message ?? error).slice(0, 120)} (not valid JSON Schema 2020-12)`);
+        valid = true;
+    }
+    if (!valid) {
+        // One problem per place: the metaschema's own anyOf wrappers repeat a place's failure.
+        const seen = new Set();
+        for (const error of metaschema.errors ?? []) {
+            if (error.keyword === "anyOf" || seen.has(error.instancePath))
+                continue;
+            seen.add(error.instancePath);
+            problems.push(`${tool}: ${pointer(error.instancePath)}: ${error.message ?? "invalid"} (not valid JSON Schema 2020-12)`);
+        }
+    }
+    // Only where a schema sits: a "$ref" inside default, examples, const or enum is a value, and a property's name is a name.
+    // A loop with its own stack, not recursion, so no depth of schema can overflow it.
+    const pending = [[schema, ""]];
+    while (pending.length) {
+        const [node, at] = pending.pop();
+        if (!isPlain(node))
+            continue;
+        const ref = node.$ref;
+        if (typeof ref === "string" && !ref.startsWith("#"))
+            problems.push(`${tool}: ${at}/$ref: a remote $ref (${JSON.stringify(ref).slice(0, 80)}) is refused; only a local one ("#/$defs/...") is followed`);
+        const next = [];
+        for (const [key, value] of Object.entries(node)) {
+            const here = `${at}/${escape(key)}`;
+            if (SCHEMA_MAPS.has(key) && isPlain(value))
+                for (const [name, sub] of Object.entries(value))
+                    next.push([sub, `${here}/${escape(name)}`]);
+            else if (SCHEMA_LISTS.has(key) && Array.isArray(value))
+                value.forEach((sub, i) => next.push([sub, `${here}/${i}`]));
+            else if (SCHEMA_ONE.has(key))
+                next.push([value, here]);
+        }
+        // Children in reverse onto the stack, so they're visited in the schema's order.
+        for (let i = next.length - 1; i >= 0; i -= 1)
+            pending.push(next[i]);
+    }
+    return problems;
+}

package/dist/skill-files.d.ts

@@ -0,0 +1,23 @@
+import type { HostTool } from "./types.js";
+/** A skill a host gives a harness, which the model may load: its name, and its files by path, `SKILL.md` among them. */
+export interface HostSkill {
+    /** Lowercase letters, digits and dashes; `SKILL.md`'s front matter names it the same. */
+    name: string;
+    /** Each file's text by its path inside the skill (`SKILL.md`, `reference/sources.md`). */
+    files: Readonly<Record<string, string>>;
+}
+/** A skill, as the tool knows it: its name, and the paths of its files. */
+export interface SkillFileList {
+    name: string;
+    files: readonly string[];
+}
+/** The tool's name, as the model calls it. */
+export declare const READ_SKILL_FILE = "read_skill_file";
+/** The most bytes a host's skills hold in all, every file of every skill (`skillProblems`): over it the set is refused. */
+export declare const SKILL_BYTES: number;
+/** The skills, checked, as every adapter that takes a host's skills checks them when it is made: each a name, a
+ *  `SKILL.md` whose front matter has that name and a description, and files at plain relative paths, 1 MiB in all; or the
+ *  problems. What one harness would refuse or rename (the Claude Agent CLI, Codex) is refused here for all of them. */
+export declare function skillProblems(skills: readonly HostSkill[]): string[];
+/** The host tool that reads the skills' files under `root` (`<root>/<skill>/<path>`): replay-safe, read-only. */
+export declare function readSkillFileTool(root: string, skills: readonly SkillFileList[]): HostTool;

package/dist/skill-files.js

@@ -0,0 +1,136 @@
+// A host's skills, as every adapter that takes them checks them (`skillProblems`), and a skill's own files, read by the
+// model through a host tool. Written for AgentRun.
+//
+// A host that gives a harness skills writes each skill's files under one root (`<root>/<skill>/<path>`). The model reads
+// what SKILL.md points it at through `read_skill_file`, a read-only host tool, and nothing else of the disk: the skill
+// and its directory come from the host's own list, never from the request; the path must be one of that skill's listed
+// files, exactly, and is refused before any filesystem call when it is absolute or climbs (`..`); no link is followed
+// anywhere in it (each part is checked, the file is opened without following one, and the opened file is checked to
+// be the expected one after the open, so a link swapped in between is caught).
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+/** The tool's name, as the model calls it. */
+export const READ_SKILL_FILE = "read_skill_file";
+const MAX_BYTES = 1024 * 1024;
+const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const SKILL_PATH = /^(?:[A-Za-z0-9_][A-Za-z0-9._-]{0,99}\/){0,4}[A-Za-z0-9_][A-Za-z0-9._-]{0,99}$/;
+/** The most bytes a host's skills hold in all, every file of every skill (`skillProblems`): over it the set is refused. */
+export const SKILL_BYTES = 1024 * 1024;
+/** The skills, checked, as every adapter that takes a host's skills checks them when it is made: each a name, a
+ *  `SKILL.md` whose front matter has that name and a description, and files at plain relative paths, 1 MiB in all; or the
+ *  problems. What one harness would refuse or rename (the Claude Agent CLI, Codex) is refused here for all of them. */
+export function skillProblems(skills) {
+    const problems = [];
+    const seen = new Set();
+    let bytes = 0;
+    for (const skill of skills) {
+        const name = String(skill?.name ?? "");
+        if (!SKILL_NAME.test(name)) {
+            problems.push(`the skill name ${JSON.stringify(name.slice(0, 80))} is not lowercase letters, digits and dashes`);
+            continue;
+        }
+        if (seen.has(name))
+            problems.push(`the skill ${name} is given twice`);
+        seen.add(name);
+        const files = skill.files ?? {};
+        const md = files["SKILL.md"];
+        const front = typeof md === "string" ? /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(md)?.[1] : undefined;
+        if (front === undefined)
+            problems.push(`the skill ${name} has no SKILL.md with front matter`);
+        else {
+            if (!new RegExp(`^name:\\s*(['"]?)${name}\\1\\s*$`, "m").test(front))
+                problems.push(`the skill ${name}'s SKILL.md names it otherwise`);
+            if (!/^description:\s*\S/m.test(front))
+                problems.push(`the skill ${name}'s SKILL.md has no description`);
+        }
+        // A path that is another's folder (reference, and reference/sources.md) can't be written as both.
+        const paths = new Set(Object.keys(files));
+        for (const folder of new Set([...paths].flatMap((path) => path.split("/").slice(0, -1).map((_, i, parts) => parts.slice(0, i + 1).join("/"))))) {
+            if (paths.has(folder))
+                problems.push(`the skill ${name}'s ${folder} is both a file and a folder`);
+        }
+        for (const [path, text] of Object.entries(files)) {
+            if (!SKILL_PATH.test(path) || path.split("/").some((part) => part === "." || part === ".."))
+                problems.push(`the skill ${name}'s file ${JSON.stringify(path.slice(0, 80))} is not a plain relative path`);
+            if (typeof text !== "string")
+                problems.push(`the skill ${name}'s file ${path} is not text`);
+            else
+                bytes += Buffer.byteLength(text);
+        }
+    }
+    if (bytes > SKILL_BYTES)
+        problems.push(`the skills hold ${bytes} bytes, more than ${SKILL_BYTES}`);
+    return problems;
+}
+/** Why `path` of `skill` is not readable, or undefined: the checks made before any filesystem call. */
+function refusedBeforeDisk(skills, skill, path) {
+    if (typeof skill !== "string" || typeof path !== "string")
+        return "give a skill's name and a file's path, both as text";
+    if (path.startsWith("/") || path.includes("\\") || path.split("/").some((part) => part === ".." || part === "." || part === ""))
+        return `the path ${JSON.stringify(path.slice(0, 120))} is absolute or climbs (..): give a path inside the skill, as its SKILL.md names it`;
+    const files = skills.get(skill);
+    if (!files)
+        return `${JSON.stringify(skill.slice(0, 80))} is not one of your skills`;
+    if (!files.has(path))
+        return `${JSON.stringify(path.slice(0, 120))} is not one of the skill ${skill}'s files`;
+    return undefined;
+}
+/** The file's text, read without following a link anywhere in its path; throws a reason a model can read. */
+function readNoFollow(root, skill, path) {
+    // The root is resolved (its own path may pass through a link, as /tmp does on some machines); the skill's directory under
+    // it is not: a link there would make its target the trusted base.
+    const dir = join(realpathSync(root), skill);
+    if (lstatSync(dir).isSymbolicLink())
+        throw new Error(`the skill ${skill}'s directory is a link, which is not followed`);
+    let at = dir;
+    for (const part of path.split("/")) {
+        at = join(at, part);
+        if (lstatSync(at).isSymbolicLink())
+            throw new Error(`the skill ${skill}'s ${path} goes through a link, which is not followed`);
+    }
+    const fd = openSync(at, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        // After the open: the file opened is the one checked, not a link swapped in between.
+        if (process.platform === "linux") {
+            if (readlinkSync(`/proc/self/fd/${fd}`) !== at)
+                throw new Error(`the skill ${skill}'s ${path} is not the file it was`);
+        }
+        else {
+            const opened = fstatSync(fd);
+            const expected = lstatSync(at);
+            if (opened.dev !== expected.dev || opened.ino !== expected.ino)
+                throw new Error(`the skill ${skill}'s ${path} is not the file it was`);
+        }
+        if (!fstatSync(fd).isFile())
+            throw new Error(`the skill ${skill}'s ${path} is not a file`);
+        if (fstatSync(fd).size > MAX_BYTES)
+            throw new Error(`the skill ${skill}'s ${path} is larger than ${MAX_BYTES} bytes`);
+        return readFileSync(fd, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The host tool that reads the skills' files under `root` (`<root>/<skill>/<path>`): replay-safe, read-only. */
+export function readSkillFileTool(root, skills) {
+    const known = new Map(skills.map((skill) => [skill.name, new Set(skill.files)]));
+    return {
+        name: READ_SKILL_FILE,
+        description: "Read a file of one of your skills: the skill's name and the file's path inside it, as its SKILL.md names it.",
+        inputSchema: { type: "object", properties: { skill: { type: "string", enum: [...known.keys()] }, path: { type: "string" } }, required: ["skill", "path"], additionalProperties: false },
+        replay: "safe",
+        async call(args) {
+            const { skill, path } = (args ?? {});
+            const refused = refusedBeforeDisk(known, skill, path);
+            if (refused)
+                return { text: `Not read: ${refused}.`, isError: true };
+            try {
+                return { text: readNoFollow(root, skill, path) };
+            }
+            catch (error) {
+                const code = error?.code;
+                return { text: `Not read: ${code === "ELOOP" ? `the skill ${String(skill)}'s ${String(path)} is a link, which is not followed` : error.message}.`, isError: true };
+            }
+        },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1,91 @@
+import type { AgentAdapter, SessionSpec, SessionState, SessionStore, TurnStatus } from "./types.js";
+export { SCHEMA_CHECK_CASES, type SchemaCheckCase } from "./schema-check-cases.js";
+/** A session store in memory: what one run's store holds, across the processes a test plays. Each `open` of a key
+ *  counts one more holder at once, and a writer appends only while its count is the newest. */
+export declare function memorySessionStore(): SessionStore & {
+    keys(): string[];
+};
+/** One model request of the faux harness, and what its reply does. */
+export type FauxAction = {
+    say: string;
+    usd?: number | null;
+} | {
+    call: string;
+    args?: unknown;
+    usd?: number | null;
+}
+/** One answer that asks for several tools, run one after another, as Claude Code and Codex run a response's calls.
+ *  `bookAfter`: the calls run before the answer's cost is booked, as with Claude Code, whose cost comes in after its
+ *  response, so a call can end before the request that asked for it is paid. */
+ | {
+    calls: {
+        call: string;
+        args?: unknown;
+    }[];
+    usd?: number | null;
+    bookAfter?: boolean;
+} | {
+    submit: unknown;
+    usd?: number | null;
+}
+/** The reply ends the turn without a submission: `completed`, or the status `turn` names (a harness that ends its own
+ *  turn interrupted, with no stop asked for, ends it so). */
+ | {
+    end: true;
+    usd?: number | null;
+    turn?: TurnStatus;
+}
+/** The request fails: the turn ends failed. */
+ | {
+    fail: string;
+}
+/** The process stops here: nothing resolves until the session's signal aborts. */
+ | {
+    hang: true;
+}
+/** The harness halts the drive with this reason (a spend cap, a mirror it cannot keep): the turn ends failed, naming it. */
+ | {
+    halt: string;
+}
+/** A paid request leaves (its beforeRequest passes) and the process dies before it answers: nothing more resolves. */
+ | {
+    cut: true;
+}
+/** A paid request leaves and holds unanswered until the turn is stopped: the stop cuts it, and its cost (what had
+ *  streamed) is still booked, as a provider bills a response cut short. */
+ | {
+    cutBooked: true;
+    usd?: number | null;
+};
+export declare const FAUX_RECORDS: {
+    readonly request: "faux.request";
+    readonly user: "faux.user";
+    readonly turn: "faux.turn";
+    readonly turnEnd: "faux.turn_end";
+    readonly call: "faux.call";
+    readonly result: "faux.result";
+};
+export interface FauxOptions {
+    /** The session's model replies, in order, by its spec: one action per paid request. */
+    script: (spec: SessionSpec) => FauxAction[];
+    /** Whether the faux harness can fork (default false). */
+    fork?: boolean;
+    /** Problems `check` reports for a spec. */
+    refuse?: (spec: SessionSpec) => string[];
+    /** How long `open` takes, ignoring the session's signal, as a slow harness start does (default 0). */
+    openDelayMs?: number;
+}
+export interface FauxAdapter extends AgentAdapter {
+    /** Paid requests made, across every session and process of this adapter. */
+    readonly requests: number;
+    /** Tool calls run, by name. */
+    readonly calls: string[];
+    /** The sessions opened, by key, with the state each was found in. */
+    readonly opened: {
+        key: string;
+        state: SessionState;
+    }[];
+    /** Sessions closed. */
+    readonly closed: string[];
+}
+export declare function fauxAdapter(options: FauxOptions): FauxAdapter;

package/dist/testing.js

@@ -0,0 +1,196 @@
+// Test kit: a session store in memory, and a scripted harness with no model and no network. The faux harness keeps its
+// own records in the store as a real adapter does (the requests it made, each tool call's intent and outcome, its turns),
+// so a later process resumes from them: a request already made is not made again, and a call a crash cut off is
+// answered interrupted, never run again.
+import { SessionFenced } from "./errors.js";
+import { abortedOutcome, SessionHalt } from "./kernel/halt.js";
+export { SCHEMA_CHECK_CASES } from "./schema-check-cases.js";
+/** A session store in memory: what one run's store holds, across the processes a test plays. Each `open` of a key
+ *  counts one more holder at once, and a writer appends only while its count is the newest. */
+export function memorySessionStore() {
+    const sessions = new Map();
+    const holders = new Map();
+    const read = async (key) => structuredClone(sessions.get(key) ?? []);
+    return {
+        read,
+        async open(key) {
+            const holder = (holders.get(key) ?? 0) + 1;
+            holders.set(key, holder);
+            return {
+                key,
+                read: () => read(key),
+                async append(records) {
+                    if (holders.get(key) !== holder)
+                        throw new SessionFenced(key);
+                    sessions.set(key, [...(sessions.get(key) ?? []), ...structuredClone(records)]);
+                },
+            };
+        },
+        keys: () => [...sessions.keys()],
+    };
+}
+export const FAUX_RECORDS = { request: "faux.request", user: "faux.user", turn: "faux.turn", turnEnd: "faux.turn_end", call: "faux.call", result: "faux.result" };
+export function fauxAdapter(options) {
+    const stats = { requests: 0, calls: [], opened: [], closed: [] };
+    const adapter = {
+        id: "faux",
+        version: "0.0.0",
+        get requests() { return stats.requests; },
+        get calls() { return stats.calls; },
+        get opened() { return stats.opened; },
+        get closed() { return stats.closed; },
+        capabilities: () => ({ fork: options.fork ?? false }),
+        check: (spec) => [
+            ...(spec.context === "fork" && !options.fork ? ["the faux harness cannot fork a session"] : []),
+            ...(options.refuse?.(spec) ?? []),
+        ],
+        async open(spec, io) {
+            if (options.openDelayMs)
+                await new Promise((resolve) => setTimeout(resolve, options.openDelayMs));
+            const script = options.script(spec);
+            const records = await io.writer.read();
+            const append = (kind, data) => io.writer.append([{ kind, data }]);
+            let cursor = records.filter((r) => r.kind === FAUX_RECORDS.request).length;
+            const turnsStarted = records.filter((r) => r.kind === FAUX_RECORDS.turn).length;
+            const turnsEnded = records.filter((r) => r.kind === FAUX_RECORDS.turnEnd).length;
+            let state = turnsStarted === 0 ? "new" : turnsStarted > turnsEnded ? "open_turn" : "idle";
+            stats.opened.push({ key: spec.key, state });
+            // A call whose intent is recorded and whose outcome is not: a crash cut it off. It is answered interrupted, once.
+            const results = new Set(records.filter((r) => r.kind === FAUX_RECORDS.result).map((r) => r.data.callId));
+            for (const r of records.filter((r) => r.kind === FAUX_RECORDS.call)) {
+                const { callId } = r.data;
+                if (!results.has(callId))
+                    await append(FAUX_RECORDS.result, { callId, interrupted: true });
+            }
+            const tools = new Map(spec.tools.map((tool) => [tool.name, tool]));
+            /** What the session has been sent, as a model would be prompted with it. */
+            const prompt = records.filter((r) => r.kind === FAUX_RECORDS.user).map((r) => r.data.text);
+            let ending;
+            let turnSignal;
+            const end = async (status, error) => {
+                // A turn whose end cannot be written (its writer was fenced) still ends: failed, saying why.
+                try {
+                    await append(FAUX_RECORDS.turnEnd, { status });
+                }
+                catch (cause) {
+                    status = "failed";
+                    error = cause.message;
+                }
+                io.onEvent({ type: "turn_end", status });
+                ending?.resolve({ status, ...(error === undefined ? {} : { error }) });
+            };
+            const hang = (signal) => new Promise((_, reject) => {
+                if (signal.aborted)
+                    reject(signal.reason);
+                else
+                    signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+            });
+            /** The turn's model loop: one scripted action per paid request, until one ends the turn. */
+            const run = async () => {
+                const signal = AbortSignal.any([io.signal, (turnSignal = new AbortController()).signal]);
+                try {
+                    for (;;) {
+                        const action = script[cursor];
+                        if (!action)
+                            return await end("completed");
+                        if ("hang" in action)
+                            return await hang(signal);
+                        if ("halt" in action) {
+                            turnSignal.abort(new Error(action.halt));
+                            return await hang(signal);
+                        }
+                        // Measured as a real adapter's proxy measures its body: the prompt's UTF-8 bytes, with nothing a provider adds.
+                        const ticket = await io.models.beforeRequest({ model: "faux", inputTokensMax: Buffer.byteLength(JSON.stringify({ system: spec.system, user: prompt }), "utf8") });
+                        if ("cut" in action) {
+                            stats.requests += 1;
+                            return await hang(signal);
+                        }
+                        if ("cutBooked" in action) {
+                            stats.requests += 1;
+                            await append(FAUX_RECORDS.request, { index: cursor++ });
+                            try {
+                                return await hang(signal);
+                            }
+                            finally {
+                                await io.models.afterRequest({ input: 10, output: 5, usd: action.usd === undefined ? 0.001 : action.usd });
+                            }
+                        }
+                        stats.requests += 1;
+                        const index = cursor++;
+                        // The output limit it was admitted with (what is left of a spend cap can buy), as a real adapter's proxy would
+                        // write it into the body: filed, for a test to see.
+                        const limit = ticket ? ticket.outputTokensMax : undefined;
+                        await append(FAUX_RECORDS.request, { index, ...(limit === undefined ? {} : { outputTokensMax: limit }) });
+                        if ("fail" in action)
+                            return await end("failed", action.fail);
+                        const book = () => io.models.afterRequest({ input: 10, output: 5, usd: action.usd === undefined ? 0.001 : action.usd });
+                        const bookAfter = "calls" in action && action.bookAfter === true;
+                        if (!bookAfter)
+                            await book();
+                        if ("say" in action)
+                            io.onEvent({ type: "text", delta: action.say });
+                        else if ("end" in action)
+                            return await end(action.turn ?? "completed");
+                        else {
+                            const asked = "calls" in action ? action.calls.map((c) => ({ name: c.call, args: c.args ?? {} }))
+                                : [{ name: "call" in action ? action.call : "submit", args: "call" in action ? action.args ?? {} : { value: action.submit } }];
+                            for (const [n, { name, args }] of asked.entries()) {
+                                const callId = "calls" in action ? `${spec.key}:${index}.${n}` : `${spec.key}:${index}`;
+                                const tool = tools.get(name);
+                                await append(FAUX_RECORDS.call, { callId, name });
+                                io.onEvent({ type: "tool_start", callId, name, args });
+                                const result = tool ? await tool.call(args, { callId, signal }).catch((error) => ({ text: error.message, isError: true })) : { text: `unknown tool ${name}`, isError: true };
+                                if (tool)
+                                    stats.calls.push(name);
+                                await append(FAUX_RECORDS.result, { callId, isError: result.isError === true });
+                                io.onEvent({ type: "tool_end", callId, name, isError: result.isError === true });
+                            }
+                            if (bookAfter)
+                                await book();
+                        }
+                    }
+                }
+                catch (error) {
+                    // Stopped by the session or its host: interrupted. Halted by anything else: failed, naming why.
+                    if (signal.aborted) {
+                        const outcome = abortedOutcome(signal, io.signal);
+                        if (outcome.status === "interrupted")
+                            return void ending?.resolve(outcome);
+                        return await end("failed", outcome.error);
+                    }
+                    return await end("failed", error.message);
+                }
+            };
+            const begin = () => {
+                let resolve;
+                const promise = new Promise((r) => { resolve = r; });
+                ending = { promise, resolve };
+                void run();
+            };
+            const session = {
+                get state() { return state; },
+                async send(text) {
+                    state = "idle";
+                    await append(FAUX_RECORDS.user, { text });
+                    prompt.push(text);
+                    await append(FAUX_RECORDS.turn, { n: turnsStarted + 1 });
+                    begin();
+                },
+                async recover() { state = "idle"; begin(); },
+                // The open turn ends in the session's records, as a turn's end is written (end()), and nothing runs. Its end is the
+                // kernel's for the session's own stop (abortedOutcome of its SessionHalt), as an interrupted turn's is here.
+                async settleOpenTurn() {
+                    if (state !== "open_turn")
+                        throw new Error("faux: there is no turn to settle");
+                    await append(FAUX_RECORDS.turnEnd, { status: abortedOutcome(AbortSignal.abort(new SessionHalt("interrupted"))).status });
+                    state = "idle";
+                },
+                turnEnd: () => ending ? ending.promise : Promise.resolve({ status: "completed" }),
+                async interrupt() { turnSignal?.abort(new SessionHalt("interrupted")); },
+                async close() { turnSignal?.abort(new SessionHalt("closed")); stats.closed.push(spec.key); },
+            };
+            return session;
+        },
+    };
+    return adapter;
+}