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

package/dist/kernel/blobs.d.ts

@@ -0,0 +1,16 @@
+import type { KernelWorld } from "./types.js";
+export declare const BLOB_RECORD = "kernel.blob";
+/** Characters per piece. */
+export declare const BLOB_PIECE_CHARS: number;
+/** Where a session's blobs are, for messages: the session's own records. */
+export declare const blobStreamName: (runId: string) => string;
+export declare function sha256Hex(content: string): Promise<string>;
+/** Write `text` as the blob `hash` (its sha256; a caller that has it already passes it), in pieces, durably before it
+ *  resolves. A hash that is not the text's is refused. */
+export declare function writeBlob(world: KernelWorld, runId: string, text: string, options?: {
+    hash?: string;
+    pieceChars?: number;
+}): Promise<string>;
+/** Every complete blob of the session, by hash: the pieces of one layout (a hash and its piece count), joined, and
+ *  only when they hash to that name. */
+export declare function readBlobs(world: KernelWorld, runId: string): Promise<Map<string, string>>;

package/dist/kernel/blobs.js

@@ -0,0 +1,59 @@
+// Records too large to keep inline, as content-addressed pieces in the session's own records (kind `kernel.blob`), by
+// the names the copied journal calls. A blob is named by its content's sha256, and counts only once all the pieces of
+// one write are there and join to text with that hash: a write again under another piece size is a layout of its own,
+// never mixed with the first. Written for AgentRun.
+import { createHash } from "node:crypto";
+import { SessionFenced } from "../errors.js";
+import { Restart } from "./errors.js";
+export const BLOB_RECORD = "kernel.blob";
+/** Characters per piece. */
+export const BLOB_PIECE_CHARS = 2 * 1024 * 1024;
+/** Where a session's blobs are, for messages: the session's own records. */
+export const blobStreamName = (runId) => `${runId} (${BLOB_RECORD} records)`;
+export async function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** Write `text` as the blob `hash` (its sha256; a caller that has it already passes it), in pieces, durably before it
+ *  resolves. A hash that is not the text's is refused. */
+export async function writeBlob(world, runId, text, options = {}) {
+    const hash = await sha256Hex(text);
+    if (options.hash !== undefined && options.hash !== hash)
+        throw new TypeError("agentrun-kernel: a blob's hash must be its text's sha256");
+    const size = options.pieceChars ?? BLOB_PIECE_CHARS;
+    const count = Math.max(1, Math.ceil(text.length / size));
+    const records = Array.from({ length: count }, (_, piece) => ({ kind: BLOB_RECORD, data: { hash, piece, count, text: text.slice(piece * size, (piece + 1) * size) } }));
+    try {
+        await world.store.append(records);
+    }
+    catch (error) {
+        // A newer drive holds the session, as for an effect's own writes.
+        if (error instanceof SessionFenced)
+            throw new Restart(`agentrun-kernel: ${error.message}`);
+        throw error;
+    }
+    return hash;
+}
+/** Every complete blob of the session, by hash: the pieces of one layout (a hash and its piece count), joined, and
+ *  only when they hash to that name. */
+export async function readBlobs(world, runId) {
+    const layouts = new Map();
+    for (const record of await world.store.read()) {
+        if (record.kind !== BLOB_RECORD)
+            continue;
+        const { hash, piece, count, text } = record.data;
+        const layout = `${hash}/${count}`;
+        const blob = layouts.get(layout) ?? { hash, count, parts: new Map() };
+        if (!blob.parts.has(piece))
+            blob.parts.set(piece, text);
+        layouts.set(layout, blob);
+    }
+    const out = new Map();
+    for (const blob of layouts.values()) {
+        if (out.has(blob.hash) || blob.parts.size !== blob.count)
+            continue;
+        const text = Array.from({ length: blob.count }, (_, i) => blob.parts.get(i) ?? "").join("");
+        if ((await sha256Hex(text)) === blob.hash)
+            out.set(blob.hash, text);
+    }
+    return out;
+}

package/dist/kernel/drive.d.ts

@@ -0,0 +1,35 @@
+import type { SessionRecord, SessionWriter } from "../types.js";
+import type { DriveContext, EffectIO, HostToolIO, SessionState, Submission } from "./types.js";
+export declare const KERNEL_RECORDS: {
+    readonly submission: "kernel.submission";
+    readonly start: "kernel.start";
+    readonly end: "kernel.end";
+    readonly retry: "kernel.retry";
+};
+/** What an interrupted `never` effect's error says. */
+export declare const INTERRUPTED_TEXT = "interrupted: the process running it stopped before it reported an outcome; it may or may not have taken effect";
+/** The state a session's records fold to. */
+export declare function foldSession(runId: string, records: readonly SessionRecord[]): SessionState;
+export declare function pendingSubmissions(state: SessionState): Submission[];
+export declare function hostToolIO(io: EffectIO, ctx: DriveContext, overrides?: {
+    signal?: AbortSignal;
+    progress?: (chunk: unknown) => void;
+}): HostToolIO;
+export interface OpenDriveOptions {
+    /** The session's writer (`SessionStore.open`): the drive writes only through it, and its key is the session's. */
+    writer: SessionWriter;
+    signal: AbortSignal;
+    config?: unknown;
+    attempt?: number;
+    deadline?: number;
+    live?: (event: unknown) => void;
+    halt?: (reason: unknown) => void;
+}
+export interface Drive extends DriveContext {
+    /** Record new input for the session (the door's accepted submission, or a withdraw). Resolves once it is durable. */
+    submit(submission: Omit<Submission, "receivedAt"> & {
+        receivedAt?: Date;
+    }): Promise<void>;
+}
+/** Open the session's drive: fold its records and resolve whatever a dead process left open. */
+export declare function openDrive(options: OpenDriveOptions): Promise<Drive>;

package/dist/kernel/drive.js

@@ -0,0 +1,202 @@
+// A session's drive over its records: the kernel the copied harness code runs on. Written for AgentRun.
+//
+// An effect is an intent (`kernel.start`), then at most one outcome (`kernel.end`), both durable before the code that
+// follows them goes on: a completed or failed key is answered from its records and never run again. One drive holds a
+// session at a time, and the store enforces it: a drive writes through the session's writer, which a newer open of the
+// session fences, so a stale drive's next write is refused and it gets a `Restart`, never a result. So when a drive
+// opens, an intent with no outcome was cut off by the process that wrote it: a `safe` one is released to run again (`kernel.retry`), a `never` one is recorded failed and interrupted
+// ("it may or may not have taken effect") and is never run again. Input is a `kernel.submission` record; an effect that
+// names submissions in `placed` takes them out of `pending()` at its intent, and a withdraw written before that wins:
+// that placement places nothing and its effect throws `Restart`.
+import { SessionFenced } from "../errors.js";
+import { EffectFailure, EffectInterrupted, Fatal, Restart } from "./errors.js";
+export const KERNEL_RECORDS = {
+    submission: "kernel.submission",
+    start: "kernel.start",
+    end: "kernel.end",
+    retry: "kernel.retry",
+};
+/** What an interrupted `never` effect's error says. */
+export const INTERRUPTED_TEXT = "interrupted: the process running it stopped before it reported an outcome; it may or may not have taken effect";
+/** The state a session's records fold to. */
+export function foldSession(runId, records) {
+    const state = { runId, status: "running", submissions: [], placed: new Set(), withdrawn: new Set(), effects: new Map(), effectOrder: [] };
+    const byStep = new Map();
+    for (const record of records) {
+        if (record.kind === KERNEL_RECORDS.submission) {
+            const data = record.data;
+            if (state.submissions.some((s) => s.id === data.id))
+                continue;
+            state.submissions.push({ ...data, receivedAt: new Date(data.receivedAt) });
+            // A withdraw lands only while its target is not placed yet.
+            if (data.kind === "withdraw" && data.target && !state.placed.has(data.target))
+                state.withdrawn.add(data.target);
+        }
+        else if (record.kind === KERNEL_RECORDS.start) {
+            const data = record.data;
+            const existing = state.effects.get(data.key);
+            // A key's first intent wins; a later one is the same key run again after a release.
+            if (existing && existing.status !== "pending")
+                continue;
+            // A placement a withdraw beat places nothing, not even its other submissions: the effect that wrote it is
+            // refused (`Restart`), and the next drive places what is still pending.
+            const placed = data.placed.some((id) => state.withdrawn.has(id)) ? [] : data.placed;
+            const effect = { key: data.key, stepId: data.stepId, name: data.name, replay: data.replay, input: data.input, status: "running", attempt: data.attempt, startedAt: new Date(data.startedAt), placed };
+            if (existing)
+                Object.assign(existing, effect, { output: undefined, error: undefined });
+            else {
+                state.effects.set(data.key, effect);
+                state.effectOrder.push(effect);
+            }
+            byStep.set(data.stepId, existing ?? effect);
+            for (const id of placed)
+                state.placed.add(id);
+        }
+        else if (record.kind === KERNEL_RECORDS.end) {
+            const data = record.data;
+            const effect = byStep.get(data.stepId);
+            // An outcome applies only to an effect that is running under that step.
+            if (!effect || effect.status !== "running" || effect.stepId !== data.stepId)
+                continue;
+            effect.status = data.status;
+            if (data.status === "completed")
+                effect.output = data.output;
+            else
+                effect.error = data.error ?? { message: "failed" };
+        }
+        else if (record.kind === KERNEL_RECORDS.retry) {
+            const effect = byStep.get(record.data.stepId);
+            if (effect && effect.status === "running")
+                effect.status = "pending";
+        }
+    }
+    return state;
+}
+export function pendingSubmissions(state) {
+    return state.submissions.filter((s) => s.kind !== "withdraw" && !state.placed.has(s.id) && !state.withdrawn.has(s.id));
+}
+export function hostToolIO(io, ctx, overrides = {}) {
+    return { signal: overrides.signal ?? io.signal, progress: overrides.progress ?? io.progress, ctx, stepId: io.stepId };
+}
+/** Open the session's drive: fold its records and resolve whatever a dead process left open. */
+export async function openDrive(options) {
+    const { writer } = options;
+    const key = writer.key;
+    let records = await writer.read();
+    let state = foldSession(key, records);
+    const appendNow = async (written) => {
+        try {
+            await writer.append(written);
+        }
+        catch (error) {
+            // A newer drive holds the session: this one must rebuild from the log, and nothing it was writing counts.
+            if (error instanceof SessionFenced)
+                throw new Restart(`agentrun-kernel: ${error.message}`);
+            throw error;
+        }
+        records = [...records, ...written];
+        state = foldSession(key, records);
+    };
+    // Appends go to the writer one at a time, in call order, so the state folds records in the order the log holds
+    // them even when a submit's input and an effect's intent are written at once and a writer resolves them out of order.
+    let queue = Promise.resolve();
+    const append = (written) => {
+        const run = queue.then(() => appendNow(written));
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    // One drive holds the session: an intent with no outcome belongs to a process that is gone.
+    const abandoned = state.effectOrder.filter((e) => e.status === "running");
+    if (abandoned.length) {
+        await append(abandoned.map((e) => e.replay === "safe"
+            ? { kind: KERNEL_RECORDS.retry, data: { stepId: e.stepId } }
+            : { kind: KERNEL_RECORDS.end, data: { stepId: e.stepId, status: "failed", error: { message: INTERRUPTED_TEXT, interrupted: true } } }));
+    }
+    const controller = new AbortController();
+    const signal = AbortSignal.any([options.signal, controller.signal]);
+    const hints = new Set();
+    // Keys this drive has begun and not finished, reserved before the first await: two calls issued together cannot both
+    // pass the checks below and dispatch one effect twice.
+    const inflight = new Set();
+    const drive = {
+        runId: key,
+        // The copied code's own writes (a journal's blobs) go through the same queue as the drive's.
+        world: { store: { key: writer.key, read: () => writer.read(), append: (written) => append([...written]) } },
+        config: options.config,
+        attempt: options.attempt ?? 0,
+        ...(options.deadline === undefined ? {} : { deadline: options.deadline }),
+        signal,
+        state: () => state,
+        isMemoized: (k) => {
+            const status = state.effects.get(k)?.status;
+            return status === "completed" || status === "failed";
+        },
+        pending: () => pendingSubmissions(state),
+        // No read: this drive is the session's only writer, so its records are the whole log, and a read that resolved
+        // after a newer append would put older state back.
+        async refresh() {
+            state = foldSession(key, records);
+        },
+        live: (event) => options.live?.(event),
+        onHint(listener) {
+            hints.add(listener);
+            return () => { hints.delete(listener); };
+        },
+        halt(reason) {
+            if (!controller.signal.aborted)
+                controller.abort(reason);
+            options.halt?.(reason);
+        },
+        async submit(submission) {
+            const { receivedAt, ...rest } = submission;
+            await append([{ kind: KERNEL_RECORDS.submission, data: { ...rest, receivedAt: (receivedAt ?? new Date()).toISOString() } }]);
+            for (const listener of [...hints])
+                listener({ eventType: "hook_received" });
+        },
+        async effect(k, effectOptions, fn) {
+            const known = state.effects.get(k);
+            if (known?.status === "completed")
+                return known.output;
+            if (known?.status === "failed")
+                throw new EffectFailure(known.error ?? { message: "failed" });
+            if (known?.status === "running" || inflight.has(k))
+                throw new Fatal(`agentrun-kernel: effect ${k} is already running in this drive`);
+            if (signal.aborted)
+                throw signal.reason;
+            const placing = effectOptions.placed ?? [];
+            // A withdraw already in the log beat this placement: refuse before writing anything, so no intent is left for
+            // recovery to report. One appended but not folded yet is caught after the intent, below.
+            if (placing.some((id) => state.withdrawn.has(id)))
+                throw new Restart(`agentrun-kernel: effect ${k} would place a withdrawn submission; the drive must be rebuilt`);
+            inflight.add(k);
+            try {
+                const attempt = known ? known.attempt + 1 : 0;
+                const stepId = `${k}#${attempt}`;
+                await append([{ kind: KERNEL_RECORDS.start, data: { key: k, stepId, name: effectOptions.name, replay: effectOptions.replay, input: effectOptions.input, placed: placing, attempt, startedAt: new Date().toISOString() } }]);
+                // A withdraw appended while this intent was being written beat the placement: what the caller would send next
+                // is not what the log placed, so it must rebuild instead of running.
+                if (placing.length && state.effects.get(k)?.placed.length !== placing.length)
+                    throw new Restart(`agentrun-kernel: effect ${k} placed a withdrawn submission; the drive must be rebuilt`);
+                const partial = [];
+                let output;
+                try {
+                    output = await fn({ signal, stepId, progress: (chunk) => { partial.push(chunk); } });
+                }
+                catch (error) {
+                    // The drive is stopping, or must be rebuilt: no outcome is written; the next drive resolves the intent.
+                    if (signal.aborted || error instanceof Restart || error instanceof Fatal)
+                        throw error;
+                    const failed = { message: String(error?.message ?? error), ...(error instanceof EffectInterrupted ? { interrupted: true } : {}), ...(partial.length ? { partial } : {}) };
+                    await append([{ kind: KERNEL_RECORDS.end, data: { stepId, status: "failed", error: failed } }]);
+                    throw new EffectFailure(failed);
+                }
+                await append([{ kind: KERNEL_RECORDS.end, data: { stepId, status: "completed", output: (output === undefined ? null : output) } }]);
+                return output;
+            }
+            finally {
+                inflight.delete(k);
+            }
+        },
+    };
+    return drive;
+}

package/dist/kernel/errors.d.ts

@@ -0,0 +1,27 @@
+import type { EffectError } from "./types.js";
+/** An effect failed; `error` is what its records say. A memoized failure is thrown again as this. */
+export declare class EffectFailure extends Error {
+    readonly error: EffectError;
+    constructor(error: EffectError);
+}
+/** An effect was stopped before it reported its outcome. */
+export declare class EffectInterrupted extends Error {
+    constructor(message: string);
+}
+/** Rebuild the drive from the session's records, in this process. */
+export declare class Restart extends Error {
+    constructor(reason: string);
+}
+/** The session's records cannot be used as they are (a missing blob): no rebuild helps. */
+export declare class Fatal extends Error {
+    constructor(message: string);
+}
+/** The harness cannot run this turn (no sandbox, a version mismatch, a cap reached); the turn ends with this text. */
+export declare class Unavailable extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    constructor(message: string, options?: {
+        code?: string;
+        hint?: string;
+    });
+}

package/dist/kernel/errors.js

@@ -0,0 +1,42 @@
+/** An effect failed; `error` is what its records say. A memoized failure is thrown again as this. */
+export class EffectFailure extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = "EffectFailure";
+    }
+}
+/** An effect was stopped before it reported its outcome. */
+export class EffectInterrupted extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EffectInterrupted";
+    }
+}
+/** Rebuild the drive from the session's records, in this process. */
+export class Restart extends Error {
+    constructor(reason) {
+        super(`restart: ${reason}`);
+        this.name = "Restart";
+    }
+}
+/** The session's records cannot be used as they are (a missing blob): no rebuild helps. */
+export class Fatal extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Fatal";
+    }
+}
+/** The harness cannot run this turn (no sandbox, a version mismatch, a cap reached); the turn ends with this text. */
+export class Unavailable extends Error {
+    code;
+    hint;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "Unavailable";
+        this.code = options.code ?? "unavailable";
+        if (options.hint !== undefined)
+            this.hint = options.hint;
+    }
+}

package/dist/kernel/follow-up.d.ts

@@ -0,0 +1,67 @@
+import type { SessionState as AdapterSessionState, SessionStore, TurnStatus } from "../types.js";
+import { foldSession } from "./drive.js";
+/** The effect's key in the follow-up's own session. */
+export declare const FOLLOW_UP_EFFECT = "follow-up";
+/** What a request the reserve refuses says, first. */
+export declare const FOLLOW_UP_BUDGET_REACHED = "follow_up_budget_reached";
+/** What a request asked for after the follow-up was cancelled says, first. */
+export declare const FOLLOW_UP_CANCELLED = "follow_up_cancelled";
+/** The follow-up's own session key, beside the session it follows up. */
+export declare const followUpKey: (session: string, name: string) => string;
+/** The session as a follow-up drives it: an adapter's session, and how a turn a crash cut off is closed unsent. */
+export interface FollowUpTarget {
+    readonly state: AdapterSessionState;
+    /** Send `text` as a new turn, its submission under `id`. */
+    send(text: string, options?: {
+        id?: string;
+    }): Promise<void>;
+    turnEnd(): Promise<{
+        status: TurnStatus;
+        error?: string;
+    }>;
+    /** Record the open turn as ended, interrupted, and send nothing. It withdraws only the submission it is named
+     *  (`opening`), while that is unplaced and the oldest pending. */
+    settleOpenTurn(options?: {
+        opening?: string;
+    }): Promise<void>;
+    /** Stop the turn in flight. */
+    interrupt(): Promise<void>;
+}
+export interface FollowUpOptions {
+    store: SessionStore;
+    /** The key of the session it follows up. */
+    session: string;
+    /** The follow-up's name: one follow-up per name per session. */
+    name: string;
+    prompt: string;
+    /** The most its paid requests may cost, in dollars, counted from its first request. */
+    reserveUsd: number;
+    /** A request's worst case, held for each request in flight and the one asked for. Required: a host with no worst case
+     *  passes 0, and the reserve may then be passed by the one request admitted last. */
+    worstUsd: number;
+}
+export type FollowUpResult = {
+    status: "done";
+} | {
+    status: "interrupted";
+} | {
+    status: "failed";
+    error: string;
+};
+export interface FollowUp {
+    readonly key: string;
+    /** Ahead of the host's own check on each paid request: undefined outside the follow-up's turn. */
+    beforeRequest(request: {
+        spentUsd: number | null;
+        inFlight: readonly unknown[];
+    }): undefined | {
+        refuse: string;
+    };
+    /** Sends the follow-up once, or answers from its record. */
+    run(target: FollowUpTarget, signal: AbortSignal): Promise<FollowUpResult>;
+}
+export type FollowUpState = "none" | "running" | "done" | "interrupted" | "failed";
+/** The follow-up's state in its records, as written: `running` is one a process that died left without an outcome. A
+ *  host reads it before it resumes an open turn: a turn of a `running` or `interrupted` follow-up is settled instead. */
+export declare function followUpState(records: Parameters<typeof foldSession>[1]): FollowUpState;
+export declare function followUpOnce(options: FollowUpOptions): FollowUp;

package/dist/kernel/follow-up.js

@@ -0,0 +1,146 @@
+import { foldSession, openDrive } from "./drive.js";
+import { EffectFailure, EffectInterrupted } from "./errors.js";
+/** The effect's key in the follow-up's own session. */
+export const FOLLOW_UP_EFFECT = "follow-up";
+/** What a request the reserve refuses says, first. */
+export const FOLLOW_UP_BUDGET_REACHED = "follow_up_budget_reached";
+/** What a request asked for after the follow-up was cancelled says, first. */
+export const FOLLOW_UP_CANCELLED = "follow_up_cancelled";
+/** The effect that records the follow-up's own cut turn settled: no later run settles another turn. */
+const SETTLED_EFFECT = "follow-up.settled";
+/** The run of each follow-up key in this process: a second run waits for it, never fences it. */
+const runs = new WeakMap();
+/** The follow-up's own session key, beside the session it follows up. */
+export const followUpKey = (session, name) => `${session}:follow-up:${name}`;
+/** The follow-up's state in its records, as written: `running` is one a process that died left without an outcome. A
+ *  host reads it before it resumes an open turn: a turn of a `running` or `interrupted` follow-up is settled instead. */
+export function followUpState(records) {
+    const effect = foldSession("", records).effects.get(FOLLOW_UP_EFFECT);
+    if (!effect)
+        return "none";
+    if (effect.status === "completed")
+        return "done";
+    if (effect.status === "failed")
+        return effect.error?.interrupted ? "interrupted" : "failed";
+    return "running";
+}
+export function followUpOnce(options) {
+    const { store, prompt, reserveUsd } = options;
+    const { worstUsd } = options;
+    if (typeof reserveUsd !== "number" || !Number.isFinite(reserveUsd) || reserveUsd <= 0)
+        throw new Error("reserveUsd must be a number of dollars above 0");
+    if (typeof worstUsd !== "number" || !Number.isFinite(worstUsd) || worstUsd < 0)
+        throw new Error("worstUsd must be given, a number of dollars, 0 or more");
+    const key = followUpKey(options.session, options.name);
+    // The id of the prompt's submission in the session: the follow-up's own, so a later run names it to the settle and a
+    // settle never withdraws input that is not the follow-up's.
+    const submission = `follow-up:${key}`;
+    let active = false;
+    let signalNow;
+    // The session's spentUsd when the follow-up's first request asks: the reserve counts from there. Whatever the session
+    // books after that counts against the reserve too: a task request whose cost was booked late (REQUEST_COST_LATE), and
+    // a harness's own background requests during the follow-up's turn (a CLI's small-model calls). Both refuse the
+    // follow-up sooner, never let it spend more.
+    let start;
+    const refuse = (why) => ({ refuse: `${FOLLOW_UP_BUDGET_REACHED}: ${why}` });
+    return {
+        key,
+        beforeRequest({ spentUsd, inFlight }) {
+            if (!active)
+                return undefined;
+            if (signalNow?.aborted)
+                return { refuse: `${FOLLOW_UP_CANCELLED}: the follow-up was cancelled; the request was not sent` };
+            if (spentUsd === null)
+                return refuse("what the session has spent is unknown, so the follow-up's reserve cannot be kept; the request was not sent");
+            start ??= spentUsd;
+            const used = spentUsd - start;
+            if (used + worstUsd * (inFlight.length + 1) > reserveUsd)
+                return refuse(`$${used.toFixed(6)} spent of a $${reserveUsd} reserve, and the next request could cost up to $${worstUsd}; the request was not sent`);
+            return undefined;
+        },
+        run(target, signal) {
+            const byKey = runs.get(store) ?? new Map();
+            runs.set(store, byKey);
+            const prior = byKey.get(key) ?? Promise.resolve();
+            // Waiting its turn, a run still hears its own signal: cancelled, it stops waiting and leaves the run before it alone.
+            const turn = new Promise((resolve, reject) => {
+                if (signal.aborted)
+                    return reject(signal.reason);
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener("abort", onAbort, { once: true });
+                void prior.then(() => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve();
+                });
+            });
+            const run = turn.then(() => runOnce(target, signal));
+            // The next run of the key waits for the one before this, whether this one ran or gave up waiting.
+            const settled = prior.then(() => run.catch(() => undefined));
+            byKey.set(key, settled);
+            void settled.then(() => byKey.get(key) === settled && byKey.delete(key));
+            return run;
+        },
+    };
+    async function runOnce(target, signal) {
+        const drive = await openDrive({ writer: await store.open(key), signal });
+        const known = drive.state().effects.get(FOLLOW_UP_EFFECT);
+        if (known?.status === "completed")
+            return { status: "done" };
+        if (known?.status === "failed") {
+            if (!known.error?.interrupted)
+                return { status: "failed", error: known.error?.message ?? "failed" };
+            // Its own turn may still be open in the session: closed unsent, never resumed, and once. An open turn after that
+            // is another's, and is left alone.
+            if (drive.state().effects.get(SETTLED_EFFECT)?.status !== "completed") {
+                if (target.state === "open_turn")
+                    await target.settleOpenTurn({ opening: submission });
+                await drive.effect(SETTLED_EFFECT, { name: SETTLED_EFFECT, replay: "safe", input: null }, async () => null);
+            }
+            return { status: "interrupted" };
+        }
+        if (target.state === "open_turn")
+            throw new Error("the session has an open turn that is not this follow-up's: recover it before the follow-up");
+        try {
+            await drive.effect(FOLLOW_UP_EFFECT, { name: options.name, replay: "never", input: { prompt } }, async () => {
+                if (signal.aborted)
+                    throw signal.reason;
+                active = true;
+                signalNow = signal;
+                // A cancel stops the turn and ends the run at once: no outcome is written, so the next process reads the
+                // follow-up interrupted, and a turn that ends after it never answers done.
+                let onAbort = () => { };
+                const aborted = new Promise((_, reject) => {
+                    onAbort = () => {
+                        void target.interrupt().catch(() => undefined);
+                        reject(signal.reason);
+                    };
+                    signal.addEventListener("abort", onAbort, { once: true });
+                });
+                aborted.catch(() => undefined);
+                try {
+                    // A send the session refuses because it holds the id already cannot strand the follow-up: the effect is
+                    // `never`, so a crash after the submission landed is recovered interrupted, and the prompt is never sent again.
+                    await Promise.race([target.send(prompt, { id: submission }), aborted]);
+                    const end = await Promise.race([target.turnEnd(), aborted]);
+                    if (signal.aborted)
+                        throw signal.reason;
+                    if (end.status === "interrupted")
+                        throw new EffectInterrupted(end.error ?? "the follow-up's turn was interrupted");
+                    if (end.status !== "completed")
+                        throw new Error(end.error ?? "the follow-up's turn failed");
+                    return null;
+                }
+                finally {
+                    active = false;
+                    signal.removeEventListener("abort", onAbort);
+                }
+            });
+            return { status: "done" };
+        }
+        catch (error) {
+            if (error instanceof EffectFailure)
+                return error.error.interrupted ? { status: "interrupted" } : { status: "failed", error: error.error.message };
+            throw error;
+        }
+    }
+}

package/dist/kernel/halt.d.ts

@@ -0,0 +1,11 @@
+import type { TurnStatus } from "../types.js";
+/** The session's own stop of its drive: told apart from every other halt by identity, never by its text. */
+export declare class SessionHalt extends Error {
+    readonly kind: "interrupted" | "closed";
+    constructor(kind: "interrupted" | "closed");
+}
+/** The outcome of a turn whose drive `signal` was aborted, the session's host being `host`. */
+export declare function abortedOutcome(signal: AbortSignal, host?: AbortSignal): {
+    status: TurnStatus;
+    error?: string;
+};

package/dist/kernel/halt.js

@@ -0,0 +1,17 @@
+/** The session's own stop of its drive: told apart from every other halt by identity, never by its text. */
+export class SessionHalt extends Error {
+    kind;
+    constructor(kind) {
+        super(kind);
+        this.kind = kind;
+        this.name = "SessionHalt";
+    }
+}
+/** The outcome of a turn whose drive `signal` was aborted, the session's host being `host`. */
+export function abortedOutcome(signal, host) {
+    const reason = signal.reason;
+    if (reason instanceof SessionHalt || host?.aborted)
+        return { status: "interrupted" };
+    const message = reason instanceof Error ? reason.message : reason === undefined ? "the turn was halted, with no reason given" : String(reason);
+    return { status: "failed", error: message.slice(0, 500) };
+}

package/dist/kernel/index.d.ts

@@ -0,0 +1,8 @@
+export type { DriveContext, EffectError, EffectIO, EffectOptions, EffectRecord, EffectStatus, HostTool, HostToolIO, ToolOutput, KernelWorld, ReplayPolicy, SessionState, Submission, SubmissionKind } from "./types.js";
+export { EffectFailure, EffectInterrupted, Fatal, Restart, Unavailable } from "./errors.js";
+export { abortedOutcome, SessionHalt } from "./halt.js";
+export { BLOB_PIECE_CHARS, BLOB_RECORD, blobStreamName, readBlobs, sha256Hex, writeBlob } from "./blobs.js";
+export { foldSession, hostToolIO, INTERRUPTED_TEXT, KERNEL_RECORDS, openDrive, pendingSubmissions } from "./drive.js";
+export type { Drive, OpenDriveOptions } from "./drive.js";
+export { FOLLOW_UP_BUDGET_REACHED, FOLLOW_UP_CANCELLED, FOLLOW_UP_EFFECT, followUpKey, followUpOnce, followUpState } from "./follow-up.js";
+export type { FollowUp, FollowUpOptions, FollowUpResult, FollowUpState, FollowUpTarget } from "./follow-up.js";

package/dist/kernel/index.js

@@ -0,0 +1,5 @@
+export { EffectFailure, EffectInterrupted, Fatal, Restart, Unavailable } from "./errors.js";
+export { abortedOutcome, SessionHalt } from "./halt.js";
+export { BLOB_PIECE_CHARS, BLOB_RECORD, blobStreamName, readBlobs, sha256Hex, writeBlob } from "./blobs.js";
+export { foldSession, hostToolIO, INTERRUPTED_TEXT, KERNEL_RECORDS, openDrive, pendingSubmissions } from "./drive.js";
+export { FOLLOW_UP_BUDGET_REACHED, FOLLOW_UP_CANCELLED, FOLLOW_UP_EFFECT, followUpKey, followUpOnce, followUpState } from "./follow-up.js";