@celestea/runtime 2.7.1

package/dist/compose.js

@@ -0,0 +1,191 @@
+/**
+ * compose — the composition root of `packages/runtime`
+ * (`crates/runtime/src/compose.rs:74-234`).
+ *
+ * Assembly order is SEMANTICS, not taste (ARCHITECTURE.md §3.2), so it is
+ * explicit and tested:
+ *
+ *   1. runtime services      event bus, usage accounting, status tracker;
+ *   2. session binding       `sessionBinding` (if given) opens the host log;
+ *   3. host plugins          `config.plugins` in order — a later `provide` of a
+ *                            token REPLACES an earlier one (patch semantics, so
+ *                            a test can mount a fake over a real implementation);
+ *   4. worker wiring         mount the default workers plugin only when the host
+ *                            did not provide a registry (worker tools must land
+ *                            in the tool registry, hence last);
+ *   4b. watchdog             W740: mount the liveness watchdog over the resolved
+ *                            worker registry and keep its stop handle, so the
+ *                            sweep timer dies with `shutdown`/`release`;
+ *   5. seam resolution       session (required) + llm / tools / agentLoop
+ *                            (optional, and `null` when no plugin provides them);
+ *   6. driver attach         hand Llm/ToolRegistry/AgentLoop to the worker
+ *                            registry so `spawn_worker` is driven, not merely
+ *                            registered, and register the host conversation so
+ *                            receipts have an address;
+ *   7. turn runner           bind the per-turn loop factory, sink mapper, usage
+ *                            accounting and receipt drain into one driver.
+ *
+ * Everything the runtime needs beyond `core` is injected: the concrete agent
+ * loop arrives as a `loopFactory`, the frame mapper as `frameMapper`, the worker
+ * log factory as `workers.logFactory`. That is what keeps this layer free of
+ * L1 implementation imports (and lets P3 tests drive it with fakes).
+ */
+import { AGENT_LOOP_SERVICE, LLM_REGISTRY_SERVICE, LLM_SERVICE, SESSION_LOG_SERVICE, TOOL_REGISTRY_SERVICE, Context, createEventBus, EVENT_BUS_SERVICE, mountPlugins, pluginNames, } from "@celestea/core";
+import { RETENTION_SERVICE } from "@celestea/agent-loop";
+import { agentConfigFromProfile } from "./agent-config.js";
+import { createToolResultRetention, retentionSettingsFromEnv } from "./retention.js";
+import { ComposeError } from "./errors.js";
+import { loopEventToFrame } from "./frames.js";
+import { Runtime } from "./runtime.js";
+import { bindSession } from "./session-binding.js";
+import { createStatusTracker } from "./status.js";
+import { STATUS_TRACKER_SERVICE, USAGE_TRACKER_SERVICE } from "./tokens.js";
+import { TurnRunner } from "./turn-runner.js";
+import { createUsageTracker } from "./usage.js";
+import { createSessionInbox } from "./inbox.js";
+import { checkpointInboxSink } from "./inbox-checkpoint.js";
+import { ensureWorkerWiring } from "./worker-wiring.js";
+import { checkpointStoreOf } from "@celestea/session";
+import { WATCHDOG_PLUGIN_NAME, celesteaWatchdogSettings, mountWatchdog, stopWatchdog, } from "./watchdog-mount.js";
+/** Compose one engine generation. Throws [ComposeError] on a missing seam. */
+export function compose(config) {
+    const ctx = Context.root();
+    const usage = config.usage ?? createUsageTracker();
+    const status = config.status ?? createStatusTracker(config.now ?? Date.now);
+    ctx.provide(EVENT_BUS_SERVICE, createEventBus());
+    ctx.provide(USAGE_TRACKER_SERVICE, usage);
+    ctx.provide(STATUS_TRACKER_SERVICE, status);
+    const binding = config.sessionBinding ?? null;
+    const bound = binding === null ? null : bindSession(ctx, binding);
+    const plugins = config.plugins ?? [];
+    mountPlugins(ctx, plugins);
+    const workerHost = ensureWorkerWiring(ctx, config.workers);
+    const mounted = mountWatchdogOf(ctx, config, workerHost);
+    const session = requireSession(ctx);
+    const sessionRef = { log: session };
+    // W855: session-scoped tool-result retention (the loop reads this per turn).
+    if (config.retention !== null) {
+        ctx.provide(RETENTION_SERVICE, config.retention ?? createToolResultRetention(retentionSettingsFromEnv(binding?.dir ?? null, config.env ?? process.env)));
+    }
+    const llm = ctx.get(LLM_REGISTRY_SERVICE) ?? null;
+    const tools = ctx.get(TOOL_REGISTRY_SERVICE) ?? null;
+    const agentLoop = ctx.get(AGENT_LOOP_SERVICE) ?? null;
+    attachDrivers(workerHost, { llm: resolveDriverLlm(ctx, llm), tools, agentLoop });
+    const agentConfig = agentConfigFromProfile(config.profile, config.agentConfig ?? {});
+    const inbox = config.inbox ?? createSessionInbox();
+    // E §1.3 P1 ①: the lanes + the accepted-id ledger live in this session's
+    // checkpoint sidecar when the log is a checkpointed persistent one; an
+    // in-memory (detached) session has no sidecar and therefore no persistence.
+    const store = bound === null ? null : checkpointStoreOf(bound);
+    if (store !== null)
+        inbox.bindPersistence(checkpointInboxSink(store));
+    const receipts = () => workerHost?.drain() ?? [];
+    const drained = (messages, boundary) => {
+        if (messages.length === 0)
+            return messages;
+        // A mailbox message never entered a lane: the BOUNDARY that consumed it is
+        // what tells the client where it landed (W515 §1/§2).
+        const lane = boundary === "step" ? "next-step" : "next-turn";
+        const annotated = messages.map((message) => (message.lane === undefined ? { ...message, lane } : message));
+        // P1-6 (W836): the lane was ALREADY drained (the message left the queue and
+        // the sidecar). A throwing observer must never take the message with it: the
+        // callback is a notification, so its failure is a warning, not a loss.
+        try {
+            config.onInjected?.(annotated, boundary);
+        }
+        catch (e) {
+            process.stderr.write(`[celestea-runtime] onInjected callback failed: ${String(e)}\n`);
+        }
+        return annotated;
+    };
+    const runner = new TurnRunner({
+        ctx,
+        session: () => sessionRef.log,
+        status,
+        usage,
+        agentConfig,
+        frameMapper: config.frameMapper ?? loopEventToFrame,
+        ...(config.ledger === undefined ? {} : { ledger: config.ledger }),
+        ...(config.loopFactory === undefined ? {} : { loopFactory: config.loopFactory }),
+        ...(config.turnContext === undefined ? {} : { turnContext: config.turnContext }),
+        drainPending: () => drained([...inbox.drain("next-turn"), ...receipts()], "turn-start"),
+        injections: {
+            drain: () => drained([...inbox.drain("next-step"), ...receipts()], "step"),
+            pending: () => inbox.pending("next-step") + (workerHost?.pending() ?? 0),
+        },
+    });
+    const parts = {
+        ctx,
+        profile: config.profile,
+        agentConfig,
+        sessionRef,
+        binding,
+        status,
+        usage,
+        inbox,
+        runner,
+        workerHost: watchdogHostOf(workerHost, mounted),
+        llm,
+        tools,
+        agentLoop,
+        plugins: pluginNamesOf(plugins, workerHost, mounted),
+        shutdownHooks: [...(config.shutdownHooks ?? []), stopWatchdog(mounted)],
+    };
+    return new Runtime(parts);
+}
+/**
+ * The plugin set that was mounted, in mount order (order is contract): the host
+ * plugins, then the workers plugin (when this root mounted it), then the W740
+ * watchdog — which is always LAST, because it may only adjudicate rows a fully
+ * mounted worker registry already owns.
+ */
+export function pluginNamesOf(plugins, workerHost, mounted = null) {
+    const names = pluginNames(plugins);
+    if (workerHost !== null && workerHost.mountedPlugin !== null)
+        names.push(workerHost.mountedPlugin);
+    if (workerHost !== null && mounted !== null)
+        names.push(WATCHDOG_PLUGIN_NAME);
+    return names;
+}
+/**
+ * W740: mount the watchdog over the RESOLVED registry — the host-provided one or
+ * the default this root mounted. It runs even when a host plugin provided the
+ * registry: liveness judgement is exactly what is missing there. With no worker
+ * wiring (`workers: false`) there is no registry to sweep and nothing mounts.
+ */
+function mountWatchdogOf(ctx, config, workerHost) {
+    if (workerHost === null || config.watchdog === false)
+        return null;
+    const fromEnv = celesteaWatchdogSettings(config.env ?? process.env);
+    return mountWatchdog(ctx, workerHost.registry, { ...fromEnv, ...config.watchdog });
+}
+/** Attach the watchdog handle to the host view (services stay in the Context). */
+function watchdogHostOf(workerHost, mounted) {
+    return workerHost === null ? null : { ...workerHost, watchdog: mounted?.watchdog ?? null };
+}
+function requireSession(ctx) {
+    const session = ctx.get(SESSION_LOG_SERVICE);
+    if (session === undefined) {
+        throw new ComposeError("no SessionLog: pass a sessionBinding or mount a session log plugin");
+    }
+    return session;
+}
+/**
+ * The single adapter the worker driver uses: the composed `LlmService`, else the
+ * registry's first registered provider (compose registers exactly one).
+ */
+function resolveDriverLlm(ctx, registry) {
+    const direct = ctx.get(LLM_SERVICE);
+    if (direct !== undefined)
+        return direct;
+    const first = registry?.list()[0];
+    return first === undefined ? undefined : registry?.resolve(first);
+}
+/** Attach every driver seam (all three, or none — a partial set cannot drive). */
+function attachDrivers(host, seams) {
+    if (host === null)
+        return;
+    const { llm, tools, agentLoop } = seams;
+    const drivers = llm === undefined || tools === null || agentLoop === null ? null : { llm, tools, agentLoop };
+    host.attach(drivers);
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Runtime-owned errors. Machine-readable first: callers branch on `status`
+ * (HTTP-shaped, via core's `StudioError`) or on `kind`, never on prose
+ * (ARCHITECTURE.md §6.2).
+ */
+import { StudioError } from "@celestea/core";
+/**
+ * A second `runTurn` while one is in flight. The engine has a single
+ * concurrency slot per Runtime generation (`AppState::busy`): a turn is
+ * either running or not, and a conflicting start is a 409, never a queue.
+ */
+export declare class TurnBusyError extends StudioError {
+    readonly kind = "turn_busy";
+    constructor(what?: string);
+}
+/** The generation was shut down / released: its handles must not be used again. */
+export declare class RuntimeReleasedError extends StudioError {
+    readonly kind = "runtime_released";
+    constructor(what?: string);
+}
+/** Composition failed: a required seam was never provided by any plugin. */
+export declare class ComposeError extends Error {
+    readonly kind = "compose";
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Runtime-owned errors. Machine-readable first: callers branch on `status`
+ * (HTTP-shaped, via core's `StudioError`) or on `kind`, never on prose
+ * (ARCHITECTURE.md §6.2).
+ */
+import { StudioError } from "@celestea/core";
+/**
+ * A second `runTurn` while one is in flight. The engine has a single
+ * concurrency slot per Runtime generation (`AppState::busy`): a turn is
+ * either running or not, and a conflicting start is a 409, never a queue.
+ */
+export class TurnBusyError extends StudioError {
+    kind = "turn_busy";
+    constructor(what = "cancel/rebind/config") {
+        super(409, `turn in progress; ${what} applies between turns`);
+        this.name = "TurnBusyError";
+    }
+}
+/** The generation was shut down / released: its handles must not be used again. */
+export class RuntimeReleasedError extends StudioError {
+    kind = "runtime_released";
+    constructor(what = "the runtime generation was shut down or released") {
+        super(410, `runtime released: ${what}`);
+        this.name = "RuntimeReleasedError";
+    }
+}
+/** Composition failed: a required seam was never provided by any plugin. */
+export class ComposeError extends Error {
+    kind = "compose";
+    constructor(message) {
+        super(message);
+        this.name = "ComposeError";
+    }
+}

package/dist/frames.d.ts

@@ -0,0 +1,46 @@
+/**
+ * LoopEvent -> SSE frame mapping and the per-turn sink shape.
+ *
+ * The runtime owns the host-facing event stream: a turn drives the
+ * `AgentLoop` seam and every `LoopEvent` (core) it produces becomes exactly one
+ * `TurnFrame` — the frozen `contracts/sse-events.json` name plus its payload
+ * (`celestea_studio/src/main.rs:667-713`, `loop_event_to_json`).
+ *
+ * The mapping is injectable (`FrameMapper`): the default below is contract-faithful
+ * and complete, and a host that already ships its own mapper (for example
+ * `@celestea/agent-loop`'s `loopEventToSse`) passes it in the compose config
+ * instead. Either way the runtime never imports an L1 implementation.
+ */
+import { type LoopEvent, type SseEventName } from "@celestea/core";
+/** One SSE frame: the frozen event name plus its `data:` payload. */
+export interface TurnFrame {
+    event: SseEventName;
+    payload: Record<string, unknown>;
+}
+/** Maps a core `LoopEvent` onto the host-facing frame. */
+export type FrameMapper = (event: LoopEvent) => TurnFrame;
+/** Sink handed to the agent loop; structurally identical to `EventSink`. */
+export type LoopEventSink = (event: LoopEvent) => void;
+/** `loop_event_to_json` — the default, contract-faithful mapping. */
+export declare function loopEventToFrame(ev: LoopEvent): TurnFrame;
+/**
+ * W783: one parked user question.
+ *
+ * This frame is NOT produced by the agent loop — a question parks the tool call,
+ * so no `LoopEvent` exists to map. It is host-emitted, which is why it is built
+ * here rather than in `loopEventToFrame`: the module that owns every frozen SSE
+ * payload owns this one too, so the two can never drift apart.
+ *
+ * `expires_at` is an absolute deadline and `timeout_ms` the resolved wait (§6.1),
+ * so a client can draw the countdown from the frame alone and judge expiry with
+ * the server's clock rather than its own.
+ */
+export declare function questionFrame(input: QuestionFrameInput): TurnFrame;
+/** What [questionFrame] needs: the request as the pending table holds it. */
+export interface QuestionFrameInput {
+    session: string | null;
+    id: string;
+    questions: readonly unknown[];
+    expiresAt: number;
+    timeoutMs: number;
+}

package/dist/frames.js

@@ -0,0 +1,62 @@
+/**
+ * LoopEvent -> SSE frame mapping and the per-turn sink shape.
+ *
+ * The runtime owns the host-facing event stream: a turn drives the
+ * `AgentLoop` seam and every `LoopEvent` (core) it produces becomes exactly one
+ * `TurnFrame` — the frozen `contracts/sse-events.json` name plus its payload
+ * (`celestea_studio/src/main.rs:667-713`, `loop_event_to_json`).
+ *
+ * The mapping is injectable (`FrameMapper`): the default below is contract-faithful
+ * and complete, and a host that already ships its own mapper (for example
+ * `@celestea/agent-loop`'s `loopEventToSse`) passes it in the compose config
+ * instead. Either way the runtime never imports an L1 implementation.
+ */
+import { outcomeError, outcomePhase } from "@celestea/core";
+/** `loop_event_to_json` — the default, contract-faithful mapping. */
+export function loopEventToFrame(ev) {
+    switch (ev.kind) {
+        case "text":
+            return frame("text", { delta: ev.delta });
+        case "thinking":
+            return frame("thinking", { delta: ev.delta });
+        case "tool_call":
+            return frame("tool", { id: ev.id, name: ev.name, args: ev.args });
+        case "tool_result":
+            return frame("tool_result", {
+                id: ev.callId,
+                ok: ev.ok,
+                value: ev.value,
+                render: ev.render,
+                error: ev.error,
+                decision: ev.decision,
+            });
+        case "turn_end":
+            return frame("turn_end", { outcome: outcomePhase(ev.outcome), error: outcomeError(ev.outcome) });
+        case "done":
+            return frame("done", { text: ev.text, tool_calls: ev.tool_calls });
+    }
+}
+function frame(event, payload) {
+    return { event, payload };
+}
+/**
+ * W783: one parked user question.
+ *
+ * This frame is NOT produced by the agent loop — a question parks the tool call,
+ * so no `LoopEvent` exists to map. It is host-emitted, which is why it is built
+ * here rather than in `loopEventToFrame`: the module that owns every frozen SSE
+ * payload owns this one too, so the two can never drift apart.
+ *
+ * `expires_at` is an absolute deadline and `timeout_ms` the resolved wait (§6.1),
+ * so a client can draw the countdown from the frame alone and judge expiry with
+ * the server's clock rather than its own.
+ */
+export function questionFrame(input) {
+    return frame("question", {
+        session: input.session,
+        id: input.id,
+        questions: [...input.questions],
+        expires_at: input.expiresAt,
+        timeout_ms: input.timeoutMs,
+    });
+}

package/dist/gen.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Generation (Gen) — the hot-swappable unit behind `/api/config`.
+ *
+ * A generation is `{ runtime, profile, sanitized config, epoch }`, and every
+ * field derives from the SAME profile, so a reader can never observe a mixed
+ * state (model from one compose, session from another). The swap protocol is a
+ * single synchronous pointer flip followed by old-generation teardown:
+ *
+ *   1. flip      `this.gen = next` — atomic in the reader's eyes: a reader holds
+ *                either the previous object or the next one, never a blend;
+ *   2. migrate   pending host receipts are moved from the old generation's
+ *                mailbox onto the new one, so a receipt that arrived during the
+ *                swap is not lost with the generation it was addressed to (W240);
+ *   3. teardown  the previous generation is shut down and released AFTER the
+ *                flip — its drivers stop, its mailbox is purged, its registry
+ *                cleared, its handles dropped (W248).
+ *
+ * `buildAndSwap` composes the next generation through an injected factory, so
+ * this module never imports `compose` (no cycle) and a test can swap in a fake.
+ */
+import type { Profile } from "./profile.js";
+import type { Runtime } from "./runtime.js";
+import { type SanitizedConfig } from "./sanitize.js";
+/** One generation: the runtime, the profile it was built from, its safe config. */
+export interface Gen {
+    readonly runtime: Runtime;
+    readonly profile: Profile;
+    readonly config: SanitizedConfig;
+    readonly epoch: number;
+}
+export interface GenSwapResult {
+    epoch: number;
+    prevEpoch: number | null;
+    /** Host receipts migrated from the previous generation's mailbox. */
+    migrated: number;
+}
+export interface GenerationHubOptions {
+    /** Queue key the host receipts are addressed to (default `cli-main`). */
+    hostSessionId?: string;
+    /** Builds the next generation; `compose(profile)` at the composition root. */
+    build?: (profile: Profile) => Runtime | Promise<Runtime>;
+    /** Observers notified after a swap, in registration order. */
+    onSwap?: (next: Gen, prev: Gen | null) => void;
+}
+/** A generation from a runtime + the profile it was composed from. */
+export declare function createGen(runtime: Runtime, profile: Profile, epoch?: number): Gen;
+export declare class GenerationHub {
+    private gen;
+    private epochCounter;
+    private swaps;
+    private readonly listeners;
+    private readonly opts;
+    constructor(opts?: GenerationHubOptions);
+    /** The current generation (throws before the first install). */
+    current(): Gen;
+    /** The current generation, or null when none is installed yet. */
+    peek(): Gen | null;
+    /** Current epoch (0 before the first install). */
+    get epoch(): number;
+    /** How many swaps happened (diagnostics / tests). */
+    get swapCount(): number;
+    /** Install the first generation (also a swap when one already exists). */
+    install(runtime: Runtime, profile: Profile): Gen;
+    /** Flip + migrate, synchronously; the previous generation is NOT torn down. */
+    swapSync(runtime: Runtime, profile: Profile): {
+        gen: Gen;
+        result: GenSwapResult;
+    };
+    /** Flip, migrate, then shut down and release the previous generation. */
+    swap(runtime: Runtime, profile: Profile): Promise<GenSwapResult>;
+    /** Compose the next generation through `build`, then swap it in. */
+    buildAndSwap(profile: Profile): Promise<GenSwapResult>;
+    /** Subscribe to swaps; the returned function unsubscribes. */
+    onSwap(listener: (next: Gen, prev: Gen | null) => void): () => void;
+    /** Shut down and release the current generation (idempotent). */
+    shutdown(): Promise<void>;
+    private hostSessionId;
+}
+/**
+ * Move pending host receipts from one generation's mailbox onto the next.
+ *
+ * `== null` on purpose (W769): a generation composed without worker wiring has no
+ * `workers` at all, and the W769 caller runs inside a session rebuild where a
+ * missing wiring must be a no-op, never a crash.
+ */
+export declare function migrateReceipts(from: Runtime, to: Runtime, hostSessionId: string): number;

package/dist/gen.js

@@ -0,0 +1,129 @@
+/**
+ * Generation (Gen) — the hot-swappable unit behind `/api/config`.
+ *
+ * A generation is `{ runtime, profile, sanitized config, epoch }`, and every
+ * field derives from the SAME profile, so a reader can never observe a mixed
+ * state (model from one compose, session from another). The swap protocol is a
+ * single synchronous pointer flip followed by old-generation teardown:
+ *
+ *   1. flip      `this.gen = next` — atomic in the reader's eyes: a reader holds
+ *                either the previous object or the next one, never a blend;
+ *   2. migrate   pending host receipts are moved from the old generation's
+ *                mailbox onto the new one, so a receipt that arrived during the
+ *                swap is not lost with the generation it was addressed to (W240);
+ *   3. teardown  the previous generation is shut down and released AFTER the
+ *                flip — its drivers stop, its mailbox is purged, its registry
+ *                cleared, its handles dropped (W248).
+ *
+ * `buildAndSwap` composes the next generation through an injected factory, so
+ * this module never imports `compose` (no cycle) and a test can swap in a fake.
+ */
+import { ComposeError } from "./errors.js";
+import { sanitizeProfile } from "./sanitize.js";
+import { HOST_SESSION_ID } from "./tokens.js";
+/** A generation from a runtime + the profile it was composed from. */
+export function createGen(runtime, profile, epoch = 0) {
+    return { runtime, profile, config: sanitizeProfile(profile), epoch };
+}
+export class GenerationHub {
+    gen = null;
+    epochCounter = 0;
+    swaps = 0;
+    listeners = [];
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+        if (opts.onSwap !== undefined)
+            this.listeners.push(opts.onSwap);
+    }
+    /** The current generation (throws before the first install). */
+    current() {
+        const gen = this.gen;
+        if (gen === null)
+            throw new ComposeError("no generation installed");
+        return gen;
+    }
+    /** The current generation, or null when none is installed yet. */
+    peek() {
+        return this.gen;
+    }
+    /** Current epoch (0 before the first install). */
+    get epoch() {
+        return this.gen?.epoch ?? 0;
+    }
+    /** How many swaps happened (diagnostics / tests). */
+    get swapCount() {
+        return this.swaps;
+    }
+    /** Install the first generation (also a swap when one already exists). */
+    install(runtime, profile) {
+        return this.swapSync(runtime, profile).gen;
+    }
+    /** Flip + migrate, synchronously; the previous generation is NOT torn down. */
+    swapSync(runtime, profile) {
+        const prev = this.gen;
+        const next = createGen(runtime, profile, ++this.epochCounter);
+        this.gen = next;
+        const migrated = prev === null ? 0 : migrateReceipts(prev.runtime, runtime, this.hostSessionId());
+        this.swaps += 1;
+        for (const listener of this.listeners)
+            listener(next, prev);
+        return { gen: next, result: { epoch: next.epoch, prevEpoch: prev?.epoch ?? null, migrated } };
+    }
+    /** Flip, migrate, then shut down and release the previous generation. */
+    async swap(runtime, profile) {
+        const prev = this.gen;
+        const { result } = this.swapSync(runtime, profile);
+        if (prev !== null)
+            await teardown(prev.runtime);
+        return result;
+    }
+    /** Compose the next generation through `build`, then swap it in. */
+    async buildAndSwap(profile) {
+        const build = this.opts.build;
+        if (build === undefined)
+            throw new ComposeError("GenerationHub has no build factory");
+        const runtime = await build(profile);
+        return this.swap(runtime, profile);
+    }
+    /** Subscribe to swaps; the returned function unsubscribes. */
+    onSwap(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const i = this.listeners.indexOf(listener);
+            if (i >= 0)
+                this.listeners.splice(i, 1);
+        };
+    }
+    /** Shut down and release the current generation (idempotent). */
+    async shutdown() {
+        const gen = this.gen;
+        this.gen = null;
+        if (gen !== null)
+            await teardown(gen.runtime);
+    }
+    hostSessionId() {
+        return this.opts.hostSessionId ?? HOST_SESSION_ID;
+    }
+}
+/**
+ * Move pending host receipts from one generation's mailbox onto the next.
+ *
+ * `== null` on purpose (W769): a generation composed without worker wiring has no
+ * `workers` at all, and the W769 caller runs inside a session rebuild where a
+ * missing wiring must be a no-op, never a crash.
+ */
+export function migrateReceipts(from, to, hostSessionId) {
+    const source = from.workers;
+    const target = to.workers;
+    if (source == null || target == null)
+        return 0;
+    const pending = source.mailbox.poll(hostSessionId);
+    for (const msg of pending)
+        target.mailbox.send(hostSessionId, msg.content, msg.from_label);
+    return pending.length;
+}
+async function teardown(runtime) {
+    await runtime.shutdown();
+    runtime.release();
+}