@cubicecho/agent-core 2.11.0 → 2.13.0

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

@@ -24,6 +24,14 @@ The loop above a turn: send, run the tools the model asked for, send again, unti
 - `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
 - `ToolCallRequest` (type) — One call the model made, as `dispatch` is handed it.
 
+### calibration
+
+How many characters a token is worth on one model, learned from what its endpoint reports.
+
+- `calibrate` — Takes one reading from a request that was answered, so the next one to this model is sized by it.
+- `charsPerTokenFor` — The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn has reported one.
+- `resetCalibration` — Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again.
+
 ### capabilities
 
 What an endpoint turned out not to support, and answering it when it says so.
@@ -63,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`.
@@ -86,6 +99,14 @@ What this package needs to know about a caller's configuration.
 - `RetryPolicy` (type) — How many times a lost or refused request is worth sending again.
 - `ToolPolicy` (type) — How tools reach the model, and how long it may keep calling them.
 
+### continuation
+
+Picking up an answer the token ceiling cut off, instead of keeping half of it.
+
+- `ContinueTurnOptions` (type) — What `continueTurn` takes besides what `runTurn` does.
+- `continueTurn` — Carries on an answer the token ceiling cut off, by sending the transcript again with the answer so far as a trailing assistant message, and joins the pieces into one turn.
+- `isContinuable` — Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun and no tool call in it.
+
 ### errors
 
 - `errorMessage` — What went wrong, as a string.
@@ -103,8 +124,12 @@ What a run is doing, while it is doing it.
 - `RunEvent` (type) — One thing that happened in a run, as a watcher receives it.
 - `RunEventInput` (type) — What `emit` is given: the run and the sequence are the bus's to assign.
 - `RunEventKind` (type) — Which kind of thing happened, and what `text`, `name`, `ok` and `usage` carry for it.
+- `RunMetrics` (type) — A run summed and derived from its events: what it cost, where the time went, and why.
+- `RunMetricsOptions` (type) — What `runMetrics` takes besides the events.
 - `RunUsage` (type) — What a run has spent, counted from the start of the run rather than for the turn that carried it: a client draws the latest one it has seen and needs no arithmetic of its own, and one lost to the backlog cap costs nothing because the next supersedes it.
 - `resetEvents` — Test seam: forget every run, so one test's events cannot be read by the next.
+- `runMetrics` — A run's totals, timings and cache findings, derived from the events it emitted.
+- `TurnReport` (type) — One turn's usage and measurements as a `usage` event carries them.
 - `watch` — Everything that has happened on a run, then everything that happens next, until it ends.
 
 ### hooks
@@ -113,6 +138,7 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 
 - `assembleContext` — Builds the context a set of outcomes adds and the notes that go with it.
 - `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for, or whose host wants its own name above the context.
+- `consult` — Runs an event's hooks and waits for their say, for a host that will hold off when one of them vetoes.
 - `Gathered` (type) — The context a set of outcomes adds to a request, and a note for each hook worth mentioning.
 - `gather` — Runs the hooks ahead of a request and builds what they add to it.
 - `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them by default, in estimated tokens.
@@ -143,6 +169,7 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 Everything about a request failing that is not about what the request said.
 
 - `backoffMs` — Exponential, with jitter so several tasks failing at once do not return in lockstep.
+- `CHARS_PER_TOKEN` — The divisor behind `estimateTokens`, applied here to a character count rather than a string.
 - `ContextOverflow` — The request was bigger than the model will read.
 - `compact` — 1234 → "1.2k".
 - `EndpointSilent` — The endpoint stopped answering mid-request.
@@ -152,9 +179,12 @@ Everything about a request failing that is not about what the request said.
 - `LOADING_POLL_MS` — How long to wait between asking a loading server again.
 - `LOADING_TIMEOUT_MS` — How long `runTurn` waits for a model to load unless told otherwise.
 - `messageTokens` — One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
+- `requestChars` — How many characters a request is worth: the walk `requestTokens` divides, without the division.
 - `requestTokens` — What this request will cost the window, in tokens, near enough.
 - `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under `runTurn`'s guard.
 - `sleep` — A delay an abort cuts short, rejecting rather than resolving early.
+- `TokenEstimateOptions` (type) — What the two token estimates below take besides what they measure.
+- `toolsChars` — How many characters a tool array is worth, measured once per array.
 
 ### run-turn
 
@@ -205,7 +235,7 @@ Reading one streamed turn back into a message.
 - `StreamTurnOptions` (type) — What `streamTurn` takes besides the request body.
 - `streamTurn` — Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a message.
 - `Turn` (type) — One streamed turn, put back together into the shape a loop and a transcript work with.
-- `TurnUsage` (type) — What a turn cost.
+- `TurnUsage` (type) — What a turn cost, and how it went.
 
 ### thinking
 
@@ -246,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.11.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",