@theoremjs/agents 0.3.1 → 0.3.3

package/esm/src/kernel/turn-events.js

@@ -464,6 +464,7 @@ const TURN_EVENTS = {
             .array(z.object({ id: z.string().regex(/\S/) }))
             .min(1)
             .optional(),
+        released: z.number().int().nonnegative().optional(),
     }),
     tool_draft: z.object({
         type: z.literal('tool_draft'),
@@ -522,10 +523,33 @@ function isReply(event) {
         event.type === 'structured' ||
         event.type === 'structured_draft');
 }
+/**
+ * `reply` with only its first `released` characters of text: the text past them, and every
+ * media and structured output that came after, are a draft the user never got.
+ */
+function cutReply(reply, released) {
+    const out = [];
+    let left = released;
+    for (const event of reply) {
+        if (!isReply(event))
+            out.push(event);
+        else if (event.type !== 'text') {
+            if (left > 0)
+                out.push(event);
+        }
+        else if (left > 0) {
+            const text = event.text.slice(0, left);
+            left -= text.length;
+            out.push(text === event.text ? event : { ...event, text });
+        }
+    }
+    return out;
+}
 /**
  * `events` without the replies a retry threw away: each `attempt` drops the text, media and
- * structured output before it, back to the turn's start or its last `done`. Tool calls, thoughts
- * and everything else stay, since they happened.
+ * structured output before it, back to the turn's start or its last `done`. A `stage` event with
+ * `released` keeps only that much of the reply's text, and drops what followed it. Tool calls,
+ * thoughts and everything else stay, since they happened.
  */
 export function keptReply(events) {
     const kept = [];
@@ -535,6 +559,9 @@ export function keptReply(events) {
             const before = kept.splice(turnStart);
             kept.push(...before.filter((each) => !isReply(each)));
         }
+        if (event.type === 'stage' && event.released !== undefined) {
+            kept.push(...cutReply(kept.splice(turnStart), event.released));
+        }
         kept.push(event);
         if (event.type === 'done')
             turnStart = kept.length;

package/esm/src/observability/trace-catalog.js

@@ -96,7 +96,8 @@ const ERROR_KIND_OPTIONS = {
     },
     rate_limit: { label: 'Rate limit', doc: 'Too many requests, or a quota used up.' },
     unsupported: { label: 'Unsupported', doc: 'The model or route cannot serve this request.' },
-    unavailable: { label: 'Unavailable', doc: 'The provider is down or overloaded.' },
+    busy: { label: 'Busy', doc: 'The provider is up but too busy for the call.' },
+    unavailable: { label: 'Unavailable', doc: 'The provider is down.' },
     bad_response: {
         label: 'Unusable response',
         doc: 'The provider answered with something that cannot be used.',

package/esm/src/providers/gemini/interactions-protocol.js

@@ -1,9 +1,8 @@
 import { z } from 'zod';
-import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
 import { asRecord } from '../../kernel/engine/record.js';
 import { jsonObjectSchema } from '../../kernel/json.js';
 import { defineProtocol, } from '../../kernel/protocols/mod.js';
-import { readGeminiApiError } from '../google/api-error.js';
+import { readGeminiApiError, statedOrStatusError } from '../google/api-error.js';
 import { googleBuiltins } from '../google/builtins.js';
 import { thoughtSignature, toInteractionsBody, } from '../google/interactions/framing.js';
 import { finalizeStructured, foldBody, foldPayload, missingMediaError, newStreamFold, openStepEvents, } from '../google/interactions/stream.js';
@@ -68,10 +67,8 @@ export const geminiInteractions = defineProtocol({
     continuation: { version: 1, schema: state, keyOptions: ['store', 'persistViaInteractionId'] },
     reasoning: thoughtSignature,
     error(failure) {
-        const kind = kindOfHttpStatus(failure.status);
         const record = asRecord(failure.body);
-        const stated = record ? readGeminiApiError(record) : null;
-        return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${failure.status}`);
+        return statedOrStatusError(record ? readGeminiApiError(record) : null, failure.status, `Gemini HTTP ${failure.status}`);
     },
     create(context) {
         return {

package/esm/src/providers/google/api-error.d.ts

@@ -6,3 +6,5 @@ import { TheoremError } from '../../guardrails/error.js';
 export declare function readGeminiApiError(record: Record<string, unknown>): TheoremError | null;
 /** The kind is the HTTP status's, unless the body names a refused key. */
 export declare function readNonOkError(response: Response): Promise<TheoremError>;
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export declare function statedOrStatusError(stated: TheoremError | null, status: number, fallback: string): TheoremError;

package/esm/src/providers/google/api-error.js

@@ -72,13 +72,15 @@ const BLOCKED_CODES = new Set([
  * codes (`malformed_function_call`, `no_image`, …) and any code Google adds later
  * are `bad_response`.
  */
-function kindOfNamedCode(code) {
+function namedCodeError(code, message) {
     if (code === 'cancelled')
-        return 'cancelled';
+        return new TheoremError('cancelled', message);
     if (BLOCKED_CODES.has(code))
-        return 'safety';
+        return new TheoremError('safety', message);
     const status = NAMED_CODE_STATUS[code];
-    return status === undefined ? 'bad_response' : kindOfHttpStatus(status);
+    return status === undefined
+        ? new TheoremError('bad_response', message)
+        : new TheoremError(kindOfHttpStatus(status), message);
 }
 /**
  * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
@@ -90,28 +92,34 @@ export function readGeminiApiError(record) {
         return null;
     }
     const { code, message, status, details } = error;
-    const kind = refusesKey(details)
-        ? 'auth'
-        : typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX
-            ? kindOfHttpStatus(code)
-            : typeof code === 'string'
-                ? kindOfNamedCode(code)
-                : 'bad_response';
-    if (typeof message !== 'string' || message.length === 0) {
-        return new TheoremError(kind, 'Gemini returned an error.');
+    const text = typeof message !== 'string' || message.length === 0
+        ? 'Gemini returned an error.'
+        : typeof status === 'string'
+            ? `${status}: ${message}`
+            : message;
+    if (refusesKey(details))
+        return new TheoremError('auth', text);
+    if (typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX) {
+        return new TheoremError(kindOfHttpStatus(code), text);
     }
-    return new TheoremError(kind, typeof status === 'string' ? `${status}: ${message}` : message);
+    return typeof code === 'string'
+        ? namedCodeError(code, text)
+        : new TheoremError('bad_response', text);
 }
 /** The kind is the HTTP status's, unless the body names a refused key. */
 export async function readNonOkError(response) {
-    const kind = kindOfHttpStatus(response.status);
     const text = await response.text().catch(() => '');
     if (!text.trim()) {
-        return new TheoremError(kind, `HTTP ${response.status}`);
+        return new TheoremError(kindOfHttpStatus(response.status), `HTTP ${response.status}`);
     }
     const parsed = parseRecord(text);
-    const stated = parsed ? readGeminiApiError(parsed) : null;
-    return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${response.status}: ${text}`);
+    return statedOrStatusError(parsed ? readGeminiApiError(parsed) : null, response.status, `Gemini HTTP ${response.status}: ${text}`);
+}
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export function statedOrStatusError(stated, status, fallback) {
+    if (stated?.kind === 'auth')
+        return stated;
+    return new TheoremError(kindOfHttpStatus(status), stated?.message ?? fallback);
 }
 function parseRecord(text) {
     try {

package/esm/src/providers/google/live/stream.js

@@ -8,7 +8,7 @@ const CLOSE_KINDS = {
     1007: 'unsupported',
     1008: 'unsupported',
     1011: 'unavailable',
-    1013: 'unavailable',
+    1013: 'busy',
 };
 /**
  * Google refuses an over-quota Live key with code 1011 (`unavailable`) and a reason

package/esm/src/providers/shared/retry.d.ts

@@ -4,6 +4,7 @@ export type Wait = (ms: number, signal?: AbortSignal | null) => Promise<void>;
 export declare const WAIT_BUDGET_MS = 5000;
 export declare const waitDefault: Wait;
 export declare function isTransientHttp(status: number): boolean;
+/** A rejected send that never got a response: a network failure, by `networkError`'s rule. An abort, a timeout, or any other kind is not. */
 export declare function isTransientThrown(err: unknown): boolean;
 export declare function backoffMs(attempt: number): number;
 /** `retry-after-ms`, else `Retry-After` in seconds or as a date; undefined when absent or unreadable. */

package/esm/src/providers/shared/retry.js

@@ -1,12 +1,12 @@
-import { isAbortError, isTimeoutError } from '../../guardrails/error.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { networkError } from './upstream-tap.js';
 const BACKOFF_MS = [1000, 2000, 4000, 8000];
 /** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
 export const WAIT_BUDGET_MS = 5000;
 /** The most tries after the first: a `Retry-After: 0` costs no wait, so the budget alone never ends it. */
 const MAX_RETRIES = BACKOFF_MS.length;
 const MS_PER_SECOND = 1000;
-const TRANSIENT_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
-const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|connection (?:refused|reset)|error sending request|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
+const TRANSIENT_STATUSES = new Set([408, 429, 500, 502, 503, 504, 529]);
 export const waitDefault = (ms, signal) => new Promise((resolve, reject) => {
     if (signal?.aborted) {
         reject(abortReason(signal));
@@ -28,11 +28,10 @@ function abortReason(signal) {
 export function isTransientHttp(status) {
     return TRANSIENT_STATUSES.has(status);
 }
+/** A rejected send that never got a response: a network failure, by `networkError`'s rule. An abort, a timeout, or any other kind is not. */
 export function isTransientThrown(err) {
-    if (isAbortError(err) || isTimeoutError(err)) {
-        return false;
-    }
-    return TRANSIENT_THROWN_RE.test(String(err));
+    const failure = networkError(err);
+    return failure instanceof TheoremError && failure.kind === 'network';
 }
 export function backoffMs(attempt) {
     return BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",