@cubicecho/agent-core 2.18.1 → 2.20.0

package/dist/agent-loop.d.ts

@@ -4,6 +4,7 @@ import type { CatalogServer } from "./catalog.ts";
 import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts";
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
+import { type TokenLedger } from "./ledger.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
 import { type KeywordPreselectOptions, type ToolOrder } from "./tool-loading.ts";
 /**
@@ -97,22 +98,76 @@ export declare function preselect(config: Endpoint, model: string, catalog: Cata
      */
     keywords?: boolean | KeywordPreselectOptions;
 }): Promise<string[]>;
-/** One call the model made, as `dispatch` is handed it. */
+/**
+ * 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. */
+    /**
+     * 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. */
+    /**
+     * 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;
 }
-/** The hooks a loop runs around one question. See `hooks.ts`. */
+/**
+ * One step's request as `onRequest` is handed it: what the model is about to read.
+ *
+ * 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.
+ */
+export interface AgentLoopRequest {
+    /** The messages as sent, system prompt first. The request's own array, not a copy. */
+    messages: readonly OpenAI.ChatCompletionMessageParam[];
+    /** The tools as sent: ordered, sanitised, relaxed where the endpoint needs it. Empty for none. */
+    tools: readonly OpenAI.ChatCompletionTool[];
+    /** 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`.
+ *
+ * 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`.
+ */
 export interface AgentLoopHooks {
     run: HookRunner;
     /** What the hooks are told. `reply` and `turn` are filled in for `afterTurn`. */
@@ -126,26 +181,47 @@ export interface AgentLoopHooks {
     /** Hears each note, from before the request and from `afterTurn`. */
     onNote?: (note: HookNote) => void;
 }
+/** How full the window is as a step is about to be sent, as `beforeStep` is told it. */
+export interface StepWindow {
+    /**
+     * The prompt tokens this run's last request reported. Absent before the first step — an earlier
+     * run's figure is the host's to vouch for, since the transcript may have been folded since —
+     * and where that request reported none. It does not count the reply and tool results added
+     * since.
+     */
+    used?: number;
+    /** The model's window, `config.contextLength`. Zero where the config names none. */
+    limit: number;
+    /** The run's ledger so far, indexed into the transcript `beforeStep` is handed beside it. */
+    ledger: TokenLedger;
+}
 /** 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.
+     * `"proxy"` is on-demand loading behind a tool array that never changes; see `PROXY_TOOLS`.
      */
     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. */
+    /**
+     * The standing instruction, sent as the first message. On-demand and proxied modes append the
+     * catalogue, each in its own wording.
+     */
     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.
+     * loaded so far, by name; proxied mode declares none, and answers a load with them instead.
      */
     tools?: OpenAI.ChatCompletionTool[];
-    /** The same tools as a name-only catalogue. On-demand mode needs it, and is eager without it. */
+    /**
+     * The same tools as a name-only catalogue. On-demand and proxied modes need it, and are eager
+     * without it.
+     */
     catalog?: CatalogServer[];
     /**
      * How the declared tools are ordered before each request. By name unless told otherwise, so a
@@ -156,10 +232,38 @@ export interface AgentLoopOptions {
     /**
      * 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.
+     * has or picks a sibling. Everything comes back on the step after. `preselectRouting` trades
+     * that for a first step shaped like the rest.
+     *
+     * 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
+     * `messages` like any other, reported as a `tool-call` and a `tool-result` event and told to
+     * `onToolCall` and `onToolResult`. Names with no definition in `tools`, or outside the
+     * catalogue, are left out, and none left is no exchange.
      */
     preselected?: readonly string[];
-    /** Tools already loaded, carried from an earlier question. See `carryOver`. */
+    /**
+     * What a preselection does to the first step. `"exclusive"`, the default, 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
+     * sends the first step like any other: the catalogue, `load_tools`, what `loaded` carried, then
+     * the shortlist after it, with a name already carried left where it is. The price is the menu
+     * back in front of the model. Which costs more has not been measured, which is why the default
+     * has not moved.
+     *
+     * 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";
+    /**
+     * 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>;
@@ -184,13 +288,49 @@ export interface AgentLoopOptions {
      * `idempotentHint` annotations can answer it; nothing in an OpenAI tool definition can.
      */
     dedupeToolCalls?: boolean | ((call: ToolCallRequest) => boolean);
-    /** Hooks gathered onto the question before the first request, and told the reply after. */
+    /**
+     * Told of every call the model made, as it starts — the ones `dispatch` never sees included:
+     * `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`.
+     *
+     * 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.
+     */
+    onToolCall?: (call: ToolCallRequest) => void;
+    /**
+     * Told of every call's answer as it lands, whole, under the id `onToolCall` announced it by.
+     *
+     * 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.
+     * Not awaited: a promise it returns is dropped.
+     */
+    onToolResult?: (result: ToolCallResult) => void;
+    /**
+     * Hooks gathered onto the question before the first request, and told the reply after.
+     *
+     * 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
+     * put them back with `withContext` on every later call. A question sent bare that was first
+     * sent with context is a different prompt from that message on, and the server's prefix cache
+     * is lost behind it on every turn.
+     */
     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.
+     * compact or prune a run that has grown into its window. Returning nothing keeps it. `window`
+     * is what `planCompaction` wants to know, so a host need not track usage itself to compact
+     * mid-run.
+     */
+    beforeStep?: (messages: readonly OpenAI.ChatCompletionMessageParam[], step: number, window: StepWindow) => OpenAI.ChatCompletionMessageParam[] | undefined | Promise<OpenAI.ChatCompletionMessageParam[] | undefined>;
+    /**
+     * The ledger an earlier run handed back for this transcript, to be continued. Its indexes have
+     * to be into `messages` as given here — see `rebaseLedger` for a transcript rewritten since.
+     * This run's requests start a new epoch, because the loop cannot see whether the request before
+     * its first one had the same system prompt and tools. Absent starts an empty one.
      */
-    beforeStep?: (messages: readonly OpenAI.ChatCompletionMessageParam[], step: number) => OpenAI.ChatCompletionMessageParam[] | undefined | Promise<OpenAI.ChatCompletionMessageParam[] | undefined>;
+    ledger?: TokenLedger;
     /** 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. */
@@ -202,6 +342,16 @@ export interface AgentLoopOptions {
      * the answer. See `recoverToolCalls`.
      */
     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.
+     *
+     * 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
+     * far on the end, and neither is reported.
+     */
+    onRequest?: (request: AgentLoopRequest) => void;
     /** Each turn as it comes back, before its tools run. Recovered calls are in it as calls. */
     onTurn?: (turn: Turn, step: number) => void;
     /**
@@ -219,19 +369,54 @@ export interface AgentLoopResult {
     messages: OpenAI.ChatCompletionMessageParam[];
     /** Summed over every turn of the run. */
     usage: TurnUsage;
-    /** Every call, `load_tools` included, in the order they were made. */
+    /**
+     * Every call, `load_tools` included, in the order they were made, each under its call id — a
+     * proxied preselection's among them, first.
+     */
     toolCalls: ToolCallOutcome[];
-    /** What is loaded at the end, for `carryOver`. Empty in eager mode. */
+    /**
+     * What is loaded at the end, for `carryOver`. Empty in eager mode, and in proxied mode: a
+     * definition loaded there is already in the history, and one a compaction folded away has to be
+     * loadable again rather than answered "already loaded".
+     */
     loaded: string[];
-    /** The tools the model actually called, `load_tools` excluded. */
+    /** The tools the model actually called, `load_tools` excluded and `call_tool` looked through. */
     used: string[];
     /** The hooks' notes from before the first request. */
     notes: HookNote[];
+    /**
+     * The `<context>` blocks the hooks added to this question, as `withContext` takes them. Empty
+     * when no hook added any, and without `hooks`. Not in `messages`, so a host that wants the next
+     * turn's request to begin with this one's stores it beside the question; see `hooks`.
+     */
+    context: string;
+    /**
+     * What was said above `context`: the hooks' own `preface`, or what `configureHooks` had set when
+     * the run began. Handed back because the second is not the host's to know later — with it,
+     * `withContext(messages, at, context, preface)` is the question as it was sent, whatever the
+     * process's preface has since become. Empty when the preface was turned off; with no `context`
+     * nothing was said either way, and `withContext` adds nothing.
+     */
+    preface: string;
+    /**
+     * The `afterTurn` hooks' notes, once they have run — failures only, as `notify` returns them.
+     * The loop does not wait for it, so the answer is never held for a hook; a host that stores the
+     * notes with the turn, or must not exit before the turn is remembered, awaits it. Each note
+     * reaches `onNote` as well. Already resolved and empty without `hooks`, and rejects only if
+     * `onNote` throws.
+     */
+    afterTurn: Promise<HookNote[]>;
     /**
      * The run summed and derived: what `runMetrics` makes of the events this loop emitted, plus the
      * `load_tools` findings only the loop sees, `wallMs` from the call to the return, and `outcome`.
      */
     metrics: RunMetrics;
+    /**
+     * What each step's request reported its prompt as, indexed into `messages` above, for
+     * `tokensBetween` and `estimateFrom`. The entries of a `ledger` passed in come first. A step
+     * whose prompt was not reported has no entry.
+     */
+    ledger: TokenLedger;
 }
 /**
  * Runs a question to its answer: one `runTurn` per step, the tools it asks for between them,
@@ -242,10 +427,25 @@ export interface AgentLoopResult {
  * prompt unchanged from step to step, a load adds to the tool array — which every request sends
  * in the stable order `toolOrder` asks for — and
  * 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 — or, given `maxContinuations`, is
+ * preselection shapes the first step unless `preselectRouting` says to append it. A turn cut off
+ * at `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
  * continued first. Every turn ends in a `usage` event carrying the turn's own report, with the
- * cache compared against the request before it; see `TurnUsage` and `runMetrics`.
+ * cache compared against the request before it and the request broken down by what filled it; see
+ * `TurnUsage` and `runMetrics`.
+ *
+ * Each step's reported prompt goes on a token ledger, in the same epoch as the step before where
+ * the request only appended to it and in a new one where it did not — a `beforeStep` that rewrote
+ * the transcript, a tool array a load grew — so that what the messages between two steps cost can
+ * be read back as a subtraction. The prompt recorded is the first request's, before any
+ * continuation, and a step that reported none, or reported a cache count above its prompt, is not
+ * recorded. The ledger comes back in the result and on every `usage` event; see `tokensBetween`.
+ *
+ * Proxied discovery is the same catalogue behind a tool array that never moves: every step
+ * declares `PROXY_TOOLS` and nothing else, a load answers with the definitions themselves, and a
+ * `call_tool` is dispatched, counted and reported as the tool it names. A preselection has no
+ * tool array to go into, so it is written into the transcript as a `load_tools` exchange after
+ * the question. `call_tool` is honoured on demand too, unless the host has a tool of that name —
+ * a session switched out of proxied mode still has it in its history, and the model copies it.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.