@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/runtime.d.ts

@@ -1,15 +1,16 @@
-import { preselect, runAgentLoop } from "./agent-loop.ts";
-import { calibrate, charsPerTokenFor, resetCalibration } from "./calibration.ts";
-import { capabilitiesFor, expireCapabilities, resetCapabilities } from "./capabilities.ts";
-import { type ClientPoolOptions, configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow } from "./client.ts";
-import { compactTranscript, runCompaction, summariser } from "./compaction.ts";
-import { continueTurn } from "./continuation.ts";
-import { configureEvents, type EventBusOptions, emit, endRun, history, resetEvents, watch } from "./events.ts";
-import { assembleContext, configureHooks, consult, gather, type HookOptions, notify, resetHooks, withContext } from "./hooks.ts";
-import { resetAll } from "./reset.ts";
-import { runTurn } from "./run-turn.ts";
-import { ask, askJson, resetHints, tryAsk } from "./side-task.ts";
-import { exportCapabilities, importCapabilities } from "./snapshot.ts";
+import { runAgentLoop } from './agent-loop.ts';
+import { calibrate, charsPerTokenFor, resetCalibration } from './calibration.ts';
+import { capabilitiesFor, expireCapabilities, resetCapabilities } from './capabilities.ts';
+import { type ClientPoolOptions, configureClients, contextLimitFor, getClient, listModels, resetClients, servedWindow } from './client.ts';
+import { compactTranscript, runCompaction, summariser } from './compaction.ts';
+import { continueTurn } from './continuation.ts';
+import { configureEvents, type EventBusOptions, emit, endRun, history, resetEvents, watch } from './events.ts';
+import { assembleContext, configureHooks, consult, gather, type HookOptions, notify, resetHooks, withContext } from './hooks.ts';
+import { preselect } from './preselect.ts';
+import { resetAll } from './reset.ts';
+import { runTurn } from './run-turn.ts';
+import { ask, askJson, resetHints, tryAsk } from './side-task.ts';
+import { exportCapabilities, importCapabilities } from './snapshot.ts';
 /**
  * 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
@@ -68,6 +69,7 @@ export interface RuntimeOptions {
 /**
  * One set of the package's caches, with the functions that use them as methods.
  *
+ * @remarks
  * Each method is the top-level function of the same name, with the same signature and doc
  * comment, run against this runtime's state instead of the process's: its pooled clients and
  * model listings, latched capabilities, measured characters per token, no-thinking hints, event
@@ -79,10 +81,11 @@ export type Runtime = typeof STATEFUL & {
      * an `await`, or from a timer it sets — uses this runtime's state. What the methods do, for
      * code that calls the top-level functions itself.
      *
+     * @param fn - What to run. Its return value, or what it throws, is handed straight back.
+     *
+     * @remarks
      * It does not reach a callback that outlives `fn` and is called from elsewhere — a generator
      * resumed later, a function handed back and called by someone else. Call a method there.
-     *
-     * @param fn What to run. Its return value, or what it throws, is handed straight back.
      */
     run<T>(fn: () => T): T;
 };
@@ -90,6 +93,11 @@ export type Runtime = typeof STATEFUL & {
  * 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.
  *
+ * @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.
+ * @returns A runtime whose state starts empty, with whatever `options` gave already applied.
+ *
+ * @remarks
  * 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
@@ -104,14 +112,12 @@ export type Runtime = typeof STATEFUL & {
  *
  * 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 declare function createRuntime(options?: RuntimeOptions): Runtime;
 /**
  * The runtime the top-level functions use when no other is running.
  *
+ * @remarks
  * `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.

package/dist/runtime.js

@@ -1,16 +1,17 @@
-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";
+import { 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 { preselect } from './preselect.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
@@ -57,13 +58,16 @@ const STATEFUL = {
     resetHooks,
     resetAll,
 };
-/** Makes the methods of the runtime whose state is `scope`. */
+/**
+ * Makes the methods of the runtime whose state is `scope`.
+ *
+ * @param scope - The state the methods run against. Held, not copied.
+ * @returns Every function in `STATEFUL` wrapped to run in `scope`, and `run`. What `summariser`
+ * hands back is wrapped as well, since it is called after the method has returned.
+ */
 function bind(scope) {
     const within = (fn) => (...args) => inScope(scope, () => fn(...args));
-    const methods = Object.fromEntries(Object.entries(STATEFUL).map(([name, fn]) => [
-        name,
-        within(fn),
-    ]));
+    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.
@@ -75,6 +79,11 @@ function bind(scope) {
  * 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.
  *
+ * @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.
+ * @returns A runtime whose state starts empty, with whatever `options` gave already applied.
+ *
+ * @remarks
  * 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
@@ -89,23 +98,24 @@ function bind(scope) {
  *
  * 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)
+    if (options.clients) {
         runtime.configureClients(options.clients);
-    if (options.events)
+    }
+    if (options.events) {
         runtime.configureEvents(options.events);
-    if (options.hooks)
+    }
+    if (options.hooks) {
         runtime.configureHooks(options.hooks);
+    }
     return runtime;
 }
 /**
  * The runtime the top-level functions use when no other is running.
  *
+ * @remarks
  * `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.

package/dist/schema-compat.d.ts

@@ -1,53 +1,70 @@
-import type OpenAI from "openai";
+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.
  *
+ * @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.
+ * @returns A new object: `type: "object"` with a `properties` map, no combinator at the root, no
+ * `required` name without a property, and no definition that nothing points at.
+ *
+ * @remarks
  * 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.
  *
+ * @param tools - The definitions as the pool hands them over. Never mutated — where a schema
+ * changed, a new definition is returned in its place.
+ * @returns A new array in the same order. Each entry is the definition remembered for its tool, so
+ * the same object on every call; a tool that is not a function tool is its own entry.
+ *
+ * @remarks
  * The first call on a connection's tools does the work and every later one is a lookup, so
  * calling this per request costs nothing.
- *
- * @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 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.
  *
+ * @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.
+ * @returns A new object, the keywords gone from every schema position in it.
+ *
+ * @remarks
  * 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
- * re-validates anyway.
+ * The tool array with every schema's `pattern` and `format` keywords gone — the shape a turn is
+ * retried with.
+ *
+ * @param tools - Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
+ * Never mutated.
+ * @returns A new array in the same order. Each entry is the relaxed definition remembered for its
+ * tool, so the same object on every call; a tool that is not a function tool is its own entry.
  *
- * @param tools Already sanitised. Relaxing is the retry, not a substitute for `sanitizeTools`.
+ * @remarks
+ * 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.
  */
 export declare const relaxTools: (tools: OpenAI.ChatCompletionTool[]) => OpenAI.ChatCompletionTool[];
 /**
- * Does this failure look like the server could not build a grammar from our tool schemas?
+ * Whether a failure looks like the server could not build a grammar from our tool schemas.
  *
+ * @param message - The server's error text. Matched case-insensitively.
+ * @returns `true` for a grammar or schema-conversion failure. `false` for anything else, and
+ * always for a chat template's "no user query found", whatever it is wrapped in.
+ *
+ * @remarks
  * Every server words this differently — llama-server says "error parsing grammar", Lemonade
  * says "Failed to initialize samplers: failed to parse grammar", others surface the converter
  * by name. Since a grammar is only ever involved in constrained decoding, treat any mention of
  * one as ours; the retry is cheap and latches after a single request.
- *
- * @param message The server's error text. Matched case-insensitively.
  */
 export declare function isGrammarError(message: string): boolean;