@inflexa-ai/harness 0.7.2 → 0.8.0

package/dist/providers/ai-sdk.d.ts

@@ -1,10 +1,23 @@
 import { type LanguageModel } from "ai";
 import type { ResolveBilling } from "../billing/resolver.js";
+import type { Logger } from "../lib/logger.js";
 import type { ChatProvider, FetchLike, ProviderCapabilities } from "./types.js";
+/**
+ * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
+ * count: its 2s initial delay and ×2 factor are fixed, it caps neither the
+ * per-attempt delay nor the total, and it ignores a server-named `Retry-After`.
+ * Wrapping each wire attempt in `retryWithExponentialBackoff` with these values
+ * gives a bounded, jittered envelope with a hard per-attempt delay ceiling.
+ */
+export declare const RETRY_MAX_RETRIES = 10;
+export declare const RETRY_INITIAL_DELAY_MS = 2000;
+export declare const RETRY_BACKOFF_FACTOR = 2;
+export declare const RETRY_MAX_DELAY_MS = 30000;
 export interface AiSdkProviderDeps {
     readonly model: LanguageModel;
     readonly resolveBilling: ResolveBilling;
     readonly capabilities?: Partial<ProviderCapabilities>;
+    readonly logger?: Logger;
 }
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
@@ -35,7 +48,17 @@ export type AiSdkProviderConfig = {
 export interface ConfiguredAiSdkProviderDeps {
     readonly config: AiSdkProviderConfig;
     readonly resolveBilling: ResolveBilling;
+    readonly logger?: Logger;
 }
+/**
+ * The delay before the next retry attempt. A server-named `Retry-After` inside
+ * the envelope is honored exactly — the server pointed at a precise time, so
+ * jitter would only fight it. Otherwise apply full jitter over the exponential
+ * delay capped at `RETRY_MAX_DELAY_MS`: full jitter spreads a crowd of callers
+ * that failed at the same instant across the window instead of re-colliding on
+ * the same retry tick. `random` is injectable so the delay is testable.
+ */
+export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDelay: number, random?: () => number): number;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's

package/dist/providers/ai-sdk.js

@@ -1,10 +1,23 @@
 import { generateText, streamText } from "ai";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { APICallError } from "@ai-sdk/provider";
+import { retryWithExponentialBackoff } from "@ai-sdk/provider-utils";
 import { ResultAsync, err, ok } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
-import { toProviderError } from "./errors.js";
-const DEFAULT_MAX_RETRIES = 2;
+import { createNoopLogger } from "../lib/console-logger.js";
+import { classifyProviderError, toProviderError } from "./errors.js";
+/**
+ * The harness-owned retry envelope. The AI SDK's built-in retry exposes only a
+ * count: its 2s initial delay and ×2 factor are fixed, it caps neither the
+ * per-attempt delay nor the total, and it ignores a server-named `Retry-After`.
+ * Wrapping each wire attempt in `retryWithExponentialBackoff` with these values
+ * gives a bounded, jittered envelope with a hard per-attempt delay ceiling.
+ */
+export const RETRY_MAX_RETRIES = 10;
+export const RETRY_INITIAL_DELAY_MS = 2_000;
+export const RETRY_BACKOFF_FACTOR = 2;
+export const RETRY_MAX_DELAY_MS = 30_000;
 function workloadOf(session) {
     return `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
 }
@@ -15,6 +28,153 @@ function isAbortError(value) {
         return true;
     return false;
 }
+/**
+ * Locate an `APICallError` on the throwable itself or one hop down its `cause`.
+ * A wire failure the SDK raises is an `APICallError` directly; once rewrapped it
+ * sits on the wrapper's `cause`, which is as deep as a `Retry-After` header is
+ * ever carried.
+ */
+function apiCallErrorOf(error) {
+    if (APICallError.isInstance(error))
+        return error;
+    const cause = error?.cause;
+    if (APICallError.isInstance(cause))
+        return cause;
+    return undefined;
+}
+/** Case-insensitive header lookup; `name` must already be lowercase. */
+function headerValue(headers, name) {
+    if (headers === undefined)
+        return undefined;
+    const direct = headers[name];
+    if (direct !== undefined)
+        return direct;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name)
+            return value;
+    }
+    return undefined;
+}
+/** Parse a header to a finite number, or `undefined` when it is not numeric. */
+function finiteNumber(value) {
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * The delay a server named via `Retry-After`, in ms, or `undefined` when none
+ * applies. `retry-after-ms` is float ms; `retry-after` is float seconds or an
+ * HTTP date read relative to now. A value outside `[0, RETRY_MAX_DELAY_MS]` is
+ * treated as absent so the jittered exponential delay governs instead — this
+ * envelope does not honor a wait longer than its own ceiling verbatim.
+ */
+function serverNamedDelayMs(error) {
+    const headers = apiCallErrorOf(error)?.responseHeaders;
+    if (headers === undefined)
+        return undefined;
+    let ms;
+    const retryAfterMs = headerValue(headers, "retry-after-ms");
+    if (retryAfterMs !== undefined)
+        ms = finiteNumber(retryAfterMs);
+    if (ms === undefined) {
+        const retryAfter = headerValue(headers, "retry-after");
+        if (retryAfter !== undefined) {
+            const seconds = finiteNumber(retryAfter);
+            if (seconds !== undefined) {
+                ms = seconds * 1_000;
+            }
+            else {
+                const at = Date.parse(retryAfter);
+                if (Number.isFinite(at))
+                    ms = at - Date.now();
+            }
+        }
+    }
+    if (ms === undefined || ms < 0 || ms > RETRY_MAX_DELAY_MS)
+        return undefined;
+    return ms;
+}
+/**
+ * The delay before the next retry attempt. A server-named `Retry-After` inside
+ * the envelope is honored exactly — the server pointed at a precise time, so
+ * jitter would only fight it. Otherwise apply full jitter over the exponential
+ * delay capped at `RETRY_MAX_DELAY_MS`: full jitter spreads a crowd of callers
+ * that failed at the same instant across the window instead of re-colliding on
+ * the same retry tick. `random` is injectable so the delay is testable.
+ */
+export function computeRetryDelayMs(error, exponentialBackoffDelay, random = Math.random) {
+    const named = serverNamedDelayMs(error);
+    if (named !== undefined)
+        return named;
+    return random() * Math.min(exponentialBackoffDelay, RETRY_MAX_DELAY_MS);
+}
+/**
+ * Marks a failure that came from the `ResolveBilling` seam rather than the model
+ * wire. The retry envelope's budget is sized for model-provider outages; the
+ * billing seam is a separate system whose failure must surface immediately, not
+ * after a multi-minute retry window — even when the underlying failure is
+ * connection-shaped and would otherwise read as retryable. The original throwable
+ * rides on `cause` so the outer catch can hand it to `toProviderError` unchanged
+ * and classify it byte-identically to a billing failure raised outside the
+ * envelope (right down to the surfaced message).
+ */
+class BillingSeamFailure extends Error {
+    constructor(cause) {
+        super("billing resolution failed", { cause });
+        this.name = "BillingSeamFailure";
+    }
+}
+/**
+ * Resolve attribution headers for one attempt, tagging any non-abort failure as
+ * a `BillingSeamFailure` so the retry envelope fails fast on it. An abort is
+ * rethrown raw so it stays on the abort control-flow path.
+ */
+async function resolveBillingHeaders(resolveBilling, session) {
+    try {
+        return await resolveBilling(session);
+    }
+    catch (e) {
+        if (isAbortError(e))
+            throw e;
+        throw new BillingSeamFailure(e);
+    }
+}
+/** Unwrap a billing-seam failure to the original throwable for classification. */
+function unwrapForClassification(e) {
+    return e instanceof BillingSeamFailure ? e.cause : e;
+}
+/**
+ * Wrap a single wire attempt in the harness retry envelope. Built per call so
+ * the caller's `AbortSignal` reaches the primitive: it rethrows abort errors
+ * without retrying and cancels its own backoff sleep when the signal fires, so
+ * the retried closure adds no abort handling of its own. `shouldRetry` defers to
+ * the harness retryability taxonomy — but never retries a `BillingSeamFailure`,
+ * whose fail-fast is the whole point of the marker — and a non-retried first
+ * failure is rethrown untouched, preserving the exact throwable the outer catch
+ * classifies. `createRetryError` carries the last real failure on `cause` so
+ * that, once retries are exhausted, `toProviderError`'s status walk reaches the
+ * true HTTP status instead of stopping at a synthetic wrapper. The attempt
+ * counter is per-instance because each call builds its own retry.
+ */
+function createRetry(signal, logger) {
+    let retryCount = 0;
+    return retryWithExponentialBackoff({
+        maxRetries: RETRY_MAX_RETRIES,
+        initialDelayInMs: RETRY_INITIAL_DELAY_MS,
+        backoffFactor: RETRY_BACKOFF_FACTOR,
+        abortSignal: signal,
+        shouldRetry: (e) => !(e instanceof BillingSeamFailure) && classifyProviderError(e).retryable,
+        getDelayInMs: ({ error, exponentialBackoffDelay }) => {
+            const delayMs = computeRetryDelayMs(error, exponentialBackoffDelay);
+            retryCount += 1;
+            logger.debug("retrying provider call", { attempt: retryCount, delayMs, ...logger.errorFields(error) });
+            return delayMs;
+        },
+        createRetryError: ({ message, errors }) => new Error(message, { cause: errors[errors.length - 1] }),
+    });
+}
 /**
  * Map AI SDK token accounting onto the harness's neutral `ChatUsage`.
  *
@@ -85,51 +245,101 @@ function sanitizeMessages(messages) {
 }
 export function createAiSdkProvider(deps) {
     const capabilities = { toolCalling: deps.capabilities?.toolCalling ?? true };
+    const logger = (deps.logger ?? createNoopLogger()).named("providers.ai-sdk");
     function chat(req, session, signal) {
         const run = async () => {
+            const retry = createRetry(signal, logger);
             try {
-                const headers = await deps.resolveBilling(session);
-                const result = await generateText({
-                    model: deps.model,
-                    system: req.system,
-                    messages: sanitizeMessages(req.messages),
-                    tools: req.tools,
-                    toolChoice: req.toolChoice ?? "auto",
-                    stopWhen: [],
-                    maxRetries: DEFAULT_MAX_RETRIES,
-                    headers,
-                    abortSignal: signal,
-                    providerOptions: req.providerOptions,
+                const result = await retry(async () => {
+                    // Attribution headers are time-limited; resolving them inside the
+                    // retried closure keeps them fresh across a multi-minute window.
+                    const headers = await resolveBillingHeaders(deps.resolveBilling, session);
+                    return generateText({
+                        model: deps.model,
+                        system: req.system,
+                        messages: sanitizeMessages(req.messages),
+                        tools: req.tools,
+                        toolChoice: req.toolChoice ?? "auto",
+                        stopWhen: [],
+                        // The harness envelope owns retries; leaving the SDK default in
+                        // place would multiply attempts (10 outer × 3 inner).
+                        maxRetries: 0,
+                        headers,
+                        abortSignal: signal,
+                        providerOptions: req.providerOptions,
+                    });
                 });
                 return ok(responseFromGenerate(result));
             }
             catch (e) {
                 if (isAbortError(e) || signal?.aborted)
                     throw e;
-                return err(toProviderError(e, workloadOf(session)));
+                return err(toProviderError(unwrapForClassification(e), workloadOf(session)));
             }
         };
         return new ResultAsync(run());
     }
     async function* chatStream(req, session, signal) {
+        const retry = createRetry(signal, logger);
         try {
-            const headers = await deps.resolveBilling(session);
-            const result = streamText({
-                model: deps.model,
-                system: req.system,
-                messages: sanitizeMessages(req.messages),
-                tools: req.tools,
-                toolChoice: req.toolChoice ?? "auto",
-                stopWhen: [],
-                maxRetries: DEFAULT_MAX_RETRIES,
-                headers,
-                abortSignal: signal,
-                providerOptions: req.providerOptions,
+            // Retry covers only stream establishment: streamText defers wire errors
+            // to consumption, so a failure is not visible until the stream is read.
+            // The retried closure resolves to one of two outcomes — the stream is
+            // live with a first delta in hand, or it finished without yielding any
+            // text — and a delta is only ever yielded OUTSIDE the closure, so a
+            // retried attempt can never re-emit a delta the consumer already saw.
+            // Resolving billing inside the closure keeps attribution headers fresh
+            // per attempt.
+            const opened = await retry(async () => {
+                const headers = await resolveBillingHeaders(deps.resolveBilling, session);
+                const result = streamText({
+                    model: deps.model,
+                    system: req.system,
+                    messages: sanitizeMessages(req.messages),
+                    tools: req.tools,
+                    toolChoice: req.toolChoice ?? "auto",
+                    stopWhen: [],
+                    maxRetries: 0,
+                    headers,
+                    abortSignal: signal,
+                    providerOptions: req.providerOptions,
+                });
+                const iterator = result.textStream[Symbol.asyncIterator]();
+                const first = await iterator.next();
+                if (first.done) {
+                    // A doStream promise rejection — the shape a real connection
+                    // failure takes — does NOT surface at this first pull: streamText
+                    // resolves it `{ done: true }` and defers the rejection to the
+                    // deferred result promises. Awaiting them here brings that failure
+                    // inside the retry envelope so a text-less establishment error is
+                    // retried; a genuine text-less turn resolves them, and the terminal
+                    // event is built from these already-resolved values without a
+                    // second await. (These promises only settle once the stream is
+                    // fully drained, so they can be awaited here only because the first
+                    // pull already reported the stream done.)
+                    return {
+                        kind: "completed",
+                        messages: await result.responseMessages,
+                        finishReason: await result.finishReason,
+                        rawFinishReason: await result.rawFinishReason,
+                        usage: await result.usage,
+                    };
+                }
+                return { kind: "streaming", result, iterator, firstDelta: first.value };
             });
-            let text = "";
-            for await (const delta of result.textStream) {
-                text += delta;
-                yield { type: "text-delta", text: delta };
+            if (opened.kind === "completed") {
+                const response = responseFromMessages(opened.messages, "", opened.finishReason, opened.rawFinishReason, opened.usage);
+                yield { type: "done", response };
+                return;
+            }
+            const { result, iterator, firstDelta } = opened;
+            let text = firstDelta;
+            yield { type: "text-delta", text: firstDelta };
+            // Drain the same iterator: past the first delta, errors propagate
+            // unchanged (no retry, no re-emit).
+            for (let next = await iterator.next(); !next.done; next = await iterator.next()) {
+                text += next.value;
+                yield { type: "text-delta", text: next.value };
             }
             const response = responseFromMessages(await result.responseMessages, text, await result.finishReason, await result.rawFinishReason, await result.usage);
             yield { type: "done", response };
@@ -137,7 +347,7 @@ export function createAiSdkProvider(deps) {
         catch (e) {
             if (isAbortError(e) || signal?.aborted)
                 throw e;
-            throw toProviderError(e, workloadOf(session));
+            throw toProviderError(unwrapForClassification(e), workloadOf(session));
         }
     }
     return { capabilities, chat, chatStream };
@@ -157,7 +367,12 @@ export function createConfiguredAiSdkProvider(deps) {
             apiKey: config.apiKey,
             fetch: config.fetch,
         });
-        return createAiSdkProvider({ model: provider.chat(config.model), resolveBilling: deps.resolveBilling, capabilities: config.capabilities });
+        return createAiSdkProvider({
+            model: provider.chat(config.model),
+            resolveBilling: deps.resolveBilling,
+            capabilities: config.capabilities,
+            logger: deps.logger,
+        });
     }
     const provider = createOpenAICompatible({
         name: config.name,
@@ -165,5 +380,10 @@ export function createConfiguredAiSdkProvider(deps) {
         apiKey: config.apiKey,
         fetch: config.fetch,
     });
-    return createAiSdkProvider({ model: provider.chatModel(config.model), resolveBilling: deps.resolveBilling, capabilities: config.capabilities });
+    return createAiSdkProvider({
+        model: provider.chatModel(config.model),
+        resolveBilling: deps.resolveBilling,
+        capabilities: config.capabilities,
+        logger: deps.logger,
+    });
 }

package/dist/providers/anthropic.d.ts

@@ -5,6 +5,7 @@
  * old factory name for embedders while returning the new `ChatProvider` seam.
  */
 import type { ResolveBilling } from "../billing/resolver.js";
+import type { Logger } from "../lib/logger.js";
 import type { ChatProvider, FetchLike } from "./types.js";
 export interface AnthropicProviderDeps {
     readonly baseURL?: string;
@@ -12,6 +13,7 @@ export interface AnthropicProviderDeps {
     readonly model: string;
     readonly resolveBilling: ResolveBilling;
     readonly fetch?: FetchLike;
+    readonly logger?: Logger;
 }
 /**
  * Convenience over the `anthropic` arm of the public `AiSdkProviderConfig`

package/dist/providers/anthropic.js

@@ -14,6 +14,7 @@ import { createConfiguredAiSdkProvider } from "./ai-sdk.js";
 export function createAnthropicProvider(deps) {
     return createConfiguredAiSdkProvider({
         resolveBilling: deps.resolveBilling,
+        logger: deps.logger,
         config: {
             kind: "anthropic",
             baseURL: deps.baseURL,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.7.2",
+    "version": "0.8.0",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -47,6 +47,7 @@
         "@ai-sdk/anthropic": "^4.0.15",
         "@ai-sdk/openai-compatible": "^3.0.10",
         "@ai-sdk/provider": "^4.0.3",
+        "@ai-sdk/provider-utils": "5.0.10",
         "@anthropic-ai/sdk": "^0.107.0",
         "@dbos-inc/dbos-sdk": "^4.23.6",
         "@kubernetes/client-node": "^1.4.0",