@cubicecho/agent-core 2.2.4 → 2.4.0

package/README.md

@@ -25,6 +25,7 @@ only, Node >=22.
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
 | `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. |
+| `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`. A watcher's backlog is capped and reports its own gaps. |
 | `client` | A pooled `OpenAI` client per endpoint, plus the context-window listing and its cache. |
 | `retry` | What to do when a request is lost, refused or too big: `isTransient`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`. |
@@ -54,7 +55,7 @@ import {
 } from "@cubicecho/agent-core";
 
 const declared = sanitizeTools(tools);
-const supports = capabilitiesFor(config.baseUrl);
+const supports = capabilitiesFor(config.baseUrl, config.apiKey);
 
 const turn = await negotiate(supports, (supports, produced) =>
   streamTurn(
@@ -70,6 +71,17 @@ const turn = await negotiate(supports, (supports, produced) =>
 );
 ```
 
+The key is passed because it is part of what an endpoint *is* here, not only how it is paid
+for: a router is free to send two keys to two different backends, and then what one of them
+refused is not a fact about the other. Absent and empty read the same, so a local server with no
+key is one entry however its caller spells it.
+
+`Turn` is `content`, `toolCalls`, `usage` and `finishReason`. The last is worth reading: a turn
+cut off at the token ceiling comes back looking exactly like a finished one, with truncated prose
+or — the case that bites — a tool call whose `arguments` stop mid-JSON, so the caller meets a
+parse failure with nothing to attribute it to. `finishReason` is `"length"` there, `""` where the
+endpoint never said.
+
 ## What the model refuses, rather than the server
 
 `strictSchemas` and `usageInStream` are facts about a server. Three more arrive through the same
@@ -157,6 +169,12 @@ before it and the transcript does not change between retries. A `ContextOverflow
 neither a capability `negotiate` can answer nor something `isTransient` accepts, so it leaves
 both loops on the first attempt.
 
+`contextLimit` decides how early the caller hears, not what it hears. Without one, the endpoint
+refuses instead — one round trip later — and `runTurn` reads that refusal back through
+`isOverflow` and raises the same `ContextOverflow`, carrying the endpoint's own wording and the
+original error as `cause`. A rate limit borrows those words and means the opposite ("Request too
+large for gpt-4o ... on tokens per min"); that is ruled out and waited through as the 429 it is.
+
 ## Watching a run
 
 `watch` replays what the run has already emitted, then yields what happens next until `done`.
@@ -166,13 +184,20 @@ de-duplicates on.
 ```ts
 import { watch } from "@cubicecho/agent-core";
 
-for await (const event of watch(runId)) {
+// The signal is how a watcher leaves early — a disconnected client, a page navigated away from.
+for await (const event of watch(runId, request.signal)) {
   render(event);
 }
 ```
 
+Pass one for anything that can go away before the run ends. `watch` otherwise finishes only on
+`done`, and returning the generator is not a substitute: waiting for the next event it is
+suspended at an `await` rather than at a `yield`, so a `return()` queues behind a promise only
+that event can settle. A watcher stuck there also holds its run's backlog past every deadline,
+because the sweep skips any stream a listener is on.
+
 A watcher that stops keeping up is capped rather than left to grow. Its queue holds the most
-recent 1000 events — trimmed in batches, so it runs a little over that before cutting back —
+recent 1000 events by default — trimmed in batches, so it runs a little over that before cutting back —
 the oldest go, and what is dropped is released where it is dropped, not held until a consumer
 that has already stalled next reads.
 
@@ -184,6 +209,90 @@ repeat, and a client doing what `seq` is documented for would throw away one of
 `history` reads what a run has emitted without subscribing, `fold` collapses a token stream into
 blocks for display, and `endRun` drops a finished run's buffer.
 
+The four numbers behind that — the backlog cap, the slack it is trimmed in batches of, and the two
+deadlines the sweep reaps on — are defaults rather than decisions. `configureEvents` moves them,
+and returns the whole set as it now stands:
+
+```ts
+import { configureEvents } from "@cubicecho/agent-core";
+
+// A long-lived server with many concurrent runs, whose tool calls are minutes rather than hours.
+configureEvents({ maxEvents: 200, retainUnendedMs: 5 * 60_000 });
+```
+
+It is module-level because the bus is: there is one of each per process, and a run does not carry
+its own. A field left out keeps what it had, and so does one given something that is not a
+positive number — nothing here has a meaningful zero, and a `0` standing in for "no opinion" must
+not turn the backlog off. `resetEvents` (and `resetAll`) puts the defaults back, so one test's cap
+is not the next one's.
+
+`expandNames`, `carryOver`, `preselection`, `preselectInput` and `preselectSystem` take their caps
+the same way — as a last argument defaulting to `MAX_PER_LOAD` or `MAX_CARRIED`. A resolution
+carries the cap it was held to, so `loadResult` tells the model the number it was actually
+measured against rather than the module's own.
+
+## Hooks
+
+A hook is something a host runs at a point in a session — `sessionStart` and `beforeTurn`, whose
+output can reach the request, then `afterTurn`, `beforeCompact`, `sessionEnd` and `sessionDelete`,
+which can only read what happened. What runs is not decided here. `gather` and `notify` take a
+`HookRunner`, and `@cubicecho/agent-mcp-pool`'s `runHooks` is one as it stands: its types are the
+shapes restated here, so its outcomes pass straight through without either package importing the
+other.
+
+```ts
+import {
+  emit,
+  gather,
+  type HookRunner,
+  notify,
+  turnIndex,
+  turnMessages,
+  withContext,
+} from "@cubicecho/agent-core";
+
+const run: HookRunner = (event, context, { signal }) =>
+  pool.runHooks(event, context, { signal, servers: agent.mcpServers });
+
+const context = { session: { id }, host: "my-host", prompt, turn: { index: turnIndex(messages) } };
+const gathered = await gather(
+  run,
+  messages.length === 0 ? ["sessionStart", "beforeTurn"] : ["beforeTurn"],
+  context,
+  { signal, onNote: (note) => emit(runId, { kind: "notice", name: note.hookId, text: note.error ?? note.text }) },
+);
+messages.push({ role: "user", content: prompt });
+const request = withContext(messages, messages.length - 1, gathered.context);
+// ... the turn ...
+void notify(run, "afterTurn", { ...context, reply, turn: { ...context.turn, messages: turnMessages(id, messages, turnStart) } });
+```
+
+The context goes on this turn's question and never into the system prompt — a prompt that changed
+every turn would miss the prompt cache every turn — and `withContext` returns a new array, so a
+host that stores what the user typed never stores the context as something they said. Every
+injecting hook shares `HOOK_CONTEXT_TOKENS` (2000) by default, each held to its own `maxTokens`
+inside that, so a generous hook cannot crowd out the conversation it was meant to inform.
+
+The budget is the caller's to move, at either level. `configureHooks` sets it for the process, and
+`maxTokens` on `gather` (or the second argument to `assembleContext`) sets it for one request and
+wins over it — the one to reach for when the budget follows the model, since a 128k window can
+afford more recall than an 8k one:
+
+```ts
+import { configureHooks, gather } from "@cubicecho/agent-core";
+
+configureHooks({ contextTokens: 4000 });
+const gathered = await gather(run, ["beforeTurn"], context, { maxTokens: contextLimit / 20 });
+```
+
+Either one given something that is not a number above zero keeps what was there, as
+`configureEvents` does, so a `0` threaded through for "no opinion" does not switch recall off.
+`resetHooks` (and `resetAll`) puts the default back.
+
+Neither function rejects. A hook failing is an outcome, and a runner that throws outright is
+noted once for its event and costs only that event's context. `notify` takes no signal: a reader
+who leaves once the turn is answered has not asked for it not to be remembered.
+
 ## The config seam
 
 Nothing here imports a config type from a consumer, and no function asks for a whole
@@ -205,6 +314,32 @@ The seam is not finished. `timeoutMs` narrows to the one field it reads, but `ge
 asks for the whole of `Endpoint`. `requestTimeoutSeconds` became optional in v2, so a consumer
 with no timeout to give now leaves it out rather than inventing a `0`.
 
+## What is kept for the life of the process
+
+Four caches outlive any one run: the `OpenAI` clients, the model listings, the latched
+capabilities, and `side-task`'s no-thinking hints. All four are module-level and keyed on the same
+notion of an endpoint — its base URL and its API key — and the clients' key carries the request
+timeout as well, since that changes how a request is sent.
+
+**They are keyed per deployment, not per request.** What belongs in them is an endpoint an
+operator configured: a settings row, an agent definition, an environment variable. Everything
+bounding them assumes that, and a consumer that mints an API key per *user* breaks the assumption
+— each tenant gets its own client, its own connection pool and its own latches, held until
+`resetAll`.
+
+That is bounded rather than unbounded: the client pool is a 32-entry LRU, and an evicted client
+costs its connection pool and nothing else, since the next request through that endpoint builds
+another. But churning connection pools is not sharing them, and at that point a client of your
+own, built and held per tenant, is the better answer than this.
+
+The listings cache also remembers, for half a minute, that an endpoint did not name a model — the
+case where a configured name never matches anything the server serves (a llama.cpp `-a` alias, an
+OpenRouter `:free` suffix, a typo) would otherwise fetch the listing on every call and answer the
+same zero each time. Half a minute later it asks again, so a model pulled onto a box that has been
+up a week is still picked up without a restart.
+
+`resetAll` drops all four, and `reset.ts` names each seam separately for a test that wants one.
+
 ## Where the merged behaviour came from
 
 - `schema-compat` — `kanban_server`/`task_server`'s version, which strips **every** sibling of a

package/dist/capabilities.d.ts

@@ -70,10 +70,14 @@ export interface ModelCapabilities {
  * What this endpoint is known not to support. The same object every time, so what `negotiate`
  * latches off stays off.
  *
- * @param baseUrl Identifies the endpoint. The two flags on it are per-server; what is
- * per-model hangs off `models`, which `modelCapabilitiesFor` reads.
+ * @param baseUrl Where the endpoint is. The two flags on it are per-server; what is per-model
+ * hangs off `models`, which `modelCapabilitiesFor` reads.
+ * @param apiKey The rest of the endpoint's identity. Optional, because it changes nothing for
+ * the ordinary case of one key per base URL and a caller with one need not thread it through;
+ * absent reads as `NO_KEY`, exactly as it does in `getClient`, so an endpoint with no key and
+ * one that passes `undefined` share an entry rather than holding two.
  */
-export declare function capabilitiesFor(baseUrl: string): Capabilities;
+export declare function capabilitiesFor(baseUrl: string, apiKey?: string): Capabilities;
 /**
  * What this model on this endpoint is known not to support. The same object every time, so what
  * `negotiate` latches off stays off.

package/dist/capabilities.js

@@ -1,29 +1,42 @@
+import { endpointKey } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isGrammarError } from "./schema-compat.js";
 /**
  * What each endpoint cannot do, remembered for the life of the process.
  *
- * Keyed by base URL, because these are facts about the server on the other end and not about
- * this one. A llama.cpp box that cannot compile a grammar and a cloud API that can are both
- * reachable from one settings row over its lifetime — an operator retargets it from Ollama this
- * afternoon to OpenAI this evening — and the first one's refusal must not quietly strip
+ * Keyed by `endpointKey`, because these are facts about the server on the other end and not
+ * about this one. A llama.cpp box that cannot compile a grammar and a cloud API that can are
+ * both reachable from one settings row over its lifetime — an operator retargets it from Ollama
+ * this afternoon to OpenAI this evening — and the first one's refusal must not quietly strip
  * pattern/format from the second one's requests, or silently cost it its token counts, for the
  * rest of the process. Bounded by the number of endpoints ever configured, which is a settings
  * row's worth.
+ *
+ * The API key is part of that identity, the same as it is for the client pool and the model
+ * listings. A router — LiteLLM, OpenRouter, a gateway with several boxes behind it — is free to
+ * send two keys to two different backends, and then what one of them refused is not a fact about
+ * the other. Keyed on the URL alone the first caller through the gateway latched for everyone
+ * behind it, including the `models` map underneath, which is the level where two keys through
+ * one host are most likely to differ at all.
  */
 const capabilities = new Map();
 /**
  * What this endpoint is known not to support. The same object every time, so what `negotiate`
  * latches off stays off.
  *
- * @param baseUrl Identifies the endpoint. The two flags on it are per-server; what is
- * per-model hangs off `models`, which `modelCapabilitiesFor` reads.
+ * @param baseUrl Where the endpoint is. The two flags on it are per-server; what is per-model
+ * hangs off `models`, which `modelCapabilitiesFor` reads.
+ * @param apiKey The rest of the endpoint's identity. Optional, because it changes nothing for
+ * the ordinary case of one key per base URL and a caller with one need not thread it through;
+ * absent reads as `NO_KEY`, exactly as it does in `getClient`, so an endpoint with no key and
+ * one that passes `undefined` share an entry rather than holding two.
  */
-export function capabilitiesFor(baseUrl) {
-    let known = capabilities.get(baseUrl);
+export function capabilitiesFor(baseUrl, apiKey) {
+    const key = endpointKey({ baseUrl, apiKey });
+    let known = capabilities.get(key);
     if (!known) {
         known = { strictSchemas: true, usageInStream: true, models: new Map() };
-        capabilities.set(baseUrl, known);
+        capabilities.set(key, known);
     }
     return known;
 }

package/dist/client.d.ts

@@ -18,6 +18,13 @@ export declare const timeoutMs: (config: Pick<Endpoint, "requestTimeoutSeconds">
  * Pooled on the three fields that change how a request is sent, so agents sharing a server share
  * a connection and agents on different servers never share a client.
  *
+ * The pool is per *deployment*, not per request: what belongs in this map is an endpoint an
+ * operator configured, and everything cached in this package is bounded on that reading. A
+ * consumer that mints an API key per user still gets a working client, but it is churning
+ * connection pools rather than sharing them and holding every one of them — `MAX_CLIENTS` keeps
+ * that from being unbounded, and it is the point at which a client of your own, built and held
+ * per tenant, is the better answer than this.
+ *
  * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
  */
 export declare function getClient(config: Endpoint): OpenAI;
@@ -26,6 +33,27 @@ export interface ModelInfo {
     id: string;
     contextLength: number;
 }
+/**
+ * What counts as one endpoint, everywhere in this package that has to remember something about
+ * one — this file's listings, `capabilities`, and the no-thinking hints in `side-task`.
+ *
+ * The URL and the key together, because the key is part of what is on the other end rather than
+ * only how it is paid for: a router is free to send two keys to two different backends, and then
+ * what one of them refused is not a fact about the other. Absent reads as `NO_KEY`, so an
+ * endpoint with no key and one that passes `undefined` are one entry rather than two.
+ *
+ * Stringified rather than joined on a separator, for the reason `getClient` gives: no character
+ * is impossible in a URL or a key, and two endpoints must never collide on one entry.
+ *
+ * @param config Read for `baseUrl` and `apiKey` alone, and the key is optional here where
+ * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
+ * config, and absent and empty already mean the same thing. The timeout is deliberately not in
+ * it; see `listings`.
+ */
+export declare const endpointKey: (config: {
+    baseUrl: string;
+    apiKey?: string;
+}) => string;
 /**
  * Asks an endpoint what it serves, and remembers the answer.
  *

package/dist/client.js

@@ -26,14 +26,39 @@ export const timeoutMs = (config) => {
  * `maxRetries: 0` turns the SDK's own retrying off. Streaming is what this is for, and a stream
  * that has already emitted tokens must not be replayed from the top — the caller knows whether
  * anything has been produced yet and the SDK does not. See `retry.ts`.
+ *
+ * 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();
+/**
+ * How many endpoints' clients are kept at once.
+ *
+ * This is a backstop rather than a design. The key includes the API key, and every argument in
+ * this file for what bounds these caches is "a settings row's worth" — true of the deployments
+ * this was written for, and false the moment a consumer mints a key per *user*, where the map
+ * grows one client and one connection pool per tenant for the life of the process with
+ * `resetClients` as the only release.
+ *
+ * Thirty-two is far more endpoints than a settings table holds, so a deployment-shaped consumer
+ * never reaches it, and an evicted client costs its connection pool and nothing else — the next
+ * request through that endpoint builds another. See `getClient` for the constraint stated as a
+ * constraint.
+ */
+const MAX_CLIENTS = 32;
 /**
  * The client for an endpoint, built once and kept.
  *
  * Pooled on the three fields that change how a request is sent, so agents sharing a server share
  * a connection and agents on different servers never share a client.
  *
+ * The pool is per *deployment*, not per request: what belongs in this map is an endpoint an
+ * operator configured, and everything cached in this package is bounded on that reading. A
+ * consumer that mints an API key per user still gets a working client, but it is churning
+ * connection pools rather than sharing them and holding every one of them — `MAX_CLIENTS` keeps
+ * that from being unbounded, and it is the point at which a client of your own, built and held
+ * per tenant, is the better answer than this.
+ *
  * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
  */
 export function getClient(config) {
@@ -43,10 +68,23 @@ export function getClient(config) {
     // 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);
-    if (existing)
+    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);
         return existing;
+    }
     const client = new OpenAI({ baseURL: config.baseUrl, apiKey, timeout, maxRetries: 0 });
     clients.set(key, client);
+    // Nothing is closed on the way out. The SDK holds no handle a caller can release, and an
+    // evicted client is garbage once whatever request is still in flight on it has finished —
+    // dropping the reference is the whole of the eviction.
+    for (const oldest of clients.keys()) {
+        if (clients.size <= MAX_CLIENTS)
+            break;
+        clients.delete(oldest);
+    }
     return client;
 }
 /**
@@ -76,7 +114,7 @@ function contextLengthOf(model) {
 /**
  * The last listing from each endpoint, so a run can size its window without a round trip.
  *
- * Keyed by base URL and key, because two endpoints are two different sets of models and one of
+ * Keyed by `endpointKey`, because two endpoints are two different sets of models and one of
  * them having answered says nothing about the other — and because a key can be the difference
  * between what a router will show one caller and another.
  *
@@ -88,7 +126,41 @@ function contextLengthOf(model) {
  * whatever was there rather than emptying it.
  */
 const listings = new Map();
-const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
+/**
+ * When an endpoint was last asked about a model it did not name, keyed on the two together.
+ *
+ * `contextLimitFor` asks again whenever the listing does not hold the model, which is right for
+ * a model that arrives late and wrong for one that is never coming. The second is the ordinary
+ * case rather than the exotic one — a llama.cpp box served under a `-a` alias that does not
+ * match the configured name, an OpenRouter `:free` suffix, a typo in a settings row — and there
+ * every call fetches the listing, re-reads it, finds the same absence and answers the same zero.
+ *
+ * Remembering the miss for a moment answers both: within `LISTING_MISS_MS` nobody is asked, and
+ * after it the endpoint is asked again, so an `ollama pull` on a box that has been up a week is
+ * 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();
+/** How long a model an endpoint did not list stays unlisted before it is asked about again. */
+const LISTING_MISS_MS = 30_000;
+/**
+ * What counts as one endpoint, everywhere in this package that has to remember something about
+ * one — this file's listings, `capabilities`, and the no-thinking hints in `side-task`.
+ *
+ * The URL and the key together, because the key is part of what is on the other end rather than
+ * only how it is paid for: a router is free to send two keys to two different backends, and then
+ * what one of them refused is not a fact about the other. Absent reads as `NO_KEY`, so an
+ * endpoint with no key and one that passes `undefined` are one entry rather than two.
+ *
+ * Stringified rather than joined on a separator, for the reason `getClient` gives: no character
+ * is impossible in a URL or a key, and two endpoints must never collide on one entry.
+ *
+ * @param config Read for `baseUrl` and `apiKey` alone, and the key is optional here where
+ * `Endpoint` requires it — `capabilitiesFor` is handed a URL and maybe a key rather than a whole
+ * config, and absent and empty already mean the same thing. The timeout is deliberately not in
+ * it; see `listings`.
+ */
+export const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
 /**
  * Asks an endpoint what it serves, and remembers the answer.
  *
@@ -122,6 +194,7 @@ 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);
     // 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
@@ -129,10 +202,14 @@ export async function contextLimitFor(config, declared = 0) {
     // of them until a restart. Zero means "nobody knows", so what the operator loses is the
     // 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.
-    //
-    // The cost of asking again is one listing per call while the model really is absent, which
-    // is exactly the case where the cached answer would have been wrong.
-    if (!listings.get(key)?.some((model) => model.id === config.model)) {
+    if (!listed()) {
+        const missKey = JSON.stringify([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; `LISTING_MISS_MS` is how long that answer is allowed to stand.
+        if (asked !== undefined && Date.now() - asked < LISTING_MISS_MS)
+            return 0;
         // 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.
         try {
@@ -141,12 +218,20 @@ export async function contextLimitFor(config, declared = 0) {
         catch {
             return 0;
         }
+        // Recorded where the endpoint was actually asked, and only there. Stamping it on the calls
+        // that skipped the request would push the deadline out ahead of any caller polling faster
+        // than the interval, which is a memory that never expires rather than one that expires in
+        // half a minute.
+        if (listed())
+            misses.delete(missKey);
+        else
+            misses.set(missKey, Date.now());
     }
-    const listed = listings.get(key) ?? [];
-    return listed.find((model) => model.id === config.model)?.contextLength ?? 0;
+    return listed()?.contextLength ?? 0;
 }
 /** Forgets every cached client and listing. For tests, and for a settings change under test. */
 export function resetClients() {
     clients.clear();
     listings.clear();
+    misses.clear();
 }

package/dist/events.d.ts

@@ -9,6 +9,60 @@
  * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
  * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
  */
+/** What the bus keeps and for how long. Every field optional; see `configureEvents`. */
+export interface EventBusOptions {
+    /** How many events one run keeps for a watcher that joins late. A chatty run loses its oldest. */
+    maxEvents?: number;
+    /**
+     * How far past the cap the backlog is allowed to run before it is trimmed.
+     *
+     * Dropping the oldest event on every push means shifting a thousand-element array tens of
+     * thousands of times over a reasoning run — the one thing in here that would ever show up in a
+     * profile. Trimming in batches makes it a few dozen splices instead, at the cost of the backlog
+     * sometimes being a little longer than the cap, which nothing depends on. The one field here
+     * that is an implementation detail rather than a policy: raising it trades memory for fewer
+     * splices, and there is no reason to lower it.
+     */
+    trimSlack?: number;
+    /** How long a finished run stays readable, for a watcher that arrives just after the end. */
+    retainMs?: number;
+    /**
+     * The same for a run that has not said `done`, which is a far more dangerous thing to drop.
+     *
+     * A finished run has nothing more to say, so forgetting it a minute later costs a late watcher
+     * a backlog and nothing else. An unfinished one is still writing: `touched` only moves on
+     * `emit`, so a live run that spends a minute inside one slow tool call looked exactly like an
+     * abandoned one and was reaped out from under itself. What made that more than a lost backlog
+     * is that the next `emit` builds a fresh stream with `seq` back at zero — and `seq` is the
+     * field `RunEvent` documents for ordering and de-duplication, so a client that reconnects
+     * across the gap discards the new events as ones it has already seen.
+     *
+     * The sweep still has to reap them, because a run killed by a signal or simply forgotten
+     * reaches no `done` either. This is the backstop for a caller that never says so; `endRun` is
+     * for one that knows. Anything shorter than the longest a tool call may take is a live run
+     * reaped out from under itself.
+     */
+    retainUnendedMs?: number;
+}
+/**
+ * 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
+ * a deployment's setting, said once at startup, and not something to move around under a run.
+ * 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.
+ *
+ * Changes apply from the next event and the next sweep. Nothing already buffered is trimmed to
+ * a cap that has just come down, because the trim happens on push; the backlog settles to the
+ * new number as the run goes on.
+ *
+ * @param options The bounds to change. A field left out — or given anything that is not a
+ * number above zero — keeps what it has, so a partial or a half-built config narrows nothing.
+ * @returns Everything in force afterwards, including what this call did not change.
+ */
+export declare function configureEvents(options?: EventBusOptions): Required<EventBusOptions>;
 /** Which kind of thing happened, and what `text`, `name`, `ok` and `usage` carry for it. */
 export type RunEventKind = 
 /** A step of a caller's own flow began. `name` is the step, `text` its kind. */
@@ -107,11 +161,22 @@ export declare function emit(runId: string, input: RunEventInput): RunEvent;
  * inside the retention window — reads the same story as one that was there from the start.
  *
  * @param runId The run to follow. One that has not started yet is waited on, not refused.
+ * @param signal Stops following. The only other way out is the run's own `done`, and a watcher
+ * with no way out is a leak rather than a lost backlog: the sweep below skips any stream a
+ * listener is on, so a run that dies without `done` pins its backlog for the life of the process.
+ * Returning the generator is not that way out — parked on the promise at the foot of this
+ * 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 declare function watch(runId: string): AsyncGenerator<RunEvent>;
+export declare function watch(runId: string, signal?: AbortSignal): AsyncGenerator<RunEvent>;
 /**
  * The backlog alone, for a caller that wants a snapshot rather than a subscription.
  *
+ * The array is a copy; the events in it are not. They are the same objects the bus holds and
+ * every watcher was handed, so writing to one rewrites the run for everybody — which is what
+ * `fold` copies to avoid, and this is the other half of the same warning. Read them, or copy
+ * what you mean to change.
+ *
  * @param runId The run to read. An unknown or already-swept run gives an empty array.
  */
 export declare const history: (runId: string) => RunEvent[];
@@ -121,6 +186,11 @@ export declare const history: (runId: string) => RunEvent[];
  * Named for what it forgets rather than bare `reset`, which sat in a consumer's imports beside
  * `resetAll`, `resetClients`, `resetCapabilities` and `resetHints` saying nothing about which
  * of the five it was — `reset.ts` had to alias it on the way in to stay readable.
+ *
+ * `configureEvents` is undone too, for the reason `reset.ts` gives about latches: a bus left
+ * holding a cap one test set is the same order-dependent suite, passing where that test ran
+ * first and failing where it did not. A consumer that configures at startup and resets at
+ * teardown configures again, which is the same line it already wrote once.
  */
 export declare const resetEvents: () => void;
 /**