@cubicecho/agent-core 2.22.0 → 2.24.0

package/dist/guards.js

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

package/dist/hook-events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The points in a session a hook can be bound to, apart from everything that runs one.
+ *
+ * A leaf with no imports, because two modules need these lists and only one of them may load
+ * `node:crypto`: `hooks.ts` hashes a turn into the uuid a memory server dedups on, and `spec.ts`
+ * has to stay importable in a browser. Before this each kept its own copy, with a test holding
+ * one pair together and nothing holding the other.
+ */
+/**
+ * A point in a session a hook can be bound to. Named after Claude Code's hooks of the same shape
+ * — `sessionStart` (SessionStart), `beforeTurn` (UserPromptSubmit), `afterTurn` (Stop),
+ * `beforeCompact` (PreCompact), `sessionEnd` (SessionEnd) — plus `sessionDelete`, for when the host
+ * deletes a session's record.
+ */
+export type HookEvent = "sessionStart" | "beforeTurn" | "afterTurn" | "beforeCompact" | "sessionEnd" | "sessionDelete";
+/** Every event a hook can be bound to, in the order a session meets them. */
+export declare const HOOK_EVENTS: readonly HookEvent[];
+/**
+ * The events whose hooks run before a request, and so the only ones whose output can reach it.
+ * Anything later runs once the model has already answered.
+ */
+export declare const INJECT_EVENTS: ReadonlySet<HookEvent>;

package/dist/hook-events.js

@@ -0,0 +1,22 @@
+/**
+ * The points in a session a hook can be bound to, apart from everything that runs one.
+ *
+ * A leaf with no imports, because two modules need these lists and only one of them may load
+ * `node:crypto`: `hooks.ts` hashes a turn into the uuid a memory server dedups on, and `spec.ts`
+ * has to stay importable in a browser. Before this each kept its own copy, with a test holding
+ * one pair together and nothing holding the other.
+ */
+/** Every event a hook can be bound to, in the order a session meets them. */
+export const HOOK_EVENTS = [
+    "sessionStart",
+    "beforeTurn",
+    "afterTurn",
+    "beforeCompact",
+    "sessionEnd",
+    "sessionDelete",
+];
+/**
+ * The events whose hooks run before a request, and so the only ones whose output can reach it.
+ * Anything later runs once the model has already answered.
+ */
+export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);

package/dist/hooks.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type HookEvent } from "./hook-events.ts";
 /**
  * Lifecycle hooks, from the host's side: what a session looks like to them, where their context
  * lands in a request, and what is said about each one.
@@ -9,20 +10,6 @@ import type OpenAI from "openai";
  * `runHooks` is a runner as it stands and its outcomes pass straight through, without this
  * package depending on it.
  */
-/**
- * A point in a session a hook can be bound to. Named after Claude Code's hooks of the same shape
- * — `sessionStart` (SessionStart), `beforeTurn` (UserPromptSubmit), `afterTurn` (Stop),
- * `beforeCompact` (PreCompact), `sessionEnd` (SessionEnd) — plus `sessionDelete`, for when the host
- * deletes a session's record.
- */
-export type HookEvent = "sessionStart" | "beforeTurn" | "afterTurn" | "beforeCompact" | "sessionEnd" | "sessionDelete";
-/** Every event a hook can be bound to, in the order a session meets them. */
-export declare const HOOK_EVENTS: readonly HookEvent[];
-/**
- * The events whose hooks run before a request, and so the only ones whose output can reach it.
- * Anything later runs once the model has already answered.
- */
-export declare const INJECT_EVENTS: ReadonlySet<HookEvent>;
 /**
  * One message of a session as a hook is handed it. The shape a memory server's `remember` takes,
  * so a template can pass a turn straight through.
@@ -160,8 +147,8 @@ export interface HookOptions {
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
  * were chosen for, or whose host wants its own name above the context.
  *
- * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
- * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * One setting per runtime for the same reason `configureEvents` is: a budget and a preface are a
+ * deployment's settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
  * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
  * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
@@ -248,6 +235,18 @@ export declare const UNTRUSTED_PREFACE: string;
 export declare function untrusted(text: string, { source }?: {
     source?: string;
 }): string;
+/**
+ * A message's text, whether its content is a string or a list of parts.
+ *
+ * Parts are joined with nothing between them, because they are one text an API split rather than
+ * several: a space put in is a character the sender never wrote, and `turnMessages` hashes this
+ * into the uuid a memory server dedups on. Compaction reads the same function, so the summariser
+ * and the hook told about a fold see one message the same way. A refusal part is left out.
+ *
+ * @param content A message's `content`, in any of the shapes the API allows. One that is neither
+ * a string nor a list reads as empty.
+ */
+export declare const textOf: (content: unknown) => string;
 /**
  * A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing
  * else.

package/dist/hooks.js

@@ -1,20 +1,9 @@
 import { createHash } from "node:crypto";
 import { errorMessage } from "./errors.js";
-import { estimateTokens } from "./tokens.js";
-/** Every event a hook can be bound to, in the order a session meets them. */
-export const HOOK_EVENTS = [
-    "sessionStart",
-    "beforeTurn",
-    "afterTurn",
-    "beforeCompact",
-    "sessionEnd",
-    "sessionDelete",
-];
-/**
- * The events whose hooks run before a request, and so the only ones whose output can reach it.
- * Anything later runs once the model has already answered.
- */
-export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
+import { isPositive } from "./guards.js";
+import { INJECT_EVENTS } from "./hook-events.js";
+import { scoped } from "./scope.js";
+import { CHARS_PER_TOKEN, estimateTokens } from "./tokens.js";
 /**
  * The most context all of a request's hooks add between them by default, in estimated tokens.
  *
@@ -36,13 +25,13 @@ const HOOK_DEFAULTS = {
     preface: HOOK_PREFACE,
 };
 /** What is in force now. Read where it is used, so a change applies from the next request. */
-let hookSettings = { ...HOOK_DEFAULTS };
+const hookSettings = scoped(() => ({ ...HOOK_DEFAULTS }));
 /**
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
  * were chosen for, or whose host wants its own name above the context.
  *
- * Module-level for the same reason `configureEvents` is: a budget and a preface are a deployment's
- * settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * One setting per runtime for the same reason `configureEvents` is: a budget and a preface are a
+ * deployment's settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
  * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
  * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  *
@@ -54,12 +43,11 @@ let hookSettings = { ...HOOK_DEFAULTS };
  */
 export function configureHooks(options = {}) {
     const { contextTokens, preface } = options;
-    if (typeof contextTokens === "number" && contextTokens > 0) {
-        hookSettings.contextTokens = contextTokens;
-    }
+    if (isPositive(contextTokens))
+        hookSettings().contextTokens = contextTokens;
     if (typeof preface === "string")
-        hookSettings.preface = preface;
-    return { ...hookSettings };
+        hookSettings().preface = preface;
+    return { ...hookSettings() };
 }
 /**
  * Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the
@@ -67,15 +55,26 @@ export function configureHooks(options = {}) {
  * `resetAll` calls it.
  */
 export const resetHooks = () => {
-    hookSettings = { ...HOOK_DEFAULTS };
+    hookSettings.reset();
 };
 /**
  * The budget a call is held to: its own when it gave a usable one, the process's otherwise. The
  * same rule `configureHooks` applies, so a `0` threaded through for "no opinion" does not quietly
  * turn every hook's context off.
  */
-const budget = (given) => typeof given === "number" && given > 0 ? given : hookSettings.contextTokens;
+const budget = (given) => (isPositive(given) ? given : hookSettings().contextTokens);
 const attribute = (text) => text.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+/** What every note about an outcome opens with: which hook it was, and on which event. */
+const noteOf = (outcome) => ({
+    event: outcome.event,
+    source: outcome.label,
+    hookId: outcome.hookId,
+});
+/** The note a failed outcome leaves, the same whichever of the three callers reports it. */
+const failureNote = (outcome) => ({
+    ...noteOf(outcome),
+    error: outcome.error ?? "failed",
+});
 /**
  * Builds the context a set of outcomes adds and the notes that go with it.
  *
@@ -99,9 +98,8 @@ export function assembleContext(outcomes, maxTokens) {
     const notes = [];
     let remaining = budget(maxTokens);
     for (const outcome of outcomes) {
-        const base = { event: outcome.event, source: outcome.label, hookId: outcome.hookId };
         if (!outcome.ok) {
-            notes.push({ ...base, error: outcome.error ?? "failed" });
+            notes.push(failureNote(outcome));
             continue;
         }
         if (!outcome.inject || !INJECT_EVENTS.has(outcome.event))
@@ -113,11 +111,11 @@ export function assembleContext(outcomes, maxTokens) {
         if (cap <= 0)
             continue;
         if (estimateTokens(text) > cap)
-            text = `${text.slice(0, cap * 4 - 1).trimEnd()}…`;
+            text = `${text.slice(0, cap * CHARS_PER_TOKEN - 1).trimEnd()}…`;
         const tokens = estimateTokens(text);
         remaining -= tokens;
         blocks.push(`<context source="${attribute(outcome.label)}">\n${text}\n</context>`);
-        notes.push({ ...base, tokens, text });
+        notes.push({ ...noteOf(outcome), tokens, text });
     }
     return { context: blocks.join("\n\n"), notes };
 }
@@ -143,7 +141,7 @@ export function assembleContext(outcomes, maxTokens) {
  * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
  * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
  */
-export function withContext(history, index, context, preface = hookSettings.preface) {
+export function withContext(history, index, context, preface = hookSettings().preface) {
     const message = history[index];
     if (!context || message?.role !== "user")
         return history;
@@ -186,8 +184,18 @@ export function untrusted(text, { source } = {}) {
     const attrs = source === undefined ? "" : ` source="${attribute(source)}"`;
     return `<untrusted${attrs}>\n${text.replace(UNTRUSTED_TAG, "&lt;$1")}\n</untrusted>`;
 }
-/** A message's text, whether its content is a string or a list of parts. */
-const textOf = (content) => {
+/**
+ * A message's text, whether its content is a string or a list of parts.
+ *
+ * Parts are joined with nothing between them, because they are one text an API split rather than
+ * several: a space put in is a character the sender never wrote, and `turnMessages` hashes this
+ * into the uuid a memory server dedups on. Compaction reads the same function, so the summariser
+ * and the hook told about a fold see one message the same way. A refusal part is left out.
+ *
+ * @param content A message's `content`, in any of the shapes the API allows. One that is neither
+ * a string nor a list reads as empty.
+ */
+export const textOf = (content) => {
     if (typeof content === "string")
         return content;
     if (!Array.isArray(content))
@@ -317,9 +325,7 @@ export async function gather(run, events, context, { signal, onNote, maxTokens,
  */
 export async function notify(run, event, context, onNote) {
     const outcomes = await runSafely(run, event, context);
-    const notes = outcomes
-        .filter((outcome) => !outcome.ok)
-        .map((outcome) => assembleContext([outcome]).notes[0]);
+    const notes = outcomes.filter((outcome) => !outcome.ok).map(failureNote);
     for (const note of notes)
         onNote?.(note);
     return notes;
@@ -344,15 +350,9 @@ export async function consult(run, event, context, onNote) {
     const notes = [];
     for (const outcome of outcomes) {
         if (!outcome.ok)
-            notes.push(assembleContext([outcome]).notes[0]);
-        else if (outcome.veto === true) {
-            notes.push({
-                event: outcome.event,
-                source: outcome.label,
-                hookId: outcome.hookId,
-                veto: true,
-            });
-        }
+            notes.push(failureNote(outcome));
+        else if (outcome.veto === true)
+            notes.push({ ...noteOf(outcome), veto: true });
     }
     for (const note of notes)
         onNote?.(note);

package/dist/index.d.ts

@@ -19,17 +19,19 @@ export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } fro
 export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
-export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
+export { HOOK_EVENTS, type HookEvent, INJECT_EVENTS } from "./hook-events.ts";
+export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, type HookContext, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { estimateFrom, type LedgerEntry, type LedgerEstimateOptions, type LedgerRequest, rebaseLedger, recordRequest, type TokenLedger, tokensBetween, } from "./ledger.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, CHARS_PER_TOKEN, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
+export { backoffMs, type ContextBreakdown, type ContextBreakdownOptions, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
-export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
+export { createRuntime, defaultRuntime, type Runtime, type RuntimeOptions } from "./runtime.ts";
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, type AgentHook, type AgentSpec, type EndpointSpec, type ExportSpecOptions, exportSpec, type ModelSpec, type ParsedSpec, type ParseSpecOptions, type PromptPart, parseSpec, RESOLVED_DEFAULTS, type ResolvedAgent, type ResolvedTask, type RetrySpec, resolveAgentSpec, SPEC_EVENTS, type SpecBundle, type SpecServer, type TaskSpec, type ToolsSpec, } from "./spec.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
-export { estimateTokens } from "./tokens.ts";
+export { CHARS_PER_TOKEN, estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, type KeywordPreselection, type KeywordPreselectOptions, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, type ToolMatch, type ToolOrder, } from "./tool-loading.ts";

package/dist/index.js

@@ -17,17 +17,19 @@ export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompact
 export { continueTurn, isContinuable, } from "./continuation.js";
 export { AgentLoopError, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
-export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
+export { HOOK_EVENTS, INJECT_EVENTS } from "./hook-events.js";
+export { assembleContext, configureHooks, consult, gather, HOOK_CONTEXT_TOKENS, HOOK_PREFACE, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.js";
 export { estimateFrom, rebaseLedger, recordRequest, tokensBetween, } from "./ledger.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
+export { backoffMs, ContextOverflow, compact, contextChars, contextTokens, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, toolsChars, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
-export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
+export { createRuntime, defaultRuntime } from "./runtime.js";
+export { isGrammarError, relaxSchema, relaxTools, sanitizeSchema, sanitizeTools, } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
 export { AGENT_SPEC, AGENT_SPEC_VERSION, AGENT_TASKS, exportSpec, parseSpec, RESOLVED_DEFAULTS, resolveAgentSpec, SPEC_EVENTS, } from "./spec.js";
 export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
-export { estimateTokens } from "./tokens.js";
+export { CHARS_PER_TOKEN, estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
 export { CALL_TOOL, carryOver, catalogList, catalogPrompt, expandNames, holdsDefinitions, inCatalog, KEYWORD_DROPOFF, KEYWORD_MIN_SCORE, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, PROXY_TOOLS, preselectByKeywords, preselectInput, preselection, preselectSystem, proxiedCall, proxyCatalogPrompt, proxyLoadResult, requestedNames, shownCall, } from "./tool-loading.js";

package/dist/reset.d.ts

@@ -1,8 +1,9 @@
 /**
  * Forgets everything this package remembers between calls.
  *
- * Six modules here keep state for the life of the process, each for a good reason and each
- * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * Six modules here keep state for the life of the runtime — the process's, unless this is called
+ * as a method of one `createRuntime` made, which clears that one alone — each for a good reason
+ * and each with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, each model's measured characters per token,
  * the models that refused the no-thinking hints, the event bus, and the hooks' configured
  * budget and preface. `resetClients`, `resetCapabilities`, `resetCalibration`, `resetHints`,
@@ -18,5 +19,8 @@
  *
  * It is also the seam that does not need finding again. A seventh module with a cache is a seventh
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ *
+ * A test that builds a `createRuntime` per case has nothing to tear down, and is the better
+ * answer where cases run in parallel: this clears state every concurrent caller is sharing.
  */
 export declare function resetAll(): void;

package/dist/reset.js

@@ -7,8 +7,9 @@ import { resetHints } from "./side-task.js";
 /**
  * Forgets everything this package remembers between calls.
  *
- * Six modules here keep state for the life of the process, each for a good reason and each
- * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * Six modules here keep state for the life of the runtime — the process's, unless this is called
+ * as a method of one `createRuntime` made, which clears that one alone — each for a good reason
+ * and each with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, each model's measured characters per token,
  * the models that refused the no-thinking hints, the event bus, and the hooks' configured
  * budget and preface. `resetClients`, `resetCapabilities`, `resetCalibration`, `resetHints`,
@@ -24,6 +25,9 @@ import { resetHints } from "./side-task.js";
  *
  * It is also the seam that does not need finding again. A seventh module with a cache is a seventh
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ *
+ * A test that builds a `createRuntime` per case has nothing to tear down, and is the better
+ * answer where cases run in parallel: this clears state every concurrent caller is sharing.
  */
 export function resetAll() {
     resetClients();

package/dist/retry.d.ts

@@ -29,13 +29,6 @@ export declare class ContextOverflow extends Error {
  * @param tokens The count to render.
  */
 export declare const compact: (tokens: number) => string;
-/**
- * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
- *
- * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
- * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
- */
-export declare const CHARS_PER_TOKEN = 4;
 /** What the two token estimates below take besides what they measure. */
 export interface TokenEstimateOptions {
     /**
@@ -192,6 +185,19 @@ export declare const SMALLEST_LIKELY_WINDOW = 8192;
  * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export declare function isTransient(error: unknown): boolean;
+/**
+ * Whether a failure is the endpoint refusing the request as written, rather than losing it.
+ *
+ * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
+ * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
+ * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
+ * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
+ * Catching everything is wider still, since an abort or a connection that never landed then
+ * latches off whatever the re-send left out.
+ *
+ * @param error The rejection, as caught. What is not an SDK error refuses nothing.
+ */
+export declare const refusesRequest: (error: unknown) => boolean;
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *

package/dist/retry.js

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import { CHARS_PER_TOKEN } from "./tokens.js";
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -62,13 +63,6 @@ const REFUSAL_PART = 32;
 const REASONING_KEY = 23;
 /** The same for `"reasoning":"",`, OpenRouter's spelling of it. */
 const REASONING_ALT_KEY = 15;
-/**
- * The divisor behind `estimateTokens`, applied here to a character count rather than a string.
- *
- * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
- * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
- */
-export const CHARS_PER_TOKEN = 4;
 /** The divisor an option asked for, or the fallback when it asked for nothing usable. */
 const divisor = (charsPerToken) => charsPerToken !== undefined && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
 /**
@@ -349,6 +343,19 @@ export function isTransient(error) {
     const { status } = error;
     return status === 408 || status === 409 || status === 429 || (status ?? 0) >= 500;
 }
+/**
+ * Whether a failure is the endpoint refusing the request as written, rather than losing it.
+ *
+ * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
+ * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
+ * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
+ * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
+ * Catching everything is wider still, since an abort or a connection that never landed then
+ * latches off whatever the re-send left out.
+ *
+ * @param error The rejection, as caught. What is not an SDK error refuses nothing.
+ */
+export const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *

package/dist/run-turn.d.ts

@@ -77,6 +77,13 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      */
     loadingTimeoutMs?: number;
 }
+/**
+ * Builds a turn's request body from what the endpoint and the model have refused so far.
+ *
+ * A function rather than a body because a downgrade changes what is sent, so it is called again
+ * per attempt. Its second argument is absent where no model was named.
+ */
+export type RequestBuilder = (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming;
 /**
  * `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`
@@ -90,4 +97,4 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
  * @param options Retry budget, context limit, the model to negotiate for, notices, and the
  * stream's own callbacks.
  */
-export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, model, droppable, loadingTimeoutMs, ...stream }?: RunTurnOptions): Promise<Turn>;
+export declare function runTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, { maxRetries, onNotice, contextLimit, model, droppable, loadingTimeoutMs, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/runtime.d.ts

@@ -0,0 +1,120 @@
+import { preselect, runAgentLoop } from "./agent-loop.ts";
+import { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
+import { capabilitiesFor, expireCapabilities, resetCapabilities } from "./capabilities.ts";
+import { type ClientPoolOptions, configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow } from "./client.ts";
+import { compactTranscript, runCompaction, summariser } from "./compaction.ts";
+import { continueTurn } from "./continuation.ts";
+import { configureEvents, type EventBusOptions, emit, endRun, history, resetEvents, watch } from "./events.ts";
+import { assembleContext, configureHooks, consult, gather, type HookOptions, notify, resetHooks, withContext } from "./hooks.ts";
+import { resetAll } from "./reset.ts";
+import { runTurn } from "./run-turn.ts";
+import { ask, askJson, resetHints, tryAsk } from "./side-task.ts";
+import { exportCapabilities, importCapabilities } from "./snapshot.ts";
+/**
+ * Every exported function that reads or writes what a runtime remembers, itself or through what
+ * it calls. The rest of the package is pure, and is the same function whichever runtime it is
+ * called beside.
+ */
+declare const STATEFUL: {
+    runAgentLoop: typeof runAgentLoop;
+    preselect: typeof preselect;
+    runTurn: typeof runTurn;
+    continueTurn: typeof continueTurn;
+    ask: typeof ask;
+    askJson: typeof askJson;
+    tryAsk: typeof tryAsk;
+    summariser: typeof summariser;
+    runCompaction: typeof runCompaction;
+    compactTranscript: typeof compactTranscript;
+    getClient: typeof getClient;
+    listModels: typeof listModels;
+    contextLimitFor: typeof contextLimitFor;
+    servedWindow: typeof servedWindow;
+    configureClients: typeof configureClients;
+    capabilitiesFor: typeof capabilitiesFor;
+    expireCapabilities: typeof expireCapabilities;
+    exportCapabilities: typeof exportCapabilities;
+    importCapabilities: typeof importCapabilities;
+    calibrate: typeof calibrate;
+    charsPerTokenFor: typeof charsPerTokenFor;
+    emit: typeof emit;
+    endRun: typeof endRun;
+    history: typeof history;
+    watch: typeof watch;
+    configureEvents: typeof configureEvents;
+    configureHooks: typeof configureHooks;
+    gather: typeof gather;
+    notify: typeof notify;
+    consult: typeof consult;
+    assembleContext: typeof assembleContext;
+    withContext: typeof withContext;
+    resetClients: typeof resetClients;
+    resetCapabilities: typeof resetCapabilities;
+    resetCalibration: typeof resetCalibration;
+    resetHints: typeof resetHints;
+    resetEvents: typeof resetEvents;
+    resetHooks: typeof resetHooks;
+    resetAll: typeof resetAll;
+};
+/** What a runtime starts out configured with. Every field optional; see `createRuntime`. */
+export interface RuntimeOptions {
+    /** The client pool's bounds, as `configureClients` takes them. */
+    clients?: ClientPoolOptions;
+    /** The event bus's bounds, as `configureEvents` takes them. */
+    events?: EventBusOptions;
+    /** The hooks' budget and preface, as `configureHooks` takes them. */
+    hooks?: HookOptions;
+}
+/**
+ * One set of the package's caches, with the functions that use them as methods.
+ *
+ * Each method is the top-level function of the same name, with the same signature and doc
+ * comment, run against this runtime's state instead of the process's: its pooled clients and
+ * model listings, latched capabilities, measured characters per token, no-thinking hints, event
+ * bus, and hook settings. `resetAll` and the six narrower resets clear this runtime alone.
+ */
+export type Runtime = typeof STATEFUL & {
+    /**
+     * Runs `fn` with this runtime current, so every top-level function it calls — directly, after
+     * an `await`, or from a timer it sets — uses this runtime's state. What the methods do, for
+     * code that calls the top-level functions itself.
+     *
+     * It does not reach a callback that outlives `fn` and is called from elsewhere — a generator
+     * resumed later, a function handed back and called by someone else. Call a method there.
+     *
+     * @param fn What to run. Its return value, or what it throws, is handed straight back.
+     */
+    run<T>(fn: () => T): T;
+};
+/**
+ * A runtime of its own: separate clients, listings, capability latches, hints, event bus and hook
+ * settings from the process's and from every other runtime's.
+ *
+ * For a host that must not share them — one that mints a key per tenant, where a shared pool has
+ * tenants evicting each other's clients and a shared bus has one tenant's run id readable by
+ * another — and for tests, where a runtime per case needs no `resetAll` between them and can run
+ * in parallel. A host with one deployment's worth of endpoints does not need one: the top-level
+ * functions are the default runtime's methods.
+ *
+ * The runtime is carried by async context rather than by argument, so `runAgentLoop` called as a
+ * method uses this runtime all the way down, and so does a top-level function the host calls from
+ * inside it — from `dispatch`, a hook, `onEvent`. Outside a method or `run`, a top-level function
+ * is the default runtime's again; a request handler that emits to a run a runtime started calls
+ * `runtime.emit`.
+ *
+ * Nothing needs closing. A runtime is garbage once nothing holds it; its one timer, the event
+ * bus's sweep, is unreferenced and stops rescheduling when its last run has been swept.
+ *
+ * @param options What to configure it with before first use. A part left out keeps the
+ * defaults — not the default runtime's settings, which a new runtime does not inherit.
+ */
+export declare function createRuntime(options?: RuntimeOptions): Runtime;
+/**
+ * The runtime the top-level functions use when no other is running.
+ *
+ * `defaultRuntime.getClient(endpoint)` and `getClient(endpoint)` are the same call outside any
+ * runtime. Inside one they differ: the top-level function follows the runtime that is running,
+ * and this always reaches the process-wide state.
+ */
+export declare const defaultRuntime: Runtime;
+export {};