@cubicecho/agent-core 2.2.1 → 2.2.3

package/README.md

@@ -46,7 +46,7 @@ the exports rather than a second description of them; CI fails if the committed
 
 `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.
+and nothing is re-sent once the model has started answering.
 
 ```ts
 import {
@@ -116,9 +116,12 @@ OpenAI and `gpt-4o` behind a proxy need not be the same weights, and one that re
 effort must not speak for the other.
 
 `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.
+flags. `produced` is one box per attempt — `streamTurn` sets it on the first chunk that carries
+text, reasoning or a piece of a tool call, 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. The content-free `{"role":"assistant"}` most servers open a stream with
+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.
 
 `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

package/dist/retry.d.ts

@@ -33,10 +33,11 @@ export declare const compact: (tokens: number) => string;
  * built the entire transcript into a string on every call and threw it away having read nothing
  * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which the envelope constants put back — one per key rather than one per message, since the
- * three keys only some shapes carry are most of what a tool-using transcript is made of. What
- * is left is a message's escaping, which is not a constant and is small against an estimate
- * that is already characters over four.
+ * which the envelope constants put back — one per key and one per content part, rather than one
+ * per message, since the keys only some shapes carry and the parts a client appends block by
+ * block are most of what a tool-using transcript is made of. What is left is a message's
+ * escaping, which is not a constant and is small against an estimate that is already characters
+ * over four.
  *
  * @param body The request as it will be sent, tools included.
  */

package/dist/retry.js

@@ -40,6 +40,14 @@ const NAME_KEY = 10;
 const TOOL_CALL_ID_KEY = 18;
 /** The same for `"tool_calls":[]` around the calls; each call's own comma is in `CALL_ENVELOPE`. */
 const TOOL_CALLS_KEY = 15;
+// A content part is an object in the body the same way a message is, and its two keys are in the
+// request exactly as `tool_call_id` was. Charging only `part.text` left them out, which is 6.5
+// tokens per part — short in proportion to how finely the content is split rather than to how
+// much it says, so a transcript a client appends block by block is worst hit.
+/** What `{"type":"text","text":""},` costs around a text part. */
+const TEXT_PART = 26;
+/** The same for `{"type":"refusal","refusal":""},` around a refusal part. */
+const REFUSAL_PART = 32;
 /** The divisor behind `estimateTokens`, applied here to a character count rather than a string. */
 const CHARS_PER_TOKEN = 4;
 /** How many characters one message is worth: its keys, and its content in whichever shape. */
@@ -51,11 +59,13 @@ function messageChars(message) {
     else if (Array.isArray(content))
         for (const part of content) {
             // Text and refusal parts carry their own strings; an image or an audio part carries a URL
-            // or a blob, and neither is priced by its length anyway.
+            // or a blob, and neither is priced by its length anyway — a vision model does not charge
+            // an image by its base64 length, so counting the data URL would overshoot by more than
+            // leaving the part out undershoots.
             if (part.type === "text")
-                chars += part.text.length;
+                chars += TEXT_PART + part.text.length;
             else if (part.type === "refusal")
-                chars += part.refusal.length;
+                chars += REFUSAL_PART + part.refusal.length;
         }
     if ("name" in message && typeof message.name === "string")
         chars += NAME_KEY + message.name.length;
@@ -105,10 +115,11 @@ function toolsCost(tools) {
  * built the entire transcript into a string on every call and threw it away having read nothing
  * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
  * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which the envelope constants put back — one per key rather than one per message, since the
- * three keys only some shapes carry are most of what a tool-using transcript is made of. What
- * is left is a message's escaping, which is not a constant and is small against an estimate
- * that is already characters over four.
+ * which the envelope constants put back — one per key and one per content part, rather than one
+ * per message, since the keys only some shapes carry and the parts a client appends block by
+ * block are most of what a tool-using transcript is made of. What is left is a message's
+ * escaping, which is not a constant and is small against an estimate that is already characters
+ * over four.
  *
  * @param body The request as it will be sent, tools included.
  */

package/dist/run-turn.d.ts

@@ -12,9 +12,11 @@ import { type StreamTurnOptions, type Turn } from "./stream.ts";
  * 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
+ * Both are bounded by the same rule: nothing is sent again once the model 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.
+ * attempt would say everything twice. That is what `produced` is, one box per attempt — set by
+ * a chunk that carried something rather than by a chunk arriving, so the empty opening chunk
+ * most servers send does not cost the retry.
  */
 /** 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"> {

package/dist/stream.d.ts

@@ -22,13 +22,19 @@ export interface Turn {
     usage: TurnUsage;
 }
 /**
- * Whether the server has started answering.
+ * Whether the model has said anything a second attempt would say twice.
  *
  * 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`.
+ *
+ * What sets it is a chunk that carried something — text, reasoning, or a piece of a tool call —
+ * rather than a chunk arriving. Those read as the same sentence until a server puts an empty
+ * chunk between them, and most of them do: a stream usually opens with a content-free
+ * `{"role":"assistant"}` that shows nobody anything, and a turn that latched on it could never
+ * be retried however early it then died.
  */
 export interface Produced {
     any: boolean;
@@ -43,7 +49,7 @@ export interface StreamTurnOptions {
      * needs.
      */
     idleMs?: number;
-    /** Set as soon as the server has said anything, so a failed call knows if it can be retried. */
+    /** Set by the first chunk that carries anything, so a failed call knows if it can be retried. */
     produced?: Produced;
     /** The model's scratchpad, as it arrives. */
     onThinking?: (delta: string) => void;

package/dist/stream.js

@@ -52,8 +52,8 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
         const calls = new Map();
         const usage = { prompt: 0, completion: 0, total: 0 };
         for await (const chunk of stream) {
-            if (produced)
-                produced.any = true;
+            // Rearmed on every chunk, latched below on only some: a priming chunk is the endpoint
+            // being alive, which is all the watchdog is asking about.
             rearm();
             // Assigned rather than accumulated. `stream_options.include_usage` sends one final chunk
             // and the two agree there, but a server that reports cumulatively per chunk makes a sum
@@ -68,6 +68,15 @@ export async function streamTurn(client, body, { signal, idleMs, produced, onThi
             if (!delta)
                 continue;
             const thinking = delta.reasoning_content || delta.reasoning || "";
+            // Latched on what the chunk carried, not on its having arrived. Most OpenAI-compatible
+            // servers open a stream with a content-free `{"role":"assistant"}` before the first
+            // token; latching on that made an endpoint that primes and then wedges unrepeatable,
+            // which is exactly the case the watchdog raises `EndpointSilent` for. Tool-call
+            // fragments count even though no callback reports them: a partial call is state the turn
+            // has accumulated, and losing a retry is the safer half of that trade. Set before the
+            // callbacks, so a watcher that throws mid-token cannot be told the same token twice.
+            if (produced && (thinking || delta.content || delta.tool_calls?.length))
+                produced.any = true;
             if (thinking)
                 onThinking?.(thinking);
             if (delta.content) {

package/llms.txt

@@ -115,7 +115,7 @@ One-shot calls that support a run without being one: picking tools, naming a ses
 
 Reading one streamed turn back into a message.
 
-- `Produced` (type) — Whether the server has started answering.
+- `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.
 - `Turn` (type) — One streamed turn, put back together into the shape a loop and a transcript work with.

package/package.json

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