@cubicecho/agent-core 4.13.0 → 4.15.0

package/README.md

@@ -768,8 +768,8 @@ distinctive than a word the catalogue shares has to have matched, and the tools
 have to score well below the ones it kept — a hit just under the line scoring nearly as much as
 one just over it means the ranking chose arbitrarily, which is the case a model is worth spending
 on. Matching nothing is not confident either, since the words cannot tell a request that needs no
-tools from one whose words are not in the catalogue. An empty `toolSelectModel` still means no
-preselection at all, words included. `preselect` also takes a `temperature` and a
+tools from one whose words are not in the catalogue. An empty model still means no preselection
+at all, words included. `preselect` also takes a `temperature` and a
 `reasoningEffort` and an `extraBody`, read as `ask` reads them, and `runAgentLoop({ preselect: true })` makes the call
 itself — see "Its side tasks" below.
 
@@ -884,10 +884,32 @@ as the host passed them, this one as typed — which is why the snippet stores o
 without waiting; a host that stores those notes with the turn, or would otherwise exit before the
 turn is remembered, awaits it once the answer is out.
 
-The loop gathers before its first request, and nothing of the host's can run beside that. A host
-with pre-turn work to overlap with the hooks — compaction, a preselection — calls `gather` itself,
-applies `withContext` to the current question as well, calls `notify` after, and passes no `hooks`
-(see [Hooks](#hooks)).
+The loop gathers before its first request, beside its own preselection when `preselect` asked for
+one, and nothing else of the host's can run beside those. A host with pre-turn work to overlap with
+the hooks — a compaction — calls `gather` itself, applies `withContext` to the current question as
+well, and calls `notify` after (see [Hooks](#hooks)). Such a host passes the question as it was
+typed as `preselectQuery` too, or the preselector is shown the context in front of it and picks
+tools for what was recalled rather than what was asked.
+
+`hooks.fire` says which events the loop fires itself, and it fires no others: `sessionStart` and
+`beforeTurn` gathered before the first request, `beforeCompact` beside each fold `compact` makes,
+`afterTurn` once answered. Left out, it is all of them — `events` (`beforeTurn` by default), then
+`afterTurn` and `beforeCompact` — which is what the loop always did. A host that fires the turn's
+events around a step of its own still hands the loop its hooks for the fold:
+
+```ts
+await runAgentLoop({
+  ...options,
+  compact: true,
+  hooks: { run, context, fire: [HookEvent.BeforeCompact] }, // beforeTurn and afterTurn are the host's
+});
+```
+
+An event left out of `fire` is one the result has nothing for: `afterTurn` is resolved and empty
+without `afterTurn`, and `notes` and `context` are empty without an injecting event, since the
+host's own `gather` and `notify` hold those. `sessionEnd` and `sessionDelete` have no point in a
+loop and are ignored there. `events` is deprecated: it is the injecting half of `fire`, and is
+ignored once `fire` is given.
 
 A host that stores its transcript — a row per message, so a crash or a stop mid-run still leaves
 readable history — gets each message as the loop appends it, and the run as it stood when the loop
@@ -1488,16 +1510,31 @@ with `tasks.compaction` writing the summary and no falling back to the main mode
 are off by default: a host that already calls `preselect` or compacts in `beforeStep` is not sent
 a second request.
 
+The preselector falls back to the main model. With neither `tasks.toolSelect` nor
+`toolSelectModel` naming one, `preselect: true` asks `config.model` on the agent's own endpoint at
+`preselect`'s defaults: a host that opted in has asked for a preselection, and an empty name is a
+setting nobody filled in. Compaction has no such fallback. A host that wants no preselection passes
+no `preselect`. A spec layer that declines the task with `model: ""` leaves it absent from the
+resolved agent, as one nobody configured is, so under `preselect: true` the main model is asked
+there too.
+
+What it asks about is the question as written: the last user message of `messages`, which the hooks'
+context never reaches because the loop puts that on the request. A host that put context on the
+question itself passes `preselectQuery`. The preselection and the hooks' `gather` run side by side,
+since neither reads the other, so asking for both costs the first request one round trip rather
+than two.
+
 What the loop picked it says twice. A `notice` event names the tools before the first `turn` event
 — `PRESELECTED_NOTICE` and then the names, comma-separated — and the result's `preselected` is the
 shortlist the run opened with, the host's own where it gave one and empty where nothing was picked.
 A run that fails carries it too, beside `loaded` and `used`.
 
-An empty `toolSelectModel` means no preselection, and says nothing about it. A host whose settings
-read `""` as "use the run's model" has to say so in the config it builds:
+Called directly, `preselect` reads an empty model as no preselection and says nothing about it; it
+is only the loop that falls back. A host calling it itself whose settings read `""` as "use the
+run's model" says so in the call:
 
 ```ts
-const config = { ...settings, toolSelectModel: settings.toolSelectModel || settings.model };
+await preselect(config, settings.toolSelectModel || settings.model, catalog, prompt, options);
 ```
 
 ```ts

package/dist/core/config.d.ts

@@ -148,7 +148,10 @@ export type ToolDiscovery = (typeof ToolDiscovery)[keyof typeof ToolDiscovery];
 export interface ToolPolicy {
     /** How tool definitions reach the model. */
     toolDiscovery: ToolDiscovery;
-    /** The model that does the preselection pass. Empty means don't preselect. */
+    /**
+     * The model that does the preselection pass. Empty means don't preselect, to `preselect` itself;
+     * `runAgentLoop`, asked to preselect, reads empty as the run's own `model`.
+     */
     toolSelectModel: string;
     /** Hard stop on runaway tool loops. */
     maxToolIterations: number;

package/dist/run/agent-loop.d.ts

@@ -43,18 +43,41 @@ export interface AgentLoopRequest {
  * The hooks a loop runs around one question. See `hooks.ts`.
  *
  * @remarks
- * 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`.
+ * The loop gathers before its first request, beside its own preselection where it was asked for
+ * one, and nothing else runs beside the two. A host with pre-turn work of its own to overlap with
+ * the hooks — a compaction — calls `gather` itself, puts the context on with `withContext`, calls
+ * `notify` after, and hands `preselectQuery` the question as it was written. It still passes
+ * `hooks` when the loop folds for it, with `fire` naming only `beforeCompact`, so what it fires
+ * itself is not fired a second time.
  */
 export interface AgentLoopHooks {
     run: HookRunner;
     /** What the hooks are told. `reply` and `turn` are filled in for `afterTurn`. */
     context: HookContext;
     /**
-     * Run before the first request.
+     * The events the loop fires, and the only ones: `sessionStart` and `beforeTurn` gathered before
+     * the first request, in the order listed; `beforeCompact` beside each fold `compact` makes; and
+     * `afterTurn` once the run has its answer. `sessionEnd` and `sessionDelete` are the host's, since
+     * the loop has no point that is either, and are ignored here.
+     *
+     * @defaultValue `events`, then `afterTurn` and `beforeCompact` — everything the loop has a point
+     * for, as it fired before this existed.
+     *
+     * @remarks
+     * For a host that fires some of them around the loop rather than inside it: one that tells
+     * `beforeTurn` and `afterTurn` around a whole step of its own, and wants only the fold's
+     * `beforeCompact` from the loop, passes `[HookEvent.BeforeCompact]`. With `afterTurn` left out the
+     * result's `afterTurn` is resolved and empty, and `notes` and `context` are empty with no
+     * injecting event listed — the host's own `gather` and `notify` hold those instead.
+     */
+    fire?: readonly HookEvent[];
+    /**
+     * Run before the first request, when `fire` is not given. Ignored beside `fire`, which says the
+     * same thing with the other events in it.
      *
      * @defaultValue `[HookEvent.BeforeTurn]`
+     * @deprecated List them in `fire` instead, with `afterTurn` and `beforeCompact` where the loop
+     * should fire those too.
      */
     events?: readonly HookEvent[];
     /**
@@ -69,7 +92,7 @@ export interface AgentLoopHooks {
      * @defaultValue The preface `configureHooks` holds.
      */
     preface?: string;
-    /** Hears each note, from before the request and from `afterTurn`. */
+    /** Hears each note, from before the request, from `beforeCompact` and from `afterTurn`. */
     onNote?: OnNote;
     /**
      * What the run's first message is numbered as in the uuids hooks are told — the host's stored
@@ -109,7 +132,8 @@ export interface AgentLoopOptions {
      * @remarks
      * `tasks` is a resolved agent's, and is read only for the side tasks the loop was asked to run:
      * `tasks.toolSelect` under `preselect` and `tasks.compaction` under `compact`. `toolSelectModel`
-     * is the flattened spelling of the first, for a host that is not on the spec.
+     * is the flattened spelling of the first, for a host that is not on the spec. With neither
+     * naming a model, `preselect` asks `model` itself; `compact` never does.
      */
     config: Endpoint & ModelParams & Pick<ToolPolicy, 'maxToolIterations'> & Partial<Pick<ToolPolicy, 'toolDiscovery' | 'toolSelectModel'>> & Partial<RetryPolicy> & {
         contextLength?: number;
@@ -200,20 +224,37 @@ export interface AgentLoopOptions {
      * The preselector is `config.tasks.toolSelect` with everything it states — its endpoint, model,
      * ceiling, temperature and reasoning effort, keyed as `taskCall` keys a task against `config` —
      * and otherwise `config.toolSelectModel` on the config's own endpoint at `preselect`'s defaults.
-     * What it is asked about is the text of the last user message. Nothing is asked in eager mode,
-     * with neither preselector named, with no user message, or when `preselected` is given — an
-     * empty one included, which is how a host says it has already decided.
+     * With neither naming a model it is `config.model` itself, on the same terms as
+     * `toolSelectModel`: a host that opted in has asked for a preselection, and an empty name is a
+     * setting nobody filled in rather than a refusal. A host that wants none passes no `preselect`.
+     *
+     * What it is asked about is `preselectQuery`, and otherwise the text of the last user message as
+     * the host gave it — the hooks' context is put on the request, never on `messages`, so the
+     * tools are picked on what was asked rather than on what was recalled. Nothing is asked in eager
+     * mode, with no question, or when `preselected` is given — an empty one included, which is how
+     * a host says it has already decided.
      *
      * `true` takes `preselect`'s defaults; an object passes `keywords` and `maxPerLoad` through.
      * Its notices arrive as `notice` events, and a preselection that fails picks nothing rather
      * than ending the run. What it picked is a notice too, `PRESELECTED_NOTICE` and the names,
-     * before the first `turn` event, and is the result's `preselected`. It runs before the hooks
-     * gather, not beside them.
+     * before the first `turn` event, and is the result's `preselected`. It runs beside the hooks'
+     * `gather` rather than before it, since neither reads what the other returns, and the first
+     * request waits for both.
      */
     preselect?: boolean | {
         keywords?: boolean | KeywordPreselectOptions;
         maxPerLoad?: number;
     };
+    /**
+     * What the loop's own preselection is asked about, in place of the last user message's text.
+     * Read only under `preselect`.
+     *
+     * @remarks
+     * For a host that gathered its hooks itself and sent the question with `withContext` already on
+     * it: the loop cannot tell the context from the question, and a preselector shown both picks
+     * tools for whatever memory recalled. Blank asks nothing, as a blank question does.
+     */
+    preselectQuery?: string;
     /**
      * Has the loop fold the transcript itself before a step, once `planCompaction` says the window
      * is filling, with the summary written by `config.tasks.compaction` on its own settings. Off by
@@ -307,7 +348,8 @@ export interface AgentLoopOptions {
      */
     onToolResult?: (result: ToolCallResult) => void;
     /**
-     * Hooks gathered onto the question before the first request, and told the reply after.
+     * Hooks gathered onto the question before the first request, and told the reply after — or
+     * whichever of those `fire` names.
      *
      * @remarks
      * Only this question is touched — the last user message of `messages` — and the context is on
@@ -447,12 +489,13 @@ export interface AgentLoopResult {
      * preselection picked it. Empty in eager mode, and where nothing was picked.
      */
     preselected: string[];
-    /** The hooks' notes from before the first request. */
+    /** The hooks' notes from before the first request. Empty where `fire` lists no injecting event. */
     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`.
+     * when no hook added any, without `hooks`, and where `fire` lists no injecting event. 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;
     /**
@@ -467,8 +510,9 @@ export interface AgentLoopResult {
      * 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.
+     * reaches `onNote` as well. Already resolved and empty without `hooks`, and where `fire` leaves
+     * `afterTurn` out — a host that tells it itself has the notes from its own `notify`. Rejects only
+     * if `onNote` throws.
      */
     afterTurn: Promise<HookNote[]>;
     /**

package/dist/run/agent-loop.js

@@ -6,7 +6,7 @@ import { charsPerTokenFor } from '../endpoint/calibration.js';
 import { capabilitiesFor, modelCapabilitiesFor, } from '../endpoint/capabilities.js';
 import { firstTokenMs, getClient, loadingMs, servedSlots, timeoutMs } from '../endpoint/client.js';
 import { CACHE_PROMPT_FIELD, SESSION_HEADER, SLOT_FIELD, slotAllocator } from '../endpoint/slots.js';
-import { HookEvent } from '../hooks/hook-events.js';
+import { HookEvent, INJECT_EVENTS } from '../hooks/hook-events.js';
 import { configureHooks, gather, notify, turnIndex, turnMessages, withContext, } from '../hooks/hooks.js';
 import { serverInstructionsPrompt } from '../tools/instructions.js';
 import { preselect } from '../tools/preselect.js';
@@ -218,17 +218,18 @@ const userText = (message) => {
  * name on its own endpoint where it does not.
  *
  * @param options - The run's options. Read for the config, the catalogue, the signal, what
- * `preselect` passes through, and the last user message, whose text is what is asked about.
+ * `preselect` passes through, and `preselectQuery` or else the last user message, whose text is
+ * what is asked about.
  * @param notice - Hears the preselector's notices, a failure among them.
- * @returns The names picked. Empty where there is no user message or its text is blank — nothing
+ * @returns The names picked. Empty where the query is blank or there is no user message — nothing
  * is asked — and where the preselection picked nothing or failed. An aborted request still rejects.
  *
  * @remarks
- * `preselect` answers an empty model with nothing, so a config that names neither asks nothing.
+ * With no preselector named the main model is asked, on the config's own endpoint.
  */
 async function chooseTools(options, notice) {
     const { config, catalog = [], signal } = options;
-    const prompt = userText(options.messages.findLast((message) => message.role === Role.User));
+    const prompt = options.preselectQuery ?? userText(options.messages.findLast((message) => message.role === Role.User));
     if (!prompt.trim()) {
         return [];
     }
@@ -239,7 +240,7 @@ async function chooseTools(options, notice) {
     };
     const selector = config.tasks?.toolSelect;
     if (!selector?.model) {
-        return preselect(config, config.toolSelectModel ?? '', catalog, prompt, asked);
+        return preselect(config, config.toolSelectModel || config.model, catalog, prompt, asked);
     }
     const call = taskCall(selector, asked, config);
     return preselect(call.endpoint, call.model, catalog, prompt, call.options);
@@ -280,6 +281,7 @@ function ownSummariser(options, notice) {
  */
 async function foldBeforeStep(transcript, reported, summarise, { options, charsPerToken, notice }) {
     const { config, hooks } = options;
+    const told = hooks && firing(hooks).beforeCompact ? hooks : undefined;
     const compactor = config.tasks?.compaction;
     const plan = planCompaction(transcript, {
         ...(typeof options.compact === 'object' ? options.compact : {}),
@@ -292,13 +294,37 @@ async function foldBeforeStep(transcript, reported, summarise, { options, charsP
         return transcript;
     }
     const folded = await compactTranscript(transcript, plan, summarise, {
-        ...(hooks ? { hooks: { run: hooks.run, context: hooks.context, onNote: hooks.onNote, offset: hooks.offset } } : {}),
+        ...(told ? { hooks: { run: told.run, context: told.context, onNote: told.onNote, offset: told.offset } } : {}),
     });
     if (folded !== transcript) {
         notice(`compacted ${plan.toSummarise.length} messages into a summary`);
     }
     return folded;
 }
+/**
+ * Which events the loop fires for these hooks, read from `fire`, or from `events` without it.
+ *
+ * @param hooks - The run's hooks.
+ * @returns The events to gather before the first request, and whether `afterTurn` and
+ * `beforeCompact` are the loop's to fire.
+ *
+ * @remarks
+ * Without `fire`, `events` goes to `gather` as it was given, unfiltered, so a host that had put
+ * something odd in it sees what it saw before. With `fire`, only the injecting events are gathered:
+ * a list that names every event is the whole of the loop's firing, and `afterTurn` gathered before
+ * the request would be the hooks told a reply that does not exist yet.
+ */
+function firing(hooks) {
+    if (!hooks.fire) {
+        return { before: hooks.events ?? [HookEvent.BeforeTurn], afterTurn: true, beforeCompact: true };
+    }
+    const fire = new Set(hooks.fire);
+    return {
+        before: [...fire].filter((event) => INJECT_EVENTS.has(event)),
+        afterTurn: fire.has(HookEvent.AfterTurn),
+        beforeCompact: fire.has(HookEvent.BeforeCompact),
+    };
+}
 /**
  * Tells the `afterTurn` hooks what was answered, with the turn it closed where the question is
  * still in the transcript.
@@ -494,6 +520,19 @@ async function runSteps(options, standing, pin) {
     // The host's own fields win over the pin's, so an explicit `cache_prompt: false` stays false.
     const extraBody = pin ? { ...pin.fields, ...config.extraBody } : config.extraBody;
     const sending = { ...config, extraBody };
+    // Started before the preselection rather than after it: neither reads the other, and in a row
+    // they cost the first request two round trips where one will do. A failing runner is a note, but
+    // a host's `onNote` that throws rejects the gather, perhaps while the preselection is still out:
+    // handled at once so that is no unhandled rejection, and still thrown below, where it always was.
+    const fired = hooks && firing(hooks);
+    const gathering = hooks
+        ? gather(hooks.run, fired?.before ?? [], hooks.context, {
+            signal,
+            onNote: hooks.onNote,
+            maxTokens: hooks.maxTokens,
+        })
+        : Promise.resolve({ context: '', notes: [] });
+    gathering.catch(() => undefined);
     const { proxied, onDemand, loaded, preselected } = await discovery(options, notice);
     const instructions = serverInstructions === false
         ? ''
@@ -531,13 +570,7 @@ async function runSteps(options, standing, pin) {
     // hooks' context with it, which is right.
     const question = messages.findLast((message) => message.role === Role.User);
     const questionAt = () => (question ? messages.indexOf(question) : -1);
-    const gathered = hooks
-        ? await gather(hooks.run, hooks.events ?? [HookEvent.BeforeTurn], hooks.context, {
-            signal,
-            onNote: hooks.onNote,
-            maxTokens: hooks.maxTokens,
-        })
-        : { context: '', notes: [] };
+    const gathered = await gathering;
     // Read once, so what the result hands back is what every step of this run said.
     const preface = hooks?.preface ?? configureHooks().preface;
     const loads = { toolsLoaded: 0, redundantLoads: 0, unknownToolNames: 0 };
@@ -722,7 +755,7 @@ async function runSteps(options, standing, pin) {
         if (isAnswer || ended) {
             // Not awaited: the answer is ready, and remembering it is not something to hold it for.
             // Handed back instead, for a host that wants its notes.
-            const afterTurn = hooks ? tellAfterTurn(hooks, messages, questionAt(), turn.content) : Promise.resolve([]);
+            const afterTurn = hooks && fired?.afterTurn ? tellAfterTurn(hooks, messages, questionAt(), turn.content) : Promise.resolve([]);
             const metrics = runMetrics(recorded, { contextLength: config.contextLength });
             let outcome = RunOutcome.Answered;
             if (ended) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "4.13.0",
+  "version": "4.15.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",