@cubicecho/agent-core 2.2.4 → 2.3.0

package/dist/index.d.ts

@@ -4,8 +4,8 @@
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
  * all of them, reading one streamed turn back into a message, answering an endpoint that
- * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
- * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * refuses one of those, one-shot calls that support a run, the host's side of lifecycle hooks,
+ * the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration,
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
@@ -14,7 +14,8 @@ export type { CatalogServer } from "./catalog.ts";
 export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, timeoutMs, } from "./client.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
-export { emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
+export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
+export { assembleContext, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
@@ -22,4 +23,4 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { estimateTokens } from "./tokens.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -4,15 +4,16 @@
  * What is here is everything that does not know what the agent is *for*: making a tool schema
  * a strict server will accept, getting tool definitions in front of a model without paying for
  * all of them, reading one streamed turn back into a message, answering an endpoint that
- * refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a
- * pooled client, and the rules about retrying. What is not here is the work — orchestration,
+ * refuses one of those, one-shot calls that support a run, the host's side of lifecycle hooks,
+ * the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration,
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
 export { errorMessage } from "./errors.js";
-export { emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
+export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
+export { assembleContext, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
@@ -20,4 +21,4 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { streamTurn, } from "./stream.js";
 export { estimateTokens } from "./tokens.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/retry.d.ts

@@ -14,6 +14,11 @@ export declare class EndpointSilent extends Error {
 /**
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
+ *
+ * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
+ * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
+ * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
+ * it was built from as `cause`.
  */
 export declare class ContextOverflow extends Error {
     readonly name = "ContextOverflow";

package/dist/retry.js

@@ -15,6 +15,11 @@ export class EndpointSilent extends Error {
 /**
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
+ *
+ * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
+ * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
+ * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
+ * it was built from as `cause`.
  */
 export class ContextOverflow extends Error {
     name = "ContextOverflow";

package/dist/run-turn.d.ts

@@ -12,6 +12,11 @@ import { type StreamTurnOptions, type Turn } from "./stream.ts";
  * The outer one is the endpoint being unreachable, busy or silent, which is not about this
  * request at all and is worth simply waiting out.
  *
+ * A request too big for the window is neither, and comes out of here as `ContextOverflow`
+ * however it was found out about — by the `contextLimit` guard below before a round trip was
+ * spent, or by the endpoint's own refusal after one. The option decides how early the caller
+ * hears, not what it hears.
+ *
  * Both are bounded by the same rule: nothing is sent again once the model has started
  * answering. The tokens are already out and on their way to whoever is watching, and a second
  * attempt would say everything twice. That is what `produced` is, one box per attempt — set by

package/dist/run-turn.js

@@ -1,6 +1,6 @@
 import { negotiate } from "./capabilities.js";
 import { errorMessage } from "./errors.js";
-import { backoffMs, ContextOverflow, compact, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+import { backoffMs, ContextOverflow, compact, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 import { streamTurn } from "./stream.js";
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -46,6 +46,19 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
             // rules in `retry.ts` — so classifying first brings a cancelled run back from the dead.
             if (produced.any || stream.signal?.aborted)
                 throw error;
+            // The endpoint's own refusal, classified here rather than left to the caller. One failure
+            // had two error types depending on an option about something else: a caller that gave a
+            // `contextLimit` got `ContextOverflow` from the guard above, and one that did not — the
+            // default — got a raw SDK error and had to know to run `isOverflow` over its message
+            // itself. `runTurn` is offered as the whole loop, so the classification this package
+            // already knows how to do belongs inside it.
+            //
+            // The original is kept as `cause`, because the endpoint's wording is the half that names
+            // the number. A rate limit borrows the same words and is not one of these — `isOverflow`
+            // rules it out, and it goes on to be retried below as the 429 it is.
+            if (!(error instanceof ContextOverflow) && isOverflow(errorMessage(error))) {
+                throw new ContextOverflow(errorMessage(error), { cause: error });
+            }
             if (attempt >= maxRetries || !isTransient(error))
                 throw error;
             const wait = backoffMs(attempt);

package/dist/side-task.js

@@ -1,6 +1,6 @@
 import OpenAI from "openai";
 import { capabilitiesFor, negotiate } from "./capabilities.js";
-import { getClient } from "./client.js";
+import { endpointKey, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
 /**
@@ -24,10 +24,10 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
 /**
  * The models that turned out not to take the hints, by endpoint and model.
  *
- * Keyed rather than global for the reason the client cache is keyed: a refusal is a fact about
- * what is on the other end, not about this process. A llama.cpp box and a cloud API are both
- * reachable from one consumer over its lifetime, and the first one's refusal must not stop the
- * second from ever being asked.
+ * Keyed rather than global for the reason the client cache is keyed, and on the same
+ * `endpointKey` it is: a refusal is a fact about what is on the other end, not about this
+ * process. A llama.cpp box and a cloud API are both reachable from one consumer over its
+ * lifetime, and the first one's refusal must not stop the second from ever being asked.
  *
  * The model belongs in the key for the same reason. One base URL is routinely many models —
  * OpenRouter, LiteLLM, vLLM serving several at once — and whether `chat_template_kwargs` reaches
@@ -38,7 +38,7 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
  * the same (endpoint, model) pair, where a run on that model can read it too.
  */
 const noHints = new Set();
-const hintKey = (baseUrl, model) => JSON.stringify([baseUrl, model]);
+const hintKey = (config, model) => JSON.stringify([endpointKey(config), model]);
 /** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
 export const resetHints = () => noHints.clear();
 /**
@@ -108,12 +108,12 @@ export async function ask(config, model, system, user, { maxTokens = 512, temper
     // whether a run or a side task found it out, and the point of latching it is that only one of
     // them has to pay for it. Nothing here sends tools or `stream_options`, so the two
     // endpoint-level flags are not in play — the model's three are the whole of what this meets.
-    const supports = capabilitiesFor(config.baseUrl);
+    const supports = capabilitiesFor(config.baseUrl, config.apiKey);
     const attempt = (hints) => negotiate(supports, (_supports, _produced, refused) => send(hints, refused), {
         model,
         onNotice,
     });
-    const key = hintKey(config.baseUrl, model);
+    const key = hintKey(config, model);
     const hints = !noHints.has(key);
     let response;
     try {

package/dist/stream.d.ts

@@ -18,8 +18,26 @@ export interface TurnUsage {
 /** One streamed turn, put back together into the shape a loop and a transcript work with. */
 export interface Turn {
     content: string;
-    toolCalls: OpenAI.ChatCompletionMessageToolCall[];
+    /**
+     * The narrower of the SDK's two tool-call shapes, because it is the only one built here — a
+     * streamed `tool_calls` delta carries a function and nothing else. Typed as the union it
+     * belongs to, every caller had to narrow before it could read `.function`, to rule out a
+     * custom call that this loop cannot produce. Still assignable wherever the union is wanted.
+     */
+    toolCalls: OpenAI.ChatCompletionMessageFunctionToolCall[];
     usage: TurnUsage;
+    /**
+     * Why the model stopped, in the endpoint's own words — `stop`, `length`, `tool_calls`, or `""`
+     * where it never said.
+     *
+     * Reported because `length` is otherwise invisible. A turn cut off at the token ceiling comes
+     * back as a well-formed `Turn` with truncated `content`, or with a tool call whose `arguments`
+     * stop mid-JSON — so the caller meets a parse failure with nothing to attribute it to. Being
+     * cut off looking whole is the same trap `throwIfAborted` below answers for the abort; this
+     * half is not an error, because the tokens are real and a caller may still want them, so it is
+     * handed over rather than raised.
+     */
+    finishReason: string;
 }
 /**
  * Whether the model has said anything a second attempt would say twice.

package/dist/stream.js

@@ -51,6 +51,7 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
         const content = [];
         const calls = new Map();
         const usage = { prompt: 0, completion: 0, total: 0 };
+        let finishReason = "";
         for await (const chunk of stream) {
             // Rearmed on every chunk, latched below on only some: a priming chunk is the endpoint
             // being alive, which is all the watchdog is asking about.
@@ -64,7 +65,15 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
                 usage.completion = chunk.usage.completion_tokens ?? 0;
                 usage.total = chunk.usage.total_tokens ?? 0;
             }
-            const delta = chunk.choices[0]?.delta;
+            // One choice, because that is what an agent loop asks for. A body with `n` above one
+            // keeps only the first; nothing here is built to reassemble several at once.
+            const choice = chunk.choices[0];
+            // Read before the delta guard rather than beside the content. The chunk that carries the
+            // reason usually carries an empty delta, and some servers send it with no delta at all —
+            // either of which the guard below skips, taking the reason with it.
+            if (choice?.finish_reason)
+                finishReason = choice.finish_reason;
+            const delta = choice?.delta;
             if (!delta)
                 continue;
             const thinking = delta.reasoning_content || delta.reasoning || "";
@@ -112,6 +121,7 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
                 function: { name: call.name, arguments: call.arguments },
             })),
             usage,
+            finishReason,
         };
     }
 }

package/dist/tool-loading.d.ts

@@ -52,6 +52,11 @@ export declare function catalogPrompt(catalog: CatalogServer[], loaded?: Readonl
  * in the position on-demand loading exists to avoid — a tool array too large to choose from.
  * Over-broad requests are refused with the matching names listed, so the next call can be
  * precise.
+ *
+ * The default rather than the rule: twelve is what a small model chooses well from, and a caller
+ * running a large one against a large window can say otherwise to `expandNames`, `preselection`
+ * and `preselectSystem`. Whatever it says is carried on the resolution, so the refusal the model
+ * reads names the number it was actually held to.
  */
 export declare const MAX_PER_LOAD = 12;
 /**
@@ -59,7 +64,7 @@ export declare const MAX_PER_LOAD = 12;
  * conversation runs; least-recently-used names fall off the front.
  *
  * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
- * carry. See `carryOver`.
+ * carry. See `carryOver`, which takes another number if this one is not yours.
  */
 export declare const MAX_CARRIED = 16;
 /**
@@ -67,8 +72,10 @@ export declare const MAX_CARRIED = 16;
  *
  * @param previous Last turn's names, oldest first.
  * @param used What this turn called. Moved to the end, so the oldest unused fall off.
+ * @param max How many to carry, defaulting to `MAX_CARRIED`. At least one: a cap of zero is
+ * read as no cap, which is what `slice` does with it and not what anybody asking for zero meant.
  */
-export declare const carryOver: (previous: string[], used: Set<string>) => string[];
+export declare const carryOver: (previous: string[], used: Set<string>, max?: number) => string[];
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
  *
@@ -80,8 +87,10 @@ export declare const carryOver: (previous: string[], used: Set<string>) => strin
  *
  * @param requested What the model asked for. A trailing `*` expands.
  * @param catalog The servers to resolve against.
+ * @param maxPerLoad The most this call may load, defaulting to `MAX_PER_LOAD`. It comes back on
+ * the resolution so `loadResult` reports the same number rather than a second opinion of it.
  */
-export declare function expandNames(requested: string[], catalog: CatalogServer[]): {
+export declare function expandNames(requested: string[], catalog: CatalogServer[], maxPerLoad?: number): {
     matched: string[];
     unknown: string[];
     overBroad: {
@@ -89,6 +98,7 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
         hits: string[];
     }[];
     deferred: string[];
+    maxPerLoad: number;
 };
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
@@ -96,7 +106,7 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
  * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
  * @param catalog The servers, read for the descriptions now worth their tokens.
  */
-export declare function loadResult({ matched, unknown, overBroad, deferred }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
+export declare function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
 /**
  * Whether the catalogue holds a tool by this name.
  *
@@ -111,7 +121,7 @@ export declare const inCatalog: (catalog: CatalogServer[], name: string) => bool
  */
 export declare function requestedNames(args: Record<string, unknown>): string[];
 /**
- * Tool preselection.
+ * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *
  * On-demand loading otherwise costs a round trip every run: the model reads the catalogue,
  * calls `load_tools`, and only then can do the work. A small model reading the same catalogue
@@ -119,22 +129,32 @@ export declare function requestedNames(args: Record<string, unknown>): string[];
  * starts working on its first step.
  *
  * A wrong guess is cheap — an unused definition is a few hundred tokens for one run — but a
- * broad guess is not, so the same `MAX_PER_LOAD` cap applies here as to a `load_tools` call.
+ * broad guess is not, so the same cap applies here as to a `load_tools` call.
+ *
+ * @param maxPerLoad The most to ask for, defaulting to `MAX_PER_LOAD`. Give `preselection` the
+ * same number: this one is what the preselector is told, and that one is what it is held to.
  */
+export declare const preselectSystem: (maxPerLoad?: number) => string;
+/** The preselection system prompt at the default cap, for a caller that never changes it. */
 export declare const PRESELECT_SYSTEM: string;
 /**
  * The user message for a preselection call: the catalogue, then the request.
  *
  * @param catalog The connected servers, rendered as the name-only listing.
- * @param prompt The request being planned for, truncated at 2000 characters — choosing tools
- * needs the shape of the ask, not all of it.
+ * @param prompt The request being planned for, truncated — choosing tools needs the shape of the
+ * ask, not all of it.
+ * @param maxPromptChars Where the request is cut, defaulting to 2000. A caller whose requests
+ * carry the part that names the work at the end wants a larger one, and pays for it in the
+ * preselector's prompt.
  */
-export declare const preselectInput: (catalog: CatalogServer[], prompt: string) => string;
+export declare const preselectInput: (catalog: CatalogServer[], prompt: string, maxPromptChars?: number) => string;
 /**
  * Resolves a preselection against the catalogue: unknown names dropped, count capped.
  *
  * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
  * that are not strings are dropped.
  * @param catalog The servers to resolve against.
+ * @param maxPerLoad The most to keep, defaulting to `MAX_PER_LOAD`. The same number
+ * `preselectSystem` was given, or the model is being held to a cap it was never told about.
  */
-export declare function preselection(names: unknown, catalog: CatalogServer[]): string[];
+export declare function preselection(names: unknown, catalog: CatalogServer[], maxPerLoad?: number): string[];

package/dist/tool-loading.js

@@ -103,6 +103,11 @@ const flatten = (catalog) => catalog.flatMap((server) => server.tools);
  * in the position on-demand loading exists to avoid — a tool array too large to choose from.
  * Over-broad requests are refused with the matching names listed, so the next call can be
  * precise.
+ *
+ * The default rather than the rule: twelve is what a small model chooses well from, and a caller
+ * running a large one against a large window can say otherwise to `expandNames`, `preselection`
+ * and `preselectSystem`. Whatever it says is carried on the resolution, so the refusal the model
+ * reads names the number it was actually held to.
  */
 export const MAX_PER_LOAD = 12;
 /**
@@ -110,7 +115,7 @@ export const MAX_PER_LOAD = 12;
  * conversation runs; least-recently-used names fall off the front.
  *
  * Only a multi-turn caller needs this — a run that starts from nothing each time has nothing to
- * carry. See `carryOver`.
+ * carry. See `carryOver`, which takes another number if this one is not yours.
  */
 export const MAX_CARRIED = 16;
 /**
@@ -118,8 +123,10 @@ export const MAX_CARRIED = 16;
  *
  * @param previous Last turn's names, oldest first.
  * @param used What this turn called. Moved to the end, so the oldest unused fall off.
+ * @param max How many to carry, defaulting to `MAX_CARRIED`. At least one: a cap of zero is
+ * read as no cap, which is what `slice` does with it and not what anybody asking for zero meant.
  */
-export const carryOver = (previous, used) => [...previous.filter((name) => !used.has(name)), ...used].slice(-MAX_CARRIED);
+export const carryOver = (previous, used, max = MAX_CARRIED) => [...previous.filter((name) => !used.has(name)), ...used].slice(-Math.max(1, max));
 /**
  * Resolves requested names against the catalogue, expanding trailing `*` wildcards.
  *
@@ -131,8 +138,10 @@ export const carryOver = (previous, used) => [...previous.filter((name) => !used
  *
  * @param requested What the model asked for. A trailing `*` expands.
  * @param catalog The servers to resolve against.
+ * @param maxPerLoad The most this call may load, defaulting to `MAX_PER_LOAD`. It comes back on
+ * the resolution so `loadResult` reports the same number rather than a second opinion of it.
  */
-export function expandNames(requested, catalog) {
+export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
     const all = flatten(catalog);
     const matched = new Set();
     const unknown = [];
@@ -179,15 +188,15 @@ export function expandNames(requested, catalog) {
         // enough already — telling a model that asked for one exact tool that it matches one tool,
         // "more than the twelve one call may load", and to choose from a list holding just that
         // name, leaves it nothing to do but send the identical call again.
-        if (fresh.length > MAX_PER_LOAD)
+        if (fresh.length > maxPerLoad)
             overBroad.push({ name, hits });
-        else if (matched.size + fresh.length > MAX_PER_LOAD)
+        else if (matched.size + fresh.length > maxPerLoad)
             deferred.push(name);
         else
             for (const hit of hits)
                 matched.add(hit);
     }
-    return { matched: [...matched], unknown, overBroad, deferred };
+    return { matched: [...matched], unknown, overBroad, deferred, maxPerLoad };
 }
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
@@ -195,7 +204,7 @@ export function expandNames(requested, catalog) {
  * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
  * @param catalog The servers, read for the descriptions now worth their tokens.
  */
-export function loadResult({ matched, unknown, overBroad, deferred }, catalog) {
+export function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }, catalog) {
     const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
     const lines = [];
     if (matched.length) {
@@ -206,12 +215,12 @@ export function loadResult({ matched, unknown, overBroad, deferred }, catalog) {
     for (const { name, hits } of overBroad) {
         if (lines.length)
             lines.push("");
-        lines.push(`\`${name}\` matches ${hits.length} tools, more than the ${MAX_PER_LOAD} one call may load.`, "Name the ones you need from:", ...hits.map((hit) => `  ${hit}`));
+        lines.push(`\`${name}\` matches ${hits.length} tools, more than the ${maxPerLoad} one call may load.`, "Name the ones you need from:", ...hits.map((hit) => `  ${hit}`));
     }
     if (deferred.length) {
         if (lines.length)
             lines.push("");
-        lines.push(`This call is full at ${MAX_PER_LOAD} tools, so these were not loaded: ${deferred.join(", ")}.`, "Ask for them on your next step.");
+        lines.push(`This call is full at ${maxPerLoad} tools, so these were not loaded: ${deferred.join(", ")}.`, "Ask for them on your next step.");
     }
     if (unknown.length) {
         if (lines.length)
@@ -241,7 +250,15 @@ export function requestedNames(args) {
     return [];
 }
 /**
- * Tool preselection.
+ * Where a request is cut for the preselector, in characters.
+ *
+ * A tool choice is made on what the work is, which is the top of a request rather than all of
+ * it — and the whole of a long one is paid for again in the preselection call. `preselectInput`
+ * takes another number for a caller whose requests are not shaped that way.
+ */
+const PRESELECT_PROMPT_CHARS = 2000;
+/**
+ * The system prompt a preselector is given, holding it to the cap its answer will be held to.
  *
  * On-demand loading otherwise costs a round trip every run: the model reads the catalogue,
  * calls `load_tools`, and only then can do the work. A small model reading the same catalogue
@@ -249,30 +266,40 @@ export function requestedNames(args) {
  * starts working on its first step.
  *
  * A wrong guess is cheap — an unused definition is a few hundred tokens for one run — but a
- * broad guess is not, so the same `MAX_PER_LOAD` cap applies here as to a `load_tools` call.
+ * broad guess is not, so the same cap applies here as to a `load_tools` call.
+ *
+ * @param maxPerLoad The most to ask for, defaulting to `MAX_PER_LOAD`. Give `preselection` the
+ * same number: this one is what the preselector is told, and that one is what it is held to.
  */
-export const PRESELECT_SYSTEM = "You choose tools. Below is a catalogue of tool names, then a request. Reply with a JSON " +
+export const preselectSystem = (maxPerLoad = MAX_PER_LOAD) => "You choose tools. Below is a catalogue of tool names, then a request. Reply with a JSON " +
     "array of the names the request is likely to need — exact names from the catalogue, at most " +
-    `${MAX_PER_LOAD}, and as few as could do the job. Reply with \`[]\` if the request can be ` +
+    `${maxPerLoad}, and as few as could do the job. Reply with \`[]\` if the request can be ` +
     "answered without tools. Reply with the array alone — no prose, no explanation.";
+/** The preselection system prompt at the default cap, for a caller that never changes it. */
+export const PRESELECT_SYSTEM = preselectSystem();
 /**
  * The user message for a preselection call: the catalogue, then the request.
  *
  * @param catalog The connected servers, rendered as the name-only listing.
- * @param prompt The request being planned for, truncated at 2000 characters — choosing tools
- * needs the shape of the ask, not all of it.
+ * @param prompt The request being planned for, truncated — choosing tools needs the shape of the
+ * ask, not all of it.
+ * @param maxPromptChars Where the request is cut, defaulting to 2000. A caller whose requests
+ * carry the part that names the work at the end wants a larger one, and pays for it in the
+ * preselector's prompt.
  */
-export const preselectInput = (catalog, prompt) => `# Tool catalogue\n\n${catalogList(catalog)}\n\n# Request\n\n${prompt.slice(0, 2000)}`;
+export const preselectInput = (catalog, prompt, maxPromptChars = PRESELECT_PROMPT_CHARS) => `# Tool catalogue\n\n${catalogList(catalog)}\n\n# Request\n\n${prompt.slice(0, maxPromptChars)}`;
 /**
  * Resolves a preselection against the catalogue: unknown names dropped, count capped.
  *
  * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
  * that are not strings are dropped.
  * @param catalog The servers to resolve against.
+ * @param maxPerLoad The most to keep, defaulting to `MAX_PER_LOAD`. The same number
+ * `preselectSystem` was given, or the model is being held to a cap it was never told about.
  */
-export function preselection(names, catalog) {
+export function preselection(names, catalog, maxPerLoad = MAX_PER_LOAD) {
     if (!Array.isArray(names))
         return [];
     const wanted = names.filter((name) => typeof name === "string");
-    return expandNames(wanted, catalog).matched.slice(0, MAX_PER_LOAD);
+    return expandNames(wanted, catalog, maxPerLoad).matched.slice(0, maxPerLoad);
 }

package/llms.txt

@@ -2,7 +2,7 @@
 
 > The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.
 
-What is here is everything that does not know what the agent is *for*: making a tool schema a strict server will accept, getting tool definitions in front of a model without paying for all of them, reading one streamed turn back into a message, answering an endpoint that refuses one of those, one-shot calls that support a run, the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration, prompts, and whatever the run is about — because that is the caller's, and it is the part that differs between one server and the next.
+What is here is everything that does not know what the agent is *for*: making a tool schema a strict server will accept, getting tool definitions in front of a model without paying for all of them, reading one streamed turn back into a message, answering an endpoint that refuses one of those, one-shot calls that support a run, the host's side of lifecycle hooks, the event bus a watcher reads, a pooled client, and the rules about retrying. What is not here is the work — orchestration, prompts, and whatever the run is about — because that is the caller's, and it is the part that differs between one server and the next.
 
 Requires Node >=22, with `openai` >=6 as a peer dependency. ESM only.
 Full prose, worked examples and the reasoning behind each seam are in README.md; this file is the index.
@@ -55,6 +55,8 @@ What this package needs to know about a caller's configuration.
 
 What a run is doing, while it is doing it.
 
+- `configureEvents` — Changes what the bus keeps, for a process whose runs are not shaped like the ones these defaults were chosen for.
+- `EventBusOptions` (type) — What the bus keeps and for how long.
 - `emit` — Records one event and hands it to everyone watching that run.
 - `endRun` — Forgets a run that will not be emitting `done` — one whose process is tearing down, or whose loop threw where it could not be caught.
 - `fold` — Consecutive tokens of one kind are one thing being said, not hundreds of things.
@@ -66,6 +68,28 @@ What a run is doing, while it is doing it.
 - `resetEvents` — Test seam: forget every run, so one test's events cannot be read by the next.
 - `watch` — Everything that has happened on a run, then everything that happens next, until it ends.
 
+### hooks
+
+Lifecycle hooks, from the host's side: what a session looks like to them, where their context lands in a request, and what is said about each one.
+
+- `assembleContext` — Builds the context a set of outcomes adds and the notes that go with it.
+- `Gathered` (type) — The context a set of outcomes adds to a request, and a note for each hook worth mentioning.
+- `gather` — Runs the hooks ahead of a request and builds what they add to it.
+- `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them, in estimated tokens.
+- `HOOK_EVENTS` — Every event a hook can be bound to, in the order a session meets them.
+- `HOOK_PREFACE` — Said once, above the blocks, so the model reads them as background rather than instructions.
+- `HookContext` (type) — What a host knows at an event.
+- `HookEvent` (type) — A point in a session a hook can be bound to.
+- `HookMessage` (type) — One message of a session as a hook is handed it.
+- `HookNote` (type) — One hook's line for whoever is watching: the context it added, or why it added none.
+- `HookOutcome` (type) — What one hook did.
+- `HookRunner` (type) — Runs one event's hooks.
+- `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
+- `notify` — Runs the hooks for an event that reads what happened and adds nothing to a request.
+- `turnIndex` — Which turn of a session begins at a point, from 0: the user messages ahead of it.
+- `turnMessages` — A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing else.
+- `withContext` — The request, with the hooks' context added to this turn's question.
+
 ### reset
 
 - `resetAll` — Forgets everything this package remembers between calls.
@@ -137,7 +161,8 @@ Reading one streamed turn back into a message.
 - `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
 - `MAX_CARRIED` — The most a conversation carries between turns.
 - `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.
-- `PRESELECT_SYSTEM` — Tool preselection.
+- `PRESELECT_SYSTEM` — The preselection system prompt at the default cap, for a caller that never changes it.
 - `preselectInput` — The user message for a preselection call: the catalogue, then the request.
 - `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.
+- `preselectSystem` — The system prompt a preselector is given, holding it to the cap its answer will be held to.
 - `requestedNames` — `load_tools` arguments, defensively — a model may send a bare string or a nested object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",