@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/scope.d.ts

@@ -1,19 +1,25 @@
 /**
  * Everything one runtime remembers: each module's state, under a key only that module holds.
  *
+ * @remarks
  * 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. */
+/**
+ * The scope of the runtime whose method is running, or the default one outside any.
+ *
+ * @returns The scope itself, not a copy — writing to it is writing to that runtime's state.
+ */
 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.
+ * @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.
+ * @returns What `fn` returned, as it returned it — from an async one the promise itself, unawaited.
  */
 export declare const inScope: <T>(scope: Scope, fn: () => T) => T;
 /** One module's state, read from whichever scope is current. See `scoped`. */
@@ -26,10 +32,27 @@ export interface Scoped<T> {
 /**
  * Declares a piece of module state that every runtime has its own copy of.
  *
+ * @param create - Builds a fresh, empty copy. Called once per scope, and again after `reset`.
+ * @returns A function that reads the copy of whichever scope is current when it is called, not
+ * when this was, with a `reset` on it that drops that scope's copy.
+ *
+ * @remarks
  * 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>;
+/**
+ * Writes what a caller gave onto the settings in force, field by field, skipping what is unusable.
+ *
+ * @param held - The settings in force. Written to — the same object the module goes on reading.
+ * @param options - What to change. A field left out is left alone.
+ * @param [usable] - Whether a value may be written under a name.
+ * @returns A copy of everything in force afterwards, including what this call did not change.
+ *
+ * @remarks
+ * The body of every `configure*`: a module's settings are one object per runtime, read where they
+ * are used, so writing a field onto it is what makes the change apply from the next read. A field
+ * that fails its check keeps what it had, which is how a half-built config narrows nothing.
+ */
+export declare function assignSettings<T extends object>(held: T, options: Partial<T>, usable?: (value: unknown, name: string) => boolean): T;

package/dist/scope.js

@@ -1,4 +1,5 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getOrCreate, isPositive } from './guards.js';
 /**
  * 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 —
@@ -8,31 +9,36 @@ import { AsyncLocalStorage } from "node:async_hooks";
 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. */
+/**
+ * The scope of the runtime whose method is running, or the default one outside any.
+ *
+ * @returns The scope itself, not a copy — writing to it is writing to that runtime's state.
+ */
 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.
+ * @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.
+ * @returns What `fn` returned, as it returned it — from an async one the promise itself, unawaited.
  */
 export const inScope = (scope, fn) => active.run(scope, fn);
 /**
  * Declares a piece of module state that every runtime has its own copy of.
  *
+ * @param create - Builds a fresh, empty copy. Called once per scope, and again after `reset`.
+ * @returns A function that reads the copy of whichever scope is current when it is called, not
+ * when this was, with a `reset` on it that drops that scope's copy.
+ *
+ * @remarks
  * 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 getOrCreate(currentScope(), key, create);
     };
     return Object.assign(read, {
         reset: () => {
@@ -40,3 +46,24 @@ export function scoped(create) {
         },
     });
 }
+/**
+ * Writes what a caller gave onto the settings in force, field by field, skipping what is unusable.
+ *
+ * @param held - The settings in force. Written to — the same object the module goes on reading.
+ * @param options - What to change. A field left out is left alone.
+ * @param [usable] - Whether a value may be written under a name.
+ * @returns A copy of everything in force afterwards, including what this call did not change.
+ *
+ * @remarks
+ * The body of every `configure*`: a module's settings are one object per runtime, read where they
+ * are used, so writing a field onto it is what makes the change apply from the next read. A field
+ * that fails its check keeps what it had, which is how a half-built config narrows nothing.
+ */
+export function assignSettings(held, options, usable = isPositive) {
+    for (const [name, value] of Object.entries(options)) {
+        if (usable(value, name)) {
+            held[name] = value;
+        }
+    }
+    return { ...held };
+}

package/dist/side-task.d.ts

@@ -1,15 +1,27 @@
-import OpenAI from "openai";
-import type { Endpoint } from "./config.ts";
-/** An (endpoint, model) pair as `noHints` holds it: `[endpointId, model]`, stringified. */
-export declare const hintKey: (endpoint: string, model: string) => string;
-/** The pairs that refused the hints, the live set, for `exportCapabilities` and `importCapabilities`. */
+import OpenAI from 'openai';
+import { type OnNotice } from './capabilities.ts';
+import type { Endpoint, EndpointIdentity } from './config.ts';
+/**
+ * The pairs that refused the hints, the live set, for `exportCapabilities` and
+ * `importCapabilities`.
+ *
+ * @returns The current scope's set itself and not a copy, each pair a
+ * `modelKey(endpointId, model)`. Adding to it stops the hints being sent to that pair from the
+ * next call.
+ */
 export declare const refusedHints: () => Set<string>;
-/** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
+/**
+ * Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints.
+ *
+ * @remarks
+ * The current scope's set is emptied in place, so a holder of it sees it empty.
+ */
 export declare const resetHints: () => void;
 /**
  * The input a side task applies its instruction to: text, or the content parts a vision model
  * reads.
  *
+ * @remarks
  * A string is the ordinary case and stays the cheapest thing to write. The array is what an
  * image needs, because a page, a screenshot or a photo reaches an OpenAI-compatible server only
  * as an `image_url` part alongside the text — there is no other spelling for it, and a caller
@@ -21,16 +33,23 @@ export type SideTaskInput = string | OpenAI.ChatCompletionContentPart[];
 /** What a side task may be given. All optional — one given none of them still runs. */
 export interface SideTaskOptions {
     /**
-     * Ceiling on the reply, default 512. These answers are meant to be short. Zero or less sends
-     * none and leaves it to the server, which is what `maxTokens: 0` means on the main model too.
+     * Ceiling on the reply. These answers are meant to be short. Zero or less sends none and leaves
+     * it to the server, which is what `maxTokens: 0` means on the main model too.
+     *
+     * @defaultValue `512`
      */
     maxTokens?: number;
-    /** Sampling temperature, default 0.3. Naming and classifying want the same answer twice. */
+    /**
+     * Sampling temperature. Naming and classifying want the same answer twice.
+     *
+     * @defaultValue `0.3`
+     */
     temperature?: number;
     /**
      * A reasoning effort to ask for in place of the no-thinking hints, for a side task an operator
      * has pointed at a model that should deliberate — a compaction summary is the usual one.
      *
+     * @remarks
      * Absent, `""` and `"off"` all keep the hints, because off is what they already ask for. Any
      * other value is sent as `reasoning_effort`, stepped up by `effortFor` where the model has
      * refused it by value, and `chat_template_kwargs` is left out of the request altogether.
@@ -41,6 +60,7 @@ export interface SideTaskOptions {
     /**
      * Told what was given up on, the same way `runTurn` and `negotiate` tell a caller.
      *
+     * @remarks
      * The one notice `ask` raises itself opens with the model's name, as `negotiate`'s do for the
      * refusals that are the model's: what it announces is latched on the (endpoint, model) pair,
      * so on a consumer reaching several models through one base URL the name is the only thing
@@ -50,11 +70,12 @@ export interface SideTaskOptions {
      * console decides for its consumer where operator text goes — which a server embedding this
      * cannot then route to its own logger, attach to the run it belongs to, or silence in tests.
      */
-    onNotice?: (message: string) => void;
+    onNotice?: OnNotice;
 }
 /**
  * One side task's own settings, as a resolved agent spec carries them under `tasks.<key>`.
  *
+ * @remarks
  * Declared here rather than imported from `spec.ts`, whose `ResolvedTask` it matches field for
  * field: the spec module is one nothing else in `src/` imports, and a host that is not on the spec
  * can write one of these by hand. An absent setting is the side task's own default — 0.3, the
@@ -68,7 +89,11 @@ export interface SideTask {
     endpoint: Endpoint;
     /** The reply's ceiling. Absent is the entry point's default; zero sends none. */
     maxTokens?: number;
-    /** Absent is 0.3, whatever the agent's own temperature is. Zero means zero. */
+    /**
+     * Sampling temperature, whatever the agent's own is. Zero means zero.
+     *
+     * @defaultValue `0.3`
+     */
     temperature?: number;
     /** As `SideTaskOptions.reasoningEffort`: a level replaces the no-thinking hints. */
     reasoningEffort?: string;
@@ -76,21 +101,29 @@ export interface SideTask {
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
  *
- * @param config Where to send it and how long to wait.
- * @param model The model to ask, usually smaller than the one running the work.
- * @param system The instruction.
- * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param options Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask, usually smaller than the one running the work.
+ * @param system - The instruction.
+ * @param user - The input it applies to. Content parts where the model is being shown an image.
+ * @param [options] - Reply ceiling, temperature, a reasoning effort, cancellation, notices.
+ * @returns The reply's content, trimmed. Where that is empty once the thinking is stripped, a
+ * `reasoning_content` the server sent beside it, stripped the same way, or an empty string.
  */
 export declare function ask(config: Endpoint, model: string, system: string, user: SideTaskInput, options?: SideTaskOptions): Promise<string>;
 /** What `askJson` takes besides a side task's options. */
 export interface AskJsonOptions extends SideTaskOptions {
-    /** What the schema is called in the request, `answer` by default. Letters, digits, `_` and `-`. */
+    /**
+     * What the schema is called in the request. Letters, digits, `_` and `-`.
+     *
+     * @defaultValue `'answer'`
+     */
     name?: string;
     /**
-     * Asks the server to hold the reply to the schema exactly, true by default. OpenAI's strict mode
-     * wants every property required and `additionalProperties: false`; a schema written otherwise
-     * wants this off there.
+     * Asks the server to hold the reply to the schema exactly. OpenAI's strict mode wants every
+     * property required and `additionalProperties: false`; a schema written otherwise wants this
+     * off there.
+     *
+     * @defaultValue `true`
      */
     strict?: boolean;
 }
@@ -98,41 +131,62 @@ export interface AskJsonOptions extends SideTaskOptions {
  * A side task whose answer is JSON matching a schema, parsed. Undefined when no JSON came back.
  * Throws like any request.
  *
+ * @param config - Where to send it and how long to wait.
+ * @param model - The model to ask.
+ * @param system - The instruction. The schema is appended to it.
+ * @param user - The input it applies to. Content parts where the model is being shown an image.
+ * @param schema - The JSON Schema of the answer. Its root is held to an object, as a tool's is.
+ * @param [options] - A side task's options, plus the schema's `name` and whether it is `strict`.
+ * @returns What the reply parsed to, unchecked against the schema: `T` is the caller's claim.
+ * `undefined` when `parseJson` found nothing in it.
+ *
+ * @remarks
  * Sends `response_format` with the schema, which a llama.cpp server compiles into a grammar and
  * vLLM, LM Studio, Ollama and OpenAI each hold the reply to, so a small model that wraps JSON in
  * prose cannot. The schema is normalised as a tool's parameters are, and relaxed where the endpoint
  * could not build a grammar, since the same converter reads both. A model that refuses the field
  * latches it off and is asked in words: the schema rides on the system prompt either way, and
  * the reply goes through `parseJson`, which finds the JSON in whatever came back.
- *
- * @param config Where to send it and how long to wait.
- * @param model The model to ask.
- * @param system The instruction. The schema is appended to it.
- * @param user The input it applies to. Content parts where the model is being shown an image.
- * @param schema The JSON Schema of the answer. Its root is held to an object, as a tool's is.
- * @param options A side task's options, plus the schema's `name` and whether it is `strict`.
  */
 export declare function askJson<T>(config: Endpoint, model: string, system: string, user: SideTaskInput, schema: Record<string, unknown>, { name, strict, ...options }?: AskJsonOptions): Promise<T | undefined>;
 /**
+ * Runs a side task and answers `undefined` where it fails, so the work it supports carries on.
+ *
+ * @param label - Names the task in the notice when it fails.
+ * @param run - The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
+ * @param [options] - `onNotice`, told what was given up on.
+ * @returns What `run` resolved with, or `undefined` when it threw. An `APIUserAbortError` is thrown
+ * on and raises no notice.
+ *
+ * @remarks
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.
- *
- * @param label Names the task in the notice when it fails.
- * @param run The call to attempt. Anything it throws becomes `undefined`, an abort excepted.
- * @param options `onNotice`, told what was given up on.
  */
-export declare function tryAsk<T>(label: string, run: () => Promise<T>, { onNotice }?: Pick<SideTaskOptions, "onNotice">): Promise<T | undefined>;
+export declare function tryAsk<T>(label: string, run: () => Promise<T>, { onNotice }?: Pick<SideTaskOptions, 'onNotice'>): Promise<T | undefined>;
 /**
- * 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.
+ * The first array or object in a model's reply, parsed, whatever prose or fence surrounds it.
+ *
+ * @param text - The reply, fences and prose included. Nothing parseable gives `undefined`.
+ * @returns What lies between the first `[` or `{` and the last `]` or `}`, parsed — inside the
+ * first fenced block where there is one. Unchecked: `T` is the caller's claim. `undefined` when
+ * there is no such stretch or it will not parse even repaired.
+ *
+ * @remarks
+ * Models are asked for JSON and often answer with prose around it, or a fenced block, and a
+ * wrapper is not worth failing the task over.
  *
- * @param text The reply, fences and prose included. Nothing parseable gives `undefined`.
+ * 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.
  */
 export declare function parseJson<T>(text: string): T | undefined;
 /**
  * Strips the quoting and list punctuation models decorate short answers with.
  *
- * @param line One line of a reply.
+ * @param line - One line of a reply.
+ * @returns The line trimmed, without one leading bullet or number, any quotes or backticks at
+ * either end, or trailing full stops. Empty when nothing else was there.
  */
 export declare const clean: (line: string) => string;
 /**
@@ -140,8 +194,42 @@ export declare const clean: (line: string) => string;
  * them with. Overlong items are dropped rather than truncated — a suggestion that has to be
  * squinted at is worse than one fewer suggestion.
  *
- * @param text The reply, one item per line.
- * @param max How many items to keep.
- * @param maxChars Longest item kept. Longer ones are dropped, not truncated.
+ * @param text - The reply, one item per line.
+ * @param max - How many items to keep.
+ * @param maxChars - Longest item kept. Longer ones are dropped, not truncated.
+ * @returns The first `max` items that survive, in reply order. Lines that clean to nothing are not
+ * items, and an overlong one does not count towards `max`.
  */
 export declare const listLines: (text: string, max: number, maxChars: number) => string[];
+/**
+ * A side task's settings as the call that honours them: its endpoint, its model, and the options
+ * `ask`, `askJson`, `summariser` and `preselect` take last.
+ *
+ * @param task - The task, ordinarily `resolved.tasks.<key>`.
+ * @param [options] - What the host adds — cancellation, notices, `keywords` — and its own defaults
+ * for the settings a task may leave out.
+ * @param [agent] - The endpoint the main turn uses, key included. Absent sends the task's endpoint
+ * as it stands.
+ * @returns The three arguments a side-task entry point takes. `options` is a new object, and
+ * `endpoint` is the task's own object when no `agent` was given, a copy otherwise.
+ *
+ * @remarks
+ * A helper rather than a second signature on each of the four, so a setting added to a task later
+ * arrives through `options` without a host's call changing. What the task states wins over the
+ * same field in `options`: the host's code is written once and the task is what an operator
+ * configured over it, so a host passes its own ceiling as the value for a task that names none.
+ * A setting the task leaves out and `options` does too is absent from the result, which is what
+ * leaves it to the entry point's own default — 0.3, not the agent's temperature.
+ *
+ * A resolved spec carries no key, so a task on the agent's own endpoint would otherwise go out
+ * unkeyed, and be remembered under a second capability entry beside the agent's. Given `agent`,
+ * such a task is sent the agent's `baseUrl` as the agent spells it and, having no key of its own,
+ * the agent's key, so `capabilitiesFor` answers both with one object; a task on another endpoint
+ * is sent only a key of its own, as `resolveApiKey` has it. The environment is not read: the
+ * agent's key is whatever the main turn is sent.
+ */
+export declare function taskCall<Options extends SideTaskOptions = SideTaskOptions>(task: SideTask, options?: Options, agent?: EndpointIdentity): {
+    endpoint: Endpoint;
+    model: string;
+    options: Options;
+};