@cubicecho/agent-core 2.22.0 → 2.24.0

package/dist/tool-calls.d.ts

@@ -26,6 +26,15 @@ export declare class ToolArgumentsError extends Error {
      */
     constructor(kind: "truncated" | "malformed", message: string);
 }
+/**
+ * JSON as it was written, then repaired, then undefined. A string holding JSON is opened once.
+ *
+ * Read as written first, so the repair can only ever add to what parses: nothing valid is
+ * reinterpreted on its way through.
+ *
+ * @param text What a model wrote where JSON was asked for, with no prose around it.
+ */
+export declare function looseJson(text: string): unknown;
 /**
  * A tool call's arguments as the object the tool is handed. Empty is no arguments.
  *

package/dist/tool-calls.js

@@ -1,3 +1,4 @@
+import { isRecord } from "./guards.js";
 /**
  * Tool arguments that could not be read as an object, with why.
  *
@@ -18,7 +19,6 @@ export class ToolArgumentsError extends Error {
         this.kind = kind;
     }
 }
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
  * Rewrites the almost-JSON local models write into JSON, in one pass that knows where strings are.
  *
@@ -71,8 +71,15 @@ function repairJson(text) {
     }
     return out;
 }
-/** JSON as it was written, then repaired, then undefined. A string holding JSON is opened once. */
-function looseJson(text) {
+/**
+ * JSON as it was written, then repaired, then undefined. A string holding JSON is opened once.
+ *
+ * Read as written first, so the repair can only ever add to what parses: nothing valid is
+ * reinterpreted on its way through.
+ *
+ * @param text What a model wrote where JSON was asked for, with no prose around it.
+ */
+export function looseJson(text) {
     for (const candidate of [text, repairJson(text)]) {
         try {
             const value = JSON.parse(candidate);
@@ -178,9 +185,7 @@ function toCall(entry) {
 function toCalls(value) {
     const entries = Array.isArray(value) ? value : [value];
     const calls = entries.map(toCall);
-    return calls.length && calls.every((call) => call)
-        ? calls
-        : undefined;
+    return calls.length && calls.every((call) => call) ? calls : undefined;
 }
 /** A value read as text: JSON where it parses, the string where it does not. */
 function scalar(text) {

package/dist/tool-loading.d.ts

@@ -53,6 +53,16 @@ export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlyS
  * not mind the cache. Absent marks nothing.
  */
 export declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * The name a tool definition is called by, or `undefined` for one that is not a function.
+ *
+ * Undefined rather than empty, so a caller that skips such a tool and one that has to place it
+ * somewhere each say which they mean — a sort and a positional comparison want `?? ""`, a lookup
+ * by name wants the tool left out.
+ *
+ * @param tool The definition, as a request declares it.
+ */
+export declare const toolName: (tool: OpenAI.ChatCompletionTool) => string | undefined;
 /**
  * A tool array with newly loaded definitions appended, in the order they were loaded.
  *

package/dist/tool-loading.js

@@ -1,3 +1,4 @@
+import { isRecord } from "./guards.js";
 /**
  * On-demand tool loading.
  *
@@ -104,6 +105,16 @@ export function catalogPrompt(catalog, loaded) {
     ].join("\n");
 }
 const flatten = (catalog) => catalog.flatMap((server) => server.tools);
+/**
+ * The name a tool definition is called by, or `undefined` for one that is not a function.
+ *
+ * Undefined rather than empty, so a caller that skips such a tool and one that has to place it
+ * somewhere each say which they mean — a sort and a positional comparison want `?? ""`, a lookup
+ * by name wants the tool left out.
+ *
+ * @param tool The definition, as a request declares it.
+ */
+export const toolName = (tool) => tool.type === "function" ? tool.function.name : undefined;
 /**
  * A tool array with newly loaded definitions appended, in the order they were loaded.
  *
@@ -116,11 +127,10 @@ const flatten = (catalog) => catalog.flatMap((server) => server.tools);
  * this list, are skipped rather than moved.
  */
 export function loadedTools(previous, matched) {
-    const nameOf = (tool) => tool.type === "function" ? tool.function.name : undefined;
-    const declared = new Set(previous.map(nameOf));
+    const declared = new Set(previous.map(toolName));
     const tools = [...previous];
     for (const tool of matched) {
-        const name = nameOf(tool);
+        const name = toolName(tool);
         if (name !== undefined && declared.has(name))
             continue;
         declared.add(name);
@@ -151,7 +161,7 @@ export function loadedTools(previous, matched) {
 export function orderTools(tools, order = true) {
     if (order === false)
         return tools;
-    const nameOf = (tool) => tool.type === "function" ? tool.function.name : "";
+    const nameOf = (tool) => toolName(tool) ?? "";
     // 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);
@@ -618,9 +628,7 @@ export const preselectInput = (catalog, prompt, maxPromptChars = PRESELECT_PROMP
  * `preselectSystem` was given, or the model is being held to a cap it was never told about.
  */
 export function preselection(names, catalog, maxPerLoad = MAX_PER_LOAD) {
-    const list = names && typeof names === "object" && !Array.isArray(names)
-        ? names.tools
-        : names;
+    const list = isRecord(names) ? names.tools : names;
     if (!Array.isArray(list))
         return [];
     const wanted = list.filter((name) => typeof name === "string");

package/llms.txt

@@ -144,6 +144,14 @@ What a run is doing, while it is doing it.
 - `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.
 
+### hook-events
+
+The points in a session a hook can be bound to, apart from everything that runs one.
+
+- `HOOK_EVENTS` — Every event a hook can be bound to, in the order a session meets them.
+- `HookEvent` (type) — A point in a session a hook can be bound to.
+- `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
+
 ### hooks
 
 Lifecycle hooks, from the host's side: what a session looks like to them, where their context lands in a request, and what is said about each one.
@@ -154,16 +162,13 @@ Lifecycle hooks, from the host's side: what a session looks like to them, where
 - `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.
-- `HOOK_EVENTS` — Every event a hook can be bound to, in the order a session meets them.
 - `HOOK_PREFACE` — Said once, above the blocks, so the model reads them as background rather than instructions.
 - `HookContext` (type) — What a host knows at an event.
-- `HookEvent` (type) — A point in a session a hook can be bound to.
 - `HookMessage` (type) — One message of a session as a hook is handed it.
 - `HookNote` (type) — One hook's line for whoever is watching: the context it added, or why it added none.
 - `HookOptions` (type) — What hooks are held to across a process.
 - `HookOutcome` (type) — What one hook did.
 - `HookRunner` (type) — Runs one event's hooks.
-- `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
 - `notify` — Runs the hooks for an event that reads what happened and adds nothing to a request.
 - `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget or preface is not the next's.
 - `turnIndex` — Which turn of a session begins at a point, from 0: the user messages ahead of it.
@@ -194,7 +199,6 @@ What stretches of a transcript cost, read off the prompt counts the server alrea
 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.
@@ -222,12 +226,21 @@ One turn, given as many attempts as the caller allows.
 - `RunTurnOptions` (type) — A retry is not the same event as a downgrade, but a watcher wants to be told about both.
 - `runTurn` — `request` is a callback rather than a body because the body has to be rebuilt from whatever the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools` has to apply to the schemas that were just sanitised.
 
+### runtime
+
+- `createRuntime` — A runtime of its own: separate clients, listings, capability latches, hints, event bus and hook settings from the process's and from every other runtime's.
+- `defaultRuntime` — The runtime the top-level functions use when no other is running.
+- `Runtime` (type) — One set of the package's caches, with the functions that use them as methods.
+- `RuntimeOptions` (type) — What a runtime starts out configured with.
+
 ### schema-compat
 
 JSON Schema compatibility for llama.cpp-backed servers.
 
 - `isGrammarError` — Does this failure look like the server could not build a grammar from our tool schemas?
+- `relaxSchema` — One schema without its `pattern` and `format` keywords, for a schema that is not a tool's.
 - `relaxTools` — The retry shape: llama.cpp's converter rejects regex escape classes (`\d`, `\w`, `\s`) in `pattern` and most `format` values, both of which only ever narrowed a string the tool re-validates anyway.
+- `sanitizeSchema` — One JSON Schema as a strict server will accept it, for a schema that is not a tool's parameters.
 - `sanitizeTools` — Tool definitions a strict server will accept, remembered per definition object.
 
 ### side-task
@@ -279,7 +292,7 @@ A JSON document that defines an agent, and the rules for reading one.
 - `ResolvedTask` (type) — One side task, resolved: a model, and the endpoint it is reached through.
 - `RetrySpec` (type) — What to do about a request lost before the model produced anything.
 - `resolveAgentSpec` — Layers documents into the flat object the loop takes, weakest first.
-- `SPEC_EVENTS` — Every event a hook may be bound to, restated so this module stays free of `node:crypto`.
+- `SPEC_EVENTS` — Every event a hook may be bound to: `HOOK_EVENTS`, under the name a document's reader knows.
 - `SpecBundle` (type) — What an agent carries so it can travel whole: the definitions of the servers it names.
 - `SpecServer` (type) — A bundled MCP server, validated only as far as a round trip needs and otherwise passed through.
 - `TaskSpec` (type) — One side task, which may run on a different model — and a different machine — than the agent.
@@ -310,6 +323,7 @@ Telling a model's scratchpad from its answer when both arrive in `content`.
 
 ### tokens
 
+- `CHARS_PER_TOKEN` — The characters one token is taken to be, where nothing has measured it.
 - `estimateTokens` — Rough token count.
 
 ### tool-calls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.22.0",
+  "version": "2.24.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",