@cubicecho/agent-core 2.12.0 → 2.13.0

package/README.md

@@ -365,8 +365,17 @@ and — naming only tools that exist — a reply that is only a JSON call or hol
 Found calls are run as `call_recovered_0` onward, the text is what is left, `onTurn` and the
 result see the turn that way, and a notice says so, since the real fix is the server's parser.
 
+Every request declares its tools in name order, whichever way the caller assembled the array. A
+chat template renders the tool block ahead of the system prompt, so the tool array is the first
+thing a prompt cache has to match, and an array built from a map, from database rows, or from the
+order servers happened to connect in is a different array on the next boot — the same tools, the
+same run, and the cache for the whole transcript thrown away. Ordering by name makes it a property
+of the set instead. `toolOrder: false` sends the caller's order, for a host that means it — a model
+reads the array top to bottom — and a comparator orders it another way. `orderTools` is the same
+thing for a caller with its own loop, and `buildBody` takes the order as its last argument.
+
 With `toolDiscovery: "ondemand"` and a catalogue, the request declares `load_tools` and what has
-been loaded, appended in the order it was loaded, and the catalogue rides on the system prompt
+been loaded, and the catalogue rides on the system prompt
 unmarked, the same text on every step. Marking loads there rewrote the head of the prompt and lost
 the prompt cache for the whole transcript on each one; a model that loads a tool twice is told in
 the `load_tools` result that it already has it. A model that calls
@@ -513,6 +522,51 @@ way to save tokens.
 `pruneToolResults` keeps the transcript's indexes, so a plan made before pruning still applies to
 what it returns, as above.
 
+### A fold you store, instead of a transcript you rewrite
+
+`compactTranscript` hands back a new array, which is the whole answer for a host whose transcript
+*is* that array. A host that keeps its messages append-only — rows in a database, every one still
+shown in the chat — wants the other half: what the fold was, as something to store on the session.
+`runCompaction` is `compactTranscript` without the rewrite. It returns `{ summary, through, at }`,
+or `undefined` when a hook vetoed or the summary came back empty, and `compactTranscript` is built
+out of it, so there is one summariser and one cut rather than two that drift.
+
+```ts
+const from = session.fold?.through ?? 0;
+const plan = planCompaction(session.messages, {
+  limit,
+  used,
+  from, // where the last fold ended, rather than scanning for it
+  previous: session.fold?.summary,
+});
+if (!plan) return;
+const fold = await runCompaction(session.messages, plan, summarise, { hooks: { run, context } });
+if (fold) await save(session.id, fold); // the messages themselves are never touched
+```
+
+`planCompaction` takes `from` and `previous` because its defaults are a *recovery*: it skips the
+leading `system` messages, and reads an earlier summary back out of a `SUMMARY_LEAD` message among
+them. A host whose system prompt is a separate argument and whose summary is a column has neither
+in the array, and knows both exactly. Given them, nothing is scanned.
+
+`applyCompaction(messages, fold)` is the way back — the summary as a `system` message, then
+everything from `through` — and it writes the same `SUMMARY_LEAD` `planCompaction` looks for, so
+the next fold continues those notes rather than summarising them a second time. No fold yet hands
+back the messages themselves.
+
+```ts
+const request = [systemMessage, ...applyCompaction(session.messages, session.fold)];
+```
+
+**Two numberings.** A stored transcript keeps its indexes and a folded request does not, so
+anything naming a position has to say which one it means. `requestIndex(index, fold)` maps the
+stored index onto the request — for `withContext`'s index, or a range being shown to a hook.
+`turnMessages` takes an `offset`, the stored index of the array's first message, so a message keeps
+the uuid it had before the fold and a memory server deduping on it files that turn once rather than
+twice; `turnIndex` takes one too, for the turns a fold took out of the array it is counting.
+Planning over the stored transcript, as above, sidesteps both: the plan's indexes are the host's
+already, and so are the ones `runCompaction` hands the `beforeCompact` hooks.
+
 ## Watching a run
 
 `watch` replays what the run has already emitted, then yields what happens next until `done`.

package/dist/agent-loop.d.ts

@@ -5,6 +5,7 @@ import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
+import { type ToolOrder } from "./tool-loading.ts";
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.
@@ -22,10 +23,13 @@ import type { Turn, TurnUsage } from "./stream.ts";
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
  * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Sanitised here — a lookup for a definition seen before —
- * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
+ * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param order How to order them before sending. `true`, the default, is by name, which keeps the
+ * cache when the caller's array is assembled differently from one request to the next. See
+ * `orderTools`.
  */
-export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionCreateParamsStreaming;
+export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[], order?: ToolOrder): OpenAI.ChatCompletionCreateParamsStreaming;
 /**
  * A long tool argument or result cut to what a watcher needs, with the full length said.
  *
@@ -131,6 +135,12 @@ export interface AgentLoopOptions {
     tools?: OpenAI.ChatCompletionTool[];
     /** The same tools as a name-only catalogue. On-demand mode needs it, and is eager without it. */
     catalog?: CatalogServer[];
+    /**
+     * How the declared tools are ordered before each request. By name unless told otherwise, so a
+     * run whose tool array was assembled in a different order than last time still meets its cache.
+     * `false` sends them as given. See `orderTools`.
+     */
+    toolOrder?: ToolOrder;
     /**
      * What `preselect` picked. The first step is sent these and nothing else — no catalogue, no
      * `load_tools` — because a model with the menu still in front of it shops: it reloads what it
@@ -203,7 +213,8 @@ export interface AgentLoopResult {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * prompt unchanged from step to step, a load adds to the tool array — which every request sends
+ * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
  * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
  * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is

package/dist/agent-loop.js

@@ -10,7 +10,7 @@ import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
 import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -40,11 +40,17 @@ const RESERVED = new Set(["model", "messages", "stream", "tools"]);
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
  * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Sanitised here — a lookup for a definition seen before —
- * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
+ * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param order How to order them before sending. `true`, the default, is by name, which keeps the
+ * cache when the caller's array is assembled differently from one request to the next. See
+ * `orderTools`.
  */
-export function buildBody(config, supports, refused, messages, tools = []) {
-    const declared = supports.strictSchemas ? sanitizeTools(tools) : relaxTools(sanitizeTools(tools));
+export function buildBody(config, supports, refused, messages, tools = [], order = true) {
+    const sorted = orderTools(tools, order);
+    const declared = supports.strictSchemas
+        ? sanitizeTools(sorted)
+        : relaxTools(sanitizeTools(sorted));
     const effort = config.reasoningEffort;
     const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
     return {
@@ -183,7 +189,8 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * prompt unchanged from step to step, a load adds to the tool array — which every request sends
+ * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
  * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
  * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
@@ -195,7 +202,7 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  */
 export async function runAgentLoop(options) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, } = options;
+    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, } = options;
     const started = Date.now();
     // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
     // than by the bus, which the loop does not know about.
@@ -262,11 +269,14 @@ export async function runAgentLoop(options) {
         messages = (await beforeStep?.(messages, step)) ?? messages;
         onEvent({ kind: "turn", text: `turn ${step + 1}` });
         const routed = preselected.length > 0 && step === 0;
-        const declared = routed
+        // Ordered here rather than left to `buildBody`, so `names` below is what the request actually
+        // declared — a diagnosis reading an order the server never saw calls an untouched tool array
+        // `tools-changed`.
+        const declared = orderTools(routed
             ? byName(new Set(preselected))
             : onDemand
                 ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
-                : tools;
+                : tools, toolOrder);
         // Unmarked, so the system prompt is the same text on every step and a load does not throw
         // away the cache for the whole transcript. What is loaded is said in `declared` and in the
         // `load_tools` result instead. The preselected first step is the one exception, by design.
@@ -275,7 +285,7 @@ export async function runAgentLoop(options) {
             ...(prompt ? [{ role: "system", content: prompt }] : []),
             ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
         ];
-        const build = (supported, refused) => buildBody(config, supported, refused, request, declared);
+        const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
         const turnOptions = {
             model: config.model,
             droppable: Object.keys(config.extraBody ?? {}),
@@ -427,7 +437,7 @@ export async function runAgentLoop(options) {
                     used.add(name);
                     const request = { id: call.id, name, args, raw };
                     content = parallel
-                        ? await once(answered, `${name}${normal}`, () => dispatch(request, signal))
+                        ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
             }

package/dist/compaction.d.ts

@@ -70,6 +70,16 @@ export interface CompactionOptions {
      * an `estimate` of the caller's own.
      */
     charsPerToken?: number;
+    /**
+     * The first message that may be folded. Absent, the leading `system` messages are skipped and
+     * the fold starts after them.
+     */
+    from?: number;
+    /**
+     * The summary an earlier fold left, which this one continues. Absent, it is recovered from a
+     * `SUMMARY_LEAD` system message at the head, if there is one.
+     */
+    previous?: string;
 }
 /** Where to cut, as `compactTranscript` takes it. */
 export interface CompactionPlan {
@@ -92,10 +102,16 @@ export interface CompactionPlan {
  * 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.
  *
+ * Both of those are recovered by reading the transcript, which is what a host whose array holds
+ * everything it sends has to do. A host that keeps its fold as a record beside an append-only
+ * transcript — its system prompt a separate argument, no summary message in the array at all —
+ * knows them exactly, and passes `from` and `previous` instead of hoping the scan agrees.
+ *
  * @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`.
+ * @param options The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
  */
-export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, }: CompactionOptions): CompactionPlan | undefined;
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, from: givenFrom, previous: givenPrevious, }: 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.
@@ -114,6 +130,93 @@ export declare function summaryInput(plan: CompactionPlan): string;
 export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
     system?: string;
 }) => (text: string) => Promise<string>;
+/**
+ * One fold, as a host that keeps its transcript append-only stores it.
+ *
+ * The other half of `compactTranscript`: the same work, recorded rather than applied. A host that
+ * persists this beside an untouched transcript still shows the user every message, can undo a fold
+ * by dropping one row, and rebuilds the request with `applyCompaction` — where a host that keeps
+ * only the rewritten array has thrown the originals away.
+ */
+export interface CompactionRecord {
+    /** The model's notes on everything before `through`. Trimmed, and never empty. */
+    summary: string;
+    /** Index into the transcript the plan was made for: the first message still sent whole. */
+    through: number;
+    /** ISO 8601, so the chat can show where history was folded and how stale the notes are. */
+    at: string;
+}
+/** What `runCompaction` and `compactTranscript` take beside the plan. */
+export interface CompactionRunOptions {
+    /**
+     * Hooks to tell. `context` is extended with `compacting` and `range`, whose indexes are the
+     * plan's — and so the host's own, for a plan made over a stored transcript. `honourVeto` waits
+     * for the hooks and lets one stop the compaction; off by default, which adds no latency.
+     */
+    hooks?: {
+        run: HookRunner;
+        context: HookContext;
+        onNote?: (note: HookNote) => void;
+        honourVeto?: boolean;
+    };
+    /**
+     * The window is already exceeded — the caller caught a `ContextOverflow`, or is compacting to
+     * make a refused request fit — which overrides `honourVeto`.
+     */
+    forced?: boolean;
+}
+/**
+ * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
+ *
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
+ *
+ * @param messages The transcript the plan was made for. Read only, and only for the hooks.
+ * @param plan What `planCompaction` returned for it.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
+ * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
+ * so the caller stores nothing and the transcript is still whole.
+ */
+export declare function runCompaction(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced }?: CompactionRunOptions): Promise<CompactionRecord | undefined>;
+/**
+ * The transcript as the server should see it: the folded head replaced by its summary.
+ *
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
+ *
+ * @param messages The stored transcript, whole. Not written to.
+ * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * back `messages` itself.
+ * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
+ * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
+ * case for a host whose system prompt is a separate argument.
+ */
+export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, "summary" | "through">, { from }?: {
+    from?: number;
+}): Message[];
+/**
+ * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
+ * everything after it.
+ *
+ * A transcript that stays append-only and a request that does not are two numberings of the same
+ * conversation, and anything that names a position — `withContext`'s index, a range handed to a
+ * hook — has to say which it is in. An index inside the folded stretch answers with the summary
+ * message that now stands for it.
+ *
+ * @param index The position in the stored transcript.
+ * @param record The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param head How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
+ * where the summary is the request's first message.
+ */
+export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, "through">, head?: number) => number;
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *
@@ -127,25 +230,18 @@ export declare const summariser: (config: Endpoint, model: string, { system, max
  * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
  * comment on when to run it.
  *
+ * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
+ * order, so a host that stores the fold instead of the array gets the same summary at the same
+ * cut rather than a second implementation that drifts from this one.
+ *
  * @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`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
- * by default, which adds no latency. `forced` says the window is already exceeded — the caller
- * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
- * `honourVeto`.
+ * @param options Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
  * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
  * new array.
  */
-export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced, }?: {
-    hooks?: {
-        run: HookRunner;
-        context: HookContext;
-        onNote?: (note: HookNote) => void;
-        honourVeto?: boolean;
-    };
-    forced?: boolean;
-}): Promise<Message[]>;
+export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, options?: CompactionRunOptions): Promise<Message[]>;
 export {};

package/dist/compaction.js

@@ -37,6 +37,25 @@ const messageText = (message) => {
     return `${textOf(message.content)} ${calls}`.trim();
 };
 const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
+/** The summary as it sits in a transcript, which is the one shape `isSummary` recognises again. */
+const summaryMessage = (summary) => ({
+    role: "system",
+    content: `${SUMMARY_LEAD}${summary.trim()}`,
+});
+/**
+ * The leading system messages a fold never touches, and the summary an earlier one left among
+ * them. What a caller who keeps its system prompt out of the array knows already, and passes.
+ */
+const systemHead = (messages) => {
+    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++;
+    }
+    return { from, previous };
+};
 /**
  * The transcript with every tool result but the latest few replaced by a one-line stub.
  *
@@ -80,22 +99,24 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * 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.
  *
+ * Both of those are recovered by reading the transcript, which is what a host whose array holds
+ * everything it sends has to do. A host that keeps its fold as a record beside an append-only
+ * transcript — its system prompt a separate argument, no summary message in the array at all —
+ * knows them exactly, and passes `from` and `previous` instead of hoping the scan agrees.
+ *
  * @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`.
+ * @param options The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
  */
-export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), }) {
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), from: givenFrom, previous: givenPrevious, }) {
     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 head = systemHead(messages);
+    const from = Math.min(Math.max(givenFrom ?? head.from, 0), messages.length);
+    const previous = givenPrevious ?? head.previous;
     const budget = limit * keepRatio;
     let kept = 0;
     let cut = messages.length;
@@ -139,31 +160,21 @@ export function summaryInput(plan) {
  */
 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.
+ * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
  *
- * `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 host that wants its hooks able to stop a compaction sets
- * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
- * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
- * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
- * past its window has no better option — a veto there only trades the summary for a
- * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
- * comment on when to run it.
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
  *
- * @param messages The transcript the plan was made for. Not written to.
+ * @param messages The transcript the plan was made for. Read only, and only for the hooks.
  * @param plan What `planCompaction` returned for it.
  * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
- * by default, which adds no latency. `forced` says the window is already exceeded — the caller
- * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
- * `honourVeto`.
- * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
- * new array.
+ * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
+ * so the caller stores nothing and the transcript is still whole.
  */
-export async function compactTranscript(messages, plan, summarise, { hooks, forced = false, } = {}) {
+export async function runCompaction(messages, plan, summarise, { hooks, forced = false } = {}) {
     const context = hooks && {
         ...hooks.context,
         compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
@@ -173,7 +184,7 @@ export async function compactTranscript(messages, plan, summarise, { hooks, forc
     if (hooks && context && hooks.honourVeto && !forced) {
         const { vetoed } = await consult(hooks.run, "beforeCompact", context, hooks.onNote);
         if (vetoed)
-            return messages;
+            return undefined;
         summary = await summarise(summaryInput(plan));
     }
     else {
@@ -183,10 +194,85 @@ export async function compactTranscript(messages, plan, summarise, { hooks, forc
         ]);
     }
     if (!summary.trim())
+        return undefined;
+    return { summary: summary.trim(), through: plan.cut, at: new Date().toISOString() };
+}
+/**
+ * The transcript as the server should see it: the folded head replaced by its summary.
+ *
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
+ *
+ * @param messages The stored transcript, whole. Not written to.
+ * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * back `messages` itself.
+ * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
+ * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
+ * case for a host whose system prompt is a separate argument.
+ */
+export function applyCompaction(messages, record, { from } = {}) {
+    if (!record?.summary.trim())
         return messages;
+    const head = Math.min(Math.max(from ?? systemHead(messages).from, 0), record.through);
     return [
-        ...messages.slice(0, plan.from).filter((message) => !isSummary(message)),
-        { role: "system", content: `${SUMMARY_LEAD}${summary.trim()}` },
-        ...messages.slice(plan.cut),
+        ...messages.slice(0, head).filter((message) => !isSummary(message)),
+        summaryMessage(record.summary),
+        ...messages.slice(record.through),
     ];
 }
+/**
+ * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
+ * everything after it.
+ *
+ * A transcript that stays append-only and a request that does not are two numberings of the same
+ * conversation, and anything that names a position — `withContext`'s index, a range handed to a
+ * hook — has to say which it is in. An index inside the folded stretch answers with the summary
+ * message that now stands for it.
+ *
+ * @param index The position in the stored transcript.
+ * @param record The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param head How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
+ * where the summary is the request's first message.
+ */
+export const requestIndex = (index, record, head = 0) => {
+    if (!record)
+        return index;
+    return index < record.through ? head : index - record.through + head + 1;
+};
+/**
+ * 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 host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
+ * comment on when to run it.
+ *
+ * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
+ * order, so a host that stores the fold instead of the array gets the same summary at the same
+ * cut rather than a second implementation that drifts from this one.
+ *
+ * @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`. Not called
+ * when a hook vetoes.
+ * @param options Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
+ * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
+ */
+export async function compactTranscript(messages, plan, summarise, options = {}) {
+    const record = await runCompaction(messages, plan, summarise, options);
+    if (!record)
+        return messages;
+    return applyCompaction(messages, record, { from: plan.from });
+}

package/dist/hooks.d.ts

@@ -256,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.
  *

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: "",

package/dist/index.d.ts

@@ -14,7 +14,7 @@ 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";
@@ -30,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";

package/dist/index.js

@@ -13,7 +13,7 @@ export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./a
 export { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { configureClients, contextLimitFor, endpointId, endpointKey, FIRST_TOKEN_FACTOR, firstTokenMs, getClient, listModels, NO_KEY, resetClients, servedWindow, timeoutMs, } from "./client.js";
-export { COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
+export { applyCompaction, COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, requestIndex, runCompaction, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { continueTurn, isContinuable, } from "./continuation.js";
 export { errorMessage } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, runMetrics, watch, } from "./events.js";
@@ -28,4 +28,4 @@ export { streamTurn, } from "./stream.js";
 export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-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.js";
+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, } from "./tool-loading.js";

package/dist/tool-loading.d.ts

@@ -56,16 +56,41 @@ export declare function catalogPrompt(catalog: CatalogServer[], loaded?: Readonl
 /**
  * A tool array with newly loaded definitions appended, in the order they were loaded.
  *
- * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
- * prompt near its head, and a load that moved an earlier definition moved everything after it,
- * so the cache was lost from there on every load; appended, the definitions already sent stay
- * a prefix of the new array.
+ * Appended and never rebuilt from a set, so what a load adds is decided by the load and not by
+ * the shape of whatever collection the definitions came out of. Where the appended array ends up
+ * in the request is `orderTools`' business, which the loop applies after this.
  *
  * @param previous What the last request declared, `load_tools` included. Not written to.
  * @param matched The definitions to add. Ones whose name is already declared, here or earlier in
  * this list, are skipped rather than moved.
  */
 export declare function loadedTools(previous: readonly OpenAI.ChatCompletionTool[], matched: readonly OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
+/**
+ * How a tool array is ordered before it is sent: `true` by name, `false` as the caller built it,
+ * or a comparator over the two names.
+ */
+export type ToolOrder = boolean | ((a: string, b: string) => number);
+/**
+ * The tool array in a stable order, so the same set of tools renders the same way twice.
+ *
+ * A chat template renders the declared tools ahead of the system prompt, which makes the tool
+ * array the first thing a prompt cache has to match — and an array assembled from a map, from
+ * database rows, or from the order servers happened to connect in changes between processes and
+ * between reconnects. Every such change costs the cache for the whole transcript rather than for
+ * the tools alone, and nothing about the request the model sees is different. Ordering by name
+ * makes the array a property of the set instead of of how it was built, at the price of a load
+ * inserting rather than appending. Definitions come back by identity, so `sanitizeTools` still
+ * finds each one in its cache.
+ *
+ * `false` is for a caller that means its order: the model reads the array top to bottom, and a
+ * host may be putting what it wants reached for first at the front.
+ *
+ * @param tools The definitions to order. Not written to.
+ * @param order `true` for name order, `false` to leave it alone, or a comparator over the names.
+ * A tool that is not a function orders as the empty name.
+ * @returns `tools` itself when it is already in that order, so the common case copies nothing.
+ */
+export declare function orderTools(tools: OpenAI.ChatCompletionTool[], order?: ToolOrder): OpenAI.ChatCompletionTool[];
 /**
  * The most a single `load_tools` call may pull in.
  *

package/dist/tool-loading.js

@@ -107,10 +107,9 @@ const flatten = (catalog) => catalog.flatMap((server) => server.tools);
 /**
  * A tool array with newly loaded definitions appended, in the order they were loaded.
  *
- * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
- * prompt near its head, and a load that moved an earlier definition moved everything after it,
- * so the cache was lost from there on every load; appended, the definitions already sent stay
- * a prefix of the new array.
+ * Appended and never rebuilt from a set, so what a load adds is decided by the load and not by
+ * the shape of whatever collection the definitions came out of. Where the appended array ends up
+ * in the request is `orderTools`' business, which the loop applies after this.
  *
  * @param previous What the last request declared, `load_tools` included. Not written to.
  * @param matched The definitions to add. Ones whose name is already declared, here or earlier in
@@ -129,6 +128,36 @@ export function loadedTools(previous, matched) {
     }
     return tools;
 }
+/**
+ * The tool array in a stable order, so the same set of tools renders the same way twice.
+ *
+ * A chat template renders the declared tools ahead of the system prompt, which makes the tool
+ * array the first thing a prompt cache has to match — and an array assembled from a map, from
+ * database rows, or from the order servers happened to connect in changes between processes and
+ * between reconnects. Every such change costs the cache for the whole transcript rather than for
+ * the tools alone, and nothing about the request the model sees is different. Ordering by name
+ * makes the array a property of the set instead of of how it was built, at the price of a load
+ * inserting rather than appending. Definitions come back by identity, so `sanitizeTools` still
+ * finds each one in its cache.
+ *
+ * `false` is for a caller that means its order: the model reads the array top to bottom, and a
+ * host may be putting what it wants reached for first at the front.
+ *
+ * @param tools The definitions to order. Not written to.
+ * @param order `true` for name order, `false` to leave it alone, or a comparator over the names.
+ * A tool that is not a function orders as the empty name.
+ * @returns `tools` itself when it is already in that order, so the common case copies nothing.
+ */
+export function orderTools(tools, order = true) {
+    if (order === false)
+        return tools;
+    const nameOf = (tool) => tool.type === "function" ? tool.function.name : "";
+    // Code-unit order rather than `localeCompare`, whose answer depends on the host's locale —
+    // which is the kind of instability this exists to remove.
+    const compare = typeof order === "function" ? order : (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    const sorted = [...tools].sort((a, b) => compare(nameOf(a), nameOf(b)));
+    return sorted.some((tool, at) => tool !== tools[at]) ? sorted : tools;
+}
 /**
  * The most a single `load_tools` call may pull in.
  *

package/llms.txt

@@ -71,14 +71,19 @@ The contract between whatever holds the tools and the loop that offers them to a
 
 Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded into a summary the model writes itself.
 
+- `applyCompaction` — The transcript as the server should see it: the folded head replaced by its summary.
 - `COMPACT_AT` — The fraction of the window in use before a summary is worth its own round trip.
 - `CompactionOptions` (type) — What `planCompaction` takes.
 - `CompactionPlan` (type) — Where to cut, as `compactTranscript` takes it.
+- `CompactionRecord` (type) — One fold, as a host that keeps its transcript append-only stores it.
+- `CompactionRunOptions` (type) — What `runCompaction` and `compactTranscript` take beside the plan.
 - `compactTranscript` — The transcript with the plan's stretch replaced by one system message holding its summary.
 - `KEEP_RATIO` — The fraction of the window the kept tail may fill, leaving room for the run to grow again.
 - `PruneOptions` (type) — What `pruneToolResults` takes.
 - `planCompaction` — Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
 - `pruneToolResults` — The transcript with every tool result but the latest few replaced by a one-line stub.
+- `requestIndex` — Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted everything after it.
+- `runCompaction` — The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
 - `SUMMARY_LEAD` — How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
 - `SUMMARY_PROMPT` — The summariser's instruction when the caller gives none.
 - `summariser` — A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
@@ -271,9 +276,11 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 - `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
 - `MAX_CARRIED` — The most a conversation carries between turns.
 - `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.
+- `orderTools` — The tool array in a stable order, so the same set of tools renders the same way twice.
 - `PRESELECT_SCHEMA` — The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
 - `PRESELECT_SYSTEM` — The preselection system prompt at the default cap, for a caller that never changes it.
 - `preselectInput` — The user message for a preselection call: the catalogue, then the request.
 - `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.
 - `preselectSystem` — The system prompt a preselector is given, holding it to the cap its answer will be held to.
 - `requestedNames` — `load_tools` arguments, defensively — a model may send a bare string or a nested object.
+- `ToolOrder` (type) — How a tool array is ordered before it is sent: `true` by name, `false` as the caller built it, or a comparator over the two names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",