@cubicecho/agent-core 2.22.0 → 2.24.0

package/dist/client.js

@@ -1,20 +1,21 @@
 import { createHash } from "node:crypto";
 import OpenAI from "openai";
+import { isPositive } from "./guards.js";
+import { scoped } from "./scope.js";
 /**
  * The SDK insists on a non-empty key even where the server will not look at it. This is what it
  * gets. It also reads as "this endpoint has no key" at a call site, which an empty string does
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export const NO_KEY = "agent-core";
+/** A wait in the SDK's spelling: milliseconds, and `undefined` where zero or less means no limit. */
+const limitMs = (seconds) => (seconds > 0 ? seconds * 1000 : undefined);
 /**
  * Zero, less, or absent means no limit, which the SDK spells as `undefined`.
  *
  * @param config Read for `requestTimeoutSeconds` alone.
  */
-export const timeoutMs = (config) => {
-    const seconds = config.requestTimeoutSeconds ?? 0;
-    return seconds > 0 ? seconds * 1000 : undefined;
-};
+export const timeoutMs = (config) => limitMs(config.requestTimeoutSeconds ?? 0);
 /**
  * A client per endpoint, made once and kept.
  *
@@ -31,7 +32,7 @@ export const timeoutMs = (config) => {
  * Bounded, because a cache is only a cache while its keys are. Insertion order is the whole of
  * the eviction: a `Map` iterates oldest-first, and `getClient` re-inserts on a hit.
  */
-const clients = new Map();
+const clients = scoped(() => new Map());
 /**
  * How many endpoints' clients are kept at once, until `configureClients` moves it.
  *
@@ -55,7 +56,7 @@ const CLIENT_DEFAULTS = {
     listingMissMs: LISTING_MISS_MS,
 };
 /** What is in force now. Read where it is used, so a change applies from the next call. */
-let poolLimits = { ...CLIENT_DEFAULTS };
+const poolLimits = scoped(() => ({ ...CLIENT_DEFAULTS }));
 /**
  * Drops the least recently asked-for clients until the pool fits. Nothing is closed on the way
  * out: the SDK holds no handle a caller can release, and an evicted client is garbage once
@@ -63,20 +64,21 @@ let poolLimits = { ...CLIENT_DEFAULTS };
  * of the eviction.
  */
 const evict = () => {
-    for (const oldest of clients.keys()) {
-        if (clients.size <= poolLimits.maxClients)
+    for (const oldest of clients().keys()) {
+        if (clients().size <= poolLimits().maxClients)
             break;
-        clients.delete(oldest);
+        clients().delete(oldest);
     }
 };
 /**
  * Changes what the client pool is held to, for a process whose endpoints are not shaped like the
  * deployments these defaults were chosen for.
  *
- * Module-level for the same reason `configureEvents` is: the pool is one module-level thing, and
- * its size is a deployment's setting, said once at startup. A multi-tenant host keying on a key
- * per user raises `maxClients` so its tenants stop evicting each other's connection pools; a dev
- * box shortens `listingMissMs` so a model it has just pulled is seen sooner.
+ * One setting per runtime for the same reason `configureEvents` is: the pool is one thing per
+ * runtime, and its size is a deployment's setting, said once at startup. A multi-tenant host
+ * keying on a key per user raises `maxClients` so its tenants stop evicting each other's
+ * connection pools, or gives each tenant a `createRuntime` of its own; a dev box shortens
+ * `listingMissMs` so a model it has just pulled is seen sooner.
  *
  * A `maxClients` below the pool's current size evicts down to it at once, least recently asked
  * for first, as the next `getClient` would have. A shorter `listingMissMs` applies to misses
@@ -90,12 +92,11 @@ const evict = () => {
  */
 export function configureClients(options = {}) {
     for (const [name, value] of Object.entries(options)) {
-        if (typeof value === "number" && value > 0) {
-            poolLimits[name] = value;
-        }
+        if (isPositive(value))
+            poolLimits()[name] = value;
     }
     evict();
-    return { ...poolLimits };
+    return { ...poolLimits() };
 }
 /** How many idle windows the first chunk gets when `firstTokenSeconds` is not given. */
 export const FIRST_TOKEN_FACTOR = 5;
@@ -109,7 +110,7 @@ export const firstTokenMs = (config) => {
         const idle = timeoutMs(config);
         return idle === undefined ? undefined : idle * FIRST_TOKEN_FACTOR;
     }
-    return config.firstTokenSeconds > 0 ? config.firstTokenSeconds * 1000 : undefined;
+    return limitMs(config.firstTokenSeconds);
 };
 /**
  * The client for an endpoint, built once and kept.
@@ -132,16 +133,16 @@ export function getClient(config) {
     // Stringified rather than joined on a separator: no character is impossible in a URL or a
     // key, and two different endpoints must never resolve to the same cached client.
     const key = JSON.stringify([config.baseUrl, apiKey, timeout]);
-    const existing = clients.get(key);
+    const existing = clients().get(key);
     if (existing) {
         // Re-inserted so it counts as the youngest. A `Map` keeps insertion order and hands the
         // oldest key over first, which is the whole of the LRU below.
-        clients.delete(key);
-        clients.set(key, existing);
+        clients().delete(key);
+        clients().set(key, existing);
         return existing;
     }
     const client = new OpenAI({ baseURL: config.baseUrl, apiKey, timeout, maxRetries: 0 });
-    clients.set(key, client);
+    clients().set(key, client);
     evict();
     return client;
 }
@@ -161,7 +162,7 @@ const CONTEXT_KEYS = [
     "context_window",
     "n_ctx",
 ];
-const positive = (value) => (typeof value === "number" && value > 0 ? value : 0);
+const positive = (value) => (isPositive(value) ? value : 0);
 /**
  * A listing entry's window, and whether it is only the one the model was trained with.
  *
@@ -197,14 +198,14 @@ function contextLengthOf(model) {
  * It is only ever a cache of something asked for anyway, and a listing that fails leaves
  * whatever was there rather than emptying it.
  */
-const listings = new Map();
+const listings = scoped(() => new Map());
 /**
  * The models in each endpoint's last listing whose window is only the trained one, by id.
  *
  * Kept beside `listings` rather than on `ModelInfo`, so what `listModels` hands back is the shape
  * it has always been. Replaced with each listing that lands, and left alone by one that fails.
  */
-const trainedOnly = new Map();
+const trainedOnly = scoped(() => new Map());
 /**
  * When an endpoint was last asked about a model it did not name, keyed on the two together.
  *
@@ -219,7 +220,7 @@ const trainedOnly = new Map();
  * picked up within the minute instead of at the next restart. Bounded by the (endpoint, model)
  * pairs actually asked about, which is the bound the listings themselves have.
  */
-const misses = new Map();
+const misses = scoped(() => new Map());
 /**
  * What counts as one endpoint, everywhere in this package that has to remember something about
  * one — the model listings, `capabilities`, and the no-thinking hints in `side-task`.
@@ -240,6 +241,8 @@ const misses = new Map();
  * it; see `listings`.
  */
 export const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+/** One model on one endpoint, as the caches below key it: stringified, so neither half runs into the other. */
+const modelKey = (endpoint, model) => JSON.stringify([endpoint, model]);
 /**
  * `endpointKey` hashed, for the remembered facts that can leave the process.
  *
@@ -257,9 +260,9 @@ export const endpointId = (config) => createHash("sha256").update(endpointKey(co
  * A model's entry stays until `resetClients`, like a listing; a server that answered without one
  * is asked again after `listingMissMs`, like a listing that did not name the model.
  */
-const served = new Map();
+const served = scoped(() => new Map());
 /** Endpoints with neither native route, which are not asked for either again. */
-const unserved = new Set();
+const unserved = scoped(() => new Set());
 /**
  * Endpoints whose `/api/v0/models` answered with an error, and when.
  *
@@ -271,11 +274,11 @@ const unserved = new Set();
  * Per endpoint and on its own, whatever `/props` said: a server whose `/props` answers without a
  * window is never `unserved`, and without this its missing route was asked again with every miss.
  */
-const refusals = new Map();
+const refusals = scoped(() => new Map());
 /** Whether `/api/v0/models` is to be left alone on this endpoint for now. */
 const refused = (endpoint) => {
-    const refusal = refusals.get(endpoint);
-    return (refusal !== undefined && (refusal.gone || Date.now() - refusal.at < poolLimits.listingMissMs));
+    const refusal = refusals().get(endpoint);
+    return (refusal !== undefined && (refusal.gone || Date.now() - refusal.at < poolLimits().listingMissMs));
 };
 /** How long a probe may take before the window is taken from the listing instead. */
 const PROBE_TIMEOUT_MS = 10_000;
@@ -324,11 +327,11 @@ async function probe(config, path) {
  */
 export async function servedWindow(config) {
     const endpoint = endpointKey(config);
-    if (unserved.has(endpoint))
+    if (unserved().has(endpoint))
         return 0;
-    const key = JSON.stringify([endpoint, config.model]);
-    const known = served.get(key);
-    if (known && (known.window > 0 || Date.now() - known.at < poolLimits.listingMissMs))
+    const key = modelKey(endpoint, config.model);
+    const known = served().get(key);
+    if (known && (known.window > 0 || Date.now() - known.at < poolLimits().listingMissMs))
         return known.window;
     let window = 0;
     try {
@@ -341,17 +344,17 @@ export async function servedWindow(config) {
             if (!refused(endpoint)) {
                 const lmstudio = await probe(config, "/api/v0/models");
                 if (lmstudio.failed)
-                    refusals.set(endpoint, { at: Date.now(), gone: lmstudio.missing });
+                    refusals().set(endpoint, { at: Date.now(), gone: lmstudio.missing });
                 else
-                    refusals.delete(endpoint);
+                    refusals().delete(endpoint);
                 const { data } = (lmstudio.body ?? {});
                 const entry = Array.isArray(data)
                     ? data.find((model) => model?.id === config.model)
                     : undefined;
                 window = positive(entry?.loaded_context_length);
             }
-            if (props.missing && refusals.get(endpoint)?.gone) {
-                unserved.add(endpoint);
+            if (props.missing && refusals().get(endpoint)?.gone) {
+                unserved().add(endpoint);
                 return 0;
             }
         }
@@ -359,7 +362,7 @@ export async function servedWindow(config) {
     catch {
         return 0;
     }
-    served.set(key, { window, at: Date.now() });
+    served().set(key, { window, at: Date.now() });
     return window;
 }
 /**
@@ -379,8 +382,8 @@ export async function listModels(config) {
     })
         .sort((a, b) => a.id.localeCompare(b.id));
     const key = endpointKey(config);
-    listings.set(key, models);
-    trainedOnly.set(key, trained);
+    listings().set(key, models);
+    trainedOnly().set(key, trained);
     return models;
 }
 /**
@@ -411,7 +414,9 @@ export async function contextLimitFor(config, declared = 0) {
     if (declared > 0)
         return declared;
     const key = endpointKey(config);
-    const listed = () => listings.get(key)?.find((model) => model.id === config.model);
+    const listed = () => listings()
+        .get(key)
+        ?.find((model) => model.id === config.model);
     // The listing is asked for again when it does not name this model, rather than only when
     // there is no listing at all. Models arrive after a process starts — an `ollama pull` on a
     // box that has been up a week, a worker added to a router, a name the operator has only just
@@ -420,12 +425,12 @@ export async function contextLimitFor(config, declared = 0) {
     // context meter and, in a consumer that compacts on it, compaction: the session then runs at
     // the window instead of under it and fails against the endpoint's own refusal.
     if (!listed()) {
-        const missKey = JSON.stringify([key, config.model]);
-        const asked = misses.get(missKey);
+        const missKey = modelKey(key, config.model);
+        const asked = misses().get(missKey);
         // Asked again, but not on every call. A model that is never coming answers the same zero
         // however often the endpoint is asked, and a caller sizing a window per turn pays a round
         // trip for each of them; `listingMissMs` is how long that answer is allowed to stand.
-        if (asked === undefined || Date.now() - asked >= poolLimits.listingMissMs) {
+        if (asked === undefined || Date.now() - asked >= poolLimits().listingMissMs) {
             // A failure is not remembered: an endpoint that was down when the last run started is not
             // an endpoint with no models, and a window nobody could ask about is not a failed run.
             const answered = await listModels(config).then(() => true, () => false);
@@ -435,9 +440,9 @@ export async function contextLimitFor(config, declared = 0) {
             // half a minute.
             if (answered) {
                 if (listed())
-                    misses.delete(missKey);
+                    misses().delete(missKey);
                 else
-                    misses.set(missKey, Date.now());
+                    misses().set(missKey, Date.now());
             }
         }
     }
@@ -445,7 +450,7 @@ export async function contextLimitFor(config, declared = 0) {
     const fromListing = entry?.contextLength ?? 0;
     // A top-level key settles it. A trained window does not: llama.cpp lists the one the model was
     // built with, and taking it over what `/props` says lets an overflow through the guard.
-    if (fromListing > 0 && !trainedOnly.get(key)?.has(config.model))
+    if (fromListing > 0 && !trainedOnly().get(key)?.has(config.model))
         return fromListing;
     const window = await servedWindow(config);
     return window > 0 ? window : fromListing;
@@ -455,12 +460,12 @@ export async function contextLimitFor(config, declared = 0) {
  * tests, and for a settings change under test.
  */
 export function resetClients() {
-    poolLimits = { ...CLIENT_DEFAULTS };
-    clients.clear();
-    listings.clear();
-    misses.clear();
-    trainedOnly.clear();
-    served.clear();
-    unserved.clear();
-    refusals.clear();
+    poolLimits.reset();
+    clients().clear();
+    listings().clear();
+    misses().clear();
+    trainedOnly().clear();
+    served().clear();
+    unserved().clear();
+    refusals().clear();
 }

package/dist/compaction.js

@@ -1,4 +1,4 @@
-import { consult, notify, turnMessages, } from "./hooks.js";
+import { consult, notify, textOf, turnMessages, } from "./hooks.js";
 import { messageTokens } from "./retry.js";
 import { ask } from "./side-task.js";
 import { holdsDefinitions } from "./tool-loading.js";
@@ -24,12 +24,6 @@ export const SUMMARY_PROMPT = "You maintain the running memory of a long convers
  * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
  */
 export const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
-/** A message's content as plain text: parts joined, anything but text left out. */
-const textOf = (content) => typeof content === "string"
-    ? content
-    : Array.isArray(content)
-        ? content.map((part) => ("text" in part ? part.text : "")).join(" ")
-        : "";
 /** What the summariser reads for one message: its text and the calls it made. */
 const messageText = (message) => {
     const calls = "tool_calls" in message && message.tool_calls
@@ -98,6 +92,8 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
     }
     return out ?? messages;
 }
+/** An index held between the start of the transcript and `most`, for a caller's `from` that is neither. */
+const clamp = (index, most) => Math.min(Math.max(index, 0), most);
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
  *
@@ -133,7 +129,7 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
     if (cost < limit * compactAt)
         return undefined;
     const head = systemHead(messages);
-    const from = Math.min(Math.max(givenFrom ?? head.from, 0), messages.length);
+    const from = clamp(givenFrom ?? head.from, messages.length);
     const previous = givenPrevious ?? head.previous;
     let cut = messages.length;
     let after;
@@ -256,7 +252,7 @@ export async function runCompaction(messages, plan, summarise, { hooks, forced =
 export function applyCompaction(messages, record, { from } = {}) {
     if (!record?.summary.trim())
         return messages;
-    const head = Math.min(Math.max(from ?? systemHead(messages).from, 0), record.through);
+    const head = clamp(from ?? systemHead(messages).from, record.through);
     return [
         ...messages.slice(0, head).filter((message) => !isSummary(message)),
         summaryMessage(record.summary),

package/dist/continuation.d.ts

@@ -1,6 +1,6 @@
-import OpenAI from "openai";
-import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
-import { type RunTurnOptions } from "./run-turn.ts";
+import type OpenAI from "openai";
+import { type Capabilities } from "./capabilities.ts";
+import { type RequestBuilder, type RunTurnOptions } from "./run-turn.ts";
 import type { Turn } from "./stream.ts";
 /**
  * Picking up an answer the token ceiling cut off, instead of keeping half of it.
@@ -56,4 +56,4 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
  * latched and each continuation finds out again — and the cap on continuations.
  */
-export declare function continueTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;
+export declare function continueTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;

package/dist/continuation.js

@@ -1,7 +1,6 @@
-import OpenAI from "openai";
 import { modelCapabilitiesFor } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { ContextOverflow } from "./retry.js";
+import { ContextOverflow, refusesRequest } from "./retry.js";
 import { runTurn } from "./run-turn.js";
 /**
  * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
@@ -79,8 +78,6 @@ function joinUsage(first, next) {
     }
     return joined;
 }
-/** Whether a failure is the endpoint refusing the request as written, rather than losing it. */
-const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
 /**
  * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
  * so far as a trailing assistant message, and joins the pieces into one turn.

package/dist/events.d.ts

@@ -50,8 +50,10 @@ export interface EventBusOptions {
  * Changes what the bus keeps, for a process whose runs are not shaped like the ones these
  * defaults were chosen for.
  *
- * The bus is one module-level thing rather than an object a caller holds, so this is too: it is
+ * The bus is one thing per runtime rather than an object a caller holds, so this is too: it is
  * a deployment's setting, said once at startup, and not something to move around under a run.
+ * Called at the top level that is the process's bus; a runtime made by `createRuntime` has its
+ * own, set through its options or its own `configureEvents`.
  * What it costs is memory against how much of a run a late or slow watcher can still read —
  * a server with hundreds of concurrent runs wants a smaller backlog, and one whose tool calls
  * take an hour wants a longer `retainUnendedMs` than the thirty minutes assumed here.
@@ -173,6 +175,19 @@ export interface RunEvent {
  * a duplicate `seq`, which is the one thing the sequence is for.
  */
 export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kind" | "runId" | "seq">>;
+/**
+ * A whole event from what a caller said of it: the empty defaults under it, the run and sequence over it.
+ *
+ * The one place the defaults are written, so an event the bus stamps, one the loop keeps for its
+ * own metrics and the notice a slow watcher is sent cannot come to disagree about what an unset
+ * field reads as.
+ *
+ * @param input What happened. An `at` it carries wins over the one given here.
+ * @param runId The run it belongs to. Written after `input`, which gets no say in it.
+ * @param seq Its place in that run, the same.
+ * @param at When, for an input that does not say.
+ */
+export declare const stamp: (input: RunEventInput, runId: string, seq: number, at: number) => RunEvent;
 /**
  * Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose
  * loop threw where it could not be caught. The sweep gets there on its own; this is for a

package/dist/events.js

@@ -1,3 +1,5 @@
+import { isPositive } from "./guards.js";
+import { scoped } from "./scope.js";
 import { LOAD_TOOLS } from "./tool-loading.js";
 /** The numbers a run of the shape this bus was written for wants. */
 const DEFAULTS = {
@@ -6,14 +8,15 @@ const DEFAULTS = {
     retainMs: 60_000,
     retainUnendedMs: 30 * 60_000,
 };
-/** What is in force now. Read where it is used, so a change applies from the next event. */
-let limits = { ...DEFAULTS };
+const bus = scoped(() => ({ limits: { ...DEFAULTS }, streams: new Map(), sweeping: null }));
 /**
  * Changes what the bus keeps, for a process whose runs are not shaped like the ones these
  * defaults were chosen for.
  *
- * The bus is one module-level thing rather than an object a caller holds, so this is too: it is
+ * The bus is one thing per runtime rather than an object a caller holds, so this is too: it is
  * a deployment's setting, said once at startup, and not something to move around under a run.
+ * Called at the top level that is the process's bus; a runtime made by `createRuntime` has its
+ * own, set through its options or its own `configureEvents`.
  * What it costs is memory against how much of a run a late or slow watcher can still read —
  * a server with hundreds of concurrent runs wants a smaller backlog, and one whose tool calls
  * take an hour wants a longer `retainUnendedMs` than the thirty minutes assumed here.
@@ -27,14 +30,37 @@ let limits = { ...DEFAULTS };
  * @returns Everything in force afterwards, including what this call did not change.
  */
 export function configureEvents(options = {}) {
+    const { limits } = bus();
     for (const [name, value] of Object.entries(options)) {
-        if (typeof value === "number" && value > 0)
+        if (isPositive(value))
             limits[name] = value;
     }
     return { ...limits };
 }
-const streams = new Map();
-const streamFor = (runId) => {
+/**
+ * A whole event from what a caller said of it: the empty defaults under it, the run and sequence over it.
+ *
+ * The one place the defaults are written, so an event the bus stamps, one the loop keeps for its
+ * own metrics and the notice a slow watcher is sent cannot come to disagree about what an unset
+ * field reads as.
+ *
+ * @param input What happened. An `at` it carries wins over the one given here.
+ * @param runId The run it belongs to. Written after `input`, which gets no say in it.
+ * @param seq Its place in that run, the same.
+ * @param at When, for an input that does not say.
+ */
+export const stamp = (input, runId, seq, at) => ({
+    at,
+    text: "",
+    name: "",
+    step: "",
+    ok: null,
+    usage: null,
+    ...input,
+    runId,
+    seq,
+});
+const streamFor = ({ streams }, runId) => {
     const existing = streams.get(runId);
     if (existing)
         return existing;
@@ -60,9 +86,9 @@ const streamFor = (runId) => {
  *
  * One timer for the whole map, rescheduled only while there is something in it to expire.
  */
-let sweeping = null;
-function sweep() {
-    sweeping = null;
+function sweep(held) {
+    const { limits, streams } = held;
+    held.sweeping = null;
     const now = Date.now();
     for (const [runId, stream] of streams) {
         if (stream.listeners.size)
@@ -70,13 +96,13 @@ function sweep() {
         if (stream.touched <= now - (stream.ended ? limits.retainMs : limits.retainUnendedMs))
             streams.delete(runId);
     }
-    scheduleSweep();
+    scheduleSweep(held);
 }
-function scheduleSweep() {
-    if (sweeping || streams.size === 0)
+function scheduleSweep(held) {
+    if (held.sweeping || held.streams.size === 0)
         return;
-    sweeping = setTimeout(sweep, limits.retainMs);
-    sweeping.unref?.();
+    held.sweeping = setTimeout(() => sweep(held), held.limits.retainMs);
+    held.sweeping.unref?.();
 }
 /**
  * Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose
@@ -86,6 +112,7 @@ function scheduleSweep() {
  * @param runId The run to forget. An id nothing was emitted under is ignored.
  */
 export function endRun(runId) {
+    const { streams } = bus();
     const stream = streams.get(runId);
     if (!stream)
         return;
@@ -106,21 +133,12 @@ export function endRun(runId) {
  * @param input The event. `kind` is required; `runId` and `seq` are not a caller's to set.
  */
 export function emit(runId, input) {
-    const stream = streamFor(runId);
+    const held = bus();
+    const { limits } = held;
+    const stream = streamFor(held, runId);
     // One clock read, used for both the event and the sweep's bookkeeping.
     const at = Date.now();
-    const event = {
-        at,
-        text: "",
-        name: "",
-        step: "",
-        ok: null,
-        usage: null,
-        ...input,
-        // After the spread, not before: these are the bus's and a caller does not get a say.
-        runId,
-        seq: ++stream.seq,
-    };
+    const event = stamp(input, runId, ++stream.seq, at);
     stream.events.push(event);
     stream.touched = at;
     if (stream.events.length > limits.maxEvents + limits.trimSlack) {
@@ -130,7 +148,7 @@ export function emit(runId, input) {
     // then dropped: a finished run's record is the row, not this.
     if (event.kind === "done")
         stream.ended = true;
-    scheduleSweep();
+    scheduleSweep(held);
     for (const listener of stream.listeners) {
         // The guarantee above is the point of this: a listener that throws must not take out the
         // emitter, the listeners after it, or the bookkeeping already done above.
@@ -155,8 +173,14 @@ export function emit(runId, input) {
  * function it is suspended at an `await` rather than at a `yield`, and a `return()` there is
  * queued behind a promise only the next event can settle. An abort resolves that promise itself.
  */
-export async function* watch(runId, signal) {
-    const stream = streamFor(runId);
+export function watch(runId, signal) {
+    // Read here, not in the generator: its body runs when the first event is asked for, and by
+    // then the caller may be outside the runtime whose run this is.
+    return watching(bus(), runId, signal);
+}
+async function* watching(held, runId, signal) {
+    const { limits, streams } = held;
+    const stream = streamFor(held, runId);
     // A cursor rather than `shift()`. Draining a backlog an event at a time off the front of an
     // array is a copy of the whole array per event, which on the ten-thousand-delta run this bus
     // is built for is the one quadratic left in the file. The prefix behind the cursor is dropped
@@ -217,17 +241,11 @@ export async function* watch(runId, signal) {
                     // Inside the gap there is nothing to collide with: those seqs reach no watcher.
                     const gap = dropped;
                     dropped = 0;
-                    yield {
-                        runId,
-                        seq: event.seq - 1,
-                        at: event.at,
+                    yield stamp({
                         kind: "notice",
                         text: `${gap} event(s) dropped: this watcher fell too far behind`,
-                        name: "",
                         step: event.step,
-                        ok: null,
-                        usage: null,
-                    };
+                    }, runId, event.seq - 1, event.at);
                 }
                 yield event;
                 // `done` is the last event a run will ever have, so the subscription completes rather
@@ -272,7 +290,7 @@ export async function* watch(runId, signal) {
  *
  * @param runId The run to read. An unknown or already-swept run gives an empty array.
  */
-export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
+export const history = (runId) => [...(bus().streams.get(runId)?.events ?? [])];
 /**
  * Test seam: forget every run, so one test's events cannot be read by the next.
  *
@@ -286,11 +304,13 @@ export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
  * teardown configures again, which is the same line it already wrote once.
  */
 export const resetEvents = () => {
-    streams.clear();
-    if (sweeping)
-        clearTimeout(sweeping);
-    sweeping = null;
-    limits = { ...DEFAULTS };
+    const held = bus();
+    held.streams.clear();
+    if (held.sweeping)
+        clearTimeout(held.sweeping);
+    held.sweeping = null;
+    // In place, so a watcher still open reads the defaults too and not the caps it began under.
+    Object.assign(held.limits, DEFAULTS);
 };
 /**
  * Consecutive tokens of one kind are one thing being said, not hundreds of things.

package/dist/guards.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The checks a value read off the wire is put through before anything is read from it.
+ *
+ * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
+ * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
+ * its own copy.
+ */
+/**
+ * Whether a value is a plain keyed object: not null, and not an array.
+ *
+ * @param value Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+/**
+ * Whether a value is a number above zero, which is what a limit has to be to be one.
+ *
+ * `Infinity` passes and `NaN` does not, so a caller lifting a bound and one handing over a
+ * half-built config are told apart without either being asked.
+ *
+ * @param value Anything, usually a setting that may be absent, zero or mistyped.
+ */
+export declare const isPositive: (value: unknown) => value is number;