@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/compaction.js

@@ -1,7 +1,9 @@
-import { consult, notify, textOf, turnMessages, } from "./hooks.js";
-import { messageTokens } from "./retry.js";
-import { ask } from "./side-task.js";
-import { holdsDefinitions } from "./tool-loading.js";
+import { HookEvent } from './hook-events.js';
+import { consult, notify, textOf, turnMessages } from './hooks.js';
+import { ask } from './side-task.js';
+import { messageTokens } from './tokens.js';
+import { holdsDefinitions } from './tool-loading.js';
+import { FUNCTION_TOOL, Role } from './wire.js';
 /** The fraction of the window in use before a summary is worth its own round trip. */
 export const COMPACT_AT = 0.75;
 /** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
@@ -10,45 +12,77 @@ export const KEEP_RATIO = 0.35;
 const SUMMARY_TOKENS = 1024;
 /** How much of any one message the summariser is shown. A pasted file is not worth it whole. */
 const SUMMARY_SLICE = 4000;
+/** The fewest messages worth folding: a summary of one costs a round trip and saves nothing. */
+const FEWEST_FOLDED = 2;
+/** The locale a cleared result's length is written in, so the stub reads the same on every host. */
+const COUNT_LOCALE = 'en-US';
 /**
  * The summariser's instruction when the caller gives none.
  *
+ * @remarks
  * Asks for notes rather than a retelling, because what the summary replaces is the model's only
  * record of what was decided, and a narrative spends its words on the order things happened in.
  */
-export const SUMMARY_PROMPT = "You maintain the running memory of a long conversation. Rewrite the exchange below as " +
-    "notes the assistant can rely on after the original messages are gone. Keep decisions, " +
-    "facts, file paths, names, numbers, and anything still unresolved. Drop pleasantries and " +
-    "anything already superseded. Write compact prose or bullets — no preamble, no sign-off.";
+export const SUMMARY_PROMPT = 'You maintain the running memory of a long conversation. Rewrite the exchange below as ' +
+    'notes the assistant can rely on after the original messages are gone. Keep decisions, ' +
+    'facts, file paths, names, numbers, and anything still unresolved. Drop pleasantries and ' +
+    'anything already superseded. Write compact prose or bullets — no preamble, no sign-off.';
 /**
  * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
  */
-export const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
-/** What the summariser reads for one message: its text and the calls it made. */
+export const SUMMARY_LEAD = 'Summary of the earlier part of this conversation, which is no longer shown in full:\n\n';
+/**
+ * What the summariser reads for one message: its text and the calls it made.
+ *
+ * @param message - Any message of the transcript. Only its function calls are written out.
+ * @returns The text, then each call as `name(arguments)`, space-separated and trimmed. Empty for a
+ * message with neither. Not cut to length; `summaryInput` does that.
+ */
 const messageText = (message) => {
-    const calls = "tool_calls" in message && message.tool_calls
+    const calls = 'tool_calls' in message && message.tool_calls
         ? message.tool_calls
-            .map((call) => call.type === "function" ? `${call.function.name}(${call.function.arguments})` : "")
-            .join(" ")
-        : "";
+            .map((call) => (call.type === FUNCTION_TOOL ? `${call.function.name}(${call.function.arguments})` : ''))
+            .join(' ')
+        : '';
     return `${textOf(message.content)} ${calls}`.trim();
 };
-const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
-/** The summary as it sits in a transcript, which is the one shape `isSummary` recognises again. */
+/**
+ * Whether a message is a summary an earlier fold left, rather than a system prompt.
+ *
+ * @param message - Any message of the transcript.
+ * @returns `true` for a `system` message whose text opens with `SUMMARY_LEAD`, which is what
+ * `summaryMessage` writes.
+ */
+const isSummary = (message) => message.role === Role.System && textOf(message.content).startsWith(SUMMARY_LEAD);
+/**
+ * The summary as it sits in a transcript, which is the one shape `isSummary` recognises again.
+ *
+ * @param summary - The notes, without the lead. Trimmed here.
+ * @returns A new `system` message: `SUMMARY_LEAD`, then the notes.
+ */
 const summaryMessage = (summary) => ({
-    role: "system",
+    role: Role.System,
     content: `${SUMMARY_LEAD}${summary.trim()}`,
 });
 /**
  * The leading system messages a fold never touches, and the summary an earlier one left among
- * them. What a caller who keeps its system prompt out of the array knows already, and passes.
+ * them.
+ *
+ * @param messages - The transcript. Not written to.
+ * @returns `from` is the index of the first message that is not `system` — the length when all of
+ * them are. `previous` is the text of the last summary among those ahead of it, lead removed, and
+ * absent when there is none.
+ *
+ * @remarks
+ * What a caller who keeps its system prompt out of the array knows already, and passes.
  */
 const systemHead = (messages) => {
     let from = 0;
     let previous;
-    while (from < messages.length && messages[from].role === "system") {
-        if (isSummary(messages[from]))
+    while (from < messages.length && messages[from].role === Role.System) {
+        if (isSummary(messages[from])) {
             previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
+        }
         from++;
     }
     return { from, previous };
@@ -56,6 +90,12 @@ const systemHead = (messages) => {
 /**
  * The transcript with every tool result but the latest few replaced by a one-line stub.
  *
+ * @param messages - The transcript. Not written to.
+ * @param [options] - How many results to keep and how long one must be to clear.
+ * @returns `messages` itself when nothing was cleared, otherwise a new array in which each cleared
+ * result is a new message and every other one the same object.
+ *
+ * @remarks
  * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
  * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
  * call answered — a call with no result is a malformed transcript — and says how much was there,
@@ -64,39 +104,54 @@ const systemHead = (messages) => {
  * only copy of them the model has (`holdsDefinitions`); either still counts as one of the latest
  * few. Returns the same array when there was nothing to clear. Rewrites the prefix;
  * see the module comment on when to run it.
- *
- * @param messages The transcript. Not written to.
- * @param options How many results to keep and how long one must be to clear.
  */
 export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}) {
     let kept = 0;
     let out;
     for (let at = messages.length - 1; at >= 0; at--) {
         const message = messages[at];
-        if (message.role !== "tool")
+        if (message.role !== Role.Tool) {
             continue;
-        if (kept++ < keepLast)
+        }
+        if (kept++ < keepLast) {
             continue;
+        }
         const text = textOf(message.content);
-        if (text.length <= maxChars || text.startsWith("[result cleared"))
+        if (text.length <= maxChars || text.startsWith('[result cleared')) {
             continue;
+        }
         // A proxied load's result is the schema itself; stubbed, the tool is one the model can still
         // name and no longer call correctly.
-        if (holdsDefinitions(text))
+        if (holdsDefinitions(text)) {
             continue;
+        }
         out ??= [...messages];
         out[at] = {
             ...message,
-            content: `[result cleared, ${text.length.toLocaleString("en-US")} chars]`,
+            content: `[result cleared, ${text.length.toLocaleString(COUNT_LOCALE)} chars]`,
         };
     }
     return out ?? messages;
 }
-/** An index held between the start of the transcript and `most`, for a caller's `from` that is neither. */
+/**
+ * An index held between the start of the transcript and `most`, for a caller's `from` that is
+ * neither.
+ *
+ * @param index - The index as it was given, which may be negative or past the end.
+ * @param most - The highest index allowed, itself included.
+ * @returns `index` where it lies from zero to `most`, otherwise the nearer of the two.
+ */
 const clamp = (index, most) => Math.min(Math.max(index, 0), most);
 /**
  * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
  *
+ * @param messages - The transcript, system prompts included if the caller keeps them in it.
+ * @param options - The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
+ * @returns The plan, its `toSummarise` a new array of the same message objects, or `undefined` when
+ * there is nothing to fold. `messages` is not written to.
+ *
+ * @remarks
  * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
  * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
  * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
@@ -117,17 +172,15 @@ const clamp = (index, most) => Math.min(Math.max(index, 0), most);
  * comes, and `after` says how far short it fell. An earlier summary the new one replaces is not
  * credited, so `after` errs high by at most that much. It is only as good as `estimate` — see
  * `estimateFrom` for one that is measured.
- *
- * @param messages The transcript, system prompts included if the caller keeps them in it.
- * @param options The window, what is in use, the ratios, and where the last fold ended. See
- * `CompactionOptions`.
  */
 export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, target, summaryTokens = SUMMARY_TOKENS, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), from: givenFrom, previous: givenPrevious, }) {
-    if (!(limit > 0))
+    if (!(limit > 0)) {
         return undefined;
+    }
     const cost = used ?? messages.reduce((total, message) => total + estimate(message), 0);
-    if (cost < limit * compactAt)
+    if (cost < limit * compactAt) {
         return undefined;
+    }
     const head = systemHead(messages);
     const from = clamp(givenFrom ?? head.from, messages.length);
     const previous = givenPrevious ?? head.previous;
@@ -137,11 +190,12 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
         // Forward from the head, so the first cut that reaches the target is the one that folds least.
         let folded = 0;
         for (let at = from; at < messages.length; at++) {
-            if (messages[at].role === "user") {
+            if (messages[at].role === Role.User) {
                 cut = at;
                 after = cost - folded + summaryTokens;
-                if (after <= limit * target)
+                if (after <= limit * target) {
                     break;
+                }
             }
             folded += estimate(messages[at]);
         }
@@ -151,15 +205,18 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
         let kept = 0;
         for (let at = messages.length - 1; at > from; at--) {
             kept += estimate(messages[at]);
-            if (kept > budget)
+            if (kept > budget) {
                 break;
+            }
             cut = at;
         }
-        while (cut < messages.length && messages[cut].role !== "user")
+        while (cut < messages.length && messages[cut].role !== Role.User) {
             cut++;
+        }
     }
-    if (cut >= messages.length || cut - from < 2)
+    if (cut >= messages.length || cut - from < FEWEST_FOLDED) {
         return undefined;
+    }
     return {
         from,
         cut,
@@ -172,16 +229,18 @@ export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT,
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.
  *
- * @param plan What `planCompaction` returned.
+ * @param plan - What `planCompaction` returned.
+ * @returns The text for the summariser, messages a blank line apart. A message with neither text
+ * nor calls is left out, and a plan with a `previous` opens with it under `Notes so far:`.
  */
 export function summaryInput(plan) {
     const transcript = plan.toSummarise
         .map((message) => {
         const text = messageText(message);
-        return text ? `${message.role}: ${text.slice(0, SUMMARY_SLICE)}` : "";
+        return text ? `${message.role}: ${text.slice(0, SUMMARY_SLICE)}` : '';
     })
         .filter(Boolean)
-        .join("\n\n");
+        .join('\n\n');
     return plan.previous
         ? `Notes so far:\n${plan.previous}\n\nContinue them with this exchange:\n\n${transcript}`
         : transcript;
@@ -189,26 +248,29 @@ export function summaryInput(plan) {
 /**
  * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
  *
- * @param config The endpoint the summary is written through.
- * @param model The model to write it, which may be a smaller one than the run's.
- * @param options Cancellation and notices; the ceiling is 1024 and the instruction
- * `SUMMARY_PROMPT` unless given.
+ * @param config - The endpoint the summary is written through.
+ * @param model - The model to write it, which may be a smaller one than the run's.
+ * @param [options] - Cancellation and notices, and the instruction and ceiling the summary is
+ * written under.
+ * @returns A function from `summaryInput`'s text to the summary. It rejects as `ask` does, and
+ * resolves with an empty string where the model wrote nothing.
  */
 export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = SUMMARY_TOKENS, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
 /**
  * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *
- * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
- * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
- * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
- *
- * @param messages The transcript the plan was made for. Read only, and only for the hooks.
- * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * @param messages - The transcript the plan was made for. Read only, and only for the hooks.
+ * @param plan - What `planCompaction` returned for it.
+ * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @param [options] - Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
  * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
  * so the caller stores nothing and the transcript is still whole.
+ *
+ * @remarks
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
  */
 export async function runCompaction(messages, plan, summarise, { hooks, forced = false } = {}) {
     const context = hooks && {
@@ -218,40 +280,46 @@ export async function runCompaction(messages, plan, summarise, { hooks, forced =
     };
     let summary;
     if (hooks && context && hooks.honourVeto && !forced) {
-        const { vetoed } = await consult(hooks.run, "beforeCompact", context, hooks.onNote);
-        if (vetoed)
+        const { vetoed } = await consult(hooks.run, HookEvent.BeforeCompact, context, hooks.onNote);
+        if (vetoed) {
             return undefined;
+        }
         summary = await summarise(summaryInput(plan));
     }
     else {
         [summary] = await Promise.all([
             summarise(summaryInput(plan)),
-            hooks && context && notify(hooks.run, "beforeCompact", context, hooks.onNote),
+            hooks && context && notify(hooks.run, HookEvent.BeforeCompact, context, hooks.onNote),
         ]);
     }
-    if (!summary.trim())
+    if (!summary.trim()) {
         return undefined;
+    }
     return { summary: summary.trim(), through: plan.cut, at: new Date().toISOString() };
 }
 /**
  * The transcript as the server should see it: the folded head replaced by its summary.
  *
- * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
- * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
- * continues these notes rather than summarising them a second time. Any earlier summary message in
- * the kept head is dropped, since the record's already contains it.
- *
- * @param messages The stored transcript, whole. Not written to.
- * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * @param messages - The stored transcript, whole. Not written to.
+ * @param [record] - The fold, or `undefined` for a session that has not been compacted, which hands
  * back `messages` itself.
- * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * @param [options] - `from` is the first message the fold was allowed to take — the plan's, for a host
  * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
  * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
  * case for a host whose system prompt is a separate argument.
+ * @returns `messages` itself when there is no record or its summary is blank, otherwise a new
+ * array: the kept head, one summary message, then everything from the record's `through` on.
+ *
+ * @remarks
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
  */
 export function applyCompaction(messages, record, { from } = {}) {
-    if (!record?.summary.trim())
+    if (!record?.summary.trim()) {
         return messages;
+    }
     const head = clamp(from ?? systemHead(messages).from, record.through);
     return [
         ...messages.slice(0, head).filter((message) => !isSummary(message)),
@@ -263,26 +331,40 @@ export function applyCompaction(messages, record, { from } = {}) {
  * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
  * everything after it.
  *
+ * @param index - The position in the stored transcript.
+ * @param [record] - The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param [head] - How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero is the stored-fold case,
+ * where the summary is the request's first message.
+ * @returns The index in the request. One before the record's `through` gives `head`, where the
+ * summary sits — an index among the kept head messages themselves included.
+ *
+ * @remarks
  * A transcript that stays append-only and a request that does not are two numberings of the same
  * conversation, and anything that names a position — `withContext`'s index, a range handed to a
  * hook — has to say which it is in. An index inside the folded stretch answers with the summary
  * message that now stands for it.
- *
- * @param index The position in the stored transcript.
- * @param record The fold in force, or `undefined` for a session that has none, which hands the
- * index straight back.
- * @param head How many messages the request keeps ahead of the summary — the leading system
- * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
- * where the summary is the request's first message.
  */
 export const requestIndex = (index, record, head = 0) => {
-    if (!record)
+    if (!record) {
         return index;
+    }
     return index < record.through ? head : index - record.through + head + 1;
 };
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *
+ * @param messages - The transcript the plan was made for. Not written to.
+ * @param plan - What `planCompaction` returned for it.
+ * @param summarise - Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
+ * @param [options] - Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
+ *
+ * @remarks
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
  * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
@@ -296,19 +378,11 @@ export const requestIndex = (index, record, head = 0) => {
  * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
  * order, so a host that stores the fold instead of the array gets the same summary at the same
  * cut rather than a second implementation that drifts from this one.
- *
- * @param messages The transcript the plan was made for. Not written to.
- * @param plan What `planCompaction` returned for it.
- * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
- * when a hook vetoes.
- * @param options Hooks to tell and whether the window is already past. See
- * `CompactionRunOptions`.
- * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
- * new array.
  */
 export async function compactTranscript(messages, plan, summarise, options = {}) {
     const record = await runCompaction(messages, plan, summarise, options);
-    if (!record)
+    if (!record) {
         return messages;
+    }
     return applyCompaction(messages, record, { from: plan.from });
 }

package/dist/config.d.ts

@@ -21,6 +21,7 @@ export interface Endpoint {
      * How long an endpoint may go quiet. Zero, less, or absent means no limit — what a local model
      * answering slowly needs.
      *
+     * @remarks
      * Not the whole request, which may take as long as the model keeps talking. On a streamed turn
      * it is the silence allowed between chunks, the idle watchdog; the wait for the first chunk is
      * `firstTokenSeconds`. On a call that does not stream, a side task or a model listing, it is
@@ -33,9 +34,11 @@ export interface Endpoint {
      */
     requestTimeoutSeconds?: number;
     /**
-     * How long a streamed turn may wait for its first chunk. Absent is five times
-     * `requestTimeoutSeconds`; zero or less is no limit.
+     * How long a streamed turn may wait for its first chunk. Zero or less is no limit.
      *
+     * @defaultValue `FIRST_TOKEN_FACTOR` times `requestTimeoutSeconds`
+     *
+     * @remarks
      * Its own number because the first wait is prefill, and on a local server prefill of a long
      * prompt is tens of seconds on a GPU and minutes on a CPU, where the gap between tokens is a
      * fraction of a second. A server loading the model on demand, Ollama after `keep_alive` or LM
@@ -45,6 +48,28 @@ export interface Endpoint {
      */
     firstTokenSeconds?: number;
 }
+/**
+ * What makes an endpoint the one it is: where it lives and whose key reaches it.
+ *
+ * @remarks
+ * The narrow half of `Endpoint`, for everything that only has to tell two endpoints apart — the
+ * client pool, the capability latches, a side task borrowing the agent's key. The timeouts are
+ * not in it, since a different patience is not a different server.
+ */
+export interface EndpointIdentity {
+    /** The base URL as given. Compared as written, so a trailing slash is another endpoint. */
+    baseUrl: string;
+    /** Absent and empty mean the same: no key, which `endpointKey` reads as `NO_KEY`. */
+    apiKey?: string;
+}
+/**
+ * The request fields `extraBody` may not set, because the loop's request is built around them.
+ *
+ * @remarks
+ * Here beside `extraBody` rather than with `buildBody`, which is what enforces it, because `spec`
+ * says so on import as well and has to stay loadable in a browser.
+ */
+export declare const RESERVED_BODY_FIELDS: readonly string[];
 /** What to ask the model for. */
 export interface ModelParams {
     model: string;
@@ -60,6 +85,7 @@ export interface ModelParams {
     /**
      * Request fields this interface cannot spell, merged into the body last by `buildBody`.
      *
+     * @remarks
      * What a model card asks for and nothing here names: `top_k`, `min_p`, `repeat_penalty` —
      * what actually stops a small model looping — and a server's own fields, such as llama.cpp's
      * `id_slot`, which pins a session to one slot of a `--parallel` server so its KV cache is
@@ -71,15 +97,24 @@ export interface ModelParams {
      */
     extraBody?: Record<string, unknown>;
 }
-/** How tools reach the model, and how long it may keep calling them. */
-export interface ToolPolicy {
+/** How tool definitions reach the model. See `tool-loading.ts`. */
+export declare const ToolDiscovery: {
+    /** Every tool definition, on every request. */
+    readonly Eager: 'eager';
+    /** A name-only catalogue, from which the model pulls in the schemas it needs. */
+    readonly OnDemand: 'ondemand';
     /**
-     * "eager" sends every tool definition on every request. "ondemand" sends a name-only
-     * catalogue and lets the model pull in the schemas it needs. "proxy" is the same catalogue
-     * behind a tool array that never changes — `load_tools` and `call_tool` — for a server whose
-     * prompt cache a growing tool array throws away. See `tool-loading.ts`.
+     * The same catalogue behind a tool array that never changes — `load_tools` and `call_tool` —
+     * for a server whose prompt cache a growing tool array throws away.
      */
-    toolDiscovery: "eager" | "ondemand" | "proxy";
+    readonly Proxy: 'proxy';
+};
+/** Any one of the modes in `ToolDiscovery`. */
+export type ToolDiscovery = (typeof ToolDiscovery)[keyof typeof ToolDiscovery];
+/** How tools reach the model, and how long it may keep calling them. */
+export interface ToolPolicy {
+    /** How tool definitions reach the model. */
+    toolDiscovery: ToolDiscovery;
     /** The model that does the preselection pass. Empty means don't preselect. */
     toolSelectModel: string;
     /** Hard stop on runaway tool loops. */
@@ -98,9 +133,10 @@ export interface RetryPolicy {
 /**
  * A whole agent configuration — every part, plus the two fields that belong to no group.
  *
- * Provided for callers that want one name for the lot. Nothing in this package asks for it:
- * the functions take the parts, so a caller missing `contextLength` can still use all of them
- * bar the window guard.
+ * @remarks
+ * Provided for callers that want one name for the lot. No function in this package asks for it:
+ * they take the parts, so a caller missing `contextLength` can still use all of them bar the
+ * window guard. `ResolvedAgent` extends it, which is how a resolved spec satisfies every one.
  */
 export interface AgentConfig extends Endpoint, ModelParams, ToolPolicy, RetryPolicy {
     /** The agent's own standing instruction, if it has one. */

package/dist/config.js

@@ -11,4 +11,23 @@
  * it structurally. Nothing imports a config *type* from a consumer, and no consumer has to grow
  * a field it has no use for in order to call `getClient`.
  */
-export {};
+/**
+ * The request fields `extraBody` may not set, because the loop's request is built around them.
+ *
+ * @remarks
+ * Here beside `extraBody` rather than with `buildBody`, which is what enforces it, because `spec`
+ * says so on import as well and has to stay loadable in a browser.
+ */
+export const RESERVED_BODY_FIELDS = ['model', 'messages', 'stream', 'tools'];
+/** How tool definitions reach the model. See `tool-loading.ts`. */
+export const ToolDiscovery = {
+    /** Every tool definition, on every request. */
+    Eager: 'eager',
+    /** A name-only catalogue, from which the model pulls in the schemas it needs. */
+    OnDemand: 'ondemand',
+    /**
+     * The same catalogue behind a tool array that never changes — `load_tools` and `call_tool` —
+     * for a server whose prompt cache a growing tool array throws away.
+     */
+    Proxy: 'proxy',
+};

package/dist/continuation.d.ts

@@ -1,7 +1,7 @@
-import type OpenAI from "openai";
-import { type Capabilities } from "./capabilities.ts";
-import { type RequestBuilder, type RunTurnOptions } from "./run-turn.ts";
-import type { Turn } from "./stream.ts";
+import type OpenAI from 'openai';
+import { type Capabilities } from './capabilities.ts';
+import { type RequestBuilder, type RunTurnOptions } from './run-turn.ts';
+import { type Turn } from './stream.ts';
 /**
  * Picking up an answer the token ceiling cut off, instead of keeping half of it.
  *
@@ -13,8 +13,10 @@ import type { Turn } from "./stream.ts";
 /** What `continueTurn` takes besides what `runTurn` does. */
 export interface ContinueTurnOptions extends RunTurnOptions {
     /**
-     * How many more requests one answer may be given, 1 unless given; zero continues nothing.
-     * The cap is what stops a model that never reaches a stop token from looping on the ceiling.
+     * How many more requests one answer may be given; zero continues nothing. The cap is what
+     * stops a model that never reaches a stop token from looping on the ceiling.
+     *
+     * @defaultValue `1`
      */
     maxContinuations?: number;
 }
@@ -22,18 +24,32 @@ export interface ContinueTurnOptions extends RunTurnOptions {
  * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
  * and no tool call in it.
  *
+ * @param turn - The turn as it came back.
+ * @returns False for a turn that stopped for any reason but `length`, whose content is blank, or
+ * that holds a tool call.
+ *
+ * @remarks
  * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
  * the template's business rather than something this can do the same way everywhere — llama.cpp
  * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
  * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
- *
- * @param turn The turn as it came back.
  */
 export declare const isContinuable: (turn: Turn) => boolean;
 /**
  * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
  * so far as a trailing assistant message, and joins the pieces into one turn.
  *
+ * @param client - The pooled client for this endpoint.
+ * @param supports - What the endpoint has already refused.
+ * @param request - Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn - The turn that came back cut off.
+ * @param [options] - `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ * @returns `turn` itself where nothing was joined to it; otherwise a new turn, with the last
+ * continuation's `finishReason` and tool calls.
+ *
+ * @remarks
  * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
  * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
  * across the requests with `continuations` counting them. The continuation is read as starting in
@@ -47,13 +63,5 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * that check is only as good as a restart being word for word. Either way the answer so far is
  * kept, with a notice. So is it when the continuation fails any other way, since the tokens
  * already in hand are worth more than the error; only a stop is thrown.
- *
- * @param client The pooled client for this endpoint.
- * @param supports What the endpoint has already refused.
- * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
- * prefill is appended to what it builds.
- * @param turn The turn that came back cut off.
- * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
- * latched and each continuation finds out again — and the cap on continuations.
  */
 export declare function continueTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;