@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/guards.d.ts

@@ -3,20 +3,51 @@
  *
  * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
  * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
- * its own copy.
+ * its own copy. `getOrCreate` and `counted` are here for the same reason and are the two things that
+ * are not checks: every cache in the package fills itself on a miss, and each had written that
+ * out, and a notice that counts something is written in more than one module.
  */
 /**
  * Whether a value is a plain keyed object: not null, and not an array.
  *
- * @param value Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ * @param value - Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ * @returns True for anything else `typeof` calls an object — a `Date`, a `Map` and a class
+ * instance included, since the prototype is not looked at.
  */
 export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
 /**
  * Whether a value is a number above zero, which is what a limit has to be to be one.
  *
+ * @param value - Anything, usually a setting that may be absent, zero or mistyped.
+ * @returns True only for a `number` greater than zero: a numeric string or a `bigint` is not one.
+ *
+ * @remarks
  * `Infinity` passes and `NaN` does not, so a caller lifting a bound and one handing over a
  * half-built config are told apart without either being asked.
- *
- * @param value Anything, usually a setting that may be absent, zero or mistyped.
  */
 export declare const isPositive: (value: unknown) => value is number;
+/** What `getOrCreate` needs of a map, so a `WeakMap` serves as well as a `Map`. */
+interface Lookup<K, V> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): unknown;
+}
+/**
+ * What a map holds under a key, made and stored first where it holds nothing.
+ *
+ * @param map - Where to look. Gains an entry on a miss, which is the point of calling this.
+ * @param key - What to look under.
+ * @param create - Builds the value on a miss, and is not called on a hit. A stored `undefined`
+ * reads as a miss, so one that returns it is called every time.
+ * @returns What the map holds under the key afterwards: the held value itself on a hit, what
+ * `create` returned on a miss.
+ */
+export declare function getOrCreate<K, V>(map: Lookup<K, V>, key: K, create: () => V): V;
+/**
+ * A count and its noun, plural unless the count is one: `1 tool`, `3 tools`.
+ *
+ * @param count - How many.
+ * @param noun - The singular, which takes an `s` and nothing cleverer.
+ * @returns The phrase. Only a count of exactly one is singular: zero reads `0 tools`.
+ */
+export declare const counted: (count: number, noun: string) => string;
+export {};

package/dist/guards.js

@@ -3,20 +3,53 @@
  *
  * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
  * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
- * its own copy.
+ * its own copy. `getOrCreate` and `counted` are here for the same reason and are the two things that
+ * are not checks: every cache in the package fills itself on a miss, and each had written that
+ * out, and a notice that counts something is written in more than one module.
  */
 /**
  * Whether a value is a plain keyed object: not null, and not an array.
  *
- * @param value Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ * @param value - Anything, usually just parsed. An array is an object to `typeof` and not to this.
+ * @returns True for anything else `typeof` calls an object — a `Date`, a `Map` and a class
+ * instance included, since the prototype is not looked at.
  */
-export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * Whether a value is a number above zero, which is what a limit has to be to be one.
  *
+ * @param value - Anything, usually a setting that may be absent, zero or mistyped.
+ * @returns True only for a `number` greater than zero: a numeric string or a `bigint` is not one.
+ *
+ * @remarks
  * `Infinity` passes and `NaN` does not, so a caller lifting a bound and one handing over a
  * half-built config are told apart without either being asked.
+ */
+export const isPositive = (value) => typeof value === 'number' && value > 0;
+/**
+ * What a map holds under a key, made and stored first where it holds nothing.
+ *
+ * @param map - Where to look. Gains an entry on a miss, which is the point of calling this.
+ * @param key - What to look under.
+ * @param create - Builds the value on a miss, and is not called on a hit. A stored `undefined`
+ * reads as a miss, so one that returns it is called every time.
+ * @returns What the map holds under the key afterwards: the held value itself on a hit, what
+ * `create` returned on a miss.
+ */
+export function getOrCreate(map, key, create) {
+    const held = map.get(key);
+    if (held !== undefined) {
+        return held;
+    }
+    const made = create();
+    map.set(key, made);
+    return made;
+}
+/**
+ * A count and its noun, plural unless the count is one: `1 tool`, `3 tools`.
  *
- * @param value Anything, usually a setting that may be absent, zero or mistyped.
+ * @param count - How many.
+ * @param noun - The singular, which takes an `s` and nothing cleverer.
+ * @returns The phrase. Only a count of exactly one is singular: zero reads `0 tools`.
  */
-export const isPositive = (value) => typeof value === "number" && value > 0;
+export const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;

package/dist/hook-events.d.ts

@@ -7,12 +7,28 @@
  * one pair together and nothing holding the other.
  */
 /**
- * A point in a session a hook can be bound to. Named after Claude Code's hooks of the same shape
- * — `sessionStart` (SessionStart), `beforeTurn` (UserPromptSubmit), `afterTurn` (Stop),
- * `beforeCompact` (PreCompact), `sessionEnd` (SessionEnd) — plus `sessionDelete`, for when the host
- * deletes a session's record.
+ * The points in a session a hook can be bound to, in the order a session meets them.
+ *
+ * @remarks
+ * Named after Claude Code's hooks of the same shape, which each member names, plus
+ * `sessionDelete`, which has no counterpart there.
  */
-export type HookEvent = "sessionStart" | "beforeTurn" | "afterTurn" | "beforeCompact" | "sessionEnd" | "sessionDelete";
+export declare const HookEvent: {
+    /** A session opened. Claude Code's SessionStart. */
+    readonly SessionStart: 'sessionStart';
+    /** A turn is about to be requested. Claude Code's UserPromptSubmit. */
+    readonly BeforeTurn: 'beforeTurn';
+    /** A turn was answered. Claude Code's Stop. */
+    readonly AfterTurn: 'afterTurn';
+    /** Part of the transcript is about to be summarised away. Claude Code's PreCompact. */
+    readonly BeforeCompact: 'beforeCompact';
+    /** A session closed. Claude Code's SessionEnd. */
+    readonly SessionEnd: 'sessionEnd';
+    /** The host deleted a session's record. */
+    readonly SessionDelete: 'sessionDelete';
+};
+/** Any one of the events in `HookEvent`. */
+export type HookEvent = (typeof HookEvent)[keyof typeof HookEvent];
 /** Every event a hook can be bound to, in the order a session meets them. */
 export declare const HOOK_EVENTS: readonly HookEvent[];
 /**

package/dist/hook-events.js

@@ -6,17 +6,31 @@
  * has to stay importable in a browser. Before this each kept its own copy, with a test holding
  * one pair together and nothing holding the other.
  */
+/**
+ * The points in a session a hook can be bound to, in the order a session meets them.
+ *
+ * @remarks
+ * Named after Claude Code's hooks of the same shape, which each member names, plus
+ * `sessionDelete`, which has no counterpart there.
+ */
+export const HookEvent = {
+    /** A session opened. Claude Code's SessionStart. */
+    SessionStart: 'sessionStart',
+    /** A turn is about to be requested. Claude Code's UserPromptSubmit. */
+    BeforeTurn: 'beforeTurn',
+    /** A turn was answered. Claude Code's Stop. */
+    AfterTurn: 'afterTurn',
+    /** Part of the transcript is about to be summarised away. Claude Code's PreCompact. */
+    BeforeCompact: 'beforeCompact',
+    /** A session closed. Claude Code's SessionEnd. */
+    SessionEnd: 'sessionEnd',
+    /** The host deleted a session's record. */
+    SessionDelete: 'sessionDelete',
+};
 /** Every event a hook can be bound to, in the order a session meets them. */
-export const HOOK_EVENTS = [
-    "sessionStart",
-    "beforeTurn",
-    "afterTurn",
-    "beforeCompact",
-    "sessionEnd",
-    "sessionDelete",
-];
+export const HOOK_EVENTS = Object.values(HookEvent);
 /**
  * The events whose hooks run before a request, and so the only ones whose output can reach it.
  * Anything later runs once the model has already answered.
  */
-export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
+export const INJECT_EVENTS = new Set([HookEvent.SessionStart, HookEvent.BeforeTurn]);

package/dist/hooks.d.ts

@@ -1,5 +1,5 @@
-import type OpenAI from "openai";
-import { type HookEvent } from "./hook-events.ts";
+import type OpenAI from 'openai';
+import { type HookEvent } from './hook-events.ts';
 /**
  * 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.
@@ -50,7 +50,7 @@ export interface HookContext {
         through: number;
     };
     /** How a run ended. */
-    status?: "ok" | "stopped" | "error";
+    status?: 'ok' | 'stopped' | 'error';
     /** The host's own extras — a card id, a task step. */
     vars?: Record<string, unknown>;
 }
@@ -83,6 +83,8 @@ export interface HookOutcome {
      */
     veto?: boolean;
 }
+/** Hears each `HookNote` as it is made, the one signature every function that raises them takes. */
+export type OnNote = (note: HookNote) => void;
 /**
  * One hook's line for whoever is watching: the context it added, or why it added none. A hook
  * that worked and added nothing gets no note — a remember that succeeded is not news.
@@ -105,6 +107,7 @@ export interface HookNote {
  * Runs one event's hooks. Should resolve rather than reject — a hook failing is an outcome — but
  * `gather` and `notify` survive one that does not.
  *
+ * @remarks
  * The pool's `runHooks` fits as it is; wrap it to pass its scope or `onNotice`.
  */
 export type HookRunner = (event: HookEvent, context: HookContext, options: {
@@ -119,6 +122,7 @@ export interface Gathered {
 /**
  * The most context all of a request's hooks add between them by default, in estimated tokens.
  *
+ * @remarks
  * Enough for a handful of recalled memories, and small against any window worth running an agent
  * in. The point is that a generous hook cannot crowd out the conversation it was meant to inform.
  * `configureHooks` moves it for a process, and `gather` and `assembleContext` for one request.
@@ -147,16 +151,17 @@ export interface HookOptions {
  * Changes what hooks are held to, for a process whose windows are not the size these defaults
  * were chosen for, or whose host wants its own name above the context.
  *
- * One setting per runtime for the same reason `configureEvents` is: a budget and a preface are a
- * deployment's settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
- * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
- * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
- *
- * @param options The settings to change. A field left out keeps what it has, and so does one given
+ * @param [options] - The settings to change. A field left out keeps what it has, and so does one given
  * the wrong kind of value — `contextTokens` anything but a number above zero, `preface` anything
  * but a string — so a half-built config narrows nothing. `Infinity` is a number above zero, and
  * lifts the shared budget entirely. An empty `preface` is a string, and turns the preface off.
  * @returns Everything in force afterwards, including what this call did not change.
+ *
+ * @remarks
+ * One setting per runtime for the same reason `configureEvents` is: a budget and a preface are a
+ * deployment's settings, said once at startup. A caller that sizes the budget per model or per agent — a 128k
+ * window can afford more recall than an 8k one — passes `maxTokens` to `gather` instead, and a
+ * `preface` passed to `withContext` or `runAgentLoop`'s hooks wins over this one the same way.
  */
 export declare function configureHooks(options?: HookOptions): Required<HookOptions>;
 /**
@@ -168,6 +173,14 @@ export declare const resetHooks: () => void;
 /**
  * Builds the context a set of outcomes adds and the notes that go with it.
  *
+ * @param outcomes - What the runners returned. An injecting outcome on an event that cannot inject
+ * adds nothing; a failed one is noted wherever it falls, including past the budget.
+ * @param [maxTokens] - The budget every block shares. Absent, or not a number above zero, is what
+ * `configureHooks` last set — `HOOK_CONTEXT_TOKENS` unless something moved it.
+ * @returns The blocks joined by a blank line — an empty string when nothing was injected — and the
+ * notes in the order of `outcomes`.
+ *
+ * @remarks
  * Each injected outcome is wrapped in `<context source="…">` naming its label, so a model reading
  * a recalled line can tell it is a memory rather than something the user said. Each is held to
  * its own `maxTokens` and the whole to `maxTokens` here, and a block past the total is dropped
@@ -177,16 +190,22 @@ export declare const resetHooks: () => void;
  *
  * The note keeps each hook's text as it was cut, so a host can show exactly what the model was
  * given without re-deriving the caps or parsing the wrapper back off.
- *
- * @param outcomes What the runners returned. An injecting outcome on an event that cannot inject
- * adds nothing; a failed one is noted wherever it falls, including past the budget.
- * @param maxTokens The budget every block shares. Absent, or not a number above zero, is what
- * `configureHooks` last set — `HOOK_CONTEXT_TOKENS` unless something moved it.
  */
 export declare function assembleContext(outcomes: readonly HookOutcome[], maxTokens?: number): Gathered;
 /**
  * The request, with the hooks' context added to this turn's question.
  *
+ * @param history - The request's messages. Neither the array nor any message in it is changed.
+ * @param index - Where the question sits in `history` — which is not where it sits in the
+ * session once a compaction has folded the head into a summary. Anything but a user message there
+ * leaves the request as it was.
+ * @param context - What `assembleContext` built, this turn or the turn the question was asked.
+ * Empty returns `history` itself.
+ * @param [preface] - Said above the blocks. Empty says nothing, rather than leaving a blank line
+ * where it was.
+ * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
+ *
+ * @remarks
  * It goes on the question and not in the system prompt, because it is about the question — and a
  * system prompt that changed every turn would miss the prompt cache every turn. Nothing is written
  * back: a host that stores what the user typed never remembers the context as something they said.
@@ -195,21 +214,12 @@ export declare function assembleContext(outcomes: readonly HookOutcome[], maxTok
  * it was said under, beside the question and calls this for each stored one on every later request
  * — a question sent with its blocks one turn and bare the next is a different prompt from that
  * message on, and loses the server's prefix cache behind it.
- *
- * @param history The request's messages. Neither the array nor any message in it is changed.
- * @param index Where the question sits in `history` — which is not where it sits in the
- * session once a compaction has folded the head into a summary. Anything but a user message there
- * leaves the request as it was.
- * @param context What `assembleContext` built, this turn or the turn the question was asked.
- * Empty returns `history` itself.
- * @param preface Said above the blocks. Absent is what `configureHooks` last set — `HOOK_PREFACE`
- * unless something moved it. Empty says nothing, rather than leaving a blank line where it was.
- * @returns `history` when there was nothing to add or nowhere to add it, otherwise a new array.
  */
 export declare function withContext(history: OpenAI.ChatCompletionMessageParam[], index: number, context: string, preface?: string): OpenAI.ChatCompletionMessageParam[];
 /**
  * One sentence for a system prompt, saying what an `untrusted` block is.
  *
+ * @remarks
  * It belongs in the system prompt rather than beside each block, because it is a standing rule
  * about every block the session will ever carry, and said once there it costs the prompt cache
  * nothing. Like `HOOK_PREFACE` it names no host.
@@ -219,6 +229,12 @@ export declare const UNTRUSTED_PREFACE: string;
  * Fences text nobody trusted — a fetched page, an email, a submitted card, a tool result — so the
  * model can see where it starts and ends and read it as data rather than as instructions.
  *
+ * @param text - What came in. Kept whole, apart from the escaped tags.
+ * @param [options] - `source` names where it came from, for the model and for whoever reads the
+ * transcript later — a URL, a sender, a tool's name. Left out, the block carries no attribute.
+ * @returns The block, with the text on its own lines between the tags.
+ *
+ * @remarks
  * A fence the text can close is no fence, so every `untrusted` tag inside it, opening or closing
  * and in any case, has its `<` escaped: a page that writes `</untrusted>` and then an instruction
  * leaves that instruction inside the block where it began. Nothing else is touched, so the text
@@ -226,11 +242,6 @@ export declare const UNTRUSTED_PREFACE: string;
  *
  * This is one layer and not a defence on its own. A model can still be talked out of a fence it
  * can see; what the text is allowed to make the agent do is the tool policy's to decide.
- *
- * @param text What came in. Kept whole, apart from the escaped tags.
- * @param options `source` names where it came from, for the model and for whoever reads the
- * transcript later — a URL, a sender, a tool's name. Left out, the block carries no attribute.
- * @returns The block, with the text on its own lines between the tags.
  */
 export declare function untrusted(text: string, { source }?: {
     source?: string;
@@ -238,19 +249,34 @@ export declare function untrusted(text: string, { source }?: {
 /**
  * A message's text, whether its content is a string or a list of parts.
  *
+ * @param content - A message's `content`, in any of the shapes the API allows. One that is neither
+ * a string nor a list reads as empty.
+ * @returns The text, untrimmed. A string comes back as it is, and a list with no text part is
+ * empty.
+ *
+ * @remarks
  * Parts are joined with nothing between them, because they are one text an API split rather than
  * several: a space put in is a character the sender never wrote, and `turnMessages` hashes this
  * into the uuid a memory server dedups on. Compaction reads the same function, so the summariser
  * and the hook told about a fold see one message the same way. A refusal part is left out.
- *
- * @param content A message's `content`, in any of the shapes the API allows. One that is neither
- * a string nor a list reads as empty.
  */
 export declare const textOf: (content: unknown) => string;
 /**
  * A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing
  * else.
  *
+ * @param sessionId - Prefixes every uuid, so two sessions never share one.
+ * @param messages - The transcript, in whatever shape the host stores it, so long as each message
+ * has an OpenAI-style `role` and `content`.
+ * @param from - The first index, inclusive. Below zero reads from the start.
+ * @param [to] - The end, exclusive. Absent, or past the end, reads to the end.
+ * @param [options] - `offset` is what the array's first message is numbered as in the uuids — the
+ * stored index of `messages[0]`, when `messages` is a request a fold has shifted. Zero numbers
+ * by position. `from` and `to` stay array indexes either way.
+ * @returns One entry per user or assistant message in the range that has text once trimmed, in
+ * transcript order. Empty when there is none.
+ *
+ * @remarks
  * Tool calls and their results are left out. They are the model's working rather than the
  * conversation, and most of a transcript's characters; a memory server that filed them would
  * recall a directory listing ahead of the decision it led to.
@@ -267,15 +293,6 @@ export declare const textOf: (content: unknown) => string;
  * and again when it is compacted, would arrive under two uuids and be remembered twice. `offset`
  * is what puts the numbering back on the host's own indexes; passing the stored transcript rather
  * than the request avoids the question entirely.
- *
- * @param sessionId Prefixes every uuid, so two sessions never share one.
- * @param messages The transcript, in whatever shape the host stores it, so long as each message
- * has an OpenAI-style `role` and `content`.
- * @param from The first index, inclusive. Below zero reads from the start.
- * @param to The end, exclusive. Absent, or past the end, reads to the end.
- * @param options `offset` is what the array's first message is numbered as in the uuids — the
- * stored index of `messages[0]`, when `messages` is a request a fold has shifted. Zero by default,
- * which numbers by position as before. `from` and `to` stay array indexes either way.
  */
 export declare function turnMessages(sessionId: string, messages: readonly {
     role: string;
@@ -286,15 +303,16 @@ export declare function turnMessages(sessionId: string, messages: readonly {
 /**
  * Which turn of a session begins at a point, from 0: the user messages ahead of it.
  *
+ * @param messages - The transcript.
+ * @param [before] - Where the turn begins.
+ * @param [offset] - Turns already folded away and so not in `messages`.
+ * @returns `offset` plus the count of user messages before `before`.
+ *
+ * @remarks
  * Counted over what it is given, which is the session only while nothing has been folded away — a
  * compacted request has lost the questions the summary now stands for, and turn eleven counting
  * itself as turn two is the kind of thing a hook writes into a memory. Count over the stored
  * transcript, or add what the fold took as `offset`.
- *
- * @param messages The transcript.
- * @param before Where the turn begins. Absent is the end, which is the index of a turn whose
- * question has not been appended yet.
- * @param offset Turns already folded away and so not in `messages`. Zero by default.
  */
 export declare const turnIndex: (messages: readonly {
     role: string;
@@ -302,59 +320,64 @@ export declare const turnIndex: (messages: readonly {
 /**
  * Runs the hooks ahead of a request and builds what they add to it.
  *
- * This is on the path of the first token, so the events run together rather than one after the
- * other, and a hook that fails costs the turn its context and never the turn — a runner that
- * rejects outright is noted once for its event, with an empty `hookId` and `source`, and the rest
- * go ahead. Bounding each hook's time is the runner's job; `signal` is how the turn ends all of
- * them.
- *
- * @param run Runs one event's hooks.
- * @param events Which to run: `["beforeTurn"]` ordinarily, and `sessionStart` ahead of it on a
+ * @param run - Runs one event's hooks.
+ * @param events - Which to run: `["beforeTurn"]` ordinarily, and `sessionStart` ahead of it on a
  * session's first turn. The outcomes are assembled in this order, so it is also the order the
  * budget is spent in.
- * @param context What the hooks are told.
- * @param options `signal` is handed to the runner, and should be the turn's own: a user who
+ * @param context - What the hooks are told.
+ * @param [options] - `signal` is handed to the runner, and should be the turn's own: a user who
  * stopped the turn stopped its recall. `onNote` hears each note as the whole is assembled.
  * `maxTokens` is the shared budget for this request, read as `assembleContext` reads it: absent
  * or unusable is the process's, from `configureHooks`.
+ * @returns What `assembleContext` built from every event's outcomes together. Does not reject for a
+ * runner that did.
+ *
+ * @remarks
+ * This is on the path of the first token, so the events run together rather than one after the
+ * other, and a hook that fails costs the turn its context and never the turn — a runner that
+ * rejects outright is noted once for its event, with an empty `hookId` and `source`, and the rest
+ * go ahead. Bounding each hook's time is the runner's job; `signal` is how the turn ends all of
+ * them.
  */
-export declare function gather(run: HookRunner, events: readonly HookEvent[], context: HookContext, { signal, onNote, maxTokens, }?: {
+export declare function gather(run: HookRunner, events: readonly HookEvent[], context: HookContext, { signal, onNote, maxTokens }?: {
     signal?: AbortSignal;
-    onNote?: (note: HookNote) => void;
+    onNote?: OnNote;
     maxTokens?: number;
 }): Promise<Gathered>;
 /**
  * Runs the hooks for an event that reads what happened and adds nothing to a request. Never
  * rejects, so a host can fire it without awaiting it.
  *
+ * @param run - Runs the event's hooks.
+ * @param event - `afterTurn`, `beforeCompact`, `sessionEnd` or `sessionDelete`. An injecting event
+ * works too, but what its hooks return is dropped, since there is no request here to add it to.
+ * @param context - What the hooks are told.
+ * @param [onNote] - Hears each note — which, with nothing injected, is only ever a failure.
+ * @returns The same notes.
+ *
+ * @remarks
  * No signal: these run once the turn has been answered, and a reader who stops listening at that
  * point has not asked for the turn not to be remembered. Nor is a `veto` read, since whatever it
  * would stop is already under way; `consult` is the one that waits for it.
- *
- * @param run Runs the event's hooks.
- * @param event `afterTurn`, `beforeCompact`, `sessionEnd` or `sessionDelete`. An injecting event
- * works too, but what its hooks return is dropped, since there is no request here to add it to.
- * @param context What the hooks are told.
- * @param onNote Hears each note — which, with nothing injected, is only ever a failure.
- * @returns The same notes.
  */
-export declare function notify(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<HookNote[]>;
+export declare function notify(run: HookRunner, event: HookEvent, context: HookContext, onNote?: OnNote): Promise<HookNote[]>;
 /**
  * Runs an event's hooks and waits for their say, for a host that will hold off when one of them
  * vetoes.
  *
+ * @param run - Runs the event's hooks.
+ * @param event - What is about to happen. Only `beforeCompact` has anything a veto can stop.
+ * @param context - What the hooks are told.
+ * @param [onNote] - Hears each note: every failure, and every veto, naming the hook that made it.
+ * @returns The same notes, and `vetoed` when any `ok` outcome carried `veto`.
+ *
+ * @remarks
  * `notify` runs beside the thing it announces and cannot stop it; this runs ahead of it, so each
  * hook's time is added to whatever waits on the answer. A host that does not mean to act on a
  * veto should call `notify` instead. Never rejects: a runner that throws is noted as a failure,
  * and a failure is not a veto — a memory server that is down has not asked for anything.
- *
- * @param run Runs the event's hooks.
- * @param event What is about to happen. Only `beforeCompact` has anything a veto can stop.
- * @param context What the hooks are told.
- * @param onNote Hears each note: every failure, and every veto, naming the hook that made it.
- * @returns The same notes, and `vetoed` when any `ok` outcome carried `veto`.
  */
-export declare function consult(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<{
+export declare function consult(run: HookRunner, event: HookEvent, context: HookContext, onNote?: OnNote): Promise<{
     notes: HookNote[];
     vetoed: boolean;
 }>;