@cubicecho/agent-core 2.23.0 → 2.25.0

package/dist/continuation.js

@@ -1,20 +1,24 @@
-import OpenAI from "openai";
-import { modelCapabilitiesFor } from "./capabilities.js";
-import { errorMessage } from "./errors.js";
-import { ContextOverflow } from "./retry.js";
-import { runTurn } from "./run-turn.js";
+import { modelCapabilitiesFor } from './capabilities.js';
+import { errorMessage } from './errors.js';
+import { ContextOverflow, refusesRequest } from './retry.js';
+import { modelLabel, runTurn } from './run-turn.js';
+import { addCounts } from './stream.js';
+import { FinishReason, Role } from './wire.js';
 /**
  * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
  * and no tool call in it.
  *
+ * @param turn - The turn as it came back.
+ * @returns False for a turn that stopped for any reason but `length`, whose content is blank, or
+ * that holds a tool call.
+ *
+ * @remarks
  * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
  * the template's business rather than something this can do the same way everywhere — llama.cpp
  * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
  * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
- *
- * @param turn The turn as it came back.
  */
-export const isContinuable = (turn) => turn.finishReason === "length" && turn.content.trim() !== "" && turn.toolCalls.length === 0;
+export const isContinuable = (turn) => turn.finishReason === FinishReason.Length && turn.content.trim() !== '' && turn.toolCalls.length === 0;
 /** How much of the answer's opening a reply has to repeat to have started over. */
 const RESTART_PROBE = 40;
 /** The shortest opening worth testing for a restart; shorter ones are repeated by chance. */
@@ -22,6 +26,11 @@ const RESTART_MIN = 12;
 /**
  * Whether the continuation began the answer again rather than carrying it on — how a server that
  * ignores the prefill shows itself, since it takes the request without complaint.
+ *
+ * @param answer - The answer so far, as it was sent back as the prefill.
+ * @param continuation - The content the continuation came back with.
+ * @returns True where the continuation opens with the answer's own opening, leading whitespace
+ * aside on both. Never true for an answer whose opening is shorter than `RESTART_MIN`.
  */
 const restarted = (answer, continuation) => {
     const opening = answer.trimStart().slice(0, RESTART_PROBE);
@@ -29,42 +38,48 @@ const restarted = (answer, continuation) => {
 };
 /** The fields of a usage that add across two requests, when both reported them. */
 const ADDED = [
-    "uncached",
-    "reasoningTokens",
-    "promptMs",
-    "predictedMs",
-    "draftTotal",
-    "draftAccepted",
-    "wallMs",
-    "retries",
-    "timeouts",
+    'uncached',
+    'reasoningTokens',
+    'promptMs',
+    'predictedMs',
+    'draftTotal',
+    'draftAccepted',
+    'wallMs',
+    'retries',
+    'timeouts',
 ];
 /** A rate, and the duration it was measured over, which is what weights it in a mean. */
 const RATES = [
-    ["promptTokensPerSecond", "promptMs"],
-    ["tokensPerSecond", "predictedMs"],
+    ['promptTokensPerSecond', 'promptMs'],
+    ['tokensPerSecond', 'predictedMs'],
 ];
 /**
- * Two requests' usage as one turn's. The first request's own measurements and the loop's
- * comparison with the request before it stay as they were; a field only one of them reported is
- * dropped rather than passed off as the total.
+ * Two requests' usage as one turn's.
+ *
+ * @param first - The turn so far, which may itself be a joined one. Not written to.
+ * @param next - The continuation's usage. Not written to.
+ * @returns A new usage: the four counts summed, `continuations` one more than `first` had, and a
+ * rate both requests timed as the mean of the two, weighted by the time each was measured over.
+ *
+ * @remarks
+ * The first request's own measurements and the loop's comparison with the request before it stay
+ * as they were; a field only one of them reported is dropped rather than passed off as the total.
  */
 function joinUsage(first, next) {
     const joined = {
         ...first,
-        prompt: first.prompt + next.prompt,
-        completion: first.completion + next.completion,
-        total: first.total + next.total,
-        cached: first.cached + next.cached,
+        ...addCounts(first, next),
         continuations: (first.continuations ?? 0) + 1,
     };
     for (const field of ADDED) {
         const a = first[field];
         const b = next[field];
-        if (a !== undefined && b !== undefined)
+        if (a !== undefined && b !== undefined) {
             joined[field] = a + b;
-        else
+        }
+        else {
             delete joined[field];
+        }
     }
     for (const [rate, over] of RATES) {
         const a = first[rate];
@@ -72,19 +87,31 @@ function joinUsage(first, next) {
         const aMs = first[over];
         const bMs = next[over];
         // Tokens over time for both together, which is each rate weighted by the time it held.
-        if (a !== undefined && b !== undefined && aMs !== undefined && bMs !== undefined && aMs + bMs)
+        const bothTimed = a !== undefined && b !== undefined && aMs !== undefined && bMs !== undefined;
+        if (bothTimed && aMs + bMs) {
             joined[rate] = (a * aMs + b * bMs) / (aMs + bMs);
-        else
+        }
+        else {
             delete joined[rate];
+        }
     }
     return joined;
 }
-/** Whether a failure is the endpoint refusing the request as written, rather than losing it. */
-const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
 /**
  * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
  * so far as a trailing assistant message, and joins the pieces into one turn.
  *
+ * @param client - The pooled client for this endpoint.
+ * @param supports - What the endpoint has already refused.
+ * @param request - Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn - The turn that came back cut off.
+ * @param [options] - `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ * @returns `turn` itself where nothing was joined to it; otherwise a new turn, with the last
+ * continuation's `finishReason` and tool calls.
+ *
+ * @remarks
  * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
  * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
  * across the requests with `continuations` counting them. The continuation is read as starting in
@@ -98,22 +125,15 @@ const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.sta
  * that check is only as good as a restart being word for word. Either way the answer so far is
  * kept, with a notice. So is it when the continuation fails any other way, since the tokens
  * already in hand are worth more than the error; only a stop is thrown.
- *
- * @param client The pooled client for this endpoint.
- * @param supports What the endpoint has already refused.
- * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
- * prefill is appended to what it builds.
- * @param turn The turn that came back cut off.
- * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
- * latched and each continuation finds out again — and the cap on continuations.
  */
 export async function continueTurn(client, supports, request, turn, { maxContinuations = 1, ...options } = {}) {
     const refused = options.model === undefined ? undefined : modelCapabilitiesFor(supports, options.model);
-    const who = options.model ?? "the model";
+    const who = modelLabel(options.model);
     let joined = turn;
     for (let count = 0; count < maxContinuations && isContinuable(joined); count++) {
-        if (refused?.assistantPrefill === false)
+        if (refused?.assistantPrefill === false) {
             break;
+        }
         const answer = joined.content;
         let next;
         try {
@@ -121,19 +141,21 @@ export async function continueTurn(client, supports, request, turn, { maxContinu
                 const body = request(capabilities, forModel);
                 return {
                     ...body,
-                    messages: [...body.messages, { role: "assistant", content: answer }],
+                    messages: [...body.messages, { role: Role.Assistant, content: answer }],
                 };
             }, { ...options, startInReasoning: false });
         }
         catch (error) {
-            if (options.signal?.aborted)
+            if (options.signal?.aborted) {
                 throw error;
+            }
             if (error instanceof ContextOverflow) {
-                options.onNotice?.("no room left in the window to continue the cut-off reply");
+                options.onNotice?.('no room left in the window to continue the cut-off reply');
             }
             else if (refusesRequest(error)) {
-                if (refused)
+                if (refused) {
                     refused.assistantPrefill = false;
+                }
                 options.onNotice?.(`${who} refused a trailing assistant message (${errorMessage(error)}); keeping the cut-off reply`);
             }
             else {
@@ -142,8 +164,9 @@ export async function continueTurn(client, supports, request, turn, { maxContinu
             break;
         }
         if (restarted(answer, next.content)) {
-            if (refused)
+            if (refused) {
                 refused.assistantPrefill = false;
+            }
             options.onNotice?.(`${who} answered afresh instead of continuing its reply; keeping the cut-off reply`);
             break;
         }

package/dist/digest.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A text's SHA-256, in hex.
+ *
+ * @param text - What to hash.
+ * @returns Sixty-four hex characters, the same for the same text on any machine.
+ */
+export declare const digestOf: (text: string) => string;

package/dist/digest.js

@@ -0,0 +1,18 @@
+/**
+ * The one digest this package takes, of an endpoint's key and of a turn's text.
+ *
+ * Apart from `platform.ts` because it loads `node:crypto`, which a browser-safe module must not
+ * come to import by reaching for a constant.
+ */
+import { createHash } from 'node:crypto';
+/** The hash every digest here is taken with. */
+const DIGEST_ALGORITHM = 'sha256';
+/** How a digest is written out. */
+const DIGEST_ENCODING = 'hex';
+/**
+ * A text's SHA-256, in hex.
+ *
+ * @param text - What to hash.
+ * @returns Sixty-four hex characters, the same for the same text on any machine.
+ */
+export const digestOf = (text) => createHash(DIGEST_ALGORITHM).update(text).digest(DIGEST_ENCODING);

package/dist/errors.d.ts

@@ -1,20 +1,24 @@
-import type OpenAI from "openai";
-import type { ToolCallOutcome } from "./agent-loop.ts";
-import { ContextOverflow } from "./retry.ts";
-import type { TurnUsage } from "./stream.ts";
+import type OpenAI from 'openai';
+import { ContextOverflow } from './retry.ts';
+import type { TurnUsage } from './stream.ts';
+import type { ToolCallOutcome } from './tool-calls.ts';
 /**
  * What went wrong, as a string.
  *
+ * @param error - Whatever a `catch` bound. Anything that is not an `Error` is stringified.
+ * @returns An `Error`'s `message` as it is, empty included; otherwise `String(error)`, so a thrown
+ * `undefined` reads `undefined`.
+ *
+ * @remarks
  * Almost everything caught here ends up in a run row, a tool result or a log line, and a
  * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
  * that had to say what happened.
- *
- * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
 export declare const errorMessage: (error: unknown) => string;
 /**
  * A run as it stood when `runAgentLoop` gave up on it.
  *
+ * @remarks
  * The loop works on its own copy of the transcript and hands it back only on success, so without
  * this a spent budget, a stop or a refused request took every step before it along — steps whose
  * assistant turns and tool results were real, and that a host storing its transcript has to keep.
@@ -38,6 +42,7 @@ export interface AgentLoopFailure {
 /**
  * What `runAgentLoop` throws, carrying the run as it stood and what was caught as `cause`.
  *
+ * @remarks
  * Its own class rather than fields hung on the error that was caught, because a stop throws the
  * signal's reason and that is one object for every run under the signal. The message is the
  * cause's own, so a host that logs `errorMessage(error)` logs what it always did. A stop is told
@@ -51,15 +56,16 @@ export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly loaded: string[];
     readonly used: string[];
     /**
-     * @param message What went wrong — the cause's own message, where there is a cause.
-     * @param run The run as it stood. Held, not copied.
-     * @param options The standard `cause`: what the loop caught, absent where the loop itself gave up.
+     * @param message - What went wrong — the cause's own message, where there is a cause.
+     * @param run - The run as it stood. Held, not copied.
+     * @param [options] - The standard `cause`: what the loop caught, absent where the loop itself gave up.
      */
     constructor(message: string, run: AgentLoopFailure, options?: ErrorOptions);
 }
 /**
  * `maxToolIterations` was spent with the model still asking for tools.
  *
+ * @remarks
  * Named so a host can tell it from a failure without matching the message, which is the same
  * sentence it has always been. There is no `cause`: nothing was caught, the loop stopped itself.
  */
@@ -69,6 +75,7 @@ export declare class ToolIterationLimit extends AgentLoopError {
 /**
  * A `ContextOverflow` out of `runAgentLoop`, carrying the run as it stood.
  *
+ * @remarks
  * A subclass of `ContextOverflow` rather than an `AgentLoopError` around one, because
  * `instanceof ContextOverflow` is how a caller knows to compact and send again, and wrapping
  * would have made that test quietly false. The overflow the loop caught is the `cause`, and the
@@ -81,19 +88,21 @@ export declare class AgentLoopOverflow extends ContextOverflow implements AgentL
     readonly loaded: string[];
     readonly used: string[];
     /**
-     * @param message The overflow's own message.
-     * @param run The run as it stood. Held, not copied.
-     * @param options The standard `cause`: the `ContextOverflow` the loop caught.
+     * @param message - The overflow's own message.
+     * @param run - The run as it stood. Held, not copied.
+     * @param [options] - The standard `cause`: the `ContextOverflow` the loop caught.
      */
     constructor(message: string, run: AgentLoopFailure, options?: ErrorOptions);
 }
 /**
  * The run a failed `runAgentLoop` left behind, read off whatever it threw, or nothing.
  *
+ * @param error - Whatever a `catch` around `runAgentLoop` bound. Anything the loop did not throw
+ * answers `undefined`.
+ * @returns The error itself, read as the run it carries — the same object, not a copy.
+ *
+ * @remarks
  * Two classes carry it — an overflow has to stay a `ContextOverflow` and so cannot also be an
  * `AgentLoopError` — and a `catch` that only wants the transcript should not have to name both.
- *
- * @param error Whatever a `catch` around `runAgentLoop` bound. Anything the loop did not throw
- * answers `undefined`.
  */
 export declare const failedRun: (error: unknown) => AgentLoopFailure | undefined;

package/dist/errors.js

@@ -1,33 +1,37 @@
-import { ContextOverflow } from "./retry.js";
+import { ContextOverflow } from './retry.js';
 /**
  * What went wrong, as a string.
  *
+ * @param error - Whatever a `catch` bound. Anything that is not an `Error` is stringified.
+ * @returns An `Error`'s `message` as it is, empty included; otherwise `String(error)`, so a thrown
+ * `undefined` reads `undefined`.
+ *
+ * @remarks
  * Almost everything caught here ends up in a run row, a tool result or a log line, and a
  * `catch` binds `unknown` — so the same three-branch ternary was being written at every site
  * that had to say what happened.
- *
- * @param error Whatever a `catch` bound. Anything that is not an `Error` is stringified.
  */
-export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
 /**
  * What `runAgentLoop` throws, carrying the run as it stood and what was caught as `cause`.
  *
+ * @remarks
  * Its own class rather than fields hung on the error that was caught, because a stop throws the
  * signal's reason and that is one object for every run under the signal. The message is the
  * cause's own, so a host that logs `errorMessage(error)` logs what it always did. A stop is told
  * the way it was before — by the signal the host aborted, not by the class of what came out.
  */
 export class AgentLoopError extends Error {
-    name = "AgentLoopError";
+    name = 'AgentLoopError';
     messages;
     usage;
     toolCalls;
     loaded;
     used;
     /**
-     * @param message What went wrong — the cause's own message, where there is a cause.
-     * @param run The run as it stood. Held, not copied.
-     * @param options The standard `cause`: what the loop caught, absent where the loop itself gave up.
+     * @param message - What went wrong — the cause's own message, where there is a cause.
+     * @param run - The run as it stood. Held, not copied.
+     * @param [options] - The standard `cause`: what the loop caught, absent where the loop itself gave up.
      */
     constructor(message, run, options) {
         super(message, options);
@@ -41,15 +45,17 @@ export class AgentLoopError extends Error {
 /**
  * `maxToolIterations` was spent with the model still asking for tools.
  *
+ * @remarks
  * Named so a host can tell it from a failure without matching the message, which is the same
  * sentence it has always been. There is no `cause`: nothing was caught, the loop stopped itself.
  */
 export class ToolIterationLimit extends AgentLoopError {
-    name = "ToolIterationLimit";
+    name = 'ToolIterationLimit';
 }
 /**
  * A `ContextOverflow` out of `runAgentLoop`, carrying the run as it stood.
  *
+ * @remarks
  * A subclass of `ContextOverflow` rather than an `AgentLoopError` around one, because
  * `instanceof ContextOverflow` is how a caller knows to compact and send again, and wrapping
  * would have made that test quietly false. The overflow the loop caught is the `cause`, and the
@@ -62,9 +68,9 @@ export class AgentLoopOverflow extends ContextOverflow {
     loaded;
     used;
     /**
-     * @param message The overflow's own message.
-     * @param run The run as it stood. Held, not copied.
-     * @param options The standard `cause`: the `ContextOverflow` the loop caught.
+     * @param message - The overflow's own message.
+     * @param run - The run as it stood. Held, not copied.
+     * @param [options] - The standard `cause`: the `ContextOverflow` the loop caught.
      */
     constructor(message, run, options) {
         super(message, options);
@@ -78,10 +84,12 @@ export class AgentLoopOverflow extends ContextOverflow {
 /**
  * The run a failed `runAgentLoop` left behind, read off whatever it threw, or nothing.
  *
+ * @param error - Whatever a `catch` around `runAgentLoop` bound. Anything the loop did not throw
+ * answers `undefined`.
+ * @returns The error itself, read as the run it carries — the same object, not a copy.
+ *
+ * @remarks
  * Two classes carry it — an overflow has to stay a `ContextOverflow` and so cannot also be an
  * `AgentLoopError` — and a `catch` that only wants the transcript should not have to name both.
- *
- * @param error Whatever a `catch` around `runAgentLoop` bound. Anything the loop did not throw
- * answers `undefined`.
  */
 export const failedRun = (error) => error instanceof AgentLoopError || error instanceof AgentLoopOverflow ? error : undefined;