@cubicecho/agent-core 2.0.0 → 2.0.2

package/README.md

@@ -25,7 +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, per endpoint, and the loop that answers it when it says so. `capabilitiesFor`, `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. |
-| `events` | The in-memory bus a watcher reads while a run happens. |
+| `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`. |
 | `config` | The structural interfaces every function here asks for. |
@@ -38,6 +38,10 @@ only, Node >=22.
 What is **not** here is the work: orchestration, prompts, and whatever the run is about. That
 is the caller's, and it is the part that actually differs between one server and the next.
 
+`llms.txt` is the same surface as a flat index — every export with the first line of its own doc
+comment. It is generated from `src/index.ts` by `npm run llms`, which the build runs, so it is
+the exports rather than a second description of them; CI fails if the committed copy has drifted.
+
 ## A turn
 
 `negotiate` wrapping `streamTurn` is the whole of one turn against an endpoint: the request is
@@ -46,7 +50,7 @@ and nothing is re-sent once it has started answering.
 
 ```ts
 import {
-  capabilitiesFor, getClient, negotiate, relaxTools, sanitizeTools, streamTurn, timeoutMs,
+  capabilitiesFor, emit, getClient, negotiate, relaxTools, sanitizeTools, streamTurn, timeoutMs,
 } from "@cubicecho/agent-core";
 
 const declared = sanitizeTools(tools);
@@ -82,13 +86,14 @@ slowly needs.
 `runTurn` will refuse a request that cannot fit rather than spending a round trip finding out:
 
 ```ts
-import { contextLimitFor, runTurn } from "@cubicecho/agent-core";
+import { contextLimitFor, emit, runTurn } from "@cubicecho/agent-core";
 
 const turn = await runTurn(client, supports, build, {
   maxRetries: 3,
-  // Opt-in: the number is the caller's to find. `contextLimitFor` asks the endpoint, and an
-  // operator's own setting overrides it — neither is network I/O a turn should be doing.
-  contextLimit: settings.contextLength || (await contextLimitFor(settings, model)),
+  // Opt-in: the number is the caller's to find, because neither of these is network I/O a
+  // turn should be doing. The second argument is the operator's own number and it wins
+  // outright when set, so there is no need to check it yourself first.
+  contextLimit: await contextLimitFor({ ...settings, model }, settings.contextLength),
   onNotice: (message) => emit(runId, { kind: "notice", text: message }),
 });
 ```
@@ -98,6 +103,33 @@ 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.
 
+## Watching a run
+
+`watch` replays what the run has already emitted, then yields what happens next until `done`.
+`emit` assigns `seq`, a per-run counter from 1, and that is what a client orders and
+de-duplicates on.
+
+```ts
+import { watch } from "@cubicecho/agent-core";
+
+for await (const event of watch(runId)) {
+  render(event);
+}
+```
+
+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 —
+the oldest go, and what is dropped is released where it is dropped, not held until a consumer
+that has already stalled next reads.
+
+The gap is reported once, as a single `notice`, not once per lost event. It carries the `seq`
+immediately before the event that follows it: inside the gap, where no real event will ever
+appear. Sharing a `seq` with the event behind it would make the pair indistinguishable from a
+repeat, and a client doing what `seq` is documented for would throw away one of the two.
+
+`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 config seam
 
 Nothing here imports a config type from a consumer, and no function asks for a whole

package/dist/capabilities.d.ts

@@ -27,10 +27,13 @@ export interface Capabilities {
 /**
  * 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. These are per-server, not per-model.
  */
 export declare function capabilitiesFor(baseUrl: string): Capabilities;
 /** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
 export declare function resetCapabilities(): void;
+/** What `negotiate` takes besides the request. Both optional, both about telling someone. */
 export interface NegotiateOptions {
     /**
      * The flag `send` will be given, for a caller that has to read it after `negotiate` returns.
@@ -64,5 +67,10 @@ export interface NegotiateOptions {
  * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
  * caller that passed it to only one of the two got a turn that had already streamed tokens sent
  * again, silently, with the watcher seeing every one of them twice.
+ *
+ * @param supports What this endpoint has already refused. Latched off further as it refuses more.
+ * @param send Builds and sends the request. Called again per downgrade, never once tokens
+ * have arrived.
+ * @param options `produced` for a caller with its own retry budget, `onNotice` for a watcher.
  */
 export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced) => Promise<T>, { produced, onNotice }?: NegotiateOptions): Promise<T>;

package/dist/capabilities.js

@@ -15,6 +15,8 @@ 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. These are per-server, not per-model.
  */
 export function capabilitiesFor(baseUrl) {
     let known = capabilities.get(baseUrl);
@@ -51,6 +53,11 @@ const REJECTS_USAGE = /stream_options/i;
  * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
  * caller that passed it to only one of the two got a turn that had already streamed tokens sent
  * again, silently, with the watcher seeing every one of them twice.
+ *
+ * @param supports What this endpoint has already refused. Latched off further as it refuses more.
+ * @param send Builds and sends the request. Called again per downgrade, never once tokens
+ * have arrived.
+ * @param options `produced` for a caller with its own retry budget, `onNotice` for a watcher.
  */
 export async function negotiate(supports, send, { produced = { any: false }, onNotice } = {}) {
     for (;;) {

package/dist/client.d.ts

@@ -6,15 +6,31 @@ import type { Endpoint } from "./config.ts";
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export declare const NO_KEY = "agent-core";
-/** Zero, less, or absent means no limit, which the SDK spells as `undefined`. */
+/**
+ * Zero, less, or absent means no limit, which the SDK spells as `undefined`.
+ *
+ * @param config Read for `requestTimeoutSeconds` alone.
+ */
 export declare const timeoutMs: (config: Pick<Endpoint, "requestTimeoutSeconds">) => number | undefined;
+/**
+ * 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.
+ *
+ * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
+ */
 export declare function getClient(config: Endpoint): OpenAI;
 /** A model an endpoint offers, and what it says the model will read. Zero means it did not say. */
 export interface ModelInfo {
     id: string;
     contextLength: number;
 }
-/** Asks an endpoint what it serves, and remembers the answer. */
+/**
+ * Asks an endpoint what it serves, and remembers the answer.
+ *
+ * @param config The endpoint to ask. Remembered per base URL and key, not per model.
+ */
 export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
 /**
  * How much a model will read, in tokens. Zero means nobody knows.
@@ -28,6 +44,9 @@ export declare function listModels(config: Endpoint): Promise<ModelInfo[]>;
  * model, since a model can arrive after the first listing was taken. A server that will not
  * list models still has to be able to run a turn: a failure here is an unknown window, not a
  * failed run.
+ *
+ * @param config The endpoint, plus the model whose window is wanted.
+ * @param declared The operator's own number. Above zero it wins and the endpoint is not asked.
  */
 export declare function contextLimitFor(config: Endpoint & {
     model: string;

package/dist/client.js

@@ -5,7 +5,11 @@ import OpenAI from "openai";
  * not — a caller must not let a local endpoint silently borrow the key meant for a paid one.
  */
 export const NO_KEY = "agent-core";
-/** Zero, less, or absent means no limit, which the SDK spells as `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;
@@ -24,6 +28,14 @@ export const timeoutMs = (config) => {
  * anything has been produced yet and the SDK does not. See `retry.ts`.
  */
 const clients = new Map();
+/**
+ * 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.
+ *
+ * @param config Where to send requests and how long to wait. An absent `apiKey` becomes `NO_KEY`.
+ */
 export function getClient(config) {
     const apiKey = config.apiKey || NO_KEY;
     const timeout = timeoutMs(config);
@@ -71,7 +83,11 @@ function contextLengthOf(model) {
  */
 const listings = new Map();
 const endpointKey = (config) => JSON.stringify([config.baseUrl, config.apiKey || NO_KEY]);
-/** Asks an endpoint what it serves, and remembers the answer. */
+/**
+ * Asks an endpoint what it serves, and remembers the answer.
+ *
+ * @param config The endpoint to ask. Remembered per base URL and key, not per model.
+ */
 export async function listModels(config) {
     const { data } = await getClient(config).models.list();
     const models = data
@@ -92,6 +108,9 @@ export async function listModels(config) {
  * model, since a model can arrive after the first listing was taken. A server that will not
  * list models still has to be able to run a turn: a failure here is an unknown window, not a
  * failed run.
+ *
+ * @param config The endpoint, plus the model whose window is wanted.
+ * @param declared The operator's own number. Above zero it wins and the endpoint is not asked.
  */
 export async function contextLimitFor(config, declared = 0) {
     if (declared > 0)

package/dist/errors.d.ts

@@ -4,5 +4,7 @@
  * Almost everything caught here ends up in a run row, a tool result or a log line, and a
  * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
  * that had to say what happened.
+ *
+ * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
 export declare const errorMessage: (error: unknown) => string;

package/dist/errors.js

@@ -4,5 +4,7 @@
  * Almost everything caught here ends up in a run row, a tool result or a log line, and a
  * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
  * that had to say what happened.
+ *
+ * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
 export const errorMessage = (error) => error instanceof Error ? error.message : String(error);

package/dist/events.d.ts

@@ -9,6 +9,7 @@
  * 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.
  */
+/** 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. */
 "step"
@@ -40,7 +41,14 @@ export interface RunUsage {
     completionTokens: number;
     totalTokens: number;
 }
+/**
+ * One thing that happened in a run, as a watcher receives it.
+ *
+ * Every field is always present — the empty ones are `""` or `null` rather than missing — so a
+ * client reads it without guarding each key.
+ */
 export interface RunEvent {
+    /** The run it belongs to. `emit` fills this in; a caller does not pass it. */
     runId: string;
     /** Per-run counter, from 1. Lets a client order and de-duplicate what it receives. */
     seq: number;
@@ -81,18 +89,31 @@ export type RunEventInput = Pick<RunEvent, "kind"> & Partial<Omit<RunEvent, "kin
  * 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
  * caller that already knows.
+ *
+ * @param runId The run to forget. An id nothing was emitted under is ignored.
  */
 export declare function endRun(runId: string): void;
-/** Records one event and hands it to everyone watching that run. Never throws at the caller. */
+/**
+ * Records one event and hands it to everyone watching that run. Never throws at the caller.
+ *
+ * @param runId The run this belongs to. Created on first use.
+ * @param input The event. `kind` is required; `runId` and `seq` are not a caller's to set.
+ */
 export declare function emit(runId: string, input: RunEventInput): RunEvent;
 /**
  * Everything that has happened on a run, then everything that happens next, until it ends.
  *
  * The backlog comes first so a watcher that joins halfway through — or after the run finished,
  * 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.
  */
 export declare function watch(runId: string): AsyncGenerator<RunEvent>;
-/** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
+/**
+ * The backlog alone, for a caller that wants a snapshot rather than a subscription.
+ *
+ * @param runId The run to read. An unknown or already-swept run gives an empty array.
+ */
 export declare const history: (runId: string) => RunEvent[];
 /**
  * Test seam: forget every run, so one test's events cannot be read by the next.
@@ -109,5 +130,7 @@ export declare const resetEvents: () => void;
  * reasoning model spends ten thousand deltas on a paragraph, and a paragraph is what it meant.
  * Each block carries the `seq` of its last event, so asking for what came after one block
  * picks up exactly where it left off.
+ *
+ * @param events Events in `seq` order, from `history` or collected from `watch`.
  */
 export declare function fold(events: RunEvent[]): RunEvent[];

package/dist/events.js

@@ -69,11 +69,18 @@ function scheduleSweep() {
  * 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
  * caller that already knows.
+ *
+ * @param runId The run to forget. An id nothing was emitted under is ignored.
  */
 export function endRun(runId) {
     streams.delete(runId);
 }
-/** Records one event and hands it to everyone watching that run. Never throws at the caller. */
+/**
+ * Records one event and hands it to everyone watching that run. Never throws at the caller.
+ *
+ * @param runId The run this belongs to. Created on first use.
+ * @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);
     // One clock read, used for both the event and the sweep's bookkeeping.
@@ -115,6 +122,8 @@ export function emit(runId, input) {
  *
  * The backlog comes first so a watcher that joins halfway through — or after the run finished,
  * 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.
  */
 export async function* watch(runId) {
     const stream = streamFor(runId);
@@ -131,9 +140,15 @@ export async function* watch(runId) {
         // The bus caps its own backlog at `MAX_EVENTS`; without this the watcher downstream of it
         // had no cap at all, so a client too slow to keep up held every delta a run ever emitted.
         // The oldest go, which is what the backlog does, and the gap is reported once below.
-        if (queue.length - head > MAX_EVENTS + TRIM_SLACK) {
-            const cut = queue.length - head - MAX_EVENTS;
-            head += cut;
+        //
+        // Dropped here means released here. Advancing the cursor alone left the dropped events in
+        // the slots behind it, to be freed by the compaction in the drain below — which a consumer
+        // that has stalled does not reach, and a stalled consumer is the whole reason for the cap.
+        // It read as capped and held every event anyway: 16MB where the cap promises a third of one.
+        const cut = queue.length - head - MAX_EVENTS;
+        if (cut > TRIM_SLACK) {
+            queue = queue.slice(head + cut);
+            head = 0;
             dropped += cut;
         }
         wake?.();
@@ -157,11 +172,17 @@ export async function* watch(runId) {
                 if (dropped > 0) {
                     // Said once per gap rather than per event, and before the event that follows it, so a
                     // client reading `seq` sees why the numbers jump instead of assuming it lost its place.
+                    //
+                    // One short of the event it precedes, which is the last seq that went missing. Sharing
+                    // a seq with the event behind it made the notice indistinguishable from a duplicate,
+                    // and de-duplicating on `seq` is the one thing the sequence is documented for — so a
+                    // client doing exactly that dropped either the gap notice or the event it explains.
+                    // Inside the gap there is nothing to collide with: those seqs reach no watcher.
                     const gap = dropped;
                     dropped = 0;
                     yield {
                         runId,
-                        seq: event.seq,
+                        seq: event.seq - 1,
                         at: event.at,
                         kind: "notice",
                         text: `${gap} event(s) dropped: this watcher fell too far behind`,
@@ -193,7 +214,11 @@ export async function* watch(runId) {
         }
     }
 }
-/** The backlog alone, for a caller that wants a snapshot rather than a subscription. */
+/**
+ * The backlog alone, for a caller that wants a snapshot rather than a subscription.
+ *
+ * @param runId The run to read. An unknown or already-swept run gives an empty array.
+ */
 export const history = (runId) => [...(streams.get(runId)?.events ?? [])];
 /**
  * Test seam: forget every run, so one test's events cannot be read by the next.
@@ -215,6 +240,8 @@ export const resetEvents = () => {
  * reasoning model spends ten thousand deltas on a paragraph, and a paragraph is what it meant.
  * Each block carries the `seq` of its last event, so asking for what came after one block
  * picks up exactly where it left off.
+ *
+ * @param events Events in `seq` order, from `history` or collected from `watch`.
  */
 export function fold(events) {
     const blocks = [];

package/dist/retry.d.ts

@@ -18,7 +18,11 @@ export declare class EndpointSilent extends Error {
 export declare class ContextOverflow extends Error {
     readonly name = "ContextOverflow";
 }
-/** 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit. */
+/**
+ * 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit.
+ *
+ * @param tokens The count to render.
+ */
 export declare const compact: (tokens: number) => string;
 /**
  * What this request will cost the window, in tokens, near enough.
@@ -31,8 +35,18 @@ export declare const compact: (tokens: number) => string;
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
  * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
  * estimate that is already characters over four.
+ *
+ * @param body The request as it will be sent, tools included.
  */
 export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
+/**
+ * Whether a refusal means the request was too big, rather than merely refused.
+ *
+ * Rate limits are ruled out first: they borrow the same words and mean the opposite, being worth
+ * another attempt where an overflow never is.
+ *
+ * @param detail The endpoint's own message.
+ */
 export declare const isOverflow: (detail: string) => boolean;
 /**
  * The smallest window worth believing in, and the floor under both of its uses.
@@ -57,8 +71,20 @@ export declare const SMALLEST_LIKELY_WINDOW = 8192;
  * to answer, an endpoint that went quiet. A 400 for a malformed tool schema would fail exactly
  * the same way on every attempt, and the two capability cases below are negotiated rather than
  * retried blindly.
+ *
+ * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export declare function isTransient(error: unknown): boolean;
-/** Exponential, with jitter so several tasks failing at once do not return in lockstep. */
+/**
+ * Exponential, with jitter so several tasks failing at once do not return in lockstep.
+ *
+ * @param attempt Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ */
 export declare const backoffMs: (attempt: number) => number;
+/**
+ * A delay an abort cuts short, rejecting rather than resolving early.
+ *
+ * @param ms How long to wait.
+ * @param signal Abandons the wait. One already aborted rejects without waiting at all.
+ */
 export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;

package/dist/retry.js

@@ -19,7 +19,11 @@ export class EndpointSilent extends Error {
 export class ContextOverflow extends Error {
     name = "ContextOverflow";
 }
-/** 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit. */
+/**
+ * 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit.
+ *
+ * @param tokens The count to render.
+ */
 export const compact = (tokens) => tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
 /** What `{"role":"","content":""},` costs around a message's own text, in characters. */
 const ENVELOPE = 25;
@@ -84,6 +88,8 @@ function toolsCost(tools) {
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
  * which `ENVELOPE` puts back approximately; the difference is a rounding error against an
  * estimate that is already characters over four.
+ *
+ * @param body The request as it will be sent, tools included.
  */
 export const requestTokens = (body) => {
     // Characters first and the division once at the end, rather than a rounded count per message:
@@ -114,6 +120,14 @@ const OVERFLOW = [
  * nothing retries it. The two classifiers in this file disagreed about one error.
  */
 const RATE_LIMITED = /per (min|hour|day)|rate.?limit|\b[tr]pm\b|quota/i;
+/**
+ * Whether a refusal means the request was too big, rather than merely refused.
+ *
+ * Rate limits are ruled out first: they borrow the same words and mean the opposite, being worth
+ * another attempt where an overflow never is.
+ *
+ * @param detail The endpoint's own message.
+ */
 export const isOverflow = (detail) => !RATE_LIMITED.test(detail) &&
     OVERFLOW.some((pattern) => pattern.test(detail)) &&
     /token|context/i.test(detail);
@@ -140,6 +154,8 @@ export const SMALLEST_LIKELY_WINDOW = 8192;
  * to answer, an endpoint that went quiet. A 400 for a malformed tool schema would fail exactly
  * the same way on every attempt, and the two capability cases below are negotiated rather than
  * retried blindly.
+ *
+ * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export function isTransient(error) {
     if (error instanceof EndpointSilent)
@@ -151,8 +167,18 @@ export function isTransient(error) {
     const { status } = error;
     return status === 408 || status === 409 || status === 429 || (status ?? 0) >= 500;
 }
-/** Exponential, with jitter so several tasks failing at once do not return in lockstep. */
+/**
+ * Exponential, with jitter so several tasks failing at once do not return in lockstep.
+ *
+ * @param attempt Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ */
 export const backoffMs = (attempt) => Math.min(8000, 2 ** attempt * 500) * (0.5 + Math.random() / 2);
+/**
+ * A delay an abort cuts short, rejecting rather than resolving early.
+ *
+ * @param ms How long to wait.
+ * @param signal Abandons the wait. One already aborted rejects without waiting at all.
+ */
 export const sleep = (ms, signal) => new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
         signal?.removeEventListener("abort", onAbort);

package/dist/run-turn.d.ts

@@ -46,5 +46,10 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
  * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused, threaded through the negotiation.
+ * @param request Builds the body. Called again per attempt, since a downgrade changes it.
+ * @param options Retry budget, context limit, notices, and the stream's own callbacks.
  */
 export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/run-turn.js

@@ -7,6 +7,11 @@ import { streamTurn } from "./stream.js";
  * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused, threaded through the negotiation.
+ * @param request Builds the body. Called again per attempt, since a downgrade changes it.
+ * @param options Retry budget, context limit, notices, and the stream's own callbacks.
  */
 export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, contextLimit = 0, ...stream } = {}) {
     // Sized once rather than per build. `request` is called again for every downgrade and every

package/dist/schema-compat.d.ts

@@ -1,9 +1,20 @@
 import type OpenAI from "openai";
+/**
+ * Tool definitions a strict server will accept, remembered per definition object.
+ *
+ * The first call on a connection's tools does the work and every later one is a lookup, so
+ * calling this per request costs nothing.
+ *
+ * @param tools The definitions as the pool hands them over. Never mutated — where a schema
+ * changed, a new definition is returned in its place.
+ */
 export declare const sanitizeTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
 /**
  * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
  * `pattern` and most `format` values, both of which only ever narrowed a string the tool
  * re-validates anyway.
+ *
+ * @param tools Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
  */
 export declare const relaxTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
 /**
@@ -13,5 +24,7 @@ export declare const relaxTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.
  * says "Failed to initialize samplers: failed to parse grammar", others surface the converter
  * by name. Since a grammar is only ever involved in constrained decoding, treat any mention of
  * one as ours; the retry is cheap and latches after a single request.
+ *
+ * @param message The server's error text. Matched case-insensitively.
  */
 export declare function isGrammarError(message: string): boolean;

package/dist/schema-compat.js

@@ -162,6 +162,50 @@ function mergeRootAllOf(out) {
     if (required.size)
         out.required = [...required];
 }
+/**
+ * Folds a root `anyOf` or `oneOf` into the root itself.
+ *
+ * The third spelling of "the arguments are this named type", after `$ref` and `allOf`, and the
+ * one still going out empty: a union of real object shapes has no `null` branch for
+ * `collapseNullableUnion` to take apart, so it reached the delete below intact and every
+ * argument went with it. Properties are unioned because a caller satisfies any one branch;
+ * `required` keeps only the names every branch asks for, since one that a branch does without
+ * is one the model has to be free to omit. A branch that is a reference is not something to
+ * guess at — it cannot vouch for a name, so its presence alone empties `required`.
+ */
+function mergeRootUnion(out) {
+    for (const key of ["anyOf", "oneOf"]) {
+        const branches = out[key];
+        if (!Array.isArray(branches))
+            continue;
+        const properties = {};
+        // `null` until a branch has been read, which is what tells "no branches yet" apart from
+        // "the branches agreed on nothing".
+        let shared = null;
+        for (const branch of branches) {
+            const previous = shared;
+            if (!isObject(branch) || "$ref" in branch) {
+                shared = new Set();
+                continue;
+            }
+            if (isObject(branch.properties))
+                Object.assign(properties, branch.properties);
+            const names = Array.isArray(branch.required)
+                ? branch.required.filter((name) => typeof name === "string")
+                : [];
+            shared = previous === null ? new Set(names) : new Set(names.filter((n) => previous.has(n)));
+        }
+        if (!Object.keys(properties).length)
+            continue;
+        out.properties = { ...(isObject(out.properties) ? out.properties : {}), ...properties };
+        if (shared?.size) {
+            const already = Array.isArray(out.required)
+                ? out.required.filter((name) => typeof name === "string")
+                : [];
+            out.required = [...new Set([...already, ...shared])];
+        }
+    }
+}
 /**
  * A required argument that is not in `properties` is one no caller can supply and no strict
  * validator will accept. Anything the rewrites above removed, `required` may still name.
@@ -181,6 +225,7 @@ function sanitizeParameters(parameters) {
         return EMPTY_OBJECT();
     const out = normalize(inlineRootRef(parameters));
     mergeRootAllOf(out);
+    mergeRootUnion(out);
     for (const key of TOP_LEVEL_COMBINATORS)
         delete out[key];
     if (out.type !== "object")
@@ -227,6 +272,15 @@ const through = (cache, tools, fn) => tools.map((tool) => {
     cache.set(tool, built);
     return built;
 });
+/**
+ * Tool definitions a strict server will accept, remembered per definition object.
+ *
+ * The first call on a connection's tools does the work and every later one is a lookup, so
+ * calling this per request costs nothing.
+ *
+ * @param tools The definitions as the pool hands them over. Never mutated — where a schema
+ * changed, a new definition is returned in its place.
+ */
 export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParameters);
 /**
  * Walked as a schema rather than as arbitrary JSON, because `pattern` and `format` are keyword
@@ -262,6 +316,8 @@ const strip = (node) => {
  * The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in
  * `pattern` and most `format` values, both of which only ever narrowed a string the tool
  * re-validates anyway.
+ *
+ * @param tools Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
  */
 export const relaxTools = (tools) => through(relaxed, tools, (parameters) => {
     const stripped = strip(parameters);
@@ -280,6 +336,8 @@ const NO_USER_QUERY = "no user query found";
  * says "Failed to initialize samplers: failed to parse grammar", others surface the converter
  * by name. Since a grammar is only ever involved in constrained decoding, treat any mention of
  * one as ours; the retry is cheap and latches after a single request.
+ *
+ * @param message The server's error text. Matched case-insensitively.
  */
 export function isGrammarError(message) {
     const text = message.toLowerCase();

package/dist/side-task.d.ts

@@ -1,9 +1,13 @@
 import type { Endpoint } from "./config.ts";
-/** Test seam, alongside `resetClients` and `reset`: forget which models refused the hints. */
+/** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
 export declare const resetHints: () => void;
+/** What a side task may be given. All optional — one given none of them still runs. */
 export interface SideTaskOptions {
+    /** Ceiling on the reply, default 512. These answers are meant to be short. */
     maxTokens?: number;
+    /** Sampling temperature, default 0.3. Naming and classifying want the same answer twice. */
     temperature?: number;
+    /** Abandons the call, usually because the run it supports has gone away. */
     signal?: AbortSignal;
     /**
      * Told what was given up on, the same way `runTurn` and `negotiate` tell a caller.
@@ -14,23 +18,45 @@ export interface SideTaskOptions {
      */
     onNotice?: (message: string) => void;
 }
-/** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
+/**
+ * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
+ *
+ * @param config Where to send it and how long to wait.
+ * @param model The model to ask, usually smaller than the one running the work.
+ * @param system The instruction.
+ * @param user The input it applies to.
+ * @param options Reply ceiling, temperature, cancellation, notices.
+ */
 export declare function ask(config: Endpoint, model: string, system: string, user: string, { maxTokens, temperature, signal, onNotice }?: SideTaskOptions): Promise<string>;
 /**
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
+ *
+ * @param label Names the task in the notice when it fails.
+ * @param run The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
+ * @param options `onNotice`, told what was given up on.
  */
 export declare function tryAsk<T>(label: string, run: () => Promise<T>, { onNotice }?: Pick<SideTaskOptions, "onNotice">): Promise<T | undefined>;
 /**
  * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
  * the first array or object rather than failing the task over a wrapper.
+ *
+ * @param text The reply, fences and prose included. Nothing parseable gives `undefined`.
  */
 export declare function parseJson<T>(text: string): T | undefined;
-/** Strips the quoting and list punctuation models decorate short answers with. */
+/**
+ * Strips the quoting and list punctuation models decorate short answers with.
+ *
+ * @param line One line of a reply.
+ */
 export declare const clean: (line: string) => string;
 /**
  * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
  * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
  * squinted at is worse than one fewer suggestion.
+ *
+ * @param text The reply, one item per line.
+ * @param max How many items to keep.
+ * @param maxChars Longest item kept. Longer ones are dropped, not truncated.
  */
 export declare const listLines: (text: string, max: number, maxChars: number) => string[];

package/dist/side-task.js

@@ -33,7 +33,7 @@ const NO_THINKING = {
  */
 const noHints = new Set();
 const hintKey = (baseUrl, model) => JSON.stringify([baseUrl, model]);
-/** Test seam, alongside `resetClients` and `reset`: forget which models refused the hints. */
+/** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
 export const resetHints = () => noHints.clear();
 /**
  * Whether a failure is the server complaining about the request, rather than failing to answer.
@@ -62,7 +62,15 @@ function rejectedTheRequest(error) {
  * arrives — and the whole deliberation was then returned to the caller as the answer.
  */
 const stripThinking = (text) => text.replace(/<think>[\s\S]*?<\/think>/gi, "").replace(/<think>[\s\S]*$/i, "");
-/** Runs a side task and returns the reply text, thinking stripped. Throws like any request. */
+/**
+ * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
+ *
+ * @param config Where to send it and how long to wait.
+ * @param model The model to ask, usually smaller than the one running the work.
+ * @param system The instruction.
+ * @param user The input it applies to.
+ * @param options Reply ceiling, temperature, cancellation, notices.
+ */
 export async function ask(config, model, system, user, { maxTokens = 512, temperature = 0.3, signal, onNotice } = {}) {
     const send = (hints) => getClient(config).chat.completions.create({
         model,
@@ -99,6 +107,10 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
 /**
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
+ *
+ * @param label Names the task in the notice when it fails.
+ * @param run The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
+ * @param options `onNotice`, told what was given up on.
  */
 export async function tryAsk(label, run, { onNotice } = {}) {
     try {
@@ -116,6 +128,8 @@ export async function tryAsk(label, run, { onNotice } = {}) {
 /**
  * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
  * the first array or object rather than failing the task over a wrapper.
+ *
+ * @param text The reply, fences and prose included. Nothing parseable gives `undefined`.
  */
 export function parseJson(text) {
     const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
@@ -133,7 +147,11 @@ export function parseJson(text) {
         return undefined;
     }
 }
-/** Strips the quoting and list punctuation models decorate short answers with. */
+/**
+ * Strips the quoting and list punctuation models decorate short answers with.
+ *
+ * @param line One line of a reply.
+ */
 export const clean = (line) => line
     .trim()
     .replace(/^(?:[-*•]|\d+[.)])\s*/, "")
@@ -143,6 +161,10 @@ export const clean = (line) => line
  * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
  * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
  * squinted at is worse than one fewer suggestion.
+ *
+ * @param text The reply, one item per line.
+ * @param max How many items to keep.
+ * @param maxChars Longest item kept. Longer ones are dropped, not truncated.
  */
 export const listLines = (text, max, maxChars) => text
     .split("\n")

package/dist/stream.d.ts

@@ -33,7 +33,9 @@ export interface Turn {
 export interface Produced {
     any: boolean;
 }
+/** What `streamTurn` takes besides the request body. */
 export interface StreamTurnOptions {
+    /** Cancels the request and the stream being read from it. */
     signal?: AbortSignal;
     /**
      * Silence allowed before the request is given up on. Zero or undefined waits forever, which
@@ -59,5 +61,9 @@ export interface StreamTurnOptions {
  * Two token callbacks rather than an event input, because a turn does not know which step of
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param body The request, which must set `stream: true`.
+ * @param options Cancellation, the idle watchdog, and the token callbacks.
  */
 export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, produced, onThinking, onOutput }?: StreamTurnOptions): Promise<Turn>;

package/dist/stream.js

@@ -10,6 +10,10 @@ import { EndpointSilent } from "./retry.js";
  * Two token callbacks rather than an event input, because a turn does not know which step of
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param body The request, which must set `stream: true`.
+ * @param options Cancellation, the idle watchdog, and the token callbacks.
  */
 export async function streamTurn(client, body, { signal, idleMs, produced, onThinking, onOutput } = {}) {
     // Silence, not duration: the timer is rearmed on every chunk, so a model that is still

package/dist/tokens.d.ts

@@ -12,5 +12,7 @@
  * owns it should not be one that also does something. It was extracted from `side-task` to
  * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
  * sizing its own prompt still do, and a leaf with no imports is the right home for it.
+ *
+ * @param text Prose or serialised JSON — both counted the same way, which is why JSON reads low.
  */
 export declare const estimateTokens: (text: string) => number;

package/dist/tokens.js

@@ -12,5 +12,7 @@
  * owns it should not be one that also does something. It was extracted from `side-task` to
  * break a cycle with `retry`; `side-task` no longer reads it, but `retry` and any consumer
  * sizing its own prompt still do, and a leaf with no imports is the right home for it.
+ *
+ * @param text Prose or serialised JSON — both counted the same way, which is why JSON reads low.
  */
 export const estimateTokens = (text) => Math.ceil(text.length / 4);

package/dist/tool-loading.d.ts

@@ -28,6 +28,9 @@ export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
  * A server with no tools is dropped rather than titled: a pool hands one over whenever a
  * server is connected but has nothing to offer, and a label with nothing under it reads as a
  * listing that got cut off.
+ *
+ * @param catalog The connected servers. Ones with no tools are dropped.
+ * @param loaded Names already loaded, marked in the listing rather than removed from it.
  */
 export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
@@ -37,6 +40,9 @@ export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlyS
  * moment it was loaded, and the model loads again to get it back; hoisting them into a separate
  * "already loaded" section splits a server's tools apart, and the model picks a sibling from
  * the longer list instead.
+ *
+ * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
+ * @param loaded Names already loaded, marked in the listing.
  */
 export declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
@@ -56,7 +62,12 @@ export declare const MAX_PER_LOAD = 12;
  * carry. See `carryOver`.
  */
 export declare const MAX_CARRIED = 16;
-/** The tools to start the next turn with: recently used, newest last, capped. */
+/**
+ * The tools to start the next turn with: recently used, newest last, capped.
+ *
+ * @param previous Last turn's names, oldest first.
+ * @param used What this turn called. Moved to the end, so the oldest unused fall off.
+ */
 export declare const carryOver: (previous: string[], used: Set<string>) => string[];
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
@@ -66,6 +77,9 @@ export declare const carryOver: (previous: string[], used: Set<string>) => strin
  * on the `__` boundary — accepted only when it is unambiguous. Rejecting those outright just
  * buys a wasted round trip while the model guesses the prefix, and pushes it toward
  * shotgunning wildcards.
+ *
+ * @param requested What the model asked for. A trailing `*` expands.
+ * @param catalog The servers to resolve against.
  */
 export declare function expandNames(requested: string[], catalog: CatalogServer[]): {
     matched: string[];
@@ -75,10 +89,25 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
         hits: string[];
     }[];
 };
-/** What `load_tools` reports back: the descriptions, now that they are worth their tokens. */
+/**
+ * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
+ *
+ * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
+ * @param catalog The servers, read for the descriptions now worth their tokens.
+ */
 export declare function loadResult({ matched, unknown, overBroad }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
+/**
+ * Whether the catalogue holds a tool by this name.
+ *
+ * @param catalog The connected servers and the tools each one offers.
+ * @param name An exact name. Nothing is prefixed, trimmed or fuzzily matched.
+ */
 export declare const inCatalog: (catalog: CatalogServer[], name: string) => boolean;
-/** `load_tools` arguments, defensively — a model may send a bare string or a nested object. */
+/**
+ * `load_tools` arguments, defensively — a model may send a bare string or a nested object.
+ *
+ * @param args The tool call's arguments, exactly as the model sent them.
+ */
 export declare function requestedNames(args: Record<string, unknown>): string[];
 /**
  * Tool preselection.
@@ -92,6 +121,19 @@ export declare function requestedNames(args: Record<string, unknown>): string[];
  * broad guess is not, so the same `MAX_PER_LOAD` cap applies here as to a `load_tools` call.
  */
 export declare const PRESELECT_SYSTEM: string;
+/**
+ * The user message for a preselection call: the catalogue, then the request.
+ *
+ * @param catalog The connected servers, rendered as the name-only listing.
+ * @param prompt The request being planned for, truncated at 2000 characters — choosing tools
+ * needs the shape of the ask, not all of it.
+ */
 export declare const preselectInput: (catalog: CatalogServer[], prompt: string) => string;
-/** Resolves a preselection against the catalogue: unknown names dropped, count capped. */
+/**
+ * Resolves a preselection against the catalogue: unknown names dropped, count capped.
+ *
+ * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
+ * that are not strings are dropped.
+ * @param catalog The servers to resolve against.
+ */
 export declare function preselection(names: unknown, catalog: CatalogServer[]): string[];

package/dist/tool-loading.js

@@ -54,6 +54,9 @@ export const LOAD_TOOLS_DEFINITION = deepFreeze({
  * A server with no tools is dropped rather than titled: a pool hands one over whenever a
  * server is connected but has nothing to offer, and a label with nothing under it reads as a
  * listing that got cut off.
+ *
+ * @param catalog The connected servers. Ones with no tools are dropped.
+ * @param loaded Names already loaded, marked in the listing rather than removed from it.
  */
 export function catalogList(catalog, loaded) {
     return catalog
@@ -71,6 +74,9 @@ export function catalogList(catalog, loaded) {
  * moment it was loaded, and the model loads again to get it back; hoisting them into a separate
  * "already loaded" section splits a server's tools apart, and the model picks a sibling from
  * the longer list instead.
+ *
+ * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
+ * @param loaded Names already loaded, marked in the listing.
  */
 export function catalogPrompt(catalog, loaded) {
     const list = catalogList(catalog, loaded);
@@ -107,7 +113,12 @@ export const MAX_PER_LOAD = 12;
  * carry. See `carryOver`.
  */
 export const MAX_CARRIED = 16;
-/** The tools to start the next turn with: recently used, newest last, capped. */
+/**
+ * The tools to start the next turn with: recently used, newest last, capped.
+ *
+ * @param previous Last turn's names, oldest first.
+ * @param used What this turn called. Moved to the end, so the oldest unused fall off.
+ */
 export const carryOver = (previous, used) => [...previous.filter((name) => !used.has(name)), ...used].slice(-MAX_CARRIED);
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
@@ -117,6 +128,9 @@ export const carryOver = (previous, used) => [...previous.filter((name) => !used
  * on the `__` boundary — accepted only when it is unambiguous. Rejecting those outright just
  * buys a wasted round trip while the model guesses the prefix, and pushes it toward
  * shotgunning wildcards.
+ *
+ * @param requested What the model asked for. A trailing `*` expands.
+ * @param catalog The servers to resolve against.
  */
 export function expandNames(requested, catalog) {
     const all = flatten(catalog);
@@ -166,7 +180,12 @@ export function expandNames(requested, catalog) {
     }
     return { matched: [...matched], unknown, overBroad };
 }
-/** What `load_tools` reports back: the descriptions, now that they are worth their tokens. */
+/**
+ * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
+ *
+ * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
+ * @param catalog The servers, read for the descriptions now worth their tokens.
+ */
 export function loadResult({ matched, unknown, overBroad }, catalog) {
     const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
     const lines = [];
@@ -187,8 +206,18 @@ export function loadResult({ matched, unknown, overBroad }, catalog) {
     }
     return lines.join("\n") || "No tool names were given.";
 }
+/**
+ * Whether the catalogue holds a tool by this name.
+ *
+ * @param catalog The connected servers and the tools each one offers.
+ * @param name An exact name. Nothing is prefixed, trimmed or fuzzily matched.
+ */
 export const inCatalog = (catalog, name) => catalog.some((server) => server.tools.some((tool) => tool.name === name));
-/** `load_tools` arguments, defensively — a model may send a bare string or a nested object. */
+/**
+ * `load_tools` arguments, defensively — a model may send a bare string or a nested object.
+ *
+ * @param args The tool call's arguments, exactly as the model sent them.
+ */
 export function requestedNames(args) {
     const value = args.names ?? args.tools ?? args.name;
     if (typeof value === "string")
@@ -212,8 +241,21 @@ export const PRESELECT_SYSTEM = "You choose tools. Below is a catalogue of tool
     "array of the names the request is likely to need — exact names from the catalogue, at most " +
     `${MAX_PER_LOAD}, and as few as could do the job. Reply with \`[]\` if the request can be ` +
     "answered without tools. Reply with the array alone — no prose, no explanation.";
+/**
+ * The user message for a preselection call: the catalogue, then the request.
+ *
+ * @param catalog The connected servers, rendered as the name-only listing.
+ * @param prompt The request being planned for, truncated at 2000 characters — choosing tools
+ * needs the shape of the ask, not all of it.
+ */
 export const preselectInput = (catalog, prompt) => `# Tool catalogue\n\n${catalogList(catalog)}\n\n# Request\n\n${prompt.slice(0, 2000)}`;
-/** Resolves a preselection against the catalogue: unknown names dropped, count capped. */
+/**
+ * Resolves a preselection against the catalogue: unknown names dropped, count capped.
+ *
+ * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
+ * that are not strings are dropped.
+ * @param catalog The servers to resolve against.
+ */
 export function preselection(names, catalog) {
     if (!Array.isArray(names))
         return [];

package/llms.txt

@@ -0,0 +1,141 @@
+# @cubicecho/agent-core
+
+> The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.
+
+What is here is everything that does not know what the agent is *for*: making a tool schema a strict server will accept, getting tool definitions in front of a model without paying for all of them, reading one streamed turn back into a message, answering an endpoint that refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration, prompts, and whatever the run is about — because that is the caller's, and it is the part that differs between one server and the next.
+
+Requires Node >=22, with `openai` >=6 as a peer dependency. ESM only.
+Full prose, worked examples and the reasoning behind each seam are in README.md; this file is the index.
+
+## Exports
+
+### capabilities
+
+What an endpoint turned out not to support, and answering it when it says so.
+
+- `Capabilities` (type) — What one endpoint turned out not to support.
+- `capabilitiesFor` — What this endpoint is known not to support.
+- `NegotiateOptions` (type) — What `negotiate` takes besides the request.
+- `negotiate` — Sends a request, re-sending it each time the answer is this endpoint refusing something the request can do without.
+- `resetCapabilities` — Forgets every endpoint's capabilities.
+
+### catalog
+
+The contract between whatever holds the tools and the loop that offers them to a model.
+
+- `CatalogServer` (type) — One server's tools, without their JSON schemas — the cheap half of a tool definition.
+
+### client
+
+- `contextLimitFor` — How much a model will read, in tokens.
+- `getClient` — The client for an endpoint, built once and kept.
+- `listModels` — Asks an endpoint what it serves, and remembers the answer.
+- `ModelInfo` (type) — A model an endpoint offers, and what it says the model will read.
+- `NO_KEY` — The SDK insists on a non-empty key even where the server will not look at it.
+- `resetClients` — Forgets every cached client and listing.
+- `timeoutMs` — Zero, less, or absent means no limit, which the SDK spells as `undefined`.
+
+### config
+
+What this package needs to know about a caller's configuration.
+
+- `AgentConfig` (type) — A whole agent configuration — every part, plus the two fields that belong to no group.
+- `Endpoint` (type) — Where to send a request and how long to wait.
+- `ModelParams` (type) — What to ask the model for.
+- `RetryPolicy` (type) — How many times a lost or refused request is worth sending again.
+- `ToolPolicy` (type) — How tools reach the model, and how long it may keep calling them.
+
+### errors
+
+- `errorMessage` — What went wrong, as a string.
+
+### events
+
+What a run is doing, while it is doing it.
+
+- `emit` — Records one event and hands it to everyone watching that run.
+- `endRun` — 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.
+- `fold` — Consecutive tokens of one kind are one thing being said, not hundreds of things.
+- `history` — The backlog alone, for a caller that wants a snapshot rather than a subscription.
+- `RunEvent` (type) — One thing that happened in a run, as a watcher receives it.
+- `RunEventInput` (type) — What `emit` is given: the run and the sequence are the bus's to assign.
+- `RunEventKind` (type) — Which kind of thing happened, and what `text`, `name`, `ok` and `usage` carry for it.
+- `RunUsage` (type) — What a run has spent, counted from the start of the run rather than for the turn that carried it: a client draws the latest one it has seen and needs no arithmetic of its own, and one lost to the backlog cap costs nothing because the next supersedes it.
+- `resetEvents` — Test seam: forget every run, so one test's events cannot be read by the next.
+- `watch` — Everything that has happened on a run, then everything that happens next, until it ends.
+
+### reset
+
+- `resetAll` — Forgets everything this package remembers between calls.
+
+### retry
+
+Everything about a request failing that is not about what the request said.
+
+- `backoffMs` — Exponential, with jitter so several tasks failing at once do not return in lockstep.
+- `ContextOverflow` — The request was bigger than the model will read.
+- `compact` — 1234 → "1.2k".
+- `EndpointSilent` — The endpoint stopped answering mid-request.
+- `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
+- `isTransient` — Whether a failed request is worth trying again.
+- `requestTokens` — What this request will cost the window, in tokens, near enough.
+- `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under both of its uses.
+- `sleep` — A delay an abort cuts short, rejecting rather than resolving early.
+
+### run-turn
+
+One turn, given as many attempts as the caller allows.
+
+- `RunTurnOptions` (type) — A retry is not the same event as a downgrade, but a watcher wants to be told about both.
+- `runTurn` — `request` is a callback rather than a body because the body has to be rebuilt from whatever the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools` has to apply to the schemas that were just sanitised.
+
+### schema-compat
+
+JSON Schema compatibility for llama.cpp-backed servers.
+
+- `isGrammarError` — Does this failure look like the server could not build a grammar from our tool schemas?
+- `relaxTools` — The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in `pattern` and most `format` values, both of which only ever narrowed a string the tool re-validates anyway.
+- `sanitizeTools` — Tool definitions a strict server will accept, remembered per definition object.
+
+### side-task
+
+One-shot calls that support a run without being one: picking tools, naming a session, summarising a transcript, proposing follow-ups.
+
+- `ask` — Runs a side task and returns the reply text, thinking stripped.
+- `clean` — Strips the quoting and list punctuation models decorate short answers with.
+- `listLines` — A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate them with.
+- `parseJson` — Models are asked for JSON and often answer with prose around it, or a fenced block.
+- `resetHints` — Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints.
+- `SideTaskOptions` (type) — What a side task may be given.
+- `tryAsk` — A side task is never worth failing the work it supports.
+
+### stream
+
+Reading one streamed turn back into a message.
+
+- `Produced` (type) — Whether the server has started answering.
+- `StreamTurnOptions` (type) — What `streamTurn` takes besides the request body.
+- `streamTurn` — Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a message.
+- `Turn` (type) — One streamed turn, put back together into the shape a loop and a transcript work with.
+- `TurnUsage` (type) — What a turn cost.
+
+### tokens
+
+- `estimateTokens` — Rough token count.
+
+### tool-loading
+
+- `carryOver` — The tools to start the next turn with: recently used, newest last, capped.
+- `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked.
+- `catalogPrompt` — The catalogue block appended to the system prompt.
+- `expandNames` — Resolves requested names against the catalogue, expanding trailing `*` wildcards.
+- `inCatalog` — Whether the catalogue holds a tool by this name.
+- `LOAD_TOOLS` — On-demand tool loading.
+- `LOAD_TOOLS_DEFINITION` — One object for the life of the process — the agent loop asks for it on every iteration.
+- `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
+- `MAX_CARRIED` — The most a conversation carries between turns.
+- `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.
+- `PRESELECT_SYSTEM` — Tool preselection.
+- `preselectInput` — The user message for a preselection call: the catalogue, then the request.
+- `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.
+- `requestedNames` — `load_tools` arguments, defensively — a model may send a bare string or a nested object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",
@@ -34,17 +34,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/llms-txt.mjs",
     "prepare": "npm run build",
     "typecheck": "tsc -p tsconfig.tests.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "llms": "node scripts/llms-txt.mjs",
+    "llms:check": "node scripts/llms-txt.mjs --check",
     "lint": "biome check .",
     "format": "biome check --write .",
     "bench": "vitest bench --run",
@@ -54,7 +57,7 @@
     "openai": ">=6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.11",
+    "@biomejs/biome": "2.5.12",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
     "@types/node": "^26.4.0",