@cubicecho/agent-core 2.3.0 → 2.5.0

package/dist/compaction.d.ts

@@ -0,0 +1,133 @@
+import type OpenAI from "openai";
+import type { Endpoint } from "./config.ts";
+import { type HookContext, type HookNote, type HookRunner } from "./hooks.ts";
+import { type SideTaskOptions } from "./side-task.ts";
+/**
+ * Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded
+ * into a summary the model writes itself.
+ *
+ * Both rewrite the transcript's prefix, and a prefix that changes is a prompt cache that misses —
+ * on a local server that is the whole prompt processed again, every token of it. So neither is
+ * meant to run a little on every turn: run them rarely, and together, at the point
+ * `planCompaction` says the window is filling, and the cache is paid for once rather than on
+ * every step.
+ */
+type Message = OpenAI.ChatCompletionMessageParam;
+/** The fraction of the window in use before a summary is worth its own round trip. */
+export declare const COMPACT_AT = 0.75;
+/** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
+export declare const KEEP_RATIO = 0.35;
+/**
+ * The summariser's instruction when the caller gives none.
+ *
+ * Asks for notes rather than a retelling, because what the summary replaces is the model's only
+ * record of what was decided, and a narrative spends its words on the order things happened in.
+ */
+export declare const SUMMARY_PROMPT: string;
+/**
+ * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
+ */
+export declare const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
+/** What `pruneToolResults` takes. */
+export interface PruneOptions {
+    /** How many of the latest tool results are left whole, 5 by default. */
+    keepLast?: number;
+    /** A result this long or shorter is left whole wherever it is, 256 characters by default. */
+    maxChars?: number;
+}
+/**
+ * The transcript with every tool result but the latest few replaced by a one-line stub.
+ *
+ * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
+ * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
+ * call answered — a call with no result is a malformed transcript — and says how much was there,
+ * so a model that does need it again knows to ask. Short results are kept, since a stub saves
+ * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * see the module comment on when to run it.
+ *
+ * @param messages The transcript. Not written to.
+ * @param options How many results to keep and how long one must be to clear.
+ */
+export declare function pruneToolResults(messages: Message[], { keepLast, maxChars }?: PruneOptions): Message[];
+/** What `planCompaction` takes. */
+export interface CompactionOptions {
+    /** The model's window, in tokens. Zero or less never compacts. */
+    limit: number;
+    /**
+     * What the transcript costs now. The last turn's reported prompt tokens are the best number;
+     * absent is the estimate of the whole transcript.
+     */
+    used?: number;
+    /** The fraction of `limit` in use before compacting. `COMPACT_AT` by default. */
+    compactAt?: number;
+    /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
+    keepRatio?: number;
+    /** One message's tokens. `messageTokens` by default. */
+    estimate?: (message: Message) => number;
+}
+/** Where to cut, as `compactTranscript` takes it. */
+export interface CompactionPlan {
+    /** The first message folded away. Everything before it is a system prompt and stays. */
+    from: number;
+    /** The first message kept whole, always a user message. */
+    cut: number;
+    /** The messages from `from` to `cut`, the ones the summary replaces. */
+    toSummarise: Message[];
+    /** The summary an earlier compaction left, which this one continues. */
+    previous?: string;
+}
+/**
+ * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
+ *
+ * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
+ * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
+ * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
+ * the head are never folded, and a summary an earlier compaction left there is continued rather
+ * than summarised as if it were conversation. No plan comes back when the window is not full
+ * enough, or when the only legal cut folds too little to pay for the summary.
+ *
+ * @param messages The transcript, system prompts included if the caller keeps them in it.
+ * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
+ */
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, estimate, }: CompactionOptions): CompactionPlan | undefined;
+/**
+ * What the summariser is handed for a plan: the earlier summary if there was one, then each
+ * message as its role and at most 4000 characters of its text.
+ *
+ * @param plan What `planCompaction` returned.
+ */
+export declare function summaryInput(plan: CompactionPlan): string;
+/**
+ * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
+ *
+ * @param config The endpoint the summary is written through.
+ * @param model The model to write it, which may be a smaller one than the run's.
+ * @param options Cancellation and notices; the ceiling is 1024 and the instruction
+ * `SUMMARY_PROMPT` unless given.
+ */
+export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
+    system?: string;
+}) => (text: string) => Promise<string>;
+/**
+ * The transcript with the plan's stretch replaced by one system message holding its summary.
+ *
+ * `beforeCompact` is told what is being folded while the summary is written, beside it rather
+ * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
+ * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
+ * and a run over its window has no better option anyway. An empty summary folds nothing, and the
+ * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ *
+ * @param messages The transcript the plan was made for. Not written to.
+ * @param plan What `planCompaction` returned for it.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`.
+ * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
+ * indexes are the plan's.
+ */
+export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, }?: {
+    hooks?: {
+        run: HookRunner;
+        context: HookContext;
+        onNote?: (note: HookNote) => void;
+    };
+}): Promise<Message[]>;
+export {};

package/dist/compaction.js

@@ -0,0 +1,173 @@
+import { notify, turnMessages } from "./hooks.js";
+import { messageTokens } from "./retry.js";
+import { ask } from "./side-task.js";
+/** The fraction of the window in use before a summary is worth its own round trip. */
+export const COMPACT_AT = 0.75;
+/** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
+export const KEEP_RATIO = 0.35;
+/** How much of any one message the summariser is shown. A pasted file is not worth it whole. */
+const SUMMARY_SLICE = 4000;
+/**
+ * The summariser's instruction when the caller gives none.
+ *
+ * Asks for notes rather than a retelling, because what the summary replaces is the model's only
+ * record of what was decided, and a narrative spends its words on the order things happened in.
+ */
+export const SUMMARY_PROMPT = "You maintain the running memory of a long conversation. Rewrite the exchange below as " +
+    "notes the assistant can rely on after the original messages are gone. Keep decisions, " +
+    "facts, file paths, names, numbers, and anything still unresolved. Drop pleasantries and " +
+    "anything already superseded. Write compact prose or bullets — no preamble, no sign-off.";
+/**
+ * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
+ */
+export const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
+/** A message's content as plain text: parts joined, anything but text left out. */
+const textOf = (content) => typeof content === "string"
+    ? content
+    : Array.isArray(content)
+        ? content.map((part) => ("text" in part ? part.text : "")).join(" ")
+        : "";
+/** What the summariser reads for one message: its text and the calls it made. */
+const messageText = (message) => {
+    const calls = "tool_calls" in message && message.tool_calls
+        ? message.tool_calls
+            .map((call) => call.type === "function" ? `${call.function.name}(${call.function.arguments})` : "")
+            .join(" ")
+        : "";
+    return `${textOf(message.content)} ${calls}`.trim();
+};
+const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
+/**
+ * The transcript with every tool result but the latest few replaced by a one-line stub.
+ *
+ * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
+ * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
+ * call answered — a call with no result is a malformed transcript — and says how much was there,
+ * so a model that does need it again knows to ask. Short results are kept, since a stub saves
+ * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * see the module comment on when to run it.
+ *
+ * @param messages The transcript. Not written to.
+ * @param options How many results to keep and how long one must be to clear.
+ */
+export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}) {
+    let kept = 0;
+    let out;
+    for (let at = messages.length - 1; at >= 0; at--) {
+        const message = messages[at];
+        if (message.role !== "tool")
+            continue;
+        if (kept++ < keepLast)
+            continue;
+        const text = textOf(message.content);
+        if (text.length <= maxChars || text.startsWith("[result cleared"))
+            continue;
+        out ??= [...messages];
+        out[at] = {
+            ...message,
+            content: `[result cleared, ${text.length.toLocaleString("en-US")} chars]`,
+        };
+    }
+    return out ?? messages;
+}
+/**
+ * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
+ *
+ * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
+ * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
+ * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
+ * the head are never folded, and a summary an earlier compaction left there is continued rather
+ * than summarised as if it were conversation. No plan comes back when the window is not full
+ * enough, or when the only legal cut folds too little to pay for the summary.
+ *
+ * @param messages The transcript, system prompts included if the caller keeps them in it.
+ * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
+ */
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, estimate = messageTokens, }) {
+    if (!(limit > 0))
+        return undefined;
+    const cost = used ?? messages.reduce((total, message) => total + estimate(message), 0);
+    if (cost < limit * compactAt)
+        return undefined;
+    let from = 0;
+    let previous;
+    while (from < messages.length && messages[from].role === "system") {
+        if (isSummary(messages[from]))
+            previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
+        from++;
+    }
+    const budget = limit * keepRatio;
+    let kept = 0;
+    let cut = messages.length;
+    for (let at = messages.length - 1; at > from; at--) {
+        kept += estimate(messages[at]);
+        if (kept > budget)
+            break;
+        cut = at;
+    }
+    while (cut < messages.length && messages[cut].role !== "user")
+        cut++;
+    if (cut >= messages.length || cut - from < 2)
+        return undefined;
+    return { from, cut, toSummarise: messages.slice(from, cut), ...(previous ? { previous } : {}) };
+}
+/**
+ * What the summariser is handed for a plan: the earlier summary if there was one, then each
+ * message as its role and at most 4000 characters of its text.
+ *
+ * @param plan What `planCompaction` returned.
+ */
+export function summaryInput(plan) {
+    const transcript = plan.toSummarise
+        .map((message) => {
+        const text = messageText(message);
+        return text ? `${message.role}: ${text.slice(0, SUMMARY_SLICE)}` : "";
+    })
+        .filter(Boolean)
+        .join("\n\n");
+    return plan.previous
+        ? `Notes so far:\n${plan.previous}\n\nContinue them with this exchange:\n\n${transcript}`
+        : transcript;
+}
+/**
+ * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
+ *
+ * @param config The endpoint the summary is written through.
+ * @param model The model to write it, which may be a smaller one than the run's.
+ * @param options Cancellation and notices; the ceiling is 1024 and the instruction
+ * `SUMMARY_PROMPT` unless given.
+ */
+export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = 1024, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
+/**
+ * The transcript with the plan's stretch replaced by one system message holding its summary.
+ *
+ * `beforeCompact` is told what is being folded while the summary is written, beside it rather
+ * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
+ * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
+ * and a run over its window has no better option anyway. An empty summary folds nothing, and the
+ * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ *
+ * @param messages The transcript the plan was made for. Not written to.
+ * @param plan What `planCompaction` returned for it.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`.
+ * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
+ * indexes are the plan's.
+ */
+export async function compactTranscript(messages, plan, summarise, { hooks, } = {}) {
+    const [summary] = await Promise.all([
+        summarise(summaryInput(plan)),
+        hooks &&
+            notify(hooks.run, "beforeCompact", {
+                ...hooks.context,
+                compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
+                range: { from: plan.from, through: plan.cut },
+            }, hooks.onNote),
+    ]);
+    if (!summary.trim())
+        return messages;
+    return [
+        ...messages.slice(0, plan.from).filter((message) => !isSummary(message)),
+        { role: "system", content: `${SUMMARY_LEAD}${summary.trim()}` },
+        ...messages.slice(plan.cut),
+    ];
+}

package/dist/config.d.ts

@@ -30,8 +30,28 @@ export interface Endpoint {
 /** What to ask the model for. */
 export interface ModelParams {
     model: string;
+    /** The reply's ceiling. Zero or less sends none, leaving it to the server. */
     maxTokens: number;
     temperature: number;
+    /**
+     * `reasoning_effort` for a model that deliberates. Absent or `"off"` sends none, which is the
+     * only value a server that has never heard of reasoning accepts — a setting that means "leave
+     * the field out" rather than a level to ask for.
+     */
+    reasoningEffort?: string;
+    /**
+     * Request fields this interface cannot spell, merged into the body last by `buildBody`.
+     *
+     * What a model card asks for and nothing here names: `top_k`, `min_p`, `repeat_penalty` —
+     * what actually stops a small model looping — and a server's own fields, such as llama.cpp's
+     * `id_slot`, which pins a session to one slot of a `--parallel` server so its KV cache is
+     * still warm on the next turn. A local server ignores a field it does not know; OpenAI refuses
+     * one by name, and `negotiate` drops that name for the model and sends the request again.
+     * `model`, `messages`, `stream` and `tools` are the loop's and are not overridden from here.
+     * Ollama's `options` object is not read on its `/v1` route, so sampling there has to go in as
+     * top-level fields like any other.
+     */
+    extraBody?: Record<string, unknown>;
 }
 /** How tools reach the model, and how long it may keep calling them. */
 export interface ToolPolicy {

package/dist/events.d.ts

@@ -94,6 +94,11 @@ export interface RunUsage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /**
+     * How much of `promptTokens` the endpoint served from its prompt cache. Optional so a caller
+     * emitting usage before this field existed still compiles; absent reads the same as zero.
+     */
+    cachedTokens?: number;
 }
 /**
  * One thing that happened in a run, as a watcher receives it.

package/dist/hooks.d.ts

@@ -122,12 +122,40 @@ export interface Gathered {
     notes: HookNote[];
 }
 /**
- * The most context all of a request's hooks add between them, in estimated tokens.
+ * The most context all of a request's hooks add between them by default, in estimated tokens.
  *
  * 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.
  */
 export declare const HOOK_CONTEXT_TOKENS = 2000;
+/** What hooks are held to across a process. Every field optional; see `configureHooks`. */
+export interface HookOptions {
+    /**
+     * The budget every injecting hook shares, when a call does not give its own. Each hook is still
+     * held to its own `maxTokens` inside it.
+     */
+    contextTokens?: number;
+}
+/**
+ * Changes what hooks are held to, for a process whose windows are not the size these defaults
+ * were chosen for.
+ *
+ * Module-level for the same reason `configureEvents` is: a budget is a deployment's setting, said
+ * once at startup. A caller that sizes it per model or per agent — a 128k window can afford more
+ * recall than an 8k one — passes `maxTokens` to `gather` instead, which wins over this.
+ *
+ * @param options The limits to change. A field left out — or given anything that is not a number
+ * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
+ * above zero, and lifts the shared budget entirely.
+ * @returns Everything in force afterwards, including what this call did not change.
+ */
+export declare function configureHooks(options?: HookOptions): Required<HookOptions>;
+/**
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * `resetAll` calls it.
+ */
+export declare const resetHooks: () => void;
 /**
  * Said once, above the blocks, so the model reads them as background rather than instructions.
  * Names no host; `withContext` takes another for one that wants to.
@@ -148,7 +176,8 @@ export declare const HOOK_PREFACE: string;
  *
  * @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. Defaults to `HOOK_CONTEXT_TOKENS`.
+ * @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;
 /**
@@ -217,7 +246,8 @@ export declare const turnIndex: (messages: readonly {
  * @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, `HOOK_CONTEXT_TOKENS` if absent.
+ * `maxTokens` is the shared budget for this request, read as `assembleContext` reads it: absent
+ * or unusable is the process's, from `configureHooks`.
  */
 export declare function gather(run: HookRunner, events: readonly HookEvent[], context: HookContext, { signal, onNote, maxTokens, }?: {
     signal?: AbortSignal;

package/dist/hooks.js

@@ -16,12 +16,50 @@ export const HOOK_EVENTS = [
  */
 export const INJECT_EVENTS = new Set(["sessionStart", "beforeTurn"]);
 /**
- * The most context all of a request's hooks add between them, in estimated tokens.
+ * The most context all of a request's hooks add between them by default, in estimated tokens.
  *
  * 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.
  */
 export const HOOK_CONTEXT_TOKENS = 2000;
+/** The numbers this module was written with. */
+const HOOK_DEFAULTS = { contextTokens: HOOK_CONTEXT_TOKENS };
+/** What is in force now. Read where it is used, so a change applies from the next request. */
+let hookLimits = { ...HOOK_DEFAULTS };
+/**
+ * Changes what hooks are held to, for a process whose windows are not the size these defaults
+ * were chosen for.
+ *
+ * Module-level for the same reason `configureEvents` is: a budget is a deployment's setting, said
+ * once at startup. A caller that sizes it per model or per agent — a 128k window can afford more
+ * recall than an 8k one — passes `maxTokens` to `gather` instead, which wins over this.
+ *
+ * @param options The limits to change. A field left out — or given anything that is not a number
+ * above zero — keeps what it has, so a half-built config narrows nothing. `Infinity` is a number
+ * above zero, and lifts the shared budget entirely.
+ * @returns Everything in force afterwards, including what this call did not change.
+ */
+export function configureHooks(options = {}) {
+    for (const [name, value] of Object.entries(options)) {
+        if (typeof value === "number" && value > 0)
+            hookLimits[name] = value;
+    }
+    return { ...hookLimits };
+}
+/**
+ * Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
+ * `resetAll` calls it.
+ */
+export const resetHooks = () => {
+    hookLimits = { ...HOOK_DEFAULTS };
+};
+/**
+ * The budget a call is held to: its own when it gave a usable one, the process's otherwise. The
+ * same rule `configureHooks` applies, so a `0` threaded through for "no opinion" does not quietly
+ * turn every hook's context off.
+ */
+const budget = (given) => typeof given === "number" && given > 0 ? given : hookLimits.contextTokens;
 /**
  * Said once, above the blocks, so the model reads them as background rather than instructions.
  * Names no host; `withContext` takes another for one that wants to.
@@ -44,12 +82,13 @@ const attribute = (text) => text.replaceAll("&", "&").replaceAll('"', "&quot
  *
  * @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. Defaults to `HOOK_CONTEXT_TOKENS`.
+ * @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 function assembleContext(outcomes, maxTokens = HOOK_CONTEXT_TOKENS) {
+export function assembleContext(outcomes, maxTokens) {
     const blocks = [];
     const notes = [];
-    let remaining = maxTokens;
+    let remaining = budget(maxTokens);
     for (const outcome of outcomes) {
         const base = { event: outcome.event, source: outcome.label, hookId: outcome.hookId };
         if (!outcome.ok) {
@@ -182,7 +221,8 @@ const runSafely = (run, event, context, signal) => Promise.resolve()
  * @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, `HOOK_CONTEXT_TOKENS` if absent.
+ * `maxTokens` is the shared budget for this request, read as `assembleContext` reads it: absent
+ * or unusable is the process's, from `configureHooks`.
  */
 export async function gather(run, events, context, { signal, onNote, maxTokens, } = {}) {
     const outcomes = await Promise.all(events.map((event) => runSafely(run, event, context, signal)));

package/dist/index.d.ts

@@ -9,18 +9,22 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
 export { type Capabilities, capabilitiesFor, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, 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 type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.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, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.ts";
+export { 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, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
-export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { estimateTokens } from "./tokens.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -9,16 +9,20 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
+export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
+export { COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { errorMessage } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
-export { assembleContext, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, turnIndex, turnMessages, withContext, } from "./hooks.js";
+export { assembleContext, configureHooks, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
-export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
+export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
+export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
 export { streamTurn, } from "./stream.js";
 export { estimateTokens } from "./tokens.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/reset.d.ts

@@ -1,20 +1,21 @@
 /**
  * Forgets everything this package remembers between calls.
  *
- * Four modules here keep state for the life of the process, each for a good reason and each
+ * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` stay
- * exported, because a test that means to clear one thing should say so.
+ * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
+ * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
+ * one thing should say so.
  *
- * This is for the other case, which is every teardown. What all four hold is *latched
+ * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
  * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
  * locally and fails in CI on a different shard: the test that latched it still passes, and the
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export declare function resetAll(): void;

package/dist/reset.js

@@ -1,24 +1,26 @@
 import { resetCapabilities } from "./capabilities.js";
 import { resetClients } from "./client.js";
 import { resetEvents } from "./events.js";
+import { resetHooks } from "./hooks.js";
 import { resetHints } from "./side-task.js";
 /**
  * Forgets everything this package remembers between calls.
  *
- * Four modules here keep state for the life of the process, each for a good reason and each
+ * Five modules here keep state for the life of the process, each for a good reason and each
  * with its own seam: the pooled clients and their model listings, the endpoints that turned
  * out not to take `stream_options` or a grammar, the models that refused the no-thinking
- * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `resetEvents` stay
- * exported, because a test that means to clear one thing should say so.
+ * hints, the event bus, and the hooks' configured budget. `resetClients`, `resetCapabilities`,
+ * `resetHints`, `resetEvents` and `resetHooks` stay exported, because a test that means to clear
+ * one thing should say so.
  *
- * This is for the other case, which is every teardown. What all four hold is *latched
+ * This is for the other case, which is every teardown. What they hold is *latched
  * refusals* — a fact one test taught the process about an endpoint, still true as far as the
  * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
  * locally and fails in CI on a different shard: the test that latched it still passes, and the
  * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
  * was written that way and only passed because every case had been handed a hostname of its own.
  *
- * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * It is also the seam that does not need finding again. A sixth module with a cache is a sixth
  * line here, rather than an edit to the teardown of three consumers who will not all notice.
  */
 export function resetAll() {
@@ -26,4 +28,5 @@ export function resetAll() {
     resetCapabilities();
     resetHints();
     resetEvents();
+    resetHooks();
 }

package/dist/retry.d.ts

@@ -47,6 +47,15 @@ export declare const compact: (tokens: number) => string;
  * @param body The request as it will be sent, tools included.
  */
 export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
+/**
+ * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
+ *
+ * For the arithmetic that weighs part of a transcript against a window — `planCompaction`'s kept
+ * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
+ *
+ * @param message The message as it will be sent.
+ */
+export declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam) => number;
 /**
  * Whether a refusal means the request was too big, rather than merely refused.
  *

package/dist/retry.js

@@ -136,6 +136,15 @@ export const requestTokens = (body) => {
         chars += messageChars(message);
     return Math.ceil(chars / CHARS_PER_TOKEN) + (body.tools?.length ? toolsCost(body.tools) : 0);
 };
+/**
+ * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
+ *
+ * For the arithmetic that weighs part of a transcript against a window — `planCompaction`'s kept
+ * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
+ *
+ * @param message The message as it will be sent.
+ */
+export const messageTokens = (message) => Math.ceil(messageChars(message) / CHARS_PER_TOKEN);
 /**
  * Servers refuse an over-long request in their own words; these are the ones worth reading as
  * that rather than as a broken request. Matched loosely — every one of them is some