@cubicecho/agent-core 2.2.4 → 2.4.0

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,31 @@ 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.
+- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for.
+- `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 by default, 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.
+- `HookOptions` (type) — What hooks are held to across a process.
+- `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.
+- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+- `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 +164,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.4.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",