@cubicecho/agent-core 2.11.0 → 2.13.0

package/dist/continuation.js

@@ -0,0 +1,159 @@
+import OpenAI from "openai";
+import { modelCapabilitiesFor } from "./capabilities.js";
+import { errorMessage } from "./errors.js";
+import { ContextOverflow } from "./retry.js";
+import { runTurn } from "./run-turn.js";
+/**
+ * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
+ * and no tool call in it.
+ *
+ * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
+ * the template's business rather than something this can do the same way everywhere — llama.cpp
+ * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
+ * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
+ *
+ * @param turn The turn as it came back.
+ */
+export const isContinuable = (turn) => turn.finishReason === "length" && turn.content.trim() !== "" && turn.toolCalls.length === 0;
+/** How much of the answer's opening a reply has to repeat to have started over. */
+const RESTART_PROBE = 40;
+/** The shortest opening worth testing for a restart; shorter ones are repeated by chance. */
+const RESTART_MIN = 12;
+/**
+ * Whether the continuation began the answer again rather than carrying it on — how a server that
+ * ignores the prefill shows itself, since it takes the request without complaint.
+ */
+const restarted = (answer, continuation) => {
+    const opening = answer.trimStart().slice(0, RESTART_PROBE);
+    return opening.length >= RESTART_MIN && continuation.trimStart().startsWith(opening);
+};
+/** The fields of a usage that add across two requests, when both reported them. */
+const ADDED = [
+    "uncached",
+    "reasoningTokens",
+    "promptMs",
+    "predictedMs",
+    "draftTotal",
+    "draftAccepted",
+    "wallMs",
+    "retries",
+    "timeouts",
+];
+/** A rate, and the duration it was measured over, which is what weights it in a mean. */
+const RATES = [
+    ["promptTokensPerSecond", "promptMs"],
+    ["tokensPerSecond", "predictedMs"],
+];
+/**
+ * Two requests' usage as one turn's. The first request's own measurements and the loop's
+ * comparison with the request before it stay as they were; a field only one of them reported is
+ * dropped rather than passed off as the total.
+ */
+function joinUsage(first, next) {
+    const joined = {
+        ...first,
+        prompt: first.prompt + next.prompt,
+        completion: first.completion + next.completion,
+        total: first.total + next.total,
+        cached: first.cached + next.cached,
+        continuations: (first.continuations ?? 0) + 1,
+    };
+    for (const field of ADDED) {
+        const a = first[field];
+        const b = next[field];
+        if (a !== undefined && b !== undefined)
+            joined[field] = a + b;
+        else
+            delete joined[field];
+    }
+    for (const [rate, over] of RATES) {
+        const a = first[rate];
+        const b = next[rate];
+        const aMs = first[over];
+        const bMs = next[over];
+        // Tokens over time for both together, which is each rate weighted by the time it held.
+        if (a !== undefined && b !== undefined && aMs !== undefined && bMs !== undefined && aMs + bMs)
+            joined[rate] = (a * aMs + b * bMs) / (aMs + bMs);
+        else
+            delete joined[rate];
+    }
+    return joined;
+}
+/** Whether a failure is the endpoint refusing the request as written, rather than losing it. */
+const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
+/**
+ * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
+ * so far as a trailing assistant message, and joins the pieces into one turn.
+ *
+ * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
+ * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * across the requests with `continuations` counting them. The continuation is read as starting in
+ * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
+ * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees
+ * one answer carry on rather than two.
+ *
+ * Whether the server continues at all is latched per model as `assistantPrefill`. A refusal of the
+ * request latches it off, and so does a continuation that begins the answer again, which is how a
+ * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
+ * that check is only as good as a restart being word for word. Either way the answer so far is
+ * kept, with a notice. So is it when the continuation fails any other way, since the tokens
+ * already in hand are worth more than the error; only a stop is thrown.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused.
+ * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn The turn that came back cut off.
+ * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ */
+export async function continueTurn(client, supports, request, turn, { maxContinuations = 1, ...options } = {}) {
+    const refused = options.model === undefined ? undefined : modelCapabilitiesFor(supports, options.model);
+    const who = options.model ?? "the model";
+    let joined = turn;
+    for (let count = 0; count < maxContinuations && isContinuable(joined); count++) {
+        if (refused?.assistantPrefill === false)
+            break;
+        const answer = joined.content;
+        let next;
+        try {
+            next = await runTurn(client, supports, (capabilities, forModel) => {
+                const body = request(capabilities, forModel);
+                return {
+                    ...body,
+                    messages: [...body.messages, { role: "assistant", content: answer }],
+                };
+            }, { ...options, startInReasoning: false });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            if (error instanceof ContextOverflow) {
+                options.onNotice?.("no room left in the window to continue the cut-off reply");
+            }
+            else if (refusesRequest(error)) {
+                if (refused)
+                    refused.assistantPrefill = false;
+                options.onNotice?.(`${who} refused a trailing assistant message (${errorMessage(error)}); keeping the cut-off reply`);
+            }
+            else {
+                options.onNotice?.(`could not continue the cut-off reply: ${errorMessage(error)}`);
+            }
+            break;
+        }
+        if (restarted(answer, next.content)) {
+            if (refused)
+                refused.assistantPrefill = false;
+            options.onNotice?.(`${who} answered afresh instead of continuing its reply; keeping the cut-off reply`);
+            break;
+        }
+        joined = {
+            content: joined.content + next.content,
+            toolCalls: next.toolCalls,
+            usage: joinUsage(joined.usage, next.usage),
+            finishReason: next.finishReason,
+            reasoning: joined.reasoning + next.reasoning,
+        };
+    }
+    return joined;
+}

package/dist/events.d.ts

@@ -1,3 +1,4 @@
+import type { TurnUsage } from "./stream.ts";
 /**
  * What a run is doing, while it is doing it.
  *
@@ -81,7 +82,11 @@ export type RunEventKind =
  | "tool-result"
 /** Something the runner did that is not the model's doing — a preselection, a retry. */
  | "notice"
-/** What the run has cost so far, as the endpoint reported it at the end of a turn. */
+/**
+ * What the run has cost so far, at the end of every turn, and what that one turn did. Sent
+ * whether or not the endpoint reported tokens, since the timings and the cache comparison are
+ * measured either way.
+ */
  | "usage"
 /** The run ended. Always last, and always sent. */
  | "done";
@@ -99,6 +104,17 @@ export interface RunUsage {
      * emitting usage before this field existed still compiles; absent reads the same as zero.
      */
     cachedTokens?: number;
+    /**
+     * The turn that carried this report, on its own rather than added in — the half `runMetrics`
+     * reads, since a total says nothing about which turn was slow or where the cache broke. Absent
+     * from a caller emitting usage of its own.
+     */
+    turn?: TurnReport;
+}
+/** One turn's usage and measurements as a `usage` event carries them. */
+export interface TurnReport extends TurnUsage {
+    /** Why the model stopped, as `Turn.finishReason` says it; `length` is a turn cut short. */
+    finishReason: string;
 }
 /**
  * One thing that happened in a run, as a watcher receives it.
@@ -209,3 +225,98 @@ export declare const resetEvents: () => void;
  * @param events Events in `seq` order, from `history` or collected from `watch`.
  */
 export declare function fold(events: RunEvent[]): RunEvent[];
+/** Why a turn's cache broke, as `TurnUsage.cacheBreakReason` names it. */
+type CacheBreakReason = NonNullable<TurnUsage["cacheBreakReason"]>;
+/**
+ * A run summed and derived from its events: what it cost, where the time went, and why.
+ *
+ * The counts are always there, zero when nothing happened. Every other field is absent where no
+ * turn reported what it is made of, and summed over the turns that did where only some did —
+ * a mean of a number a server never sent would be a number nobody measured.
+ */
+export interface RunMetrics {
+    /** The caller's own `step` events. */
+    steps: number;
+    /** Turns of the agent loop, one per `usage` report. */
+    turns: number;
+    /** Model requests, which is turns plus the continuations joined onto them. */
+    requests: number;
+    /** Tool results, `load_tools` included. */
+    toolCalls: number;
+    /** Tool results that came back not ok, by tool name. */
+    toolErrors: Record<string, number>;
+    /** `load_tools` calls. */
+    loadCalls: number;
+    /**
+     * Tools `load_tools` loaded that were not loaded already. Filled by `runAgentLoop`, which sees
+     * the resolution; the events carry only its text.
+     */
+    toolsLoaded?: number;
+    /** Tools the model asked `load_tools` for that it already had, filled the same way. */
+    redundantLoads?: number;
+    /** Names the model asked `load_tools` for that are in no catalogue, filled the same way. */
+    unknownToolNames?: number;
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+    /** Summed over the turns that reported a cache count. */
+    uncachedTokens?: number;
+    reasoningTokens?: number;
+    /** Cached over prompt tokens, across only the turns that reported a cache count. */
+    cacheHitRatio?: number;
+    /** Turns whose cache fell short of what the turn before left it. */
+    cacheBreaks: number;
+    /** Those turns by what the loop changed. */
+    cacheBreakReasons: Partial<Record<CacheBreakReason, number>>;
+    /** Turns cut off at `maxTokens` after any continuation. */
+    truncatedTurns: number;
+    /** From the first event to the last, which a still-running run keeps moving. */
+    wallMs?: number;
+    /** Prefill time summed over the turns. */
+    promptMs?: number;
+    /** Decode time summed over the turns. */
+    predictedMs?: number;
+    /**
+     * Time from each tool call to its result, summed per call — so calls run in parallel can add up
+     * to more than the wall time they took.
+     */
+    toolMs?: number;
+    /** The longest any one turn took, retries and continuations in. */
+    slowestTurnMs?: number;
+    /** The mean time to first token over the turns that produced one. */
+    firstTokenMs?: number;
+    draftTotal?: number;
+    draftAccepted?: number;
+    /** Accepted over drafted. */
+    draftAcceptance?: number;
+    /** The biggest prompt any turn reported. */
+    largestPrompt?: number;
+    /** `largestPrompt` over the window `runMetrics` was told, for how close the run came. */
+    largestPromptShare?: number;
+    /**
+     * How it ended, read off `done` and the last turn: `truncated` is an answer the ceiling cut off.
+     * A failure does not say whether it was an error, a stop or the tool budget — that is in the
+     * host's own `done` text.
+     */
+    outcome?: "answered" | "truncated" | "failed";
+}
+/** What `runMetrics` takes besides the events. */
+export interface RunMetricsOptions {
+    /** The window the run was served, for `largestPromptShare`. Absent or zero leaves it out. */
+    contextLength?: number;
+}
+/**
+ * A run's totals, timings and cache findings, derived from the events it emitted.
+ *
+ * A sibling of `fold` rather than part of it. `fold` hands back events, and a client renders
+ * what it returns as blocks; a summary is another shape, and folding one in would give every
+ * consumer of `fold` a block it does not know how to draw. Derived from the `usage` reports' own
+ * `turn` rather than the running totals, so a run with several loops in it — a question per loop —
+ * adds up the same as one with a single loop.
+ *
+ * @param events A run's events in `seq` order, from `history` or collected from `watch`. A backlog
+ * that has lost its oldest events to the cap sums what it still has.
+ * @param options The served window, for how full the run came to it.
+ */
+export declare function runMetrics(events: RunEvent[], { contextLength }?: RunMetricsOptions): RunMetrics;
+export {};

package/dist/events.js

@@ -1,14 +1,4 @@
-/**
- * What a run is doing, while it is doing it.
- *
- * A run row only exists as a before and an after: it is written when the agent starts and
- * updated when it stops, and everything in between — the thinking, the tool the model reached
- * for, the argument it got wrong — is gone by the time anyone can read it. This is that middle,
- * kept in memory and handed to whoever is watching.
- *
- * In memory on purpose: it is debugging output, worth nothing once the run has finished and its
- * outcome is in the database. Nothing here survives a restart, and nothing here is the record.
- */
+import { LOAD_TOOLS } from "./tool-loading.js";
 /** The numbers a run of the shape this bus was written for wants. */
 const DEFAULTS = {
     maxEvents: 1000,
@@ -348,3 +338,113 @@ export function fold(events) {
     close();
     return blocks;
 }
+/**
+ * A run's totals, timings and cache findings, derived from the events it emitted.
+ *
+ * A sibling of `fold` rather than part of it. `fold` hands back events, and a client renders
+ * what it returns as blocks; a summary is another shape, and folding one in would give every
+ * consumer of `fold` a block it does not know how to draw. Derived from the `usage` reports' own
+ * `turn` rather than the running totals, so a run with several loops in it — a question per loop —
+ * adds up the same as one with a single loop.
+ *
+ * @param events A run's events in `seq` order, from `history` or collected from `watch`. A backlog
+ * that has lost its oldest events to the cap sums what it still has.
+ * @param options The served window, for how full the run came to it.
+ */
+export function runMetrics(events, { contextLength } = {}) {
+    const metrics = {
+        steps: 0,
+        turns: 0,
+        requests: 0,
+        toolCalls: 0,
+        toolErrors: {},
+        loadCalls: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        cachedTokens: 0,
+        cacheBreaks: 0,
+        cacheBreakReasons: {},
+        truncatedTurns: 0,
+    };
+    /** Adds to a field that is absent until something reports it. */
+    const add = (field, value) => {
+        if (value === undefined)
+            return;
+        const known = metrics;
+        known[field] = (known[field] ?? 0) + value;
+    };
+    let reportedPrompt = 0;
+    let reportedCached = 0;
+    let firstTokens = 0;
+    // Calls waiting for their results, by tool name, oldest first.
+    const pending = new Map();
+    let last;
+    for (const event of events) {
+        if (event.kind === "step")
+            metrics.steps++;
+        else if (event.kind === "tool-call") {
+            if (event.name === LOAD_TOOLS)
+                metrics.loadCalls++;
+            const waiting = pending.get(event.name) ?? [];
+            waiting.push(event.at);
+            pending.set(event.name, waiting);
+        }
+        else if (event.kind === "tool-result") {
+            metrics.toolCalls++;
+            if (event.ok === false)
+                metrics.toolErrors[event.name] = (metrics.toolErrors[event.name] ?? 0) + 1;
+            const called = pending.get(event.name)?.shift();
+            if (called !== undefined)
+                add("toolMs", event.at - called);
+        }
+        else if (event.kind === "usage" && event.usage?.turn) {
+            const turn = event.usage.turn;
+            last = turn;
+            metrics.turns++;
+            metrics.requests += 1 + (turn.continuations ?? 0);
+            metrics.promptTokens += turn.prompt;
+            metrics.completionTokens += turn.completion;
+            metrics.cachedTokens += turn.cached;
+            if (turn.uncached !== undefined) {
+                add("uncachedTokens", turn.uncached);
+                reportedPrompt += turn.prompt;
+                reportedCached += turn.cached;
+            }
+            add("reasoningTokens", turn.reasoningTokens);
+            add("promptMs", turn.promptMs);
+            add("predictedMs", turn.predictedMs);
+            add("draftTotal", turn.draftTotal);
+            add("draftAccepted", turn.draftAccepted);
+            if (turn.cacheBroken) {
+                metrics.cacheBreaks++;
+                const reason = turn.cacheBreakReason ?? "none-known";
+                metrics.cacheBreakReasons[reason] = (metrics.cacheBreakReasons[reason] ?? 0) + 1;
+            }
+            if (turn.finishReason === "length")
+                metrics.truncatedTurns++;
+            if (turn.wallMs !== undefined)
+                metrics.slowestTurnMs = Math.max(metrics.slowestTurnMs ?? 0, turn.wallMs);
+            if (turn.firstTokenMs !== undefined) {
+                add("firstTokenMs", turn.firstTokenMs);
+                firstTokens++;
+            }
+            if (turn.prompt > 0)
+                metrics.largestPrompt = Math.max(metrics.largestPrompt ?? 0, turn.prompt);
+        }
+        else if (event.kind === "done") {
+            metrics.outcome =
+                event.ok === false ? "failed" : last?.finishReason === "length" ? "truncated" : "answered";
+        }
+    }
+    if (events.length > 1)
+        metrics.wallMs = events[events.length - 1].at - events[0].at;
+    if (reportedPrompt > 0)
+        metrics.cacheHitRatio = reportedCached / reportedPrompt;
+    if (metrics.firstTokenMs !== undefined)
+        metrics.firstTokenMs /= firstTokens;
+    if (metrics.draftTotal && metrics.draftAccepted !== undefined)
+        metrics.draftAcceptance = metrics.draftAccepted / metrics.draftTotal;
+    if (metrics.largestPrompt !== undefined && contextLength && contextLength > 0)
+        metrics.largestPromptShare = metrics.largestPrompt / contextLength;
+    return metrics;
+}

package/dist/hooks.d.ts

@@ -89,6 +89,12 @@ export interface HookOutcome {
     inject: boolean;
     /** The most of `text` that is injected, in estimated tokens. */
     maxTokens: number;
+    /**
+     * Asks that what the event announces not happen. Only a `beforeCompact` hook's is read, and
+     * only by a host that waits for it — see `consult` — and never on an outcome that is not `ok`,
+     * since a hook that crashed has not said anything.
+     */
+    veto?: boolean;
 }
 /**
  * One hook's line for whoever is watching: the context it added, or why it added none. A hook
@@ -105,6 +111,8 @@ export interface HookNote {
     text?: string;
     /** Why it added nothing: it failed, timed out, or never ran. */
     error?: string;
+    /** Set when the hook vetoed what the event announced, and was waited for. See `consult`. */
+    veto?: true;
 }
 /**
  * Runs one event's hooks. Should resolve rather than reject — a hook failing is an outcome — but
@@ -248,26 +256,44 @@ export declare function untrusted(text: string, { source }?: {
  * two identical "ok"s one memory. The same message sent twice, after its turn and again when it
  * is compacted, is one.
  *
+ * That position is the array's, which is the host's only while the two agree. Once a compaction
+ * has folded the head of a request into one summary message, the same message sits at a lower
+ * index there than it does in a transcript the host kept whole — so the same turn, sent after it
+ * 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;
     content?: unknown;
-}[], from: number, to?: number): HookMessage[];
+}[], from: number, to?: number, { offset }?: {
+    offset?: number;
+}): HookMessage[];
 /**
  * Which turn of a session begins at a point, from 0: the user messages ahead of it.
  *
+ * 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;
-}[], before?: number) => number;
+}[], before?: number, offset?: number) => number;
 /**
  * Runs the hooks ahead of a request and builds what they add to it.
  *
@@ -297,7 +323,8 @@ export declare function gather(run: HookRunner, events: readonly HookEvent[], co
  * rejects, so a host can fire it without awaiting it.
  *
  * 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.
+ * 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
@@ -307,3 +334,22 @@ export declare function gather(run: HookRunner, events: readonly HookEvent[], co
  * @returns The same notes.
  */
 export declare function notify(run: HookRunner, event: HookEvent, context: HookContext, onNote?: (note: HookNote) => void): Promise<HookNote[]>;
+/**
+ * Runs an event's hooks and waits for their say, for a host that will hold off when one of them
+ * vetoes.
+ *
+ * `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<{
+    notes: HookNote[];
+    vetoed: boolean;
+}>;

package/dist/hooks.js

@@ -204,13 +204,23 @@ const textOf = (content) => {
  * two identical "ok"s one memory. The same message sent twice, after its turn and again when it
  * is compacted, is one.
  *
+ * That position is the array's, which is the host's only while the two agree. Once a compaction
+ * has folded the head of a request into one summary message, the same message sits at a lower
+ * index there than it does in a transcript the host kept whole — so the same turn, sent after it
+ * 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 function turnMessages(sessionId, messages, from, to) {
+export function turnMessages(sessionId, messages, from, to, { offset = 0 } = {}) {
     const end = Math.min(to ?? messages.length, messages.length);
     const out = [];
     for (let at = Math.max(0, from); at < end; at++) {
@@ -221,18 +231,28 @@ export function turnMessages(sessionId, messages, from, to) {
         if (!text)
             continue;
         const digest = createHash("sha256").update(`${message.role}\0${text}`).digest("hex");
-        out.push({ speaker: message.role, text, uuid: `${sessionId}:${at}:${digest.slice(0, 12)}` });
+        out.push({
+            speaker: message.role,
+            text,
+            uuid: `${sessionId}:${at + offset}:${digest.slice(0, 12)}`,
+        });
     }
     return out;
 }
 /**
  * Which turn of a session begins at a point, from 0: the user messages ahead of it.
  *
+ * 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 const turnIndex = (messages, before = messages.length) => messages.slice(0, before).filter((message) => message.role === "user").length;
+export const turnIndex = (messages, before = messages.length, offset = 0) => offset + messages.slice(0, before).filter((message) => message.role === "user").length;
 /** A runner that rejected, as the one outcome its event can still be noted by. */
 const rejected = (event, error) => ({
     serverId: "",
@@ -279,7 +299,8 @@ export async function gather(run, events, context, { signal, onNote, maxTokens,
  * rejects, so a host can fire it without awaiting it.
  *
  * 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.
+ * 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
@@ -297,3 +318,37 @@ export async function notify(run, event, context, onNote) {
         onNote?.(note);
     return notes;
 }
+/**
+ * Runs an event's hooks and waits for their say, for a host that will hold off when one of them
+ * vetoes.
+ *
+ * `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 async function consult(run, event, context, onNote) {
+    const outcomes = await runSafely(run, event, context);
+    const notes = [];
+    for (const outcome of outcomes) {
+        if (!outcome.ok)
+            notes.push(assembleContext([outcome]).notes[0]);
+        else if (outcome.veto === true) {
+            notes.push({
+                event: outcome.event,
+                source: outcome.label,
+                hookId: outcome.hookId,
+                veto: true,
+            });
+        }
+    }
+    for (const note of notes)
+        onNote?.(note);
+    return { notes, vetoed: notes.some((note) => note.veto) };
+}

package/dist/index.d.ts

@@ -10,16 +10,18 @@
  * that differs between one server and the next.
  */
 export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
+export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
 export { type Capabilities, capabilitiesFor, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { type ClientPoolOptions, configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, type ModelInfo, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.ts";
-export { COMPACT_AT, type CompactionOptions, type CompactionPlan, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
+export { applyCompaction, COMPACT_AT, type CompactionOptions, type CompactionPlan, type CompactionRecord, type CompactionRunOptions, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
+export { type ContinueTurnOptions, continueTurn, isContinuable, } from "./continuation.ts";
 export { errorMessage } from "./errors.ts";
-export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
-export { assembleContext, configureHooks, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
+export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunMetrics, type RunMetricsOptions, type RunUsage, resetEvents, runMetrics, type TurnReport, watch, } from "./events.ts";
+export { assembleContext, configureHooks, consult, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, UNTRUSTED_PREFACE, untrusted, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { backoffMs, CHARS_PER_TOKEN, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, messageTokens, requestChars, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, type TokenEstimateOptions, toolsChars, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskInput, type SideTaskOptions, tryAsk, } from "./side-task.ts";
@@ -28,4 +30,4 @@ export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type Turn
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, type ToolOrder, } from "./tool-loading.ts";