@cubicecho/agent-core 2.12.0 → 2.14.0

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

@@ -38,11 +38,12 @@ What an endpoint turned out not to support, and answering it when it says so.
 
 - `Capabilities` (type) — What one endpoint turned out not to support.
 - `capabilitiesFor` — What this endpoint is known not to support.
+- `expireCapabilities` — Forgets every endpoint whose entry is older than this, so the next request finds out again.
 - `ModelCapabilities` (type) — What one model on that endpoint turned out not to support.
 - `modelCapabilitiesFor` — What this model on this endpoint is known not to support.
 - `NegotiateOptions` (type) — What `negotiate` takes besides the request.
 - `negotiate` — Sends a request, re-sending it each time the answer is this endpoint refusing something the request can do without.
-- `resetCapabilities` — Forgets every endpoint's capabilities.
+- `resetCapabilities` — Forgets what one endpoint refused, or every endpoint's when told none.
 
 ### catalog
 
@@ -71,14 +72,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`.
@@ -165,8 +171,12 @@ 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.
+- `ContextBreakdown` (type) — What a request is made of, by the part of it a consumer can actually do something about.
+- `ContextBreakdownOptions` (type) — What `contextTokens` takes besides the request.
 - `ContextOverflow` — The request was bigger than the model will read.
 - `compact` — 1234 → "1.2k".
+- `contextChars` — What each part of a request is worth in characters, by the same walk `requestTokens` divides.
+- `contextTokens` — What each part of a request costs the window, in tokens, adding up to the whole.
 - `EndpointSilent` — The endpoint stopped answering mid-request.
 - `isModelLoading` — Whether a failure is a local server still loading the model, rather than one failing to serve.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
@@ -271,9 +281,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.14.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",