@cubicecho/agent-core 2.22.0 → 2.24.0

package/dist/runtime.js

@@ -0,0 +1,113 @@
+import { preselect, runAgentLoop } from "./agent-loop.js";
+import { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.js";
+import { capabilitiesFor, expireCapabilities, resetCapabilities } from "./capabilities.js";
+import { configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow, } from "./client.js";
+import { compactTranscript, runCompaction, summariser } from "./compaction.js";
+import { continueTurn } from "./continuation.js";
+import { configureEvents, emit, endRun, history, resetEvents, watch, } from "./events.js";
+import { assembleContext, configureHooks, consult, gather, notify, resetHooks, withContext, } from "./hooks.js";
+import { resetAll } from "./reset.js";
+import { runTurn } from "./run-turn.js";
+import { inScope, rootScope } from "./scope.js";
+import { ask, askJson, resetHints, tryAsk } from "./side-task.js";
+import { exportCapabilities, importCapabilities } from "./snapshot.js";
+/**
+ * Every exported function that reads or writes what a runtime remembers, itself or through what
+ * it calls. The rest of the package is pure, and is the same function whichever runtime it is
+ * called beside.
+ */
+const STATEFUL = {
+    runAgentLoop,
+    preselect,
+    runTurn,
+    continueTurn,
+    ask,
+    askJson,
+    tryAsk,
+    summariser,
+    runCompaction,
+    compactTranscript,
+    getClient,
+    listModels,
+    contextLimitFor,
+    servedWindow,
+    configureClients,
+    capabilitiesFor,
+    expireCapabilities,
+    exportCapabilities,
+    importCapabilities,
+    calibrate,
+    charsPerTokenFor,
+    emit,
+    endRun,
+    history,
+    watch,
+    configureEvents,
+    configureHooks,
+    gather,
+    notify,
+    consult,
+    assembleContext,
+    withContext,
+    resetClients,
+    resetCapabilities,
+    resetCalibration,
+    resetHints,
+    resetEvents,
+    resetHooks,
+    resetAll,
+};
+/** Makes the methods of the runtime whose state is `scope`. */
+function bind(scope) {
+    const within = (fn) => (...args) => inScope(scope, () => fn(...args));
+    const methods = Object.fromEntries(Object.entries(STATEFUL).map(([name, fn]) => [
+        name,
+        within(fn),
+    ]));
+    return {
+        ...methods,
+        // What it hands back is called later, by `compactTranscript` or by the host, and asks then.
+        summariser: (...args) => within(summariser(...args)),
+        run: (fn) => inScope(scope, fn),
+    };
+}
+/**
+ * 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.
+ *
+ * For a host that must not share them — one that mints a key per tenant, where a shared pool has
+ * tenants evicting each other's clients and a shared bus has one tenant's run id readable by
+ * another — and for tests, where a runtime per case needs no `resetAll` between them and can run
+ * in parallel. A host with one deployment's worth of endpoints does not need one: the top-level
+ * functions are the default runtime's methods.
+ *
+ * The runtime is carried by async context rather than by argument, so `runAgentLoop` called as a
+ * method uses this runtime all the way down, and so does a top-level function the host calls from
+ * inside it — from `dispatch`, a hook, `onEvent`. Outside a method or `run`, a top-level function
+ * is the default runtime's again; a request handler that emits to a run a runtime started calls
+ * `runtime.emit`.
+ *
+ * Nothing needs closing. A runtime is garbage once nothing holds it; its one timer, the event
+ * bus's sweep, is unreferenced and stops rescheduling when its last run has been swept.
+ *
+ * @param options What to configure it with before first use. A part left out keeps the
+ * defaults — not the default runtime's settings, which a new runtime does not inherit.
+ */
+export function createRuntime(options = {}) {
+    const runtime = bind(new Map());
+    if (options.clients)
+        runtime.configureClients(options.clients);
+    if (options.events)
+        runtime.configureEvents(options.events);
+    if (options.hooks)
+        runtime.configureHooks(options.hooks);
+    return runtime;
+}
+/**
+ * The runtime the top-level functions use when no other is running.
+ *
+ * `defaultRuntime.getClient(endpoint)` and `getClient(endpoint)` are the same call outside any
+ * runtime. Inside one they differ: the top-level function follows the runtime that is running,
+ * and this always reaches the process-wide state.
+ */
+export const defaultRuntime = bind(rootScope);

package/dist/schema-compat.d.ts

@@ -1,4 +1,17 @@
 import type OpenAI from "openai";
+/**
+ * One JSON Schema as a strict server will accept it, for a schema that is not a tool's parameters.
+ *
+ * What `sanitizeTools` does to each tool, without the tool: a `response_format` schema goes through
+ * the same grammar converter a tool's parameters do, and a caller holding only the schema had to
+ * wrap it in a definition to get here. Nothing is remembered — the cache is keyed on a tool
+ * definition's identity, and a bare schema has no object that stands for it across requests.
+ *
+ * @param schema The schema as written. Never mutated. Its root is held to an object, as a tool's
+ * parameters are, and anything that is not a schema at all comes back as an object with no
+ * properties.
+ */
+export declare function sanitizeSchema(schema: unknown): Record<string, unknown>;
 /**
  * Tool definitions a strict server will accept, remembered per definition object.
  *
@@ -9,6 +22,16 @@ import type OpenAI from "openai";
  * changed, a new definition is returned in its place.
  */
 export declare const sanitizeTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
+/**
+ * One schema without its `pattern` and `format` keywords, for a schema that is not a tool's.
+ *
+ * The retry `relaxTools` makes, on a bare schema. Only the keywords go: a property that happens to
+ * be called `format` is an argument name and stays.
+ *
+ * @param schema Already sanitised. Relaxing is the retry, not a substitute for `sanitizeSchema`.
+ * Never mutated; anything that is not a schema comes back as an object with no properties.
+ */
+export declare function relaxSchema(schema: unknown): Record<string, unknown>;
 /**
  * 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

package/dist/schema-compat.js

@@ -1,4 +1,4 @@
-const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+import { isRecord } from "./guards.js";
 /** Lookahead and lookbehind: `(?=`, `(?!`, `(?<=`, `(?<!`. */
 const LOOKAROUND = /\(\?<?[=!]/;
 const PRIMITIVES = new Set(["object", "string", "number", "integer", "boolean", "array", "null"]);
@@ -20,6 +20,24 @@ const SCHEMA_KEYS = new Set([
 ]);
 /** Keys whose value is a name -> schema map. */
 const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+/** The two spellings of a schema's own pool of named definitions. */
+const POOL_KEYS = ["definitions", "$defs"];
+/**
+ * One keyword's value with `fn` applied wherever it holds a schema, and untouched where it holds
+ * data — which is what keeps a walk out of `default`, `enum` and `const`.
+ */
+const mapChildren = (key, value, fn) => {
+    if (SCHEMA_KEYS.has(key))
+        return Array.isArray(value) ? value.map((sub) => fn(sub)) : fn(value);
+    // The keys here are argument names; only the values are schemas.
+    if (SCHEMA_MAPS.has(key) && isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, fn(sub)]));
+    return value;
+};
+/** The names a schema's `required` lists, without whatever in it is not a name. */
+const requiredOf = (node) => Array.isArray(node.required)
+    ? node.required.filter((name) => typeof name === "string")
+    : [];
 /**
  * Coerces one schema position. Malformed MCP output sometimes puts a bare type name where a
  * whole schema belongs, which the grammar converter reports as `Unrecognized schema: "object"`.
@@ -29,7 +47,7 @@ function asSchema(node) {
         return PRIMITIVES.has(node) && node !== "object" ? { type: node } : EMPTY_OBJECT();
     if (typeof node === "boolean")
         return node;
-    if (!isObject(node))
+    if (!isRecord(node))
         return EMPTY_OBJECT();
     return normalize(node);
 }
@@ -50,14 +68,8 @@ function normalize(node) {
             else
                 out.type = "null";
         }
-        else if (SCHEMA_KEYS.has(key)) {
-            out[key] = Array.isArray(value) ? value.map(asSchema) : asSchema(value);
-        }
-        else if (SCHEMA_MAPS.has(key) && isObject(value)) {
-            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, asSchema(sub)]));
-        }
         else {
-            out[key] = value;
+            out[key] = mapChildren(key, value, asSchema);
         }
     }
     collapseNullableUnion(out);
@@ -66,7 +78,7 @@ function normalize(node) {
     if (typeof out.pattern === "string" && LOOKAROUND.test(out.pattern))
         delete out.pattern;
     // `{"type": "object"}` with no properties produces invalid GBNF.
-    if (out.type === "object" && !isObject(out.properties))
+    if (out.type === "object" && !isRecord(out.properties))
         out.properties = {};
     // Strict validators reject any sibling of `$ref`, and draft-07 ignores them, so a reference
     // stands alone or not at all. This is not hypothetical tidying: collapsing `anyOf: [{$ref},
@@ -88,11 +100,11 @@ function collapseNullableUnion(node) {
         const variants = node[key];
         if (!Array.isArray(variants))
             continue;
-        const concrete = variants.filter((item) => !(isObject(item) && item.type === "null"));
+        const concrete = variants.filter((item) => !(isRecord(item) && item.type === "null"));
         if (concrete.length !== 1 || concrete.length === variants.length)
             continue;
         delete node[key];
-        Object.assign(node, { nullable: true, ...(isObject(concrete[0]) ? concrete[0] : {}) });
+        Object.assign(node, { nullable: true, ...(isRecord(concrete[0]) ? concrete[0] : {}) });
     }
 }
 /** Combinators at the top level of a parameters schema; strict backends reject them outright. */
@@ -102,8 +114,8 @@ const LOCAL_POINTER = /^#\/(definitions|\$defs)\/([^/]+)$/;
 /** The `definitions` and `$defs` that a local pointer in this schema resolves against. */
 function poolsOf(parameters) {
     const defs = {};
-    for (const key of ["definitions", "$defs"])
-        if (isObject(parameters[key]))
+    for (const key of POOL_KEYS)
+        if (isRecord(parameters[key]))
             defs[key] = parameters[key];
     return defs;
 }
@@ -119,16 +131,16 @@ function poolsOf(parameters) {
 function resolveRef(node, defs) {
     const seen = new Set();
     let current = node;
-    while (isObject(current) && typeof current.$ref === "string") {
+    while (isRecord(current) && typeof current.$ref === "string") {
         const pointer = current.$ref;
         const target = LOCAL_POINTER.exec(pointer);
         if (!target || seen.has(pointer))
             return undefined;
         seen.add(pointer);
         const pool = defs[target[1]];
-        current = isObject(pool) ? pool[target[2]] : undefined;
+        current = isRecord(pool) ? pool[target[2]] : undefined;
     }
-    return isObject(current) ? current : undefined;
+    return isRecord(current) ? current : undefined;
 }
 /**
  * Replaces a root-level `$ref` with what it points at.
@@ -164,18 +176,16 @@ function mergeRootAllOf(out) {
     if (!Array.isArray(branches))
         return;
     const defs = poolsOf(out);
-    const properties = isObject(out.properties) ? { ...out.properties } : {};
-    const required = new Set(Array.isArray(out.required) ? out.required.filter((name) => typeof name === "string") : []);
+    const properties = isRecord(out.properties) ? { ...out.properties } : {};
+    const required = new Set(requiredOf(out));
     for (const raw of branches) {
         const branch = resolveRef(raw, defs);
         if (!branch)
             continue;
-        if (isObject(branch.properties))
+        if (isRecord(branch.properties))
             Object.assign(properties, branch.properties);
-        if (Array.isArray(branch.required))
-            for (const name of branch.required)
-                if (typeof name === "string")
-                    required.add(name);
+        for (const name of requiredOf(branch))
+            required.add(name);
     }
     if (!Object.keys(properties).length)
         return;
@@ -214,22 +224,16 @@ function mergeRootUnion(out) {
                 shared = new Set();
                 continue;
             }
-            if (isObject(branch.properties))
+            if (isRecord(branch.properties))
                 Object.assign(properties, branch.properties);
-            const names = Array.isArray(branch.required)
-                ? branch.required.filter((name) => typeof name === "string")
-                : [];
+            const names = requiredOf(branch);
             shared = previous === null ? new Set(names) : new Set(names.filter((n) => previous.has(n)));
         }
         if (!Object.keys(properties).length)
             continue;
-        out.properties = { ...(isObject(out.properties) ? out.properties : {}), ...properties };
-        if (shared?.size) {
-            const already = Array.isArray(out.required)
-                ? out.required.filter((name) => typeof name === "string")
-                : [];
-            out.required = [...new Set([...already, ...shared])];
-        }
+        out.properties = { ...(isRecord(out.properties) ? out.properties : {}), ...properties };
+        if (shared?.size)
+            out.required = [...new Set([...requiredOf(out), ...shared])];
     }
 }
 /**
@@ -246,7 +250,7 @@ function collectRefs(node, into) {
             collectRefs(item, into);
         return;
     }
-    if (!isObject(node))
+    if (!isRecord(node))
         return;
     for (const [key, value] of Object.entries(node)) {
         if (key === "$ref" && typeof value === "string")
@@ -269,7 +273,7 @@ function collectRefs(node, into) {
  * outside it still refers in.
  */
 function pruneDefs(out) {
-    const pools = ["definitions", "$defs"].filter((key) => isObject(out[key]));
+    const pools = POOL_KEYS.filter((key) => isRecord(out[key]));
     if (!pools.length)
         return;
     const live = {};
@@ -282,7 +286,7 @@ function pruneDefs(out) {
                 continue;
             const [, poolKey, name] = target;
             const pool = out[poolKey];
-            if (!isObject(pool) || !(name in pool))
+            if (!isRecord(pool) || !(name in pool))
                 continue;
             live[poolKey] ??= new Set();
             const names = live[poolKey];
@@ -317,24 +321,36 @@ function pruneDefs(out) {
 function pruneRequired(out) {
     if (!Array.isArray(out.required))
         return;
-    const properties = isObject(out.properties) ? out.properties : {};
+    const properties = isRecord(out.properties) ? out.properties : {};
     const kept = out.required.filter((name) => typeof name === "string" && name in properties);
     if (kept.length)
         out.required = kept;
     else
         delete out.required;
 }
-function sanitizeParameters(parameters) {
-    if (!isObject(parameters))
+/**
+ * One JSON Schema as a strict server will accept it, for a schema that is not a tool's parameters.
+ *
+ * What `sanitizeTools` does to each tool, without the tool: a `response_format` schema goes through
+ * the same grammar converter a tool's parameters do, and a caller holding only the schema had to
+ * wrap it in a definition to get here. Nothing is remembered — the cache is keyed on a tool
+ * definition's identity, and a bare schema has no object that stands for it across requests.
+ *
+ * @param schema The schema as written. Never mutated. Its root is held to an object, as a tool's
+ * parameters are, and anything that is not a schema at all comes back as an object with no
+ * properties.
+ */
+export function sanitizeSchema(schema) {
+    if (!isRecord(schema))
         return EMPTY_OBJECT();
-    const out = normalize(inlineRootRef(parameters));
+    const out = normalize(inlineRootRef(schema));
     mergeRootAllOf(out);
     mergeRootUnion(out);
     for (const key of TOP_LEVEL_COMBINATORS)
         delete out[key];
     if (out.type !== "object")
         out.type = "object";
-    if (!isObject(out.properties))
+    if (!isRecord(out.properties))
         out.properties = {};
     pruneRequired(out);
     pruneDefs(out);
@@ -386,7 +402,7 @@ const through = (cache, tools, fn) => tools.map((tool) => {
  * @param tools The definitions as the pool hands them over. Never mutated — where a schema
  * changed, a new definition is returned in its place.
  */
-export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParameters);
+export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeSchema);
 /**
  * Walked as a schema rather than as arbitrary JSON, because `pattern` and `format` are keyword
  * names and perfectly ordinary argument names at once. Matching on the key alone deleted a
@@ -394,29 +410,33 @@ export const sanitizeTools = (tools) => through(sanitized, tools, sanitizeParame
  * argument that no longer existed — which every strict validator rejects, so the retry produced
  * the failure it was reaching for. The same distinction keeps the walk out of `default`, `enum`
  * and `const`, whose contents are data, not schema.
- *
- * At module scope rather than inside `relaxTools`, so the closure is made once rather than per
- * call — which, on the path this is on, is per request.
  */
 const strip = (node) => {
     if (Array.isArray(node))
         return node.map(strip);
-    if (!isObject(node))
+    if (!isRecord(node))
         return node;
     const out = {};
     for (const [key, value] of Object.entries(node)) {
         if (key === "pattern" || key === "format")
             continue;
-        if (SCHEMA_KEYS.has(key))
-            out[key] = Array.isArray(value) ? value.map(strip) : strip(value);
-        else if (SCHEMA_MAPS.has(key) && isObject(value))
-            // The keys here are argument names; only the values are schemas.
-            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, strip(sub)]));
-        else
-            out[key] = value;
+        out[key] = mapChildren(key, value, strip);
     }
     return out;
 };
+/**
+ * One schema without its `pattern` and `format` keywords, for a schema that is not a tool's.
+ *
+ * The retry `relaxTools` makes, on a bare schema. Only the keywords go: a property that happens to
+ * be called `format` is an argument name and stays.
+ *
+ * @param schema Already sanitised. Relaxing is the retry, not a substitute for `sanitizeSchema`.
+ * Never mutated; anything that is not a schema comes back as an object with no properties.
+ */
+export function relaxSchema(schema) {
+    const stripped = strip(schema);
+    return isRecord(stripped) ? stripped : EMPTY_OBJECT();
+}
 /**
  * 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
@@ -424,10 +444,7 @@ const strip = (node) => {
  *
  * @param tools Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
  */
-export const relaxTools = (tools) => through(relaxed, tools, (parameters) => {
-    const stripped = strip(parameters);
-    return isObject(stripped) ? stripped : EMPTY_OBJECT();
-});
+export const relaxTools = (tools) => through(relaxed, tools, relaxSchema);
 /**
  * Qwen chat templates raise this when the transcript has no user turn. Some servers wrap it
  * in the same "unable to generate parser" wording as a real schema failure, and stripping

package/dist/scope.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Everything one runtime remembers: each module's state, under a key only that module holds.
+ *
+ * A map rather than a record of named caches, so a module that grows a cache declares it where
+ * it is used and `runtime.ts` does not have to hear about it.
+ */
+export type Scope = Map<symbol, unknown>;
+/** The default runtime's scope: what the top-level functions use when no runtime is running. */
+export declare const rootScope: Scope;
+/** The scope of the runtime whose method is running, or the default one outside any. */
+export declare const currentScope: () => Scope;
+/**
+ * Runs `fn` with `scope` as the current one, for it and for everything it awaits or schedules.
+ *
+ * @param scope The runtime's state. Nested calls replace it for their own duration only.
+ * @param fn What to run. Its return value, or what it throws, is handed straight back.
+ */
+export declare const inScope: <T>(scope: Scope, fn: () => T) => T;
+/** One module's state, read from whichever scope is current. See `scoped`. */
+export interface Scoped<T> {
+    /** The current scope's copy, made on first use. */
+    (): T;
+    /** Drops the current scope's copy, so the next read makes a fresh one. */
+    reset(): void;
+}
+/**
+ * Declares a piece of module state that every runtime has its own copy of.
+ *
+ * What used to be `const cache = new Map()` at the top of a module is `scoped(() => new Map())`,
+ * and each use reads `cache()`. The copy is made lazily, so a runtime pays only for the modules
+ * it touches.
+ *
+ * @param create Builds a fresh, empty copy. Called once per scope, and again after `reset`.
+ */
+export declare function scoped<T>(create: () => T): Scoped<T>;

package/dist/scope.js

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Which scope the code running now belongs to, carried across every `await` beneath a runtime's
+ * method. Async context rather than a parameter, because the state is read five calls down —
+ * `runAgentLoop` to `runTurn` to `negotiate` to `capabilitiesFor` — and threading it would put a
+ * runtime argument on every exported function in between.
+ */
+const active = new AsyncLocalStorage();
+/** The default runtime's scope: what the top-level functions use when no runtime is running. */
+export const rootScope = new Map();
+/** The scope of the runtime whose method is running, or the default one outside any. */
+export const currentScope = () => active.getStore() ?? rootScope;
+/**
+ * Runs `fn` with `scope` as the current one, for it and for everything it awaits or schedules.
+ *
+ * @param scope The runtime's state. Nested calls replace it for their own duration only.
+ * @param fn What to run. Its return value, or what it throws, is handed straight back.
+ */
+export const inScope = (scope, fn) => active.run(scope, fn);
+/**
+ * Declares a piece of module state that every runtime has its own copy of.
+ *
+ * What used to be `const cache = new Map()` at the top of a module is `scoped(() => new Map())`,
+ * and each use reads `cache()`. The copy is made lazily, so a runtime pays only for the modules
+ * it touches.
+ *
+ * @param create Builds a fresh, empty copy. Called once per scope, and again after `reset`.
+ */
+export function scoped(create) {
+    const key = Symbol();
+    const read = () => {
+        const scope = currentScope();
+        if (!scope.has(key))
+            scope.set(key, create());
+        return scope.get(key);
+    };
+    return Object.assign(read, {
+        reset: () => {
+            currentScope().delete(key);
+        },
+    });
+}

package/dist/side-task.d.ts

@@ -126,6 +126,11 @@ export declare function tryAsk<T>(label: string, run: () => Promise<T>, { onNoti
  * Models are asked for JSON and often answer with prose around it, or a fenced block. Pull out
  * the first array or object rather than failing the task over a wrapper.
  *
+ * What is pulled out is read the way a tool call's arguments are: as written where that parses,
+ * and otherwise with the almost-JSON a local model writes repaired — single quotes, `True` and
+ * `None`, bare keys, a trailing comma. A small model asked for a list gets these wrong as often in
+ * a reply as in a call, and a side task that fails over one costs the run a second request.
+ *
  * @param text The reply, fences and prose included. Nothing parseable gives `undefined`.
  */
 export declare function parseJson<T>(text: string): T | undefined;