@cubicecho/agent-core 2.4.0 → 2.6.0

package/README.md

@@ -24,13 +24,17 @@ only, Node >=22.
 | `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. |
 | `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
-| `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. |
-| `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
+| `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. |
+| `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`. 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. |
 | `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`, and `resolveApiKey` for a caller deciding which key an endpoint gets. |
+| `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. |
+| `compaction` | Keeping a long run inside its window: `pruneToolResults` clears stale tool results, `planCompaction` and `compactTranscript` fold the oldest stretch into a summary. |
+| `snapshot` | `exportCapabilities` and `importCapabilities`: the latched refusals as a JSON blob a consumer stores, so a restart need not learn them again. |
 | `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
 | `tokens` | `estimateTokens`: characters over four, deliberately low, for everything here that has to guess at a window. |
 | `errors` | `errorMessage`: a caught `unknown` turned into something a run row can hold. |
@@ -147,6 +151,29 @@ still talking is never cut off however long it takes, and one that has stopped a
 `requestTimeoutSeconds` of zero or absent, which waits forever — what a local model answering
 slowly needs.
 
+## Structured side tasks
+
+`askJson` is `ask` for an answer with a shape. It sends the schema as `response_format` of type
+`json_schema`, which llama.cpp compiles into a grammar and vLLM, LM Studio, Ollama and OpenAI each
+hold the reply to, so a small model that wraps JSON in prose on its own cannot do so here. The
+schema is normalised the way a tool's parameters are, and relaxed where the endpoint could not
+build a grammar, because llama.cpp reads both with the same converter. It also rides on the system
+prompt, and the reply goes through `parseJson` either way.
+
+```ts
+const picked = await askJson<{ tools: string[] }>(config, small, system, request, PRESELECT_SCHEMA, {
+  name: "preselection",
+  onNotice,
+});                                              // undefined when no JSON came back
+```
+
+A model that refuses the field latches `structuredOutput` off, per `(endpoint, model)` like the
+other refusals here, and is asked in words from then on. A server that finds the *schema* invalid
+is not latched: that error is the caller's to see. `strict` defaults to true, which OpenAI takes to
+mean every property required and `additionalProperties: false`; a looser schema wants it off there.
+`preselect` is its first user, answering `{ tools: [...] }`, and `preselection` still takes the
+bare array an older prompt produced.
+
 ## Sizing a request before sending it
 
 `runTurn` will refuse a request that cannot fit rather than spending a round trip finding out:
@@ -164,6 +191,13 @@ const turn = await runTurn(client, supports, build, {
 });
 ```
 
+What is weighed is the prompt plus the reply ceiling the body carries, under whichever spelling
+was chosen, because that is what the endpoint weighs: a 30k prompt into a 32k window with
+`max_tokens: 4096` is refused there, so it is refused here. A body with no ceiling reserves
+nothing, and the server gives the reply whatever the prompt leaves. A consumer that subtracted
+`maxTokens` from the limit itself before calling in no longer needs to, and doing both reserves
+the ceiling twice.
+
 The body is sized once, not per attempt: a downgraded request is strictly smaller than the one
 before it and the transcript does not change between retries. A `ContextOverflow` from this is
 neither a capability `negotiate` can answer nor something `isTransient` accepts, so it leaves
@@ -175,6 +209,138 @@ refuses instead — one round trip later — and `runTurn` reads that refusal ba
 original error as `cause`. A rate limit borrows those words and means the opposite ("Request too
 large for gpt-4o ... on tokens per min"); that is ruled out and waited through as the 429 it is.
 
+## The loop
+
+`runAgentLoop` is the part of an agent that three servers had each written, and that had drifted
+the way the turn had before `runTurn`: 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 it does not know is what the run is for — the prompt, the tools, and what a tool call
+*does* are the caller's.
+
+```ts
+import { runAgentLoop, emit } from "@cubicecho/agent-core";
+
+const { turn, messages, usage, loaded } = await runAgentLoop({
+  config,                         // Endpoint & ModelParams & { maxToolIterations, toolDiscovery?, maxRetries?, contextLength? }
+  system,                         // sent as the first message; on-demand mode appends the catalogue
+  messages: history,              // ending in the question; not written to
+  tools,                          // every tool the run may reach
+  catalog,                        // the same, name-only, for on-demand loading
+  preselected,                    // from `preselect`, if a small model chose
+  dispatch: ({ name, args }, signal) => pool.call(name, args, signal),
+  hooks: { run, context: { session: { id } } },
+  signal,
+  onEvent: (event) => emit(runId, event),
+});
+```
+
+Each step is one `runTurn` with the body from `buildBody`, so everything `negotiate` answers is
+answered here too, and a request that is too big throws `ContextOverflow` whichever side found
+out. Between steps the loop runs the calls: sequentially by default, or together with
+`parallel: true`, which also makes an identical call — the same name and arguments, byte for byte
+— once for the run. A call that threw is forgotten rather than cached, so asking again is a real
+retry. What a tool throws is what the model reads, and so are arguments that did not parse.
+
+Arguments go through `parseToolArguments`, which is lenient where the model's meaning is plain:
+JSON held in a string is opened, and the almost-JSON local models write — single quotes, Python's
+`True` and `None`, bare keys, a trailing comma — is repaired, without touching what is inside a
+string. What still is not an object throws a `ToolArgumentsError` whose `kind` is `truncated` when
+the turn stopped at the ceiling, with a message telling the model so, and `malformed` otherwise.
+The repaired JSON is what the transcript keeps, and an unreadable call is replayed as `{}`, because
+a server that parses replayed arguments refuses the originals on every later request. `dispatch`
+is still handed the model's own text as `raw`, and the parallel dedupe compares repaired arguments,
+so `{'a': 1}` and `{"a": 1}` are one call.
+
+A server whose tool-call parser was written for another template streams the model's call as
+plain text, and the run ends on a reply that is nothing but a call nobody made. Unless
+`recoverToolCalls: false`, a turn with no calls, some text, and tools to call is passed through
+`recoverToolCalls`, which finds `<tool_call>` blocks (Hermes, Qwen, Qwen3-Coder's markup),
+`[TOOL_CALLS]` (Mistral, both spellings) and `<|python_tag|>` (Llama 3) after the last `</think>`,
+and — naming only tools that exist — a reply that is only a JSON call or holds one fenced one.
+Found calls are run as `call_recovered_0` onward, the text is what is left, `onTurn` and the
+result see the turn that way, and a notice says so, since the real fix is the server's parser.
+
+With `toolDiscovery: "ondemand"` and a catalogue, the request declares `load_tools` and what has
+been loaded, and the catalogue rides on the system prompt marked with what is. A model that calls
+a catalogued tool without loading it first is right about what it wants, and gets it loaded and
+run. A preselection shapes the first step alone: those tools, no catalogue, no `load_tools` —
+a model with the menu still in front of it shops, reloading what it has or picking a sibling —
+and everything is back from the second step on.
+
+`beforeStep` is handed the transcript before each request and may return a replacement, which is
+where compaction goes (below). Hooks are gathered once, onto the question, and never written into
+the transcript that comes back; `afterTurn` is told the reply without the run waiting on it.
+
+`resolveApiKey` is exported and not applied, because which key an endpoint gets is a rule a
+consumer states and a library guessing it could send one where it was not meant to go. The rule
+it encodes is the conservative one: an endpoint's own key wins; one that names a base URL of its
+own, different from the settings it inherits from, gets `NO_KEY` rather than the operator's key or
+`$OPENAI_API_KEY`; anything else inherits.
+
+## Fields this interface cannot spell
+
+`ModelParams` has `temperature`, `maxTokens` and `reasoningEffort`. Everything else a model card or
+a server asks for — `top_k`, `min_p`, `repeat_penalty`, llama.cpp's `id_slot`, `cache_prompt` and
+`reasoning_budget` — goes in `extraBody`, which `buildBody` merges in last. It can override
+`temperature` but not `model`, `messages`, `stream` or `tools`, which are the loop's.
+
+A local server ignores a field it does not know. OpenAI refuses it — `Unrecognized request
+argument supplied: min_p` — and so do some proxies, as `Unknown parameter: 'min_p'`. Given the
+names it may drop as `droppable` (`runTurn` takes the same option, and `runAgentLoop` passes the
+`extraBody` keys),
+`negotiate` reads either wording, latches the name off for that model on that endpoint, and sends
+again without it, with a notice naming it. A nested name is dropped at its top-level field. A
+refused field nobody said was droppable is passed on, since dropping it would change the request
+behind the caller's back.
+
+On a llama.cpp server started with `--parallel`, pin each session to a slot with
+`extraBody: { id_slot: n }`. The slot keeps that session's KV cache warm, which is the difference
+between a cached prefill on every turn and a full one — but only while the prefix stays the same
+from turn to turn; see #63, and the caution on compaction below.
+
+Ollama's `options` object is not read on its OpenAI-compatible `/v1` route, so sampling set there
+does nothing; send the fields at the top level.
+
+## Keeping a long run inside its window
+
+Two ways to make a transcript smaller, cheap first.
+
+`pruneToolResults(messages, { keepLast: 5, maxChars: 256 })` replaces every tool result but the
+latest five with a stub — `[result cleared, 10,412 chars]`. A 40k-character `read_file` is 10k
+tokens on every turn after it, and by then the model has usually taken what it wanted; the stub
+keeps the call answered and says how much was there.
+
+`planCompaction(messages, { limit, used })` says where to fold the oldest stretch into a summary,
+once `used` (the last turn's prompt tokens, or the estimate) is past three quarters of the window.
+The kept tail fills at most 35% of it and starts on a user message, since a transcript resuming
+mid-exchange is one servers refuse; leading system prompts are never folded, and an earlier
+summary is continued rather than summarised. `compactTranscript` writes the summary and tells
+`beforeCompact` hooks what is going while it does. A hook cannot veto it. Because the cut lands on
+a user message, one long tool run under a single question has nothing to fold — pruning is what
+keeps that one going.
+
+```ts
+beforeStep: async (messages, step) => {
+  const plan = planCompaction(messages, { limit: config.contextLength ?? 0, used: lastPromptTokens });
+  if (!plan) return;
+  return compactTranscript(
+    pruneToolResults(messages),
+    plan,
+    summariser(config, config.model, { signal }),
+    { hooks: { run, context } },
+  );
+},
+```
+
+**Both rewrite the prefix.** A prompt cache matches from the first token, so a transcript whose
+early messages change is re-processed whole — on a local server that is the entire prefill, every
+time. Run them rarely and together, at the point `planCompaction` says the window is filling, so
+the cache is lost once rather than a little on every turn. Pruning on every step is the expensive
+way to save tokens.
+
+`pruneToolResults` keeps the transcript's indexes, so a plan made before pruning still applies to
+what it returns, as above.
+
 ## Watching a run
 
 `watch` replays what the run has already emitted, then yields what happens next until `done`.
@@ -293,6 +459,26 @@ Neither function rejects. A hook failing is an outcome, and a runner that throws
 noted once for its event and costs only that event's context. `notify` takes no signal: a reader
 who leaves once the turn is answered has not asked for it not to be remembered.
 
+### Untrusted text
+
+Hook context is not the only text in a prompt that nobody vouched for. A fetched page, an email, a
+submitted card and a tool result all reach the model in the same words as the operator's own, and
+`untrusted` gives the model a fence it can see around them. Put `UNTRUSTED_PREFACE` in the system
+prompt once, where it costs the prompt cache nothing, and wrap each piece where it is pasted in:
+
+```ts
+import { UNTRUSTED_PREFACE, untrusted } from "@cubicecho/agent-core";
+
+const system = `${instructions}\n\n${UNTRUSTED_PREFACE}`;
+const content = `Summarise this page.\n\n${untrusted(page, { source: url })}`;
+```
+
+Any `untrusted` tag inside the text, opening or closing and in any case, has its `<` escaped, so a
+page that writes `</untrusted>` followed by an instruction leaves that instruction inside the
+block. This is one layer and not a defence on its own. A model can still be talked out of a fence,
+and the tool policy is what decides what the text can make the agent do. `withContext` does not
+fence hook blocks this way, because they have to stay identical to the MCP pool's `contextBlocks`.
+
 ## The config seam
 
 Nothing here imports a config type from a consumer, and no function asks for a whole
@@ -340,6 +526,22 @@ up a week is still picked up without a restart.
 
 `resetAll` drops all four, and `reset.ts` names each seam separately for a test that wants one.
 
+The latches can outlive the process as well, because otherwise every restart spends one refused
+request per endpoint and model learning the same facts again. `exportCapabilities` returns every
+refusal as a JSON-safe `CapabilitySnapshot`, and `importCapabilities` takes one back:
+
+```ts
+importCapabilities(settings.capabilities);          // on boot; false if the version moved on
+// ...
+settings.capabilities = exportCapabilities();       // on shutdown, or after a notice
+```
+
+A snapshot names endpoints by `endpointId`, a SHA-256 digest of the URL and key, so it can be
+written to a settings row or a file without a credential going with it. Importing merges and only
+latches off, the same as a refusal does. A snapshot of another `version` is ignored. How old is too
+old is left to the consumer, who can read `savedAt` first: a server upgraded between boots may
+accept what it used to refuse, and nothing latched ever unlatches without a reset.
+
 ## Where the merged behaviour came from
 
 - `schema-compat` — `kanban_server`/`task_server`'s version, which strips **every** sibling of a
@@ -352,3 +554,9 @@ up a week is still picked up without a restart.
   its `fold` fix: two blocks in different steps are not one block.
 - `retry` — `kanban_server`'s, which is the only one of the three with the `ContextOverflow`
   guard. `min-agent` had no retry layer at all.
+- `agent-loop` — `task_server`'s `length` notice and abort checks, `min-agent`'s parallel dispatch
+  with its dedupe (as an option) and its handling of nameless call fragments and empty stored
+  arguments, and the ceiling test `task_server` and `kanban_server` agreed on rather than
+  `min-agent`'s inverted one.
+- `compaction` — `min-agent`'s arithmetic and `SUMMARY_PROMPT`, the only implementation of the
+  three. Pruning had none.

package/dist/agent-loop.d.ts

@@ -0,0 +1,202 @@
+import type OpenAI from "openai";
+import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
+import type { CatalogServer } from "./catalog.ts";
+import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts";
+import type { RunEventInput } from "./events.ts";
+import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
+import type { Turn, TurnUsage } from "./stream.ts";
+/**
+ * The one place a streamed request's body is decided from a config and what the endpoint and
+ * the model have refused.
+ *
+ * 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.
+ * @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. Sanitised here — a lookup for a definition seen before —
+ * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ */
+export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[]): 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;
+/**
+ * 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.
+ *
+ * @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) and the cap the choice is held to
+ * (`MAX_PER_LOAD`).
+ */
+export declare function preselect(config: Endpoint, model: string, catalog: CatalogServer[], prompt: string, { signal, onNotice, maxTokens, maxPerLoad, }?: {
+    signal?: AbortSignal;
+    onNotice?: (message: string) => void;
+    maxTokens?: number;
+    maxPerLoad?: number;
+}): Promise<string[]>;
+/** One call the model made, as `dispatch` is handed it. */
+export interface ToolCallRequest {
+    id: string;
+    name: string;
+    /** Parsed by `parseToolArguments`, repairs and all. */
+    args: Record<string, unknown>;
+    /** The arguments as the model wrote them, before any repair. */
+    raw: string;
+}
+/** What one tool call did, in the order the model asked. */
+export interface ToolCallOutcome {
+    name: string;
+    /** False when the arguments did not parse, the tool threw, or `load_tools` loaded nothing. */
+    ok: boolean;
+}
+/** The hooks a loop runs around one question. See `hooks.ts`. */
+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. */
+    events?: readonly HookEvent[];
+    /** The shared context budget. Absent is `configureHooks`'s. */
+    maxTokens?: number;
+    /** Said above the context blocks. Absent is `HOOK_PREFACE`. */
+    preface?: string;
+    /** Hears each note, from before the request and from `afterTurn`. */
+    onNote?: (note: HookNote) => void;
+}
+/** What `runAgentLoop` takes. */
+export interface AgentLoopOptions {
+    /**
+     * The endpoint, what to ask the model for, and how long it may keep calling tools.
+     * `toolDiscovery` absent is eager, `maxRetries` absent is none, and `contextLength` is handed
+     * to `runTurn` as `contextLimit`, which sizes each request against the window before sending.
+     */
+    config: Endpoint & ModelParams & Pick<ToolPolicy, "maxToolIterations"> & Partial<Pick<ToolPolicy, "toolDiscovery">> & Partial<RetryPolicy> & {
+        contextLength?: number;
+    };
+    /** The standing instruction, sent as the first message. On-demand mode appends the catalogue. */
+    system?: string;
+    /** The transcript so far, ending in the question. Not written to; see the result's `messages`. */
+    messages: OpenAI.ChatCompletionMessageParam[];
+    /**
+     * Every tool this run may reach. Eager mode sends all of them; on-demand mode sends the ones
+     * loaded so far, by name.
+     */
+    tools?: OpenAI.ChatCompletionTool[];
+    /** The same tools as a name-only catalogue. On-demand mode needs it, and is eager without it. */
+    catalog?: CatalogServer[];
+    /**
+     * What `preselect` picked. The first step is sent these and nothing else — no catalogue, no
+     * `load_tools` — because a model with the menu still in front of it shops: it reloads what it
+     * has or picks a sibling. Everything comes back on the step after.
+     */
+    preselected?: readonly string[];
+    /** Tools already loaded, carried from an earlier question. See `carryOver`. */
+    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>;
+    /**
+     * Runs a step's calls together rather than one after another, and makes an identical call —
+     * the same name and arguments, word for word — once for the run, handing a repeat the first
+     * answer. A call that threw is not an answer and is made again. Results still go into the
+     * transcript in the order the model asked.
+     */
+    parallel?: boolean;
+    /** Hooks gathered onto the question before the first request, and told the reply after. */
+    hooks?: AgentLoopHooks;
+    /**
+     * Called before each step with the transcript, and what it returns replaces it — the point to
+     * compact or prune a run that has grown into its window. Returning nothing keeps it.
+     */
+    beforeStep?: (messages: readonly OpenAI.ChatCompletionMessageParam[], step: number) => OpenAI.ChatCompletionMessageParam[] | undefined | Promise<OpenAI.ChatCompletionMessageParam[] | undefined>;
+    /** Stops the run: the request in flight, and between steps and calls. */
+    signal?: AbortSignal;
+    /** Told what the run is doing, as the events a watcher reads. */
+    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`.
+     */
+    recoverToolCalls?: boolean;
+    /** Each turn as it comes back, before its tools run. Recovered calls are in it as calls. */
+    onTurn?: (turn: Turn, step: number) => void;
+}
+/** What a finished loop hands back. */
+export interface AgentLoopResult {
+    /** The last turn: the one that asked for no tools, as `onTurn` was handed it. */
+    turn: Turn;
+    /** The transcript, with every assistant turn and tool result the run added. No system prompt. */
+    messages: OpenAI.ChatCompletionMessageParam[];
+    /** Summed over every turn of the run. */
+    usage: TurnUsage;
+    /** Every call, `load_tools` included, in the order they were made. */
+    toolCalls: ToolCallOutcome[];
+    /** What is loaded at the end, for `carryOver`. Empty in eager mode. */
+    loaded: string[];
+    /** The tools the model actually called, `load_tools` excluded. */
+    used: string[];
+    /** The hooks' notes from before the first request. */
+    notes: HookNote[];
+}
+/**
+ * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
+ * 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.
+ *
+ * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
+ * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
+ * run rather than refused, and a preselection shapes the first step. A turn cut off at
+ * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ *
+ * @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>;