@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/calibration.d.ts

@@ -1,32 +1,36 @@
-import type OpenAI from "openai";
-import type { Capabilities } from "./capabilities.ts";
+import type OpenAI from 'openai';
+import type { Capabilities } from './capabilities.ts';
 /**
  * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
  * has reported one.
  *
+ * @param supports - The endpoint, as `capabilitiesFor` hands it over.
+ * @param model - The name the endpoint knows the model as, as it goes in the body.
+ * @returns The highest of the readings held for the model in the current runtime, or
+ * `CHARS_PER_TOKEN` where it holds none.
+ *
+ * @remarks
  * The highest of the model's last few readings rather than their mean. The estimate guards a
  * window, and `estimateTokens` says which side of wrong that should be on: a count that comes out
  * high refuses a run that would have fit, one that comes out low only costs the round trip the
  * guard was saving. The highest ratio is the lowest count, and the last few rather than all of
  * them because a run's transcript grows by appending, so the latest requests are the best
  * likeness of the next.
- *
- * @param supports The endpoint, as `capabilitiesFor` hands it over.
- * @param model The name the endpoint knows the model as, as it goes in the body.
  */
 export declare function charsPerTokenFor(supports: Capabilities, model: string): number;
 /**
  * Takes one reading from a request that was answered, so the next one to this model is sized by it.
  *
+ * @param supports - The endpoint the request went to.
+ * @param body - The request as it was last sent, which names the model.
+ * @param promptTokens - The prompt count the endpoint reported for it. Zero or less is no report.
+ * @returns The ratio now in force for the model.
+ *
+ * @remarks
  * `runTurn` calls it after every turn whose prompt was reported, so a caller using that has
  * nothing to do. A request carrying an image or audio is not read: a vision model charges a
  * picture hundreds of tokens its characters say nothing about. Neither is a reading outside what a
  * tokenizer could produce, which is a miscount and not a tokenizer.
- *
- * @param supports The endpoint the request went to.
- * @param body The request as it was last sent, which names the model.
- * @param promptTokens The prompt count the endpoint reported for it. Zero or less is no report.
- * @returns The ratio now in force for the model.
  */
 export declare function calibrate(supports: Capabilities, body: OpenAI.ChatCompletionCreateParamsStreaming, promptTokens: number): number;
 /** Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again. */

package/dist/calibration.js

@@ -1,6 +1,7 @@
-import { requestChars, toolsChars } from "./retry.js";
-import { scoped } from "./scope.js";
-import { CHARS_PER_TOKEN } from "./tokens.js";
+import { getOrCreate } from './guards.js';
+import { scoped } from './scope.js';
+import { CHARS_PER_TOKEN, requestChars, toolsChars } from './tokens.js';
+import { PartType } from './wire.js';
 /**
  * How many characters a token is worth on one model, learned from what its endpoint reports.
  *
@@ -34,53 +35,59 @@ const readings = scoped(() => new WeakMap());
  * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
  * has reported one.
  *
+ * @param supports - The endpoint, as `capabilitiesFor` hands it over.
+ * @param model - The name the endpoint knows the model as, as it goes in the body.
+ * @returns The highest of the readings held for the model in the current runtime, or
+ * `CHARS_PER_TOKEN` where it holds none.
+ *
+ * @remarks
  * The highest of the model's last few readings rather than their mean. The estimate guards a
  * window, and `estimateTokens` says which side of wrong that should be on: a count that comes out
  * high refuses a run that would have fit, one that comes out low only costs the round trip the
  * guard was saving. The highest ratio is the lowest count, and the last few rather than all of
  * them because a run's transcript grows by appending, so the latest requests are the best
  * likeness of the next.
- *
- * @param supports The endpoint, as `capabilitiesFor` hands it over.
- * @param model The name the endpoint knows the model as, as it goes in the body.
  */
 export function charsPerTokenFor(supports, model) {
     const known = readings().get(supports)?.get(model);
     return known?.length ? Math.max(...known) : CHARS_PER_TOKEN;
 }
-/** Whether any message carries a part whose tokens its characters do not count. */
-const hasMedia = (messages) => messages.some(({ content }) => Array.isArray(content) &&
-    content.some((part) => part.type !== "text" && part.type !== "refusal"));
+/**
+ * Whether any message carries a part whose tokens its characters do not count.
+ *
+ * @param messages - A request's messages.
+ * @returns True where some message's content is an array holding a part that is neither text nor
+ * a refusal. Content that is a string never counts.
+ */
+const hasMedia = (messages) => messages.some(({ content }) => Array.isArray(content) && content.some((part) => part.type !== PartType.Text && part.type !== PartType.Refusal));
 /**
  * Takes one reading from a request that was answered, so the next one to this model is sized by it.
  *
+ * @param supports - The endpoint the request went to.
+ * @param body - The request as it was last sent, which names the model.
+ * @param promptTokens - The prompt count the endpoint reported for it. Zero or less is no report.
+ * @returns The ratio now in force for the model.
+ *
+ * @remarks
  * `runTurn` calls it after every turn whose prompt was reported, so a caller using that has
  * nothing to do. A request carrying an image or audio is not read: a vision model charges a
  * picture hundreds of tokens its characters say nothing about. Neither is a reading outside what a
  * tokenizer could produce, which is a miscount and not a tokenizer.
- *
- * @param supports The endpoint the request went to.
- * @param body The request as it was last sent, which names the model.
- * @param promptTokens The prompt count the endpoint reported for it. Zero or less is no report.
- * @returns The ratio now in force for the model.
  */
 export function calibrate(supports, body, promptTokens) {
-    if (!(promptTokens > 0) || hasMedia(body.messages))
+    if (!(promptTokens > 0) || hasMedia(body.messages)) {
         return charsPerTokenFor(supports, body.model);
+    }
     const ratio = (requestChars(body) + toolsChars(body.tools ?? [])) / promptTokens;
     if (ratio < PLAUSIBLE.least || ratio > PLAUSIBLE.most) {
         return charsPerTokenFor(supports, body.model);
     }
-    let models = readings().get(supports);
-    if (!models) {
-        models = new Map();
-        readings().set(supports, models);
-    }
-    const known = models.get(body.model) ?? [];
+    const models = getOrCreate(readings(), supports, () => new Map());
+    const known = getOrCreate(models, body.model, () => []);
     known.push(ratio);
-    if (known.length > READINGS)
+    if (known.length > READINGS) {
         known.shift();
-    models.set(body.model, known);
+    }
     return charsPerTokenFor(supports, body.model);
 }
 /** Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again. */

package/dist/capabilities.d.ts

@@ -1,4 +1,5 @@
-import type { Produced } from "./stream.ts";
+import type { EndpointIdentity } from './config.ts';
+import type { Produced } from './stream.ts';
 /**
  * What an endpoint turned out not to support, and answering it when it says so.
  *
@@ -39,6 +40,7 @@ export interface Capabilities {
      * When this entry was opened, as epoch milliseconds: first contact with the endpoint in this
      * process, or the age an imported snapshot gave it. What `expireCapabilities` measures.
      *
+     * @remarks
      * Not when a flag latched. A flag that latches at all almost always does so on the first
      * request or two, and an entry that latched nothing has nothing to expire, so the difference
      * costs at most one retried field somewhat earlier than it was due — which is the direction to
@@ -51,6 +53,7 @@ export interface Capabilities {
  * What one model on that endpoint turned out not to support. All start optimistic and only ever
  * latch off, the same as the endpoint's own.
  *
+ * @remarks
  * These arrive through the same channel as the endpoint's — an error string on a chat
  * completion — which is why they are negotiated by the same loop rather than a second one. What
  * makes them the model's is that the answer differs between two models the same key reaches.
@@ -65,6 +68,7 @@ export interface ModelCapabilities {
      * Spells its ceiling `max_tokens`. The reasoning models want `max_completion_tokens` instead,
      * and they are exactly the models anyone sets an effort on.
      *
+     * @remarks
      * Read it as `=== false` rather than for truthiness. This is the one flag whose two answers are
      * both a field to send, so a caller that named no model — and was told that changes nothing —
      * gets `undefined` here and, on a truthiness test, sends `max_completion_tokens` to a server
@@ -81,6 +85,7 @@ export interface ModelCapabilities {
      * builder leaves out of what `extraBody` asks for. Only ever grows, which is this set's way of
      * latching off.
      *
+     * @remarks
      * Only the fields a caller offered as droppable reach it (see `NegotiateOptions.droppable`),
      * because a name read out of an error string is not otherwise something to stop sending: a
      * refusal naming `messages` is a broken request, not a field the model can do without.
@@ -97,6 +102,7 @@ export interface ModelCapabilities {
      * Efforts this model refused by value rather than by field — a request that named `none` on a
      * model whose list starts at `minimal`. Only ever grows, which is this set's way of latching.
      *
+     * @remarks
      * Separate from `reasoningEffort` because the two refusals mean opposite things: that one says
      * the model cannot reason and the field must go, this one says it reasons and was handed an
      * effort off a list this package does not know. Dropping the field there would run at the
@@ -104,7 +110,7 @@ export interface ModelCapabilities {
      */
     refusedEfforts: Set<string>;
     /**
-     * The efforts a refusal published as this model's, in ladder order, filtered to the ones
+     * The efforts a refusal published as this model's, in the order it gave them, filtered to the ones
      * `EFFORT_LADDER` can place. Absent until a refusal lists them, and a model that lists nothing
      * is walked up the ladder a rung per refusal instead.
      */
@@ -125,6 +131,7 @@ export type ModelFlag = {
 /**
  * A model's on/off flags as it starts out, every one optimistic.
  *
+ * @remarks
  * A record over every boolean on `ModelCapabilities`, so a flag added there does not compile until
  * it is listed here — and this is the list a snapshot is exported, imported and judged empty by,
  * where each of those used to name the flags again and one could be missed.
@@ -133,58 +140,103 @@ export declare const OPTIMISTIC_MODEL: Readonly<Record<ModelFlag, true>>;
 /** The names of those flags, for a caller that reads or latches each in turn. */
 export declare const MODEL_FLAGS: ModelFlag[];
 /**
- * What this endpoint is known not to support. The same object every time, so what `negotiate`
- * latches off stays off.
+ * What each endpoint cannot do, remembered for the life of the process.
  *
- * @param baseUrl Where the endpoint is. The two flags on it are per-server; what is per-model
+ * @remarks
+ * Keyed by `endpointId` — `endpointKey` hashed, so a snapshot holds no key — because these are
+ * facts about the server on the other end and not about this one. A llama.cpp box that cannot
+ * compile a grammar and a cloud API that can are both reachable from one settings row over its
+ * lifetime — an operator retargets it from Ollama this afternoon to OpenAI this evening — and the
+ * first one's refusal must not quietly strip pattern/format from the second one's requests, or
+ * silently cost it its token counts, for the rest of the process. Bounded by the number of
+ * endpoints ever configured, which is a settings row's worth.
+ *
+ * The API key is part of that identity, the same as it is for the client pool and the model
+ * listings. A router — LiteLLM, OpenRouter, a gateway with several boxes behind it — is free to
+ * send two keys to two different backends, and then what one of them refused is not a fact about
+ * the other. Keyed on the URL alone the first caller through the gateway latched for everyone
+ * behind it, including the `models` map underneath, which is the level where two keys through
+ * one host are most likely to differ at all.
+ */
+/**
+ * Hears one line of operator text: what was given up on, what is being waited out, what was chosen.
+ *
+ * @remarks
+ * One name for it because the same listener is handed down from the loop through a turn to
+ * `negotiate` and across to every side task, and each had spelled the signature out.
+ */
+export type OnNotice = (message: string) => void;
+/**
+ * What this endpoint is known not to support.
+ *
+ * @param baseUrl - Where the endpoint is. The two flags on it are per-server; what is per-model
  * hangs off `models`, which `modelCapabilitiesFor` reads.
- * @param apiKey The rest of the endpoint's identity. Optional, because it changes nothing for
+ * @param [apiKey] - The rest of the endpoint's identity. Optional, because it changes nothing for
  * the ordinary case of one key per base URL and a caller with one need not thread it through;
  * absent reads as `NO_KEY`, exactly as it does in `getClient`, so an endpoint with no key and
  * one that passes `undefined` share an entry rather than holding two.
+ * @returns The endpoint's live entry, made with both flags on and no models the first time it is
+ * asked for.
+ *
+ * @remarks
+ * The same object every time, so what `negotiate` latches off stays off.
  */
 export declare function capabilitiesFor(baseUrl: string, apiKey?: string): Capabilities;
 /**
  * What this model on this endpoint is known not to support. The same object every time, so what
  * `negotiate` latches off stays off.
  *
+ * @param supports - The endpoint's own, as `capabilitiesFor` hands it over.
+ * @param model - The name the endpoint knows the model as — whatever goes in the request body,
+ * since that is the only name the refusal is about.
+ * @returns The model's live entry under `supports.models`, made with every flag on and nothing
+ * refused the first time it is asked for.
+ *
+ * @remarks
  * Nested under the endpoint rather than keyed by name alone, because `gpt-4o` at OpenAI and
  * `gpt-4o` behind a proxy need not be the same weights — and a proxy is free to answer to a name
  * it does not really serve. One that refused a reasoning effort must not speak for the other.
  * Bounded by the models actually asked for on that endpoint, which is what a dropdown holds.
- *
- * @param supports The endpoint's own, as `capabilitiesFor` hands it over.
- * @param model The name the endpoint knows the model as — whatever goes in the request body,
- * since that is the only name the refusal is about.
  */
 export declare function modelCapabilitiesFor(supports: Capabilities, model: string): ModelCapabilities;
-/** Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`. */
+/**
+ * Every endpoint's capabilities by `endpointId`, the live objects, for `exportCapabilities`.
+ *
+ * @returns The map itself rather than a copy, read-only by type alone: what is latched or forgotten
+ * afterwards shows through it.
+ */
 export declare const knownCapabilities: () => ReadonlyMap<string, Capabilities>;
 /**
  * The capabilities of the endpoint with this `endpointId`, created optimistic if unseen — the way
  * `importCapabilities` reaches an endpoint it has only a digest for.
+ *
+ * @param id - The digest `endpointId` gives. Not checked: any string opens an entry under itself.
+ * @returns The live entry, the same object `capabilitiesFor` hands over for that endpoint.
  */
 export declare function capabilitiesById(id: string): Capabilities;
 /**
  * Forgets what one endpoint refused, or every endpoint's when told none.
  *
+ * @param [endpoint] - Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ *
+ * @remarks
  * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
  * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
  * sent the downgraded request for the life of the process. This is the seam for a consumer that
  * *knows* it changed: a settings row saved, a health check that reads a new build string, an
  * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
- *
- * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
- * every endpoint, which is what tests and `resetAll` mean by it.
- * @returns Whether there was anything to forget.
  */
-export declare function resetCapabilities(endpoint?: {
-    baseUrl: string;
-    apiKey?: string;
-}): boolean;
+export declare function resetCapabilities(endpoint?: EndpointIdentity): boolean;
 /**
  * Forgets every endpoint whose entry is older than this, so the next request finds out again.
  *
+ * @param maxAgeMs - How old an entry may be. Zero or less expires everything.
+ * @param [now] - The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ *
+ * @remarks
  * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
  * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
  * request carries the field again, and a server that still refuses it refuses it once and
@@ -194,15 +246,16 @@ export declare function resetCapabilities(endpoint?: {
  *
  * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
  * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
- *
- * @param maxAgeMs How old an entry may be. Zero or less expires everything.
- * @param now The clock, for tests.
- * @returns How many endpoints were forgotten.
  */
 export declare function expireCapabilities(maxAgeMs: number, now?: number): number;
+/** The setting that asks for no `reasoning_effort` field at all. Ours, and never sent. */
+export declare const EFFORT_OFF: 'off';
+/** The lowest effort the wire has a word for, which is what a side task asks for. */
+export declare const EFFORT_NONE: 'none';
 /**
  * The efforts this package can place, cheapest first. A substitution only ever walks *up* it.
  *
+ * @remarks
  * Not a list of what any model takes — `medium` is refused by a model whose list is
  * `minimal, low, high`, and `xhigh` is real and deliberately absent. It is the order the values
  * OpenAI has shipped stand in, which is all a step needs to know. A value not on it cannot be
@@ -210,37 +263,45 @@ export declare function expireCapabilities(maxAgeMs: number, now?: number): numb
  * refused `xhigh` to `high` would quietly answer a question with less deliberation than whoever
  * typed it asked for, where stepping up from `none` to `minimal` only costs tokens and says so.
  */
-export declare const EFFORT_LADDER: readonly ["none", "minimal", "low", "medium", "high"];
+export declare const EFFORT_LADDER: readonly ["none", 'minimal', 'low', 'medium', 'high'];
 /**
  * What to actually put in `reasoning_effort` for a model that has refused the value asked for.
  *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param asked - What the config asks for. `"off"` and absent mean no effort.
+ * @returns The value for the field, or the empty string for no field. `asked` itself, as written,
+ * where the model has not refused it — and where it has but there is no rung left to step to.
+ *
+ * @remarks
  * The caller's own value, until this model has said that value is not one of its own; then the
  * cheapest it will take that is at least as much deliberation. A model that takes no effort at
  * all, and an absent or `"off"` setting, both answer the empty string, which is the body
  * builders' signal to send no field.
- *
- * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
- * has refused nothing.
- * @param asked What the config asks for. `"off"` and absent mean no effort.
  */
 export declare function effortFor(refused: ModelCapabilities | undefined, asked: string | undefined): string;
 /**
  * The reply ceiling and the temperature as this model takes them, to spread into a request body.
  *
+ * @param refused - What the model has refused, as `negotiate` hands it over. Absent is a model that
+ * has refused nothing.
+ * @param maxTokens - The ceiling. Zero or less sends none and leaves it to the server: a zero sent
+ * as `max_tokens: 0` asks for an empty reply.
+ * @param temperature - What to sample at, where the model takes one that was picked for it.
+ * @returns A fresh object holding the ceiling under one of its two names, or under neither, and
+ * `temperature` unless the model refused ours.
+ *
+ * @remarks
  * The reasoning models want the ceiling spelled the other way, and one that will only run at the
  * temperature it was built with is sent none. Both are tested `=== false`, so a caller that named
  * no model sends what one that has refused nothing is sent; see `ModelCapabilities.legacyTokenLimit`.
- *
- * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model that
- * has refused nothing.
- * @param maxTokens The ceiling. Zero or less sends none and leaves it to the server: a zero sent
- * as `max_tokens: 0` asks for an empty reply.
- * @param temperature What to sample at, where the model takes one that was picked for it.
  */
 export declare const ceilingAndTemperature: (refused: ModelCapabilities | undefined, maxTokens: number, temperature: number) => {
     max_completion_tokens: number;
+    max_tokens?: undefined;
     temperature?: number | undefined;
 } | {
+    max_completion_tokens?: undefined;
     max_tokens: number;
     temperature?: number | undefined;
 } | {
@@ -251,6 +312,7 @@ export interface NegotiateOptions {
     /**
      * The flag `send` will be given, for a caller that has to read it after `negotiate` returns.
      *
+     * @remarks
      * An outer retry loop needs it: nothing is retried once the server has started answering, and
      * by the time a rejected promise is in hand the turn is over. Callers without one can leave
      * this out and take the flag from `send`'s second argument, which is the same object.
@@ -259,6 +321,7 @@ export interface NegotiateOptions {
     /**
      * Told what was given up on, for a watcher who would otherwise see an unexplained pause.
      *
+     * @remarks
      * Each message opens with the thing that refused, so a reader tells the two levels apart
      * without parsing: `server` for the endpoint's own, and the model's own name — as `model` was
      * given it — for the three that are the model's. That matters because these latch for the
@@ -267,10 +330,11 @@ export interface NegotiateOptions {
      * line for every model on the endpoint, and the operator who later asks why the setting still
      * reads `high` has no way to tell which one it was about.
      */
-    onNotice?: (message: string) => void;
+    onNotice?: OnNotice;
     /**
      * Which model this request is for, by the name the endpoint knows it as.
      *
+     * @remarks
      * Given one, the refusals that are about the model rather than the server are answered too,
      * and `send` is handed what that model has already refused. Left out, nothing changes — which
      * is the point of it being here rather than a third positional argument: a caller with one
@@ -282,6 +346,7 @@ export interface NegotiateOptions {
      * them — what `extraBody` added, ordinarily. Such a name is latched into the model's
      * `refusedFields` and the request is sent again, which `send` is expected to build without it.
      *
+     * @remarks
      * Opt-in by name, because the answer is to stop sending the field, and a name out of an error
      * string that `send` does not know how to leave out would only be refused again. Needs `model`,
      * since the latch is the model's.
@@ -293,6 +358,17 @@ export interface NegotiateOptions {
  * request can do without. Returns once the endpoint has answered, or throws if the refusal is
  * not one of ours.
  *
+ * @typeParam T - What `send` resolves, which is handed back as it came.
+ * @param supports - What this endpoint has already refused. Latched off further as it refuses more.
+ * @param send - Builds and sends the request. Called again per downgrade, never once tokens
+ * have arrived. Its third argument is what the named model has refused, absent when no model
+ * was named.
+ * @param [options] - `produced` for a caller with its own retry budget, `onNotice` for a watcher,
+ * `model` to negotiate the model's refusals alongside the endpoint's.
+ * @returns What the first `send` to succeed resolved. A rejection is `send`'s own error, rethrown
+ * as it was caught.
+ *
+ * @remarks
  * A loop rather than one retry. A server that has heard of neither `stream_options` nor a
  * grammar keyword complains about them one at a time, and answering only the first leaves the
  * second to fail the request — so the first run against such an endpoint is spent discovering
@@ -314,12 +390,5 @@ export interface NegotiateOptions {
  * ever one flag in a turn — the same box `streamTurn` sets and the re-send below reads — and a
  * caller that passed it to only one of the two got a turn that had already streamed tokens sent
  * again, silently, with the watcher seeing every one of them twice.
- *
- * @param supports What this endpoint has already refused. Latched off further as it refuses more.
- * @param send Builds and sends the request. Called again per downgrade, never once tokens
- * have arrived. Its third argument is what the named model has refused, absent when no model
- * was named.
- * @param options `produced` for a caller with its own retry budget, `onNotice` for a watcher,
- * `model` to negotiate the model's refusals alongside the endpoint's.
  */
 export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced, model: ModelCapabilities | undefined) => Promise<T>, { produced, onNotice, model: name, droppable }?: NegotiateOptions): Promise<T>;