@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/side-task.js

@@ -1,11 +1,13 @@
-import OpenAI from "openai";
-import { capabilitiesFor, effortFor, modelCapabilitiesFor, negotiate, } from "./capabilities.js";
-import { endpointId, getClient } from "./client.js";
-import { errorMessage } from "./errors.js";
-import { isTransient } from "./retry.js";
-import { relaxTools, sanitizeTools } from "./schema-compat.js";
-import { scoped } from "./scope.js";
-import { stripThinking } from "./thinking.js";
+import OpenAI from 'openai';
+import { capabilitiesFor, ceilingAndTemperature, EFFORT_NONE, effortFor, modelCapabilitiesFor, negotiate, } from './capabilities.js';
+import { endpointId, getClient, modelKey, resolveApiKey, sameUrl } from './client.js';
+import { errorMessage } from './errors.js';
+import { refusesRequest } from './retry.js';
+import { relaxSchema, sanitizeSchema } from './schema-compat.js';
+import { scoped } from './scope.js';
+import { stripThinking } from './thinking.js';
+import { looseJson } from './tool-calls.js';
+import { JSON_SCHEMA_FORMAT, Role } from './wire.js';
 /**
  * One-shot calls that support a run without being one: picking tools, naming a session,
  * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short
@@ -18,6 +20,7 @@ import { stripThinking } from "./thinking.js";
  * disagree about which they take, so send both. One that rejects the unknown fields gets a
  * single retry without them, and is not offered them again.
  *
+ * @remarks
  * Only the second half is latched here. `reasoning_effort` is a field `negotiate` already knows
  * how to be refused, so it is sent under `ModelCapabilities.reasoningEffort` instead — which
  * both narrows the fallback below to the field it is really about, and shares the answer with
@@ -27,6 +30,7 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
 /**
  * The models that turned out not to take the hints, by endpoint and model.
  *
+ * @remarks
  * Keyed rather than global for the reason the client cache is keyed, and on the same
  * endpoint it is, by `endpointId`: a refusal is a fact about what is on the other end, not about this
  * process. A llama.cpp box and a cloud API are both reachable from one consumer over its
@@ -38,42 +42,36 @@ const NO_THINKING = { chat_template_kwargs: { enable_thinking: false } };
  * Keyed on the host alone, the first model to refuse spoke for every model on it.
  *
  * Only the `chat_template_kwargs` half is here. `reasoning_effort` is `negotiate`'s to latch, on
- * the same (endpoint, model) pair, where a run on that model can read it too.
+ * the same (endpoint, model) pair, where a run on that model can read it too. A pair is held as
+ * `modelKey(endpointId, model)`, which is what `importCapabilities` adds to it by.
  */
 const noHints = scoped(() => new Set());
-/** An (endpoint, model) pair as `noHints` holds it: `[endpointId, model]`, stringified. */
-export const hintKey = (endpoint, model) => JSON.stringify([endpoint, model]);
-/** The pairs that refused the hints, the live set, for `exportCapabilities` and `importCapabilities`. */
-export const refusedHints = () => noHints();
-/** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
-export const resetHints = () => noHints().clear();
 /**
- * Whether a failure is the server complaining about the request, rather than failing to answer.
+ * The pairs that refused the hints, the live set, for `exportCapabilities` and
+ * `importCapabilities`.
  *
- * The retry below used to catch everything, so an aborted first call — or a connection that
- * never landed — latched the hints off for the life of the process and every later side task
- * paid for it by burning a whole budget on deliberation. Narrowing that to any 4xx was still
- * too wide: 401, 404 and 429 are all 4xx and none of them is about the fields. A 429 was the
- * worst of them, because the retry then re-sent the whole request immediately — doubling the
- * rate against a server that had just asked for less of it — and `isTransient` accepts exactly
- * that status, so the two halves of this package disagreed about one error.
+ * @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 const refusedHints = () => noHints();
+/**
+ * Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints.
  *
- * 400 and 422 are what a server says when it read the body and disliked it. Everything else
- * is left to the caller's own retry.
+ * @remarks
+ * The current scope's set is emptied in place, so a holder of it sees it empty.
  */
-function rejectedTheRequest(error) {
-    if (!(error instanceof OpenAI.APIError) || isTransient(error))
-        return false;
-    return error.status === 400 || error.status === 422;
-}
+export const resetHints = () => noHints().clear();
 /**
  * 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 function ask(config, model, system, user, options = {}) {
     return complete(config, model, system, user, options);
@@ -81,6 +79,19 @@ export function ask(config, model, system, user, options = {}) {
 /**
  * The request `ask` and `askJson` share, with `format` deciding the extra body fields from what
  * the model and the endpoint have refused, rebuilt on every re-send.
+ *
+ * @param config - Where to send it. Its `baseUrl` and key also pick the capabilities the request is
+ * negotiated against, and with `model` the pair a refusal of the hints is latched on.
+ * @param model - The model to ask.
+ * @param system - The instruction, sent as the system message.
+ * @param user - The input, sent as the user message as it was given.
+ * @param options - A side task's options. A `reasoningEffort` that is a level leaves the
+ * no-thinking hints out; absent, `""` or `"off"` sends them unless this pair has refused them.
+ * @param [format] - Builds the extra body fields from the endpoint's capabilities and the model's.
+ * Called on every send, so a re-send is built from what has been latched since. Absent adds none.
+ * @returns The first choice's message as `answerOf` reads it, empty when there was no answer.
+ * Throws what the request throws, except that a 400 or 422 `negotiate` did not answer, on a
+ * request that carried the hints or an effort, is retried once without either.
  */
 async function complete(config, model, system, user, { maxTokens = 512, temperature = 0.3, reasoningEffort, signal, onNotice }, format) {
     // The effort the caller chose, or empty where it chose none: `""` and `"off"` read as absent,
@@ -93,24 +104,18 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // models refuse it by value and list `minimal` as their floor. `effortFor` answers with the
         // cheapest rung this one takes, which `negotiate` has been stepping up as it was refused.
         // A level the caller chose goes through the same ladder, which only ever steps up from it.
-        const asked = effort ? effortFor(refused, level || "none") : "";
-        sentEffort = asked !== "";
+        const asked = effort ? effortFor(refused, level || EFFORT_NONE) : '';
+        sentEffort = asked !== '';
         return getClient(config).chat.completions.create({
             model,
             // The reasoning models want the ceiling spelled the other way, and they are exactly the
-            // models a side task most wants to stop deliberating. Zero is no ceiling, as it is on the
-            // main model: a spec's `maxTokens: 0` sent as `max_tokens: 0` asks for an empty reply.
-            ...(maxTokens > 0
-                ? refused && !refused.legacyTokenLimit
-                    ? { max_completion_tokens: maxTokens }
-                    : { max_tokens: maxTokens }
-                : {}),
-            // One that will only run at the temperature it was built with is sent none: a side task
-            // wants the same answer twice, and 1.0 from that model is as close as it gets.
-            ...(refused && !refused.chosenTemperature ? {} : { temperature }),
+            // models a side task most wants to stop deliberating. One that will only run at its own
+            // temperature is sent none: a side task wants the same answer twice, and 1.0 from that
+            // model is as close as it gets.
+            ...ceilingAndTemperature(refused, maxTokens, temperature),
             messages: [
-                { role: "system", content: system },
-                { role: "user", content: user },
+                { role: Role.System, content: system },
+                { role: Role.User, content: user },
             ],
             ...(hints ? NO_THINKING : {}),
             // Not gated on `hints`: a model that refuses `chat_template_kwargs` may still read the
@@ -128,7 +133,7 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         model,
         onNotice,
     });
-    const key = hintKey(endpointId(config), model);
+    const key = modelKey(endpointId(config), model);
     // A chosen effort replaces the template hint rather than riding beside it: `enable_thinking:
     // false` next to `reasoning_effort: "high"` is a request that contradicts itself.
     const hints = !level && !noHints().has(key);
@@ -142,8 +147,9 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // does not offer as `none`. Or a 400 about something else entirely, which is why the
         // notice says what was tried rather than what was wrong.
         const effort = sentEffort;
-        if (!(hints || effort) || !rejectedTheRequest(error))
+        if (!(hints || effort) || !refusesRequest(error)) {
             throw error;
+        }
         onNotice?.(level
             ? `${model} rejected a request carrying a reasoning effort; retrying without it`
             : `${model} rejected a request carrying the no-thinking hints; retrying without them`);
@@ -153,57 +159,70 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
         // hints again. When both went out the refusal cannot say which, so the one `negotiate`
         // cannot latch is blamed; if it was the effort after all, the next call is left with only
         // the effort to drop and latches that instead.
-        if (hints)
+        if (hints) {
             noHints().add(key);
-        else
+        }
+        else {
             modelCapabilitiesFor(supports, model).reasoningEffort = false;
+        }
+    }
+    return answerOf(response.choices[0]?.message);
+}
+/**
+ * A reply's answer, thinking stripped, or its scratchpad where the answer is nothing else.
+ *
+ * @param message - The first choice's message. Absent, as when the reply held no choices, reads as
+ * an empty one.
+ * @returns The content, trimmed, with its thinking fences stripped. Where that leaves nothing, a
+ * string `reasoning_content` read the same way, and an empty string where there is none.
+ *
+ * @remarks
+ * Reasoning models that ignore the hints still fence their scratchpad. A side task answers under
+ * a small ceiling, so the fence often never closes, and a template that opened it in the prompt
+ * leaves only the close; either way the deliberation used to come back as the answer.
+ */
+function answerOf(message) {
+    const answer = stripThinking(message?.content ?? '').trim();
+    if (answer) {
+        return answer;
     }
-    const message = response.choices[0]?.message;
-    // Reasoning models that ignore the hints still fence their scratchpad. A side task answers
-    // under a small ceiling, so the fence often never closes, and a template that opened it in
-    // the prompt leaves only the close; either way the deliberation used to come back as the answer.
-    const answer = stripThinking(message?.content ?? "").trim();
     // Nothing but scratchpad. Some servers put the deliberation in its own field and leave the
     // content genuinely empty, in which case there is no answer to find anywhere else.
-    if (answer)
-        return answer;
     const reasoning = message?.reasoning_content;
-    return typeof reasoning === "string" ? stripThinking(reasoning).trim() : "";
+    return typeof reasoning === 'string' ? stripThinking(reasoning).trim() : '';
 }
 /**
  * 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 async function askJson(config, model, system, user, schema, { name = "answer", strict = true, ...options } = {}) {
-    const tool = (parameters) => ({
-        type: "function",
-        function: { name, parameters },
-    });
-    const [sanitized] = sanitizeTools([tool(schema)]);
-    const shapeOf = (definition) => definition?.type === "function" ? (definition.function.parameters ?? {}) : {};
-    const instruction = `${system}\n\nReply with JSON alone, matching this JSON Schema:\n${JSON.stringify(shapeOf(sanitized))}`;
+export async function askJson(config, model, system, user, schema, { name = 'answer', strict = true, ...options } = {}) {
+    const sanitized = sanitizeSchema(schema);
+    const instruction = `${system}\n\nReply with JSON alone, matching this JSON Schema:\n${JSON.stringify(sanitized)}`;
     const reply = await complete(config, model, instruction, user, options, (supports, refused) => refused.structuredOutput
         ? {
             response_format: {
-                type: "json_schema",
+                type: JSON_SCHEMA_FORMAT,
                 json_schema: {
                     name,
                     strict,
-                    schema: shapeOf(supports.strictSchemas ? sanitized : relaxTools([sanitized])[0]),
+                    schema: supports.strictSchemas ? sanitized : relaxSchema(sanitized),
                 },
             },
         }
@@ -211,12 +230,17 @@ export async function askJson(config, model, system, user, schema, { name = "ans
     return parseJson(reply);
 }
 /**
+ * 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 async function tryAsk(label, run, { onNotice } = {}) {
     try {
@@ -225,55 +249,120 @@ export async function tryAsk(label, run, { onNotice } = {}) {
     catch (error) {
         // A cancelled run is not a failed side task. Swallowing the abort made the two
         // indistinguishable and left the cancellation with nowhere to go.
-        if (error instanceof OpenAI.APIUserAbortError)
+        if (error instanceof OpenAI.APIUserAbortError) {
             throw error;
+        }
         onNotice?.(`${label}: ${errorMessage(error)}`);
         return 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 function parseJson(text) {
     const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
     const body = (fenced?.[1] ?? text).trim();
     const start = body.search(/[[{]/);
-    if (start < 0)
+    if (start < 0) {
         return undefined;
-    const end = Math.max(body.lastIndexOf("]"), body.lastIndexOf("}"));
-    if (end <= start)
-        return undefined;
-    try {
-        return JSON.parse(body.slice(start, end + 1));
     }
-    catch {
+    const end = Math.max(body.lastIndexOf(']'), body.lastIndexOf('}'));
+    if (end <= start) {
         return undefined;
     }
+    return looseJson(body.slice(start, end + 1));
 }
 /**
  * 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 const clean = (line) => line
     .trim()
-    .replace(/^(?:[-*•]|\d+[.)])\s*/, "")
-    .replace(/^["'`]+|["'`.]+$/g, "")
+    .replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+    .replace(/^["'`]+|["'`.]+$/g, '')
     .trim();
 /**
  * A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate
  * 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 const listLines = (text, max, maxChars) => text
-    .split("\n")
+    .split('\n')
     .map(clean)
     .filter((line) => line.length > 0 && line.length <= maxChars)
     .slice(0, max);
+/**
+ * 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 function taskCall(task, options, agent) {
+    const own = task.endpoint;
+    const shared = agent && (!own.baseUrl.trim() || sameUrl(own.baseUrl, agent.baseUrl));
+    const stated = {};
+    if (task.maxTokens !== undefined) {
+        stated.maxTokens = task.maxTokens;
+    }
+    if (task.temperature !== undefined) {
+        stated.temperature = task.temperature;
+    }
+    if (task.reasoningEffort !== undefined) {
+        stated.reasoningEffort = task.reasoningEffort;
+    }
+    return {
+        endpoint: agent
+            ? {
+                ...own,
+                ...(shared ? { baseUrl: agent.baseUrl } : {}),
+                apiKey: resolveApiKey(own, agent, {}),
+            }
+            : own,
+        model: task.model,
+        options: { ...options, ...stated },
+    };
+}

package/dist/snapshot.d.ts

@@ -16,8 +16,8 @@ export interface ModelSnapshot {
     refusedFields: string[];
     structuredOutput: boolean;
     /**
-     * Continues a trailing assistant message. Absent in a snapshot taken before it was latched, which
-     * reads as not refused.
+     * Continues a trailing assistant message. Always written; a stored snapshot from before it was
+     * latched lacks it, which `importCapabilities` reads as not refused.
      */
     assistantPrefill: boolean;
     /** Takes the no-thinking hints `ask` sends. */
@@ -28,7 +28,7 @@ export interface ModelSnapshot {
      * none refused.
      */
     refusedEfforts?: string[];
-    /** The efforts a refusal published as this model's, in ladder order. Absent is none published. */
+    /** The efforts a refusal published as this model's, in the order it gave them. Absent is none published. */
     supportedEfforts?: string[];
 }
 /** What one endpoint refused, and under it what each of its models did. */
@@ -55,6 +55,10 @@ export interface CapabilitySnapshot {
 /**
  * Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
  *
+ * @returns A fresh object that shares nothing with the live latches, its lists copied and the two
+ * refused ones sorted.
+ *
+ * @remarks
  * Covers what `negotiate` latches on endpoints and models and the models `ask` found refusing the
  * no-thinking hints. Only what was actually refused is in it, so a snapshot of a process that met
  * no refusals has no endpoints. Endpoints are named by digest rather than URL and key, since the
@@ -65,15 +69,16 @@ export declare function exportCapabilities(): CapabilitySnapshot;
 /**
  * Latches what a stored snapshot says was refused, on top of whatever this process has learned.
  *
+ * @param snapshot - What `exportCapabilities` returned, as stored. Read defensively: a field of the
+ * wrong type is skipped rather than trusted.
+ * @returns Whether the snapshot was of this version and applied.
+ *
+ * @remarks
  * Refusals only ever latch off, so importing merges rather than replaces: a flag already off stays
  * off whatever the snapshot says, and one the snapshot has off is turned off. A snapshot of another
  * version, or anything that is not one, is ignored — a stale shape costs the refused requests it
  * would have saved, which is what a restart cost before. How old is too old is the consumer's call,
  * made on `savedAt` before importing, or afterwards per endpoint with `expireCapabilities`, since a
  * server behind a URL can be upgraded between boots.
- *
- * @param snapshot What `exportCapabilities` returned, as stored. Read defensively: a field of the
- * wrong type is skipped rather than trusted.
- * @returns Whether the snapshot was of this version and applied.
  */
 export declare function importCapabilities(snapshot: unknown): boolean;