@cubicecho/agent-core 1.1.0 → 1.3.0

package/README.md

@@ -29,12 +29,52 @@ only, Node >=22.
 | `client` | A pooled `OpenAI` client per endpoint, plus the context-window listing and its cache. |
 | `retry` | What to do when a request is lost, refused or too big: `isTransient`, `backoffMs`, `ContextOverflow`, `EndpointSilent`. |
 | `config` | The structural interfaces every function here asks for. |
+| `run-turn` | `runTurn`: one turn with the retry loop around the negotiation around the stream. The whole loop, for a caller that wants it rather than its parts. |
+| `reset` | `resetAll`: drops every cache and latch in one call, so a teardown cannot forget one. |
 | `errors` | `errorMessage`: a caught `unknown` turned into something a run row can hold. |
 | `catalog` | `CatalogServer`: the name-only shape `tool-loading` reads a connected server as. |
 
 What is **not** here is the work: orchestration, prompts, and whatever the run is about. That
 is the caller's, and it is the part that actually differs between one server and the next.
 
+## A turn
+
+`negotiate` wrapping `streamTurn` is the whole of one turn against an endpoint: the request is
+re-sent for as long as the answer is this server refusing something the request can do without,
+and nothing is re-sent once it has started answering.
+
+```ts
+import {
+  capabilitiesFor, getClient, negotiate, relaxTools, sanitizeTools, streamTurn, timeoutMs,
+} from "@cubicecho/agent-core";
+
+const declared = sanitizeTools(tools);
+const supports = capabilitiesFor(config.baseUrl);
+
+const turn = await negotiate(supports, (supports, produced) =>
+  streamTurn(
+    getClient(config),
+    {
+      model, messages, stream: true,
+      // Rebuilt per attempt: what the endpoint has refused is latched off by the line above.
+      ...(supports.usageInStream ? { stream_options: { include_usage: true } } : {}),
+      tools: supports.strictSchemas ? declared : relaxTools(declared),
+    },
+    { produced, signal, idleMs: timeoutMs(config), onOutput: (text) => emit(runId, { kind: "output", text }) },
+  ),
+);
+```
+
+`send` takes a callback rather than a body because the body has to be rebuilt from the latched
+flags. `produced` is one box per attempt — `streamTurn` sets it as soon as the server says
+anything, and the re-send reads it — so a caller with its own retry budget passes one in
+(`{ produced }`) and reads it afterwards to decide whether the failure is worth another attempt.
+
+`idleMs` is silence, not a deadline: the timer is rearmed on every chunk, so a model that is
+still talking is never cut off however long it takes, and one that has stopped answering raises
+`EndpointSilent` rather than hanging the run. `timeoutMs(config)` returns `undefined` for a
+`requestTimeoutSeconds` of zero, which waits forever — what a local model answering slowly needs.
+
 ## The config seam
 
 Nothing here imports a config type from a consumer, and no function asks for a whole

package/dist/capabilities.d.ts

@@ -1,3 +1,4 @@
+import type { Produced } from "./stream.ts";
 /**
  * What an endpoint turned out not to support, and answering it when it says so.
  *
@@ -32,13 +33,13 @@ export declare function capabilitiesFor(baseUrl: string): Capabilities;
 export declare function resetCapabilities(): void;
 export interface NegotiateOptions {
     /**
-     * Whether the server has started answering. Nothing is re-sent once it has: the tokens are
-     * already out and on their way to whoever is watching, and a second attempt would say
-     * everything twice. See `streamTurn`, which sets this.
+     * The flag `send` will be given, for a caller that has to read it after `negotiate` returns.
+     *
+     * 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.
      */
-    produced?: {
-        any: boolean;
-    };
+    produced?: Produced;
     /** Told what was given up on, for a watcher who would otherwise see an unexplained pause. */
     onNotice?: (message: string) => void;
 }
@@ -58,5 +59,10 @@ export interface NegotiateOptions {
  * `stream_options` is present or absent rather than adjusted. It is generic over what it
  * resolves, so a caller whose request resolves a stream object before any chunk is read is the
  * same shape as one that resolves a finished turn.
+ *
+ * It is handed the `produced` flag rather than being expected to close over one. There is only
+ * 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.
  */
-export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities) => Promise<T>, { produced, onNotice }?: NegotiateOptions): Promise<T>;
+export declare function negotiate<T>(supports: Capabilities, send: (supports: Capabilities, produced: Produced) => Promise<T>, { produced, onNotice }?: NegotiateOptions): Promise<T>;

package/dist/capabilities.js

@@ -46,14 +46,19 @@ const REJECTS_USAGE = /stream_options/i;
  * `stream_options` is present or absent rather than adjusted. It is generic over what it
  * resolves, so a caller whose request resolves a stream object before any chunk is read is the
  * same shape as one that resolves a finished turn.
+ *
+ * It is handed the `produced` flag rather than being expected to close over one. There is only
+ * 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.
  */
-export async function negotiate(supports, send, { produced, onNotice } = {}) {
+export async function negotiate(supports, send, { produced = { any: false }, onNotice } = {}) {
     for (;;) {
         try {
-            return await send(supports);
+            return await send(supports, produced);
         }
         catch (error) {
-            if (produced?.any)
+            if (produced.any)
                 throw error;
             const detail = errorMessage(error);
             if (supports.strictSchemas && isGrammarError(detail)) {

package/dist/index.d.ts

@@ -15,9 +15,11 @@ export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetCl
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
 export { emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, reset, watch, } from "./events.ts";
+export { resetAll } from "./reset.ts";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
-export { type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
+export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { estimateTokens } from "./tokens.ts";
 export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -13,7 +13,9 @@ export { capabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.j
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
 export { errorMessage } from "./errors.js";
 export { emit, endRun, fold, history, reset, watch, } from "./events.js";
+export { resetAll } from "./reset.js";
 export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { streamTurn, } from "./stream.js";

package/dist/reset.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Forgets everything this package remembers between calls.
+ *
+ * Four modules here keep state for the life of the process, each for a good reason and each
+ * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * out not to take `stream_options` or a grammar, the models that refused the no-thinking
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `reset` stay
+ * exported, because a test that means to clear one thing should say so.
+ *
+ * This is for the other case, which is every teardown. What all four hold is *latched
+ * refusals* — a fact one test taught the process about an endpoint, still true as far as the
+ * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
+ * locally and fails in CI on a different shard: the test that latched it still passes, and the
+ * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
+ * was written that way and only passed because every case had been handed a hostname of its own.
+ *
+ * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ */
+export declare function resetAll(): void;

package/dist/reset.js

@@ -0,0 +1,29 @@
+import { resetCapabilities } from "./capabilities.js";
+import { resetClients } from "./client.js";
+import { reset as resetEvents } from "./events.js";
+import { resetHints } from "./side-task.js";
+/**
+ * Forgets everything this package remembers between calls.
+ *
+ * Four modules here keep state for the life of the process, each for a good reason and each
+ * with its own seam: the pooled clients and their model listings, the endpoints that turned
+ * out not to take `stream_options` or a grammar, the models that refused the no-thinking
+ * hints, and the event bus. `resetClients`, `resetCapabilities`, `resetHints` and `reset` stay
+ * exported, because a test that means to clear one thing should say so.
+ *
+ * This is for the other case, which is every teardown. What all four hold is *latched
+ * refusals* — a fact one test taught the process about an endpoint, still true as far as the
+ * next test can tell. Miss one and the suite becomes order-dependent in the way that passes
+ * locally and fails in CI on a different shard: the test that latched it still passes, and the
+ * one that reads the latch fails only when it happens to run second. `tests/side-task-hints.test.ts`
+ * was written that way and only passed because every case had been handed a hostname of its own.
+ *
+ * It is also the seam that does not need finding again. A fifth module with a cache is a fifth
+ * line here, rather than an edit to the teardown of three consumers who will not all notice.
+ */
+export function resetAll() {
+    resetClients();
+    resetCapabilities();
+    resetHints();
+    resetEvents();
+}

package/dist/run-turn.d.ts

@@ -0,0 +1,38 @@
+import type OpenAI from "openai";
+import { type Capabilities } from "./capabilities.ts";
+import { type StreamTurnOptions, type Turn } from "./stream.ts";
+/**
+ * One turn, given as many attempts as the caller allows.
+ *
+ * Two different things are being recovered from here, and they nest. The inner one is a
+ * capability the endpoint turns out not to have — `stream_options`, a grammar keyword — which
+ * is a refusal: it is answered by sending a lesser request, and it latches against that
+ * endpoint for the life of the process, so it costs one failed call rather than one a run.
+ * The outer one is the endpoint being unreachable, busy or silent, which is not about this
+ * request at all and is worth simply waiting out.
+ *
+ * Both are bounded by the same rule: nothing is sent again once the server has started
+ * answering. The tokens are already out and on their way to whoever is watching, and a second
+ * attempt would say everything twice. That is what `produced` is, one box per attempt.
+ */
+/** A retry is not the same event as a downgrade, but a watcher wants to be told about both. */
+export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
+    /**
+     * How many times a lost request is worth sending again. Zero is one attempt, which is the
+     * default because a caller with no retry budget in its settings should not inherit one.
+     * A downgrade does not spend an attempt: it is a different request, not the same one again.
+     */
+    maxRetries?: number;
+    /**
+     * Told what was given up on and what is being waited out, for a watcher who would otherwise
+     * see an unexplained pause. Carries both the capability notices and the retry notices.
+     */
+    onNotice?: (message: string) => void;
+}
+/**
+ * `request` is a callback rather than a body because the body has to be rebuilt from whatever
+ * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
+ * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
+ * object throughout, and a caller that reads those from its own closure can ignore the argument.
+ */
+export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/run-turn.js

@@ -0,0 +1,33 @@
+import { negotiate } from "./capabilities.js";
+import { errorMessage } from "./errors.js";
+import { backoffMs, isTransient, sleep } from "./retry.js";
+import { streamTurn } from "./stream.js";
+/**
+ * `request` is a callback rather than a body because the body has to be rebuilt from whatever
+ * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
+ * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
+ * object throughout, and a caller that reads those from its own closure can ignore the argument.
+ */
+export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, ...stream } = {}) {
+    for (let attempt = 0;; attempt++) {
+        const produced = { any: false };
+        try {
+            return await negotiate(supports, (capabilities, box) => streamTurn(client, request(capabilities), { ...stream, produced: box }), { produced, onNotice });
+        }
+        catch (error) {
+            // The abort is read before the classification, not after. A run stopped by its operator
+            // can trip the idle watchdog on the way out, and `EndpointSilent` is transient by the
+            // rules in `retry.ts` — so classifying first brings a cancelled run back from the dead.
+            if (produced.any || stream.signal?.aborted)
+                throw error;
+            if (attempt >= maxRetries || !isTransient(error))
+                throw error;
+            const wait = backoffMs(attempt);
+            // Reported in whatever unit reads as a number: the first backoff is under a second, and
+            // "retrying in 0s" is what rounding it to seconds says.
+            const delay = wait < 1000 ? `${Math.round(wait)}ms` : `${Math.round(wait / 1000)}s`;
+            onNotice?.(`${errorMessage(error)} — retrying in ${delay} (${attempt + 1}/${maxRetries})`);
+            await sleep(wait, stream.signal);
+        }
+    }
+}

package/dist/stream.d.ts

@@ -21,6 +21,18 @@ export interface Turn {
     toolCalls: OpenAI.ChatCompletionMessageToolCall[];
     usage: TurnUsage;
 }
+/**
+ * Whether the server has started answering.
+ *
+ * A box rather than a return value because it has to be readable *while* the request is in
+ * flight: the rules in `retry.ts` are built on the premise that a stream which has already
+ * emitted tokens must never be replayed, and by the time a rejected promise is in hand the turn
+ * is over. There is one of these per attempt, shared by everything that has a say in whether
+ * the attempt is repeated. See `negotiate`.
+ */
+export interface Produced {
+    any: boolean;
+}
 export interface StreamTurnOptions {
     signal?: AbortSignal;
     /**
@@ -29,15 +41,8 @@ export interface StreamTurnOptions {
      * needs.
      */
     idleMs?: number;
-    /**
-     * Set as soon as the server has said anything, so a failed call knows whether it can be
-     * retried. The rules in `retry.ts` are built on the premise that a stream which has already
-     * emitted tokens must never be replayed, and this is the flag that says so — a caller that
-     * has to thread it by hand is a caller that can forget to.
-     */
-    produced?: {
-        any: boolean;
-    };
+    /** Set as soon as the server has said anything, so a failed call knows if it can be retried. */
+    produced?: Produced;
     /** The model's scratchpad, as it arrives. */
     onThinking?: (delta: string) => void;
     /** The model's answer, as it arrives. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "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",