@cubicecho/agent-core 2.24.0 → 2.25.1

package/README.md

@@ -23,28 +23,31 @@ only, Node >=22.
 | Module | What it does |
 | --- | --- |
 | `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`, and `sanitizeSchema` and `relaxSchema` for a schema that is not a tool's. |
-| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus `preselectByKeywords`, which picks from it without a model, and the proxied form of the same thing — `PROXY_TOOLS`, `proxyLoadResult`, `proxiedCall` — for a server whose prompt cache a growing tool array throws away. |
+| `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. Plus the proxied form of the same thing — `PROXY_TOOLS`, `proxyLoadResult`, `proxiedCall` — for a server whose prompt cache a growing tool array throws away. |
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, fenced reasoning taken out of the answer, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
 | `thinking` | Tells a scratchpad fenced inside `content` from the answer: `FenceSplitter` for a stream, `stripThinking` for a whole reply, and the fence tables both read. |
-| `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. `askJson` holds the answer to a schema where the server can. |
+| `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. `askJson` holds the answer to a schema where the server can, and `taskCall` turns the settings an agent spec gives a task into the call that honours them. |
 | `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, `untrusted` to fence text nobody vouched for, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`, and `runMetrics` for what a run cost. A watcher's backlog is capped and reports its own gaps. |
-| `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. |
-| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`, `contextTokens`. |
+| `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. And `resolveApiKey`, for a caller deciding which key an endpoint gets. |
+| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`. |
 | `calibration` | How many characters a token is worth on one model, learned from the prompt counts its endpoint reports: `charsPerTokenFor`, `calibrate`. |
 | `continuation` | `continueTurn`: carries on an answer the token ceiling cut off, by prefilling it as a trailing assistant message. |
 | `config` | The structural interfaces every function here asks for. |
 | `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. Sizes the request against an opt-in `contextLimit`. |
-| `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. Plus the parts it is made of: `buildBody`, `preselect`, `preview`, `resolveApiKey` for a caller deciding which key an endpoint gets, and `taskCall` for running a side task on the settings an agent spec gives it. |
-| `tool-calls` | Reading what a model meant by a tool call it did not write cleanly: `parseToolArguments` repairs almost-JSON arguments and says when they were cut off, `recoverToolCalls` finds calls written into the reply as text. |
+| `agent-loop` | `runAgentLoop`: the loop above a turn — `runTurn` per step, the tools between, `load_tools` and preselection handled, until the model stops asking. |
+| `request-body` | `buildBody`: the one place a streamed request's body is decided from a config and what the endpoint and the model have refused. |
+| `run-calls` | The tools between two turns: a step's calls read, run and written into the transcript, with every call answered whatever happens. `preview` cuts a long argument or result for a watcher. |
+| `preselect` | Choosing a run's tools before it starts: `preselect` asks a small model, `preselectByKeywords` scores the request's own words against the tool names without one, and `preselectSystem`, `preselectInput` and `preselection` are the prompt and the reading of the reply for a host that makes the call itself. |
+| `tool-calls` | Reading what a model meant by a tool call it did not write cleanly: `parseToolArguments` repairs almost-JSON arguments and says when they were cut off, `recoverToolCalls` finds calls written into the reply as text. Plus the shapes a call is handed round in: `ToolCallRequest`, `ToolCallResult`, `ToolCallOutcome`. |
 | `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
 | `ledger` | What stretches of a transcript cost, read off the prompt counts the server reported rather than estimated: `recordRequest`, `tokensBetween`, `estimateFrom`, `rebaseLedger`. |
 | `snapshot` | `exportCapabilities` and `importCapabilities`: the latched refusals as a JSON blob a consumer stores, so a restart need not learn them again. |
 | `spec` | `parseSpec`, `resolveAgentSpec` and `exportSpec`: an agent as a versioned JSON document, layered into the flat config the loop takes. Imports nothing but types, and is published separately at `@cubicecho/agent-core/spec`. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
 | `runtime` | `createRuntime`: a second set of those caches, with the functions that use them as methods — for a host whose tenants must not share a client pool, a latch or an event bus. `defaultRuntime` is the one the top-level functions use. |
-| `tokens` | `estimateTokens`: characters over four, deliberately low, for everything here that has to guess at a window. |
+| `tokens` | How big a request is, estimated: `estimateTokens` — characters over four, deliberately low — and what is built on it for everything here that has to guess at a window: `messageTokens`, `requestTokens`, `contextTokens`. |
 | `errors` | `errorMessage`: a caught `unknown` turned into something a run row can hold. And what `runAgentLoop` throws, with the run as it stood: `AgentLoopError`, `ToolIterationLimit`, `AgentLoopOverflow`, and `failedRun` to read it off any of them. |
 | `catalog` | `CatalogServer`: the name-only shape `tool-loading` reads a connected server as. |
 

package/dist/agent-loop.d.ts

@@ -1,180 +1,31 @@
-import type OpenAI from "openai";
-import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
-import type { CatalogServer } from "./catalog.ts";
-import { type CompactionOptions } from "./compaction.ts";
-import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts";
-import { type RunEventInput, type RunMetrics } from "./events.ts";
-import type { HookEvent } from "./hook-events.ts";
-import { type HookContext, type HookNote, type HookRunner } from "./hooks.ts";
-import { type TokenLedger } from "./ledger.ts";
-import { type SideTask, type SideTaskOptions } from "./side-task.ts";
-import { type Turn, type TurnUsage } from "./stream.ts";
-import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
+import type OpenAI from 'openai';
+import type { CatalogServer } from './catalog.ts';
+import { type CompactionOptions } from './compaction.ts';
+import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from './config.ts';
+import { type RunEventInput, type RunMetrics } from './events.ts';
+import { HookEvent } from './hook-events.ts';
+import { type HookContext, type HookNote, type HookRunner, type OnNote } from './hooks.ts';
+import { type TokenLedger } from './ledger.ts';
+import { type KeywordPreselectOptions } from './preselect.ts';
+import { type ToolDispatch } from './run-calls.ts';
+import { type SideTask } from './side-task.ts';
+import { type Turn, type TurnUsage } from './stream.ts';
+import { type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from './tool-calls.ts';
+import { type ToolOrder } from './tool-loading.ts';
 /**
- * The one place a streamed request's body is decided from a config and what the endpoint and
- * the model have refused.
+ * The loop above a turn: send, run the tools the model asked for, send again, until it stops
+ * asking.
  *
- * Every field that negotiates lives here: the ceiling's two spellings, a temperature only a
- * model that takes ours is sent, a reasoning effort only one that takes it is, `stream_options`
- * only where the server has heard of it, relaxed schemas only where it could not build a grammar,
- * and `extraBody` last, less whatever the model refused by name. The ceiling is tested
- * `=== false` — `modelCapabilitiesFor` starts a model at `legacyTokenLimit: true` and an absent
- * one has to read the same — which is the test one of the three copies had inverted.
- *
- * @param config What to ask for. `maxTokens` of zero or less sends no ceiling; `reasoningEffort`
- * absent or `"off"` sends no effort, and one the model has refused by value is stepped up to the
- * cheapest it takes by `effortFor`.
- * @param supports What the endpoint has refused, as `negotiate` hands it to `send`.
- * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
- * that has refused nothing.
- * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
- * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
- * @param order How to order them before sending. `true`, the default, is by name, which keeps the
- * cache when the caller's array is assembled differently from one request to the next. See
- * `orderTools`.
- */
-export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[], order?: ToolOrder): OpenAI.ChatCompletionCreateParamsStreaming;
-/**
- * A long tool argument or result cut to what a watcher needs, with the full length said.
- *
- * For events, never for the transcript: the model reads the whole of what a tool returned.
- *
- * @param text What to show.
- * @param limit Characters kept, 2000 by default. Text at or under it comes back as it was.
- */
-export declare const preview: (text: string, limit?: number) => string;
-/**
- * The key to send, where an endpoint may inherit one from the settings it overrides.
- *
- * A credential issued for one endpoint has no business being posted to another. A profile that
- * names its own `baseUrl` and no key of its own is sent `NO_KEY` — not the operator's key, and
- * not `$OPENAI_API_KEY` — because "I pointed an agent at a friend's server and it sent my OpenAI
- * key" is not a mistake worth being able to make, and a local server wants no key anyway. One on
- * the same endpoint inherits the key as it inherits everything else, and the environment is the
- * last word on the endpoint that was configured rather than overridden.
- *
- * @param own The endpoint as the agent or profile states it. Its own key always wins. An empty or
- * absent `baseUrl` is one that inherits the endpoint too.
- * @param inherited The settings it overrides. Absent treats `own` as the configured endpoint, so
- * only its key and the environment's are in play.
- * @param env Where `OPENAI_API_KEY` is read from, `process.env` by default.
- */
-export declare function resolveApiKey(own: {
-    baseUrl?: string;
-    apiKey?: string;
-}, inherited?: {
-    baseUrl: string;
-    apiKey?: string;
-}, env?: Record<string, string | undefined>): string;
-/**
- * A side task's settings as the call that honours them: its endpoint, its model, and the options
- * `ask`, `askJson`, `summariser` and `preselect` take last.
- *
- * A helper rather than a second signature on each of the four, so a setting added to a task later
- * arrives through `options` without a host's call changing. What the task states wins over the
- * same field in `options`: the host's code is written once and the task is what an operator
- * configured over it, so a host passes its own ceiling as the value for a task that names none.
- * A setting the task leaves out and `options` does too is absent from the result, which is what
- * leaves it to the entry point's own default — 0.3, not the agent's temperature.
- *
- * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
- * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
- * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
- * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
- * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
- * agent's key is whatever the main turn is sent.
- *
- * @param task The task, ordinarily `resolved.tasks.<key>`.
- * @param options What the host adds — cancellation, notices, `keywords` — and its own defaults
- * for the settings a task may leave out.
- * @param agent The endpoint the main turn uses, key included. Absent sends the task's endpoint
- * as it stands.
+ * Three servers wrote this loop separately after `runTurn` had already been pulled in here, and
+ * the copies drifted the way the turn's own had — one noticed a turn cut off at the ceiling and
+ * two did not, one tested the ceiling's spelling the other way round, one sent a reasoning effort
+ * and two never did. What is here is the part that does not know what the run is for; the
+ * prompts, the tools and what a run means stay with the caller.
  */
-export declare function taskCall<Options extends SideTaskOptions = SideTaskOptions>(task: SideTask, options?: Options, agent?: {
-    baseUrl: string;
-    apiKey?: string;
-}): {
-    endpoint: Endpoint;
-    model: string;
-    options: Options;
-};
-/**
- * The tools a request is likely to need, picked by a small model before the run starts, or none.
- *
- * On-demand loading otherwise spends a round trip on reading the catalogue and calling
- * `load_tools`; a small model reading the same catalogue usually names the right tools, and the
- * task model opens with them in hand. A wrong guess costs a few hundred tokens for one run, and
- * a failed one costs nothing — it is reported through `onNotice` and answered with an empty list,
- * since a side task is never worth failing the run. A stop still throws.
- *
- * With `keywords`, the request's own words are matched against the catalogue first and the model
- * is spent only on what they cannot settle, which on a local box is the difference between a run
- * starting now and starting in a few seconds. The words have to be clear about it; see
- * `preselectByKeywords` for what that means.
- *
- * @param config The endpoint the preselector is reached through.
- * @param model The preselector. An empty name picks nothing, which is what `toolSelectModel`
- * means by empty.
- * @param catalog The servers to choose from.
- * @param prompt The request being planned for. Only its head is read; see `preselectInput`.
- * @param options Cancellation, notices, the reply ceiling (256), the temperature and reasoning
- * effort as `ask` reads them (0.3 and none when absent), the cap the choice is held to
- * (`MAX_PER_LOAD`), and whether to try the words first.
- */
-export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, temperature, reasoningEffort, maxPerLoad, keywords, }?: {
-    signal?: AbortSignal;
-    onNotice?: (message: string) => void;
-    maxTokens?: number;
-    /** As `SideTaskOptions.temperature`: absent is 0.3. */
-    temperature?: number;
-    /** As `SideTaskOptions.reasoningEffort`: absent keeps the no-thinking hints. */
-    reasoningEffort?: string;
-    maxPerLoad?: number;
-    /**
-     * Try `preselectByKeywords` first and spend the model only on what it cannot settle. `true`
-     * takes its defaults; an object tunes the thresholds. An empty `model` still means no
-     * preselection at all, words included — that is what `toolSelectModel: ""` asks for.
-     */
-    keywords?: boolean | KeywordPreselectOptions;
-}): Promise<string[]>;
-/**
- * One call the model made, as `dispatch` and `onToolCall` are handed it.
- *
- * A `call_tool` arrives as the tool it names — that tool's name and arguments, under the
- * `call_tool`'s id — so a dispatcher is the same in every discovery mode.
- */
-export interface ToolCallRequest {
-    id: string;
-    name: string;
-    /**
-     * Parsed by `parseToolArguments`, repairs and all. Empty for a call whose arguments could not be
-     * read, which only `onToolCall` is ever handed.
-     */
-    args: Record<string, unknown>;
-    /**
-     * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
-     * arguments as JSON text.
-     */
-    raw: string;
-}
-/** What one tool call did, in the order the model asked. */
-export interface ToolCallOutcome {
-    /**
-     * The id the model's reply gave the call, which is what tells two calls to one tool apart.
-     * Distinct within a step — `streamTurn` mints one where the server sent none or repeated one —
-     * but nothing stops a server using the same id again in a later step. `runAgentLoop` always
-     * sets it; optional so an outcome built before it existed still compiles.
-     */
-    id?: string;
-    /** The tool that was called. For a `call_tool`, the tool it named. */
-    name: string;
-    /** False when the arguments did not parse, the tool threw, or `load_tools` loaded nothing. */
-    ok: boolean;
-}
 /**
  * One step's request as `onRequest` is handed it: what the model is about to read.
  *
+ * @remarks
  * The loop assembles this and nothing else sees it — the system prompt with the catalogue on it,
  * the hooks' context on the question, the tool array ordered and sanitised as it is sent — so a
  * host that wants to say what is filling the window has nothing to measure without it.
@@ -187,23 +38,10 @@ export interface AgentLoopRequest {
     /** Which step of the run this is, from zero, as `beforeStep` and `onTurn` count them. */
     step: number;
 }
-/**
- * One call's whole answer, as `onToolResult` is handed it.
- *
- * The `tool-result` event carries the same answer cut by `preview`, which is right for a readout
- * and wrong for a host that renders or stores the result: this is the text the model reads.
- */
-export interface ToolCallResult extends ToolCallOutcome {
-    id: string;
-    /**
-     * What went into the transcript for this call, uncut: what the tool returned, what it threw, the
-     * `load_tools` answer, or why the arguments could not be read.
-     */
-    content: string;
-}
 /**
  * The hooks a loop runs around one question. See `hooks.ts`.
  *
+ * @remarks
  * The loop gathers before its first request and nothing else can run beside that, so a host with
  * pre-turn work of its own to overlap with the hooks — compaction, a preselection — calls `gather`
  * itself, puts the context on with `withContext`, calls `notify` after, and passes no `hooks`.
@@ -212,14 +50,26 @@ export interface AgentLoopHooks {
     run: HookRunner;
     /** What the hooks are told. `reply` and `turn` are filled in for `afterTurn`. */
     context: HookContext;
-    /** Run before the first request, `["beforeTurn"]` by default. */
+    /**
+     * Run before the first request.
+     *
+     * @defaultValue `[HookEvent.BeforeTurn]`
+     */
     events?: readonly HookEvent[];
-    /** The shared context budget. Absent is `configureHooks`'s. */
+    /**
+     * The shared context budget.
+     *
+     * @defaultValue The budget `configureHooks` holds.
+     */
     maxTokens?: number;
-    /** Said above the context blocks. Absent is `configureHooks`'s; empty is none. */
+    /**
+     * Said above the context blocks. Empty is none.
+     *
+     * @defaultValue The preface `configureHooks` holds.
+     */
     preface?: string;
     /** Hears each note, from before the request and from `afterTurn`. */
-    onNote?: (note: HookNote) => void;
+    onNote?: OnNote;
 }
 /** How full the window is as a step is about to be sent, as `beforeStep` is told it. */
 export interface StepWindow {
@@ -235,6 +85,10 @@ export interface StepWindow {
     /** The run's ledger so far, indexed into the transcript `beforeStep` is handed beside it. */
     ledger: TokenLedger;
 }
+/** The `preselectRouting` that sends the first step the shortlist alone. */
+export declare const PRESELECT_EXCLUSIVE: 'exclusive';
+/** The `preselectRouting` that loads the shortlist after what was carried, and sends the first step like any other. */
+export declare const PRESELECT_APPEND: 'append';
 /** What `runAgentLoop` takes. */
 export interface AgentLoopOptions {
     /**
@@ -243,11 +97,12 @@ export interface AgentLoopOptions {
      * to `runTurn` as `contextLimit`, which sizes each request against the window before sending.
      * `"proxy"` is on-demand loading behind a tool array that never changes; see `PROXY_TOOLS`.
      *
+     * @remarks
      * `tasks` is a resolved agent's, and is read only for the side tasks the loop was asked to run:
      * `tasks.toolSelect` under `preselect` and `tasks.compaction` under `compact`. `toolSelectModel`
      * is the flattened spelling of the first, for a host that is not on the spec.
      */
-    config: Endpoint & ModelParams & Pick<ToolPolicy, "maxToolIterations"> & Partial<Pick<ToolPolicy, "toolDiscovery" | "toolSelectModel">> & Partial<RetryPolicy> & {
+    config: Endpoint & ModelParams & Pick<ToolPolicy, 'maxToolIterations'> & Partial<Pick<ToolPolicy, 'toolDiscovery' | 'toolSelectModel'>> & Partial<RetryPolicy> & {
         contextLength?: number;
         tasks?: Readonly<Record<string, SideTask>>;
     };
@@ -280,6 +135,7 @@ export interface AgentLoopOptions {
      * has or picks a sibling. Everything comes back on the step after. `preselectRouting` trades
      * that for a first step shaped like the rest.
      *
+     * @remarks
      * Proxied, the tool array is fixed and there is no such step. The shortlist is written into the
      * transcript instead, after the question, as a `load_tools` call the model did not make and the
      * result that call would have had — an assistant message and a tool message, handed back in
@@ -289,7 +145,7 @@ export interface AgentLoopOptions {
      */
     preselected?: readonly string[];
     /**
-     * What a preselection does to the first step. `"exclusive"`, the default, is the shortlist alone
+     * What a preselection does to the first step. `"exclusive"` is the shortlist alone
      * as `preselected` describes — and a system prompt and tool array unlike the last request's and
      * unlike the next step's, so a prompt cache misses the whole transcript on the first step and
      * again on the second. `"append"` loads the shortlist as a `load_tools` call would have and
@@ -298,18 +154,24 @@ export interface AgentLoopOptions {
      * back in front of the model. Which costs more has not been measured, which is why the default
      * has not moved.
      *
+     * @defaultValue `PRESELECT_EXCLUSIVE`
+     *
+     * @remarks
      * Appended is before `toolOrder` has its say: sorted, a preselected tool lands at its name's
      * place and moves every definition after it, so only `toolOrder: false` keeps a carried array
      * a strict prefix. Either way the first step's system prompt is the second's, and so is its
      * tool array until something else is loaded. Nothing to do without a preselection, in eager
      * mode, or proxied, where no step is routed either way.
      */
-    preselectRouting?: "exclusive" | "append";
+    preselectRouting?: typeof PRESELECT_EXCLUSIVE | typeof PRESELECT_APPEND;
     /**
      * Has the loop make the preselection itself, before its first request, with the preselector
-     * the config names. Off by default: a host that passes a resolved agent and calls `preselect`
+     * the config names. Opt-in, so that a host that passes a resolved agent and calls `preselect`
      * on its own is not sent a second one.
      *
+     * @defaultValue `false`
+     *
+     * @remarks
      * The preselector is `config.tasks.toolSelect` with everything it states — its endpoint, model,
      * ceiling, temperature and reasoning effort, keyed as `taskCall` keys a task against `config` —
      * and otherwise `config.toolSelectModel` on the config's own endpoint at `preselect`'s defaults.
@@ -331,6 +193,7 @@ export interface AgentLoopOptions {
      * default, and nothing is folded without that task — there is no falling back to the main model
      * — or without a `config.contextLength` to plan against.
      *
+     * @remarks
      * It runs after `beforeStep`, on what that returned, and is `compactTranscript` and nothing
      * more: the plan is made from the last request's reported prompt, or an estimate before the
      * first step and after a `beforeStep` rewrite; `hooks`, when given, are told `beforeCompact`
@@ -341,14 +204,14 @@ export interface AgentLoopOptions {
      * that keeps its transcript append-only wants `runCompaction` and a stored fold instead. `true`
      * plans by `planCompaction`'s defaults; an object moves its thresholds.
      */
-    compact?: boolean | Pick<CompactionOptions, "compactAt" | "keepRatio" | "target">;
+    compact?: boolean | Pick<CompactionOptions, 'compactAt' | 'keepRatio' | 'target'>;
     /**
      * Tools already loaded, carried from an earlier question. See `carryOver`. Not read in proxied
      * mode, where a tool is loaded only while its definition is in the history.
      */
     loaded?: Iterable<string>;
     /** Runs one tool call and returns what the model reads. What it throws, the model reads too. */
-    dispatch: (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
+    dispatch: ToolDispatch;
     /**
      * Runs a step's calls together rather than one after another. Results still go into the
      * transcript in the order the model asked. See `dedupeToolCalls`, which applies either way.
@@ -358,7 +221,10 @@ export interface AgentLoopOptions {
      * Answers an identical repeat of a call — the same name and the same arguments, word for word —
      * within one step from the first one, rather than dispatching it again.
      *
-     * On by default, and on whether or not the calls run in `parallel`: a model that asks the same
+     * @defaultValue `true`
+     *
+     * @remarks
+     * It holds whether or not the calls run in `parallel`: a model that asks the same
      * question twice in one reply gets one answer, and two that are still in flight share the
      * request. A call that threw is not an answer and is made again. The scope is the step and not
      * the run, because between steps other tools have run and the file the model read may be the
@@ -375,6 +241,7 @@ export interface AgentLoopOptions {
      * `load_tools`, an identical repeat answered from the first, and a call whose arguments could
      * not be read, which arrives with empty `args` and the model's own text in `raw`.
      *
+     * @remarks
      * For a host that shows each call as it is made and fills it in when its result lands, which
      * `dispatch` alone cannot do for those three. Not awaited: a promise it returns is dropped.
      */
@@ -382,6 +249,7 @@ export interface AgentLoopOptions {
     /**
      * Told of every call's answer as it lands, whole, under the id `onToolCall` announced it by.
      *
+     * @remarks
      * One per call the model made: a deduplicated repeat gets its own, carrying the answer it
      * shares with the first. With `parallel` they arrive as the calls finish, which need not be
      * the order they were made in; the transcript and the result's `toolCalls` keep that order.
@@ -391,6 +259,7 @@ export interface AgentLoopOptions {
     /**
      * Hooks gathered onto the question before the first request, and told the reply after.
      *
+     * @remarks
      * Only this question is touched — the last user message of `messages` — and the context is on
      * the request, never in the transcript handed back. An earlier question's context is therefore
      * the host's to send again: keep the result's `context` and `preface` beside the question, and
@@ -419,15 +288,18 @@ export interface AgentLoopOptions {
     onEvent?: (event: RunEventInput) => void;
     /**
      * Takes tool calls a model wrote into its reply as text and runs them as calls, with a notice
-     * saying so. On by default: a server whose tool-call parser does not match the model's template
-     * otherwise ends the run on a reply that is only a call nobody made. Off leaves such a reply as
-     * the answer. See `recoverToolCalls`.
+     * saying so. A server whose tool-call parser does not match the model's template otherwise ends
+     * the run on a reply that is only a call nobody made. Off leaves such a reply as the answer. See
+     * `recoverToolCalls`.
+     *
+     * @defaultValue `true`
      */
     recoverToolCalls?: boolean;
     /**
      * Each step's request as first built, before it goes out — for measuring what was sent, not for
      * changing it, which is `beforeStep`'s.
      *
+     * @remarks
      * Called once a step, synchronously, and what it throws ends the run. It is not called again
      * for what `runTurn` sends after that: a retry sends the same request, but a refusal is answered
      * with a lesser body — relaxed schemas, a field dropped — and a continuation with the reply so
@@ -441,6 +313,7 @@ export interface AgentLoopOptions {
      * the loop goes on — so a host that stores its transcript has written the assistant message
      * before its tools run, and every tool result before the next request is sent.
      *
+     * @remarks
      * The assistant message is the one replayed on later requests — arguments repaired, recovered
      * calls folded in — and comes with its `turn`, as `onTurn` was handed it, for the `reasoning` a
      * host keeps beside the message. A tool result comes without one, and so do the two messages
@@ -450,9 +323,11 @@ export interface AgentLoopOptions {
      */
     onMessage?: (message: OpenAI.ChatCompletionMessageParam, step: number, turn?: Turn) => void | Promise<void>;
     /**
-     * How many times an answer cut off at `maxTokens` is continued, zero — the default — for never.
-     * Opt-in because it spends another request, and on a server that does not continue a trailing
-     * assistant message it spends one to find that out. See `continueTurn`.
+     * How many times an answer cut off at `maxTokens` is continued, zero for never. Opt-in because
+     * it spends another request, and on a server that does not continue a trailing assistant
+     * message it spends one to find that out. See `continueTurn`.
+     *
+     * @defaultValue `0`
      */
     maxContinuations?: number;
 }
@@ -518,6 +393,13 @@ export interface AgentLoopResult {
  * until a turn asks for none. Throws when `maxToolIterations` is spent, when stopped, and on
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
+ * @param options - The config, transcript, tools and dispatcher, plus the optional hooks, events
+ * and cancellation. See `AgentLoopOptions`.
+ * @returns The turn that asked for no tools and the run around it: the transcript with what the
+ * run added, usage, every call, what is loaded and used, the hooks' notes and context, metrics
+ * and the ledger. See `AgentLoopResult`.
+ *
+ * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded` and
  * `used` — because the steps before a failure were real and a host that stores its transcript
  * has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an overflow is
@@ -555,8 +437,5 @@ export interface AgentLoopResult {
  * `compact` has it fold the transcript, each by the task `config.tasks` carries for it and on
  * that task's own settings — a setting the task leaves out is the side task's default, never the
  * run's `temperature` or `maxTokens`.
- *
- * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
- * and cancellation. See `AgentLoopOptions`.
  */
 export declare function runAgentLoop(options: AgentLoopOptions): Promise<AgentLoopResult>;