@cubicecho/agent-core 2.25.0 → 2.25.1

package/dist/agent-loop.js

@@ -204,7 +204,7 @@ function ownSummariser(options, notice) {
     const call = taskCall(compactor, { signal, onNotice: notice }, config);
     const write = summariser(call.endpoint, call.model, call.options);
     // A summary that fails folds nothing, and the step goes out as it was.
-    return async (text) => (await tryAsk('compaction', () => write(text), { onNotice: notice })) ?? '';
+    return async (text) => (await tryAsk('compaction', () => write(text), { onNotice: notice, signal })) ?? '';
 }
 /**
  * A step's transcript after the loop's own compaction: folded where a fold was due and its summary

package/dist/client.js

@@ -1,6 +1,6 @@
 import OpenAI from 'openai';
 import { digestOf } from './digest.js';
-import { isPositive } from './guards.js';
+import { byCodeUnit, isPositive } from './guards.js';
 import { MS_PER_SECOND } from './platform.js';
 import { assignSettings, scoped } from './scope.js';
 import { HttpStatus } from './wire.js';
@@ -466,7 +466,7 @@ export async function listModels(config) {
         }
         models.push({ id: model.id, contextLength: window.contextLength });
     }
-    models.sort((a, b) => a.id.localeCompare(b.id));
+    models.sort((a, b) => byCodeUnit(a.id, b.id));
     const key = endpointKey(config);
     listings().set(key, models);
     trainedOnly().set(key, trained);

package/dist/guards.d.ts

@@ -3,9 +3,10 @@
  *
  * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
  * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
- * its own copy. `getOrCreate` and `counted` are here for the same reason and are the two things that
- * are not checks: every cache in the package fills itself on a miss, and each had written that
- * out, and a notice that counts something is written in more than one module.
+ * its own copy. `getOrCreate`, `counted` and `byCodeUnit` are here for the same reason and are the
+ * three things that are not checks: every cache in the package fills itself on a miss, and each had
+ * written that out; a notice that counts something is written in more than one module; and so is a
+ * sort whose order must not depend on the host.
  */
 /**
  * Whether a value is a plain keyed object: not null, and not an array.
@@ -50,4 +51,17 @@ export declare function getOrCreate<K, V>(map: Lookup<K, V>, key: K, create: ()
  * @returns The phrase. Only a count of exactly one is singular: zero reads `0 tools`.
  */
 export declare const counted: (count: number, noun: string) => string;
+/**
+ * Orders two strings by code unit, which is the same on every host.
+ *
+ * @param a - The string on the left.
+ * @param b - The string on the right.
+ * @returns Negative where `a` sorts first, positive where `b` does, zero where they are the same.
+ *
+ * @remarks
+ * Rather than `localeCompare`, whose answer depends on the host's locale. An order the package
+ * relies on — the tool array a prompt cache matches, a tie between two ranked tools, a listing a
+ * host may key on — has to come out the same wherever it runs.
+ */
+export declare function byCodeUnit(a: string, b: string): number;
 export {};

package/dist/guards.js

@@ -3,9 +3,10 @@
  *
  * A leaf with no imports, because the modules that need these — a browser-safe `spec`, the schema
  * walk, the tool-call reader, the snapshot importer — otherwise share nothing, and each had grown
- * its own copy. `getOrCreate` and `counted` are here for the same reason and are the two things that
- * are not checks: every cache in the package fills itself on a miss, and each had written that
- * out, and a notice that counts something is written in more than one module.
+ * its own copy. `getOrCreate`, `counted` and `byCodeUnit` are here for the same reason and are the
+ * three things that are not checks: every cache in the package fills itself on a miss, and each had
+ * written that out; a notice that counts something is written in more than one module; and so is a
+ * sort whose order must not depend on the host.
  */
 /**
  * Whether a value is a plain keyed object: not null, and not an array.
@@ -53,3 +54,24 @@ export function getOrCreate(map, key, create) {
  * @returns The phrase. Only a count of exactly one is singular: zero reads `0 tools`.
  */
 export const counted = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+/**
+ * Orders two strings by code unit, which is the same on every host.
+ *
+ * @param a - The string on the left.
+ * @param b - The string on the right.
+ * @returns Negative where `a` sorts first, positive where `b` does, zero where they are the same.
+ *
+ * @remarks
+ * Rather than `localeCompare`, whose answer depends on the host's locale. An order the package
+ * relies on — the tool array a prompt cache matches, a tie between two ranked tools, a listing a
+ * host may key on — has to come out the same wherever it runs.
+ */
+export function byCodeUnit(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}

package/dist/platform.d.ts

@@ -11,3 +11,5 @@ export declare const MS_PER_SECOND = 1000;
 export declare const MS_PER_MINUTE: number;
 /** The event an `AbortSignal` fires when it aborts. */
 export declare const ABORT_EVENT = "abort";
+/** The name an error carries when it is what an aborted `AbortSignal` gave as its reason. */
+export declare const ABORT_ERROR = "AbortError";

package/dist/platform.js

@@ -11,3 +11,5 @@ export const MS_PER_SECOND = 1000;
 export const MS_PER_MINUTE = 60 * MS_PER_SECOND;
 /** The event an `AbortSignal` fires when it aborts. */
 export const ABORT_EVENT = 'abort';
+/** The name an error carries when it is what an aborted `AbortSignal` gave as its reason. */
+export const ABORT_ERROR = 'AbortError';

package/dist/preselect.d.ts

@@ -189,7 +189,8 @@ export interface PreselectOptions {
     maxPerLoad?: number;
     /**
      * Try `preselectByKeywords` first and spend the model only on what it cannot settle. `true`
-     * takes its defaults; an object tunes the thresholds. An empty `model` still means no
+     * takes its defaults; an object tunes the thresholds. Its own `maxPerLoad` can ask the words
+     * for fewer than `maxPerLoad` above, never for more. An empty `model` still means no
      * preselection at all, words included — that is what `toolSelectModel: ""` asks for.
      */
     keywords?: boolean | KeywordPreselectOptions;
@@ -204,8 +205,8 @@ export interface PreselectOptions {
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
  * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort
  * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
- * @returns Names as the catalogue spells them. Empty where `model` is empty, the catalogue has no
- * tools, the call failed, or its reply named nothing in the catalogue.
+ * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
+ * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
  * @remarks
  * On-demand loading otherwise spends a round trip on reading the catalogue and calling

package/dist/preselect.js

@@ -1,4 +1,4 @@
-import { counted, isRecord } from './guards.js';
+import { byCodeUnit, counted, isRecord } from './guards.js';
 import { askJson, tryAsk } from './side-task.js';
 import { catalogList, expandNames, MAX_PER_LOAD } from './tool-loading.js';
 import { SchemaType } from './wire.js';
@@ -230,7 +230,7 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
     }
     // Ties break on the name, not on where the tool sat in the catalogue, so reconnecting a
     // server in a different order does not change what a run opens with.
-    ranked.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+    ranked.sort((a, b) => b.score - a.score || byCodeUnit(a.name, b.name));
     if (!ranked.length) {
         return empty;
     }
@@ -249,8 +249,8 @@ export function preselectByKeywords(catalog, prompt, { maxPerLoad = MAX_PER_LOAD
  * @param prompt - The request being planned for. Only its head is read; see `preselectInput`.
  * @param [options] - Cancellation, notices, the reply ceiling, the temperature and reasoning effort
  * as `ask` reads them, the cap the choice is held to, and whether to try the words first.
- * @returns Names as the catalogue spells them. Empty where `model` is empty, the catalogue has no
- * tools, the call failed, or its reply named nothing in the catalogue.
+ * @returns Names as the catalogue spells them, never more than `maxPerLoad`. Empty where `model` is
+ * empty, the catalogue has no tools, the call failed, or its reply named nothing in the catalogue.
  *
  * @remarks
  * On-demand loading otherwise spends a round trip on reading the catalogue and calling
@@ -269,9 +269,10 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
         return [];
     }
     if (keywords) {
+        const tuned = keywords === true ? {} : keywords;
         const guess = preselectByKeywords(catalog, prompt, {
-            maxPerLoad,
-            ...(keywords === true ? {} : keywords),
+            ...tuned,
+            maxPerLoad: Math.min(maxPerLoad, tuned.maxPerLoad ?? maxPerLoad),
         });
         if (guess.confident) {
             onNotice?.(`chose ${counted(guess.names.length, 'tool')} by name`);
@@ -285,6 +286,6 @@ export async function preselect(config, model, catalog, prompt, { signal, onNoti
         reasoningEffort,
         signal,
         onNotice,
-    }), { onNotice });
+    }), { onNotice, signal });
     return preselection(reply, catalog, maxPerLoad);
 }

package/dist/retry.d.ts

@@ -82,6 +82,21 @@ export declare function isTransient(error: unknown): boolean;
  * latches off whatever the re-send left out.
  */
 export declare const refusesRequest: (error: unknown) => boolean;
+/**
+ * Whether a failure is the caller cancelling, rather than anything going wrong.
+ *
+ * @param error - The rejection, as caught.
+ * @returns `true` for the SDK's `APIUserAbortError` and for any error named `AbortError`, which is
+ * what an aborted signal gives as its reason; `false` for everything else, a timeout included.
+ *
+ * @remarks
+ * An abort reaches a catch in two shapes. The SDK raises its own class when a request in flight is
+ * cancelled, and `sleep` rejects with the signal's reason when the cancel lands between attempts.
+ * A catch that knew only the first reported the second as a failure. A signal aborted with a
+ * reason of the caller's own making is not recognised, since only the error is looked at: a
+ * catch that holds the signal asks it as well, as `tryAsk` does.
+ */
+export declare const isAbort: (error: unknown) => boolean;
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *

package/dist/retry.js

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { ABORT_EVENT } from './platform.js';
+import { ABORT_ERROR, ABORT_EVENT } from './platform.js';
 import { HttpStatus } from './wire.js';
 /**
  * Everything about a request failing that is not about what the request said.
@@ -126,6 +126,21 @@ export function isTransient(error) {
  */
 export const refusesRequest = (error) => error instanceof OpenAI.APIError &&
     (error.status === HttpStatus.BadRequest || error.status === HttpStatus.UnprocessableEntity);
+/**
+ * Whether a failure is the caller cancelling, rather than anything going wrong.
+ *
+ * @param error - The rejection, as caught.
+ * @returns `true` for the SDK's `APIUserAbortError` and for any error named `AbortError`, which is
+ * what an aborted signal gives as its reason; `false` for everything else, a timeout included.
+ *
+ * @remarks
+ * An abort reaches a catch in two shapes. The SDK raises its own class when a request in flight is
+ * cancelled, and `sleep` rejects with the signal's reason when the cancel lands between attempts.
+ * A catch that knew only the first reported the second as a failure. A signal aborted with a
+ * reason of the caller's own making is not recognised, since only the error is looked at: a
+ * catch that holds the signal asks it as well, as `tryAsk` does.
+ */
+export const isAbort = (error) => error instanceof OpenAI.APIUserAbortError || (error instanceof Error && error.name === ABORT_ERROR);
 /** The error type llama.cpp gives a request it cannot serve yet. */
 const UNAVAILABLE_ERROR = 'unavailable_error';
 /**

package/dist/schema-compat.js

@@ -381,7 +381,13 @@ function collectRefs(node, into) {
  * outside it still refers in.
  */
 function pruneDefs(schema) {
-    const pools = POOL_KEYS.filter((key) => isRecord(schema[key]));
+    const pools = [];
+    for (const key of POOL_KEYS) {
+        const pool = schema[key];
+        if (isRecord(pool)) {
+            pools.push([key, pool]);
+        }
+    }
     if (!pools.length) {
         return schema;
     }
@@ -411,19 +417,18 @@ function pruneDefs(schema) {
     // The pools themselves are not roots: a definition is reached from the schema body, or by
     // another definition that was, or not at all.
     const body = { ...schema };
-    for (const key of pools) {
+    for (const [key] of pools) {
         delete body[key];
     }
     visit(body);
     let pruned = schema;
-    for (const key of pools) {
+    for (const [key, pool] of pools) {
         const names = live[key];
         if (!names?.size) {
             const { [key]: _unreached, ...rest } = pruned;
             pruned = rest;
             continue;
         }
-        const pool = schema[key];
         if (names.size === Object.keys(pool).length) {
             continue;
         }

package/dist/side-task.d.ts

@@ -1,4 +1,4 @@
-import OpenAI from 'openai';
+import type OpenAI from 'openai';
 import { type OnNotice } from './capabilities.ts';
 import type { Endpoint, EndpointIdentity } from './config.ts';
 /**
@@ -154,15 +154,16 @@ export declare function askJson<T>(config: Endpoint, model: string, system: stri
  *
  * @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.
+ * @param [options] - `onNotice`, told what was given up on, and the `signal` that `run` is
+ * cancelled by.
+ * @returns What `run` resolved with, or `undefined` when it threw. Whatever it threw once the
+ * signal had aborted is thrown on and raises no notice, as is an error that is itself an abort.
  *
  * @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.
  */
-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, signal }?: Pick<SideTaskOptions, 'onNotice' | 'signal'>): Promise<T | undefined>;
 /**
  * The first array or object in a model's reply, parsed, whatever prose or fence surrounds it.
  *

package/dist/side-task.js

@@ -1,12 +1,11 @@
-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 { isAbort, 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 { CODE_FENCE, 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,
@@ -234,22 +233,25 @@ export async function askJson(config, model, system, user, schema, { name = 'ans
  *
  * @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.
+ * @param [options] - `onNotice`, told what was given up on, and the `signal` that `run` is
+ * cancelled by.
+ * @returns What `run` resolved with, or `undefined` when it threw. Whatever it threw once the
+ * signal had aborted is thrown on and raises no notice, as is an error that is itself an abort.
  *
  * @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.
  */
-export async function tryAsk(label, run, { onNotice } = {}) {
+export async function tryAsk(label, run, { onNotice, signal } = {}) {
     try {
         return await run();
     }
     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) {
+        // indistinguishable and left the cancellation with nowhere to go. The signal is asked first:
+        // an abort with a reason of the caller's own rejects with that reason, which no class names.
+        const wasCancelled = signal?.aborted === true || isAbort(error);
+        if (wasCancelled) {
             throw error;
         }
         onNotice?.(`${label}: ${errorMessage(error)}`);
@@ -274,7 +276,7 @@ export async function tryAsk(label, run, { onNotice } = {}) {
  * 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 [fenced] = text.matchAll(CODE_FENCE);
     const body = (fenced?.[1] ?? text).trim();
     const start = body.search(/[[{]/);
     if (start < 0) {

package/dist/tool-calls.d.ts

@@ -14,6 +14,14 @@ export declare const ARGUMENT_PREVIEW_CHARS = 200;
 export declare const ARGUMENTS_TRUNCATED: 'truncated';
 /** The `ToolArgumentsError` kind for a call the model wrote wrongly. */
 export declare const ARGUMENTS_MALFORMED: 'malformed';
+/**
+ * A fenced block in a model's reply, tagged `json` or not tagged; the first group is what it holds.
+ *
+ * @remarks
+ * Global, for `matchAll`, which reads from a copy: nothing here keeps a place in the text between
+ * two uses. What it captures still wants trimming.
+ */
+export declare const CODE_FENCE: RegExp;
 /** A tool call as the loop handles it, recovered or streamed. */
 export type ToolCall = OpenAI.ChatCompletionMessageFunctionToolCall;
 /**

package/dist/tool-calls.js

@@ -16,6 +16,14 @@ export const ARGUMENT_PREVIEW_CHARS = 200;
 export const ARGUMENTS_TRUNCATED = 'truncated';
 /** The `ToolArgumentsError` kind for a call the model wrote wrongly. */
 export const ARGUMENTS_MALFORMED = 'malformed';
+/**
+ * A fenced block in a model's reply, tagged `json` or not tagged; the first group is what it holds.
+ *
+ * @remarks
+ * Global, for `matchAll`, which reads from a copy: nothing here keeps a place in the text between
+ * two uses. What it captures still wants trimming.
+ */
+export const CODE_FENCE = /```(?:json)?\s*([\s\S]*?)```/gi;
 /**
  * Tool arguments that could not be read as an object, with why.
  *
@@ -405,7 +413,7 @@ function bareCalls(text, names) {
             return [{ start, end: read.end, calls }];
         }
     }
-    const fences = [...text.matchAll(/```(?:json)?[ \t]*\n?([\s\S]*?)```/gi)];
+    const fences = [...text.matchAll(CODE_FENCE)];
     if (fences.length !== 1) {
         return [];
     }

package/dist/tool-loading.js

@@ -1,4 +1,4 @@
-import { isRecord } from './guards.js';
+import { byCodeUnit, isRecord } from './guards.js';
 import { ARGUMENT_PREVIEW_CHARS } from './tool-calls.js';
 import { FUNCTION_TOOL, SchemaType } from './wire.js';
 /**
@@ -170,26 +170,6 @@ export function loadedTools(previous, matched) {
     }
     return tools;
 }
-/**
- * Orders two names by code unit.
- *
- * @param a - The name on the left.
- * @param b - The name on the right.
- * @returns Negative where `a` sorts first, positive where `b` does, zero where they are the same.
- *
- * @remarks
- * Rather than `localeCompare`, whose answer depends on the host's locale — which is the kind of
- * instability `orderTools` exists to remove.
- */
-function byCodeUnit(a, b) {
-    if (a < b) {
-        return -1;
-    }
-    if (a > b) {
-        return 1;
-    }
-    return 0;
-}
 /**
  * The tool array in a stable order, so the same set of tools renders the same way twice.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.25.0",
+  "version": "2.25.1",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",