@cubicecho/agent-core 4.17.0 → 4.18.0

package/README.md

@@ -213,6 +213,11 @@ is worth another attempt. The content-free `{"role":"assistant"}` most servers o
 does not set it: nothing has been shown to anybody yet, so an endpoint that primes the stream and
 then wedges is retried like one that never answered at all.
 
+`inFlight` is the other box `streamTurn` takes, for what an attempt had said once it has thrown:
+each call sets its `read` as it starts, so after a retry it reads the attempt that failed last and
+nothing of the one before. `runTurn` and `continueTurn` pass it through, the second with the
+answer it is continuing joined on, and `runAgentLoop` reads it into a failure's `partial`.
+
 `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
@@ -946,7 +951,7 @@ try {
       store.add(sessionId, turn?.reasoning ? { ...message, reasoning_content: turn.reasoning } : message),
   });
 } catch (error) {
-  const run = failedRun(error); // messages, usage, toolCalls, loaded, used, preselected — or undefined
+  const run = failedRun(error); // messages, partial, usage, toolCalls, loaded, used, preselected — or undefined
   if (run) await store.keep(sessionId, { usage: run.usage, loaded: run.loaded });
   if (signal.aborted) return; // a stop, told by the signal as it always was
   if (error instanceof ContextOverflow) return compactAndRetry(run?.messages);
@@ -973,9 +978,14 @@ A failure while a step's tools are running leaves a transcript that can be sent
 that came back are kept, a call the run was stopped during is answered `Stopped before this call
 finished.`, and one the loop never reached `Not run: the run stopped first.` — a call with no
 result is a transcript an endpoint refuses. Those are announced through `onMessage` like any other
-result. The reply of a request that was in flight when the run stopped is not kept: the host has
-the deltas from its `output` and `thinking` events, and whether half an answer belongs in the
-history is its call.
+result. The reply of a request that was in flight when the run stopped or failed — a stop, the
+endpoint going silent, a stream that broke after its first token — is not in `messages`, because it
+is not a turn an endpoint will take back. It is on the failure as `partial`: its `content`, its
+`reasoning` and the `toolCalls` it had begun, assembled as far as they had arrived, with a
+continuation's piece joined onto the answer it was continuing and, after a retry, only the attempt
+that was in flight. A request that had said nothing leaves no `partial`, and neither does a
+failure while the tools run, since that step's reply is already in `messages`. Whether half an
+answer belongs in the history is the host's call.
 
 `resolveApiKey` is exported and not applied, because which key an endpoint gets is a rule a
 consumer states and a library guessing it could send one where it was not meant to go. The rule

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { type RunTurnOptions, runTurn } from './turn/run-turn.ts';
 export { type AskJsonOptions, ask, askJson, askReply, clean, listLines, parseJson, resetHints, type SideTask, type SideTaskInput, type SideTaskOptions, type SideTaskReply, taskCall, tryAsk, } from './turn/side-task.ts';
 export { AgentLoopError, type AgentLoopFailure, AgentLoopOverflow, errorMessage, failedRun, ToolIterationLimit, } from './wire/errors.ts';
 export { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, SMALLEST_LIKELY_WINDOW, } from './wire/retry.ts';
-export { CacheBreakReason, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
+export { CacheBreakReason, type InFlight, type PartialTurn, type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from './wire/stream.ts';
 export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, SPLIT_OUTPUT, SPLIT_REASONING, type Split, stripThinking, THINK_FENCE, } from './wire/thinking.ts';
 export { type ContextBreakdown, type ContextBreakdownOptions, compact, contextChars, contextTokens, estimateTokens, messageTokens, requestChars, requestTokens, type TokenEstimateOptions, } from './wire/tokens.ts';
 export { ARGUMENTS_MALFORMED, ARGUMENTS_TRUNCATED, type EndedBy, parseToolArguments, type ResourceLink, type RunArtifact, recoverToolCalls, type ServerLogEntry, ServerLogLevel, type ToolAnswer, ToolArgumentsError, type ToolCall, type ToolCallOutcome, type ToolCallReport, type ToolCallRequest, type ToolCallResult, } from './wire/tool-calls.ts';

package/dist/run/agent-loop.d.ts

@@ -577,7 +577,8 @@ export interface AgentLoopResult {
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
  * and `preselected` — because the steps before a failure were real and a host that stores its
- * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * transcript has nothing else to store them from. What the request in flight had said is on it
+ * as `partial`, and not in `messages`. A spent budget is a `ToolIterationLimit`, an
  * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript

package/dist/run/agent-loop.js

@@ -77,7 +77,8 @@ function cacheDiagnosis(previous, next, usage) {
  * @remarks
  * What it throws carries the run as it stood — `messages`, `usage`, `toolCalls`, `loaded`, `used`
  * and `preselected` — because the steps before a failure were real and a host that stores its
- * transcript has nothing else to store them from. A spent budget is a `ToolIterationLimit`, an
+ * transcript has nothing else to store them from. What the request in flight had said is on it
+ * as `partial`, and not in `messages`. A spent budget is a `ToolIterationLimit`, an
  * overflow is an `AgentLoopOverflow`, which is still a `ContextOverflow`, and anything else is an
  * `AgentLoopError` with what was caught as its `cause` and its message as its own; `failedRun`
  * reads the run off any of the three. A failure while a step's tools run leaves the transcript
@@ -630,16 +631,23 @@ async function runSteps(options, standing, pin) {
     let usage = noUsage();
     const toolCalls = [];
     const artifacts = new Map();
-    standing.read = () => ({
-        messages,
-        usage,
-        toolCalls,
-        artifacts: [...artifacts.values()],
-        // As the result would have said it: proxied, nothing is loaded that the history does not hold.
-        loaded: proxied ? [] : [...loaded],
-        used: [...used],
-        preselected: [...preselected],
-    });
+    // A box per request, emptied once its turn is in `messages`: a failure while the tools run had
+    // no request in flight.
+    let inFlight = {};
+    standing.read = () => {
+        const partial = inFlight.read?.();
+        return {
+            messages,
+            ...(partial ? { partial } : {}),
+            usage,
+            toolCalls,
+            artifacts: [...artifacts.values()],
+            // As the result would have said it: proxied, nothing is loaded that the history does not hold.
+            loaded: proxied ? [] : [...loaded],
+            used: [...used],
+            preselected: [...preselected],
+        };
+    };
     const announce = announcer(onMessage);
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
     // moves the question without losing it — and one that summarises the question away takes the
@@ -764,8 +772,10 @@ async function runSteps(options, standing, pin) {
             ...withContext(messages, questionAt(), gathered.context, preface),
         ];
         const build = (supported, refused) => buildBody(sending, supported, refused, request, declared, toolOrder);
+        inFlight = {};
         const turnOptions = {
             model: config.model,
+            inFlight,
             droppable: Object.keys(extraBody ?? {}),
             ...(pin ? { headers: pin.headers } : {}),
             maxRetries,
@@ -819,6 +829,7 @@ async function runSteps(options, standing, pin) {
         const turn = maxContinuations > 0
             ? await continueTurn(client, supports, build, first, { ...turnOptions, maxContinuations })
             : first;
+        inFlight = {};
         previous = {
             messages: request,
             tools: names,

package/dist/turn/continuation.d.ts

@@ -62,6 +62,8 @@ export declare const isContinuable: (turn: Turn) => boolean;
  * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
  * 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.
+ * already in hand are worth more than the error; only a stop is thrown. An `inFlight` box reads
+ * the answer so far with the continuation's piece joined on, so a stop mid-continuation keeps it
+ * all.
  */
 export declare function continueTurn(client: OpenAI, supports: Capabilities, request: RequestBuilder, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;

package/dist/turn/continuation.js

@@ -97,6 +97,22 @@ function joinUsage(first, next) {
     }
     return joined;
 }
+/**
+ * The answer so far with the piece a continuation in flight had added to it.
+ *
+ * @param sofar - The turn being continued, which may itself be a joined one. Not written to.
+ * @param [piece] - What the continuation had said. Absent adds nothing.
+ * @returns The two joined as `continueTurn` joins turns: content and reasoning in order, and the
+ * continuation's own calls. `reasoning` and `toolCalls` are left out where empty.
+ */
+function joinPartial(sofar, piece) {
+    const reasoning = sofar.reasoning + (piece?.reasoning ?? '');
+    return {
+        content: sofar.content + (piece?.content ?? ''),
+        ...(reasoning ? { reasoning } : {}),
+        ...(piece?.toolCalls ? { toolCalls: piece.toolCalls } : {}),
+    };
+}
 /**
  * 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.
@@ -124,17 +140,28 @@ function joinUsage(first, next) {
  * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
  * 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.
+ * already in hand are worth more than the error; only a stop is thrown. An `inFlight` box reads
+ * the answer so far with the continuation's piece joined on, so a stop mid-continuation keeps it
+ * all.
  */
 export async function continueTurn(client, supports, request, turn, { maxContinuations = 1, ...options } = {}) {
     const refused = options.model === undefined ? undefined : modelCapabilitiesFor(supports, options.model);
     const who = modelLabel(options.model);
+    // The caller's box reads the whole answer, not only the piece the continuation streams.
+    const outer = options.inFlight;
+    const piece = {};
+    const told = outer ? { inFlight: piece } : {};
     let joined = turn;
     for (let count = 0; count < maxContinuations && isContinuable(joined); count++) {
         if (refused?.assistantPrefill === false) {
             break;
         }
         const answer = joined.content;
+        if (outer) {
+            const sofar = joined;
+            piece.read = undefined;
+            outer.read = () => joinPartial(sofar, piece.read?.());
+        }
         let next;
         try {
             next = await runTurn(client, supports, (capabilities, forModel) => {
@@ -143,7 +170,7 @@ export async function continueTurn(client, supports, request, turn, { maxContinu
                     ...body,
                     messages: [...body.messages, { role: Role.Assistant, content: answer }],
                 };
-            }, { ...options, startInReasoning: false });
+            }, { ...options, ...told, startInReasoning: false });
         }
         catch (error) {
             if (options.signal?.aborted) {

package/dist/wire/errors.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from 'openai';
 import { ContextOverflow } from './retry.ts';
-import type { TurnUsage } from './stream.ts';
+import type { PartialTurn, TurnUsage } from './stream.ts';
 import type { RunArtifact, ToolCallOutcome } from './tool-calls.ts';
 /**
  * What went wrong, as a string.
@@ -27,9 +27,19 @@ export interface AgentLoopFailure {
     /**
      * The transcript, as the result's `messages` would have been: every assistant turn and tool
      * result the run added, and no system prompt. Well-formed — a call the run was stopped during
-     * has a result saying so. The reply of a request that was in flight is not in it.
+     * has a result saying so. The reply of a request that was in flight is not in it: see `partial`.
      */
     messages: OpenAI.ChatCompletionMessageParam[];
+    /**
+     * What the request in flight had said when the run stopped or failed — a stop, the endpoint
+     * going silent, a stream that broke — continuations joined on. Absent where no request was in
+     * flight or it had said nothing.
+     *
+     * @remarks
+     * Not in `messages`, because it is not a turn an endpoint will take back. It is what a person
+     * watching had been shown, and whether it belongs in the history is the host's call.
+     */
+    partial?: PartialTurn;
     /** Summed over the turns that came back. A request that failed or was stopped adds nothing. */
     usage: TurnUsage;
     /** Every call that was made, in order. One the run was stopped during is `ok: false`. */
@@ -59,6 +69,7 @@ export interface AgentLoopFailure {
 export declare class AgentLoopError extends Error implements AgentLoopFailure {
     readonly name: string;
     readonly messages: OpenAI.ChatCompletionMessageParam[];
+    readonly partial?: PartialTurn;
     readonly usage: TurnUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];
@@ -93,6 +104,7 @@ export declare class ToolIterationLimit extends AgentLoopError {
  */
 export declare class AgentLoopOverflow extends ContextOverflow implements AgentLoopFailure {
     readonly messages: OpenAI.ChatCompletionMessageParam[];
+    readonly partial?: PartialTurn;
     readonly usage: TurnUsage;
     readonly toolCalls: ToolCallOutcome[];
     readonly artifacts: RunArtifact[];

package/dist/wire/errors.js

@@ -24,6 +24,7 @@ export const errorMessage = (error) => (error instanceof Error ? error.message :
 export class AgentLoopError extends Error {
     name = 'AgentLoopError';
     messages;
+    partial;
     usage;
     toolCalls;
     artifacts;
@@ -38,6 +39,9 @@ export class AgentLoopError extends Error {
     constructor(message, run, options) {
         super(message, options);
         this.messages = run.messages;
+        if (run.partial) {
+            this.partial = run.partial;
+        }
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
         this.artifacts = run.artifacts ?? [];
@@ -67,6 +71,7 @@ export class ToolIterationLimit extends AgentLoopError {
  */
 export class AgentLoopOverflow extends ContextOverflow {
     messages;
+    partial;
     usage;
     toolCalls;
     artifacts;
@@ -81,6 +86,9 @@ export class AgentLoopOverflow extends ContextOverflow {
     constructor(message, run, options) {
         super(message, options);
         this.messages = run.messages;
+        if (run.partial) {
+            this.partial = run.partial;
+        }
         this.usage = run.usage;
         this.toolCalls = run.toolCalls;
         this.artifacts = run.artifacts ?? [];

package/dist/wire/stream.d.ts

@@ -213,6 +213,39 @@ export interface Turn {
 export interface Produced {
     any: boolean;
 }
+/**
+ * What a turn had said when it ended without coming back: the answer, the scratchpad and the calls,
+ * as far as each had arrived.
+ *
+ * @remarks
+ * It is not a `Turn`, and not a message an endpoint will take back: it has no usage, no reason it
+ * ended, and a call in it may stop mid-JSON. It is what a person watching had been shown, for a
+ * host to keep or to show.
+ */
+export interface PartialTurn {
+    /** The answer so far, fences taken out; `""` where it had not begun. */
+    content: string;
+    /** The scratchpad so far, from its own field or a fence. Absent where none had arrived. */
+    reasoning?: string;
+    /**
+     * The calls begun, assembled as `Turn.toolCalls` would have been — a name may be missing and
+     * arguments may stop mid-JSON. Absent where none had begun.
+     */
+    toolCalls?: ToolCall[];
+}
+/**
+ * Where the request in flight can be read from, after it has thrown.
+ *
+ * @remarks
+ * A box for the reason `Produced` is one: a rejected promise carries no stream state, and the
+ * error is often the signal's reason, which is shared by every run under it. Each `streamTurn`
+ * sets `read` as it starts, so after a retry or a downgrade it reads the latest attempt and
+ * nothing of the one before.
+ */
+export interface InFlight {
+    /** What the stream had said, or `undefined` where it had said nothing. */
+    read?: () => PartialTurn | undefined;
+}
 /** What `streamTurn` takes besides the request body. */
 export interface StreamTurnOptions {
     /** Cancels the request and the stream being read from it. */
@@ -235,6 +268,11 @@ export interface StreamTurnOptions {
     firstChunkMs?: number;
     /** Set by the first chunk that carries anything, so a failed call knows if it can be retried. */
     produced?: Produced;
+    /**
+     * Given a `read` of what this call has said so far, as the call starts. Read it once the call has
+     * thrown; a turn that came back has it all, and the box is not cleared.
+     */
+    inFlight?: InFlight;
     /**
      * The fences that mark a scratchpad written into `content`.
      *
@@ -282,4 +320,4 @@ export interface StreamTurnOptions {
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
  */
-export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, fences, startInReasoning, onThinking, onOutput, headers, }?: StreamTurnOptions): Promise<Turn>;
+export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, inFlight, fences, startInReasoning, onThinking, onOutput, headers, }?: StreamTurnOptions): Promise<Turn>;

package/dist/wire/stream.js

@@ -188,6 +188,25 @@ function assembledCalls(calls) {
 }
 /** The largest delay a timer takes, which is as close to none as the SDK's timeout option goes. */
 const NO_SDK_TIMEOUT = 2_147_483_647;
+/**
+ * A partial turn from what a stream had put together, or nothing where it had put nothing.
+ *
+ * @param content - The answer so far.
+ * @param reasoning - The scratchpad so far.
+ * @param calls - The calls begun, as they arrived. Not written to.
+ * @returns `undefined` where all three are empty; otherwise the content, with `reasoning` and
+ * `toolCalls` only where they hold something.
+ */
+function partialTurn(content, reasoning, calls) {
+    if (content === '' && reasoning === '' && calls.length === 0) {
+        return undefined;
+    }
+    return {
+        content,
+        ...(reasoning ? { reasoning } : {}),
+        ...(calls.length ? { toolCalls: assembledCalls(calls) } : {}),
+    };
+}
 /**
  * Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a
  * message.
@@ -208,7 +227,7 @@ const NO_SDK_TIMEOUT = 2_147_483_647;
  * which run it is: `step` is the caller's flow concept, and wrapping these into an `emit` is one
  * line at the call site.
  */
-export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, fences = DEFAULT_FENCES, startInReasoning, onThinking, onOutput, headers, } = {}) {
+export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, inFlight, fences = DEFAULT_FENCES, startInReasoning, onThinking, onOutput, headers, } = {}) {
     // Silence, not duration: 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 talking does not
     // hang the run until someone notices. A request that never answers at all is the same case
@@ -229,6 +248,10 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
             idle = setTimeout(() => watchdog.abort(), ms);
         }
     };
+    if (inFlight) {
+        // Before the request, so a box an earlier attempt filled reads nothing of it.
+        inFlight.read = () => undefined;
+    }
     try {
         rearm(false);
         const started = Date.now();
@@ -271,6 +294,11 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
         // In arrival order, sorted by index at the end; a call from a server that sent none keeps
         // its place in the order they arrived.
         const calls = [];
+        if (inFlight) {
+            // Lazy, so a stream nobody stops pays nothing for it. Text held back as a possible tag is
+            // left out: it is a few characters that may yet be a marker.
+            inFlight.read = () => partialTurn(splitter.output, reasoning.join('') + splitter.reasoning, calls);
+        }
         const usage = noUsage();
         // The usage block's own cache count wins over llama.cpp's, which is the same number in the
         // servers that send both; kept apart so the order the two arrive in does not decide.

package/llms.txt

@@ -387,6 +387,8 @@ Everything about a request failing that is not about what the request said.
 Reading one streamed turn back into a message.
 
 - `CacheBreakReason` — Any one of the reasons in `CacheBreakReason`.
+- `InFlight` (type) — Where the request in flight can be read from, after it has thrown.
+- `PartialTurn` (type) — What a turn had said when it ended without coming back: the answer, the scratchpad and the calls, as far as each had arrived.
 - `Produced` (type) — Whether the model has said anything a second attempt would say twice.
 - `StreamTurnOptions` (type) — What `streamTurn` takes besides the request body.
 - `streamTurn` — Runs one turn as a stream, reporting tokens as they arrive and assembling them back into a message.

package/package.json

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