@inflexa-ai/harness 0.1.1

package/dist/providers/ai-sdk.js

@@ -0,0 +1,142 @@
+import { generateText, streamText } from "ai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { ResultAsync, err, ok } from "neverthrow";
+import { scopeWorkloadId } from "../auth/types.js";
+import { toProviderError } from "./errors.js";
+const DEFAULT_MAX_RETRIES = 2;
+function workloadOf(session) {
+    return `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
+}
+function isAbortError(value) {
+    if (value instanceof DOMException && value.name === "AbortError")
+        return true;
+    if (value instanceof Error && value.name === "AbortError")
+        return true;
+    return false;
+}
+function responseFromMessages(messages, fallbackText, finishReason, rawFinishReason) {
+    const message = [...messages].reverse().find((m) => m.role === "assistant");
+    if (message === undefined) {
+        return {
+            message: { role: "assistant", content: fallbackText },
+            finishReason,
+            rawFinishReason,
+        };
+    }
+    return { message, finishReason, rawFinishReason };
+}
+function responseFromGenerate(result) {
+    return responseFromMessages(result.responseMessages, result.text, result.finishReason, result.rawFinishReason);
+}
+/**
+ * Drop empty text parts — and messages left with no content at all — before
+ * the wire call. The Anthropic Messages API rejects any request containing an
+ * empty text block, and the SDK's own response assembly legitimately produces
+ * them: a turn that goes straight to tool calls yields an assistant message
+ * carrying a ""-text part, which the agent loop then echoes back as history
+ * on its next request. Filtering once at the outbound boundary covers every
+ * source at once — loop echo, stored thread history, legacy backfill, and the
+ * empty-string fallback in `responseFromMessages`.
+ */
+function sanitizeMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (typeof m.content === "string") {
+            if (m.content !== "")
+                out.push(m);
+            continue;
+        }
+        const parts = m.content.filter((p) => p.type !== "text" || p.text !== "");
+        // The filtered parts are a subset of this message's own content, so the
+        // message remains valid for its role — the cast only re-associates the
+        // narrowed array with the union member TS can no longer correlate.
+        if (parts.length > 0)
+            out.push({ ...m, content: parts });
+    }
+    return out;
+}
+export function createAiSdkProvider(deps) {
+    const capabilities = { toolCalling: deps.capabilities?.toolCalling ?? true };
+    function chat(req, session, signal) {
+        const run = async () => {
+            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,
+                });
+                return ok(responseFromGenerate(result));
+            }
+            catch (e) {
+                if (isAbortError(e) || signal?.aborted)
+                    throw e;
+                return err(toProviderError(e, workloadOf(session)));
+            }
+        };
+        return new ResultAsync(run());
+    }
+    async function* chatStream(req, session, signal) {
+        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,
+            });
+            let text = "";
+            for await (const delta of result.textStream) {
+                text += delta;
+                yield { type: "text-delta", text: delta };
+            }
+            const response = responseFromMessages(await result.responseMessages, text, await result.finishReason, await result.rawFinishReason);
+            yield { type: "done", response };
+        }
+        catch (e) {
+            if (isAbortError(e) || signal?.aborted)
+                throw e;
+            throw toProviderError(e, workloadOf(session));
+        }
+    }
+    return { capabilities, chat, chatStream };
+}
+/**
+ * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
+ * connection and model. The model is closed into the returned provider here (it
+ * is never passed per `ChatRequest`), so N models require N provider
+ * instances over one shared connection configuration — one instance serves the
+ * single model it was built with.
+ */
+export function createConfiguredAiSdkProvider(deps) {
+    const config = deps.config;
+    if (config.kind === "anthropic") {
+        const provider = createAnthropic({
+            baseURL: config.baseURL,
+            apiKey: config.apiKey,
+            fetch: config.fetch,
+        });
+        return createAiSdkProvider({ model: provider.chat(config.model), resolveBilling: deps.resolveBilling, capabilities: config.capabilities });
+    }
+    const provider = createOpenAICompatible({
+        name: config.name,
+        baseURL: config.baseURL,
+        apiKey: config.apiKey,
+        fetch: config.fetch,
+    });
+    return createAiSdkProvider({ model: provider.chatModel(config.model), resolveBilling: deps.resolveBilling, capabilities: config.capabilities });
+}

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Compatibility entry point for Anthropic-backed chat.
+ *
+ * The production provider path is AI SDK-backed; this wrapper preserves the
+ * old factory name for embedders while returning the new `ChatProvider` seam.
+ */
+import type { ResolveBilling } from "../billing/resolver.js";
+import type { ChatProvider, FetchLike } from "./types.js";
+export interface AnthropicProviderDeps {
+    readonly baseURL?: string;
+    readonly token: string;
+    readonly model: string;
+    readonly resolveBilling: ResolveBilling;
+    readonly fetch?: FetchLike;
+}
+/**
+ * Convenience over the `anthropic` arm of the public `AiSdkProviderConfig`
+ * union: it takes the Anthropic connection fields directly (`token` as the api
+ * key) and delegates to `createConfiguredAiSdkProvider`. The same construction
+ * contract holds — the `model` is bound into the returned provider.
+ */
+export declare function createAnthropicProvider(deps: AnthropicProviderDeps): ChatProvider;

package/dist/providers/anthropic.js

@@ -0,0 +1,26 @@
+/**
+ * Compatibility entry point for Anthropic-backed chat.
+ *
+ * The production provider path is AI SDK-backed; this wrapper preserves the
+ * old factory name for embedders while returning the new `ChatProvider` seam.
+ */
+import { createConfiguredAiSdkProvider } from "./ai-sdk.js";
+/**
+ * Convenience over the `anthropic` arm of the public `AiSdkProviderConfig`
+ * union: it takes the Anthropic connection fields directly (`token` as the api
+ * key) and delegates to `createConfiguredAiSdkProvider`. The same construction
+ * contract holds — the `model` is bound into the returned provider.
+ */
+export function createAnthropicProvider(deps) {
+    return createConfiguredAiSdkProvider({
+        resolveBilling: deps.resolveBilling,
+        config: {
+            kind: "anthropic",
+            baseURL: deps.baseURL,
+            apiKey: deps.token,
+            model: deps.model,
+            fetch: deps.fetch,
+            capabilities: { toolCalling: true },
+        },
+    });
+}

package/dist/providers/embedding.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Embedding provider.
+ *
+ * The ONLY file in the harness that imports `openai`. The SDK client is
+ * pointed at the billing-gateway base URL; per-call billing headers are assembled
+ * from the `Session`. Embeds with OpenAI `text-embedding-3-small`.
+ */
+import type { ResolveBilling } from "../billing/resolver.js";
+import type { EmbeddingProvider, FetchLike } from "./types.js";
+export interface EmbeddingProviderDeps {
+    /** Billing-gateway base URL — all embedding traffic is routed through it. */
+    readonly baseURL: string;
+    /** API token presented to the billing gateway. */
+    readonly token: string;
+    /** Embedding model id. Defaults to `text-embedding-3-small`. */
+    readonly model?: string;
+    /**
+     * Vector width the configured model emits, advertised on the returned
+     * provider (see {@link EmbeddingProvider.dimensions}). Defaults to the
+     * default model's 1536 — a host wiring a non-default `model` must supply
+     * the matching width or the per-analysis index is created at the wrong size.
+     */
+    readonly dimensions?: number;
+    /** Resolves the billing attribution map at the call site. */
+    readonly resolveBilling: ResolveBilling;
+    /**
+     * `fetch` override. Production omits it (the SDK's default is used);
+     * tests inject a fake to feed a recorded response.
+     */
+    readonly fetch?: FetchLike;
+}
+export declare function createEmbeddingProvider(deps: EmbeddingProviderDeps): EmbeddingProvider;

package/dist/providers/embedding.js

@@ -0,0 +1,42 @@
+/**
+ * Embedding provider.
+ *
+ * The ONLY file in the harness that imports `openai`. The SDK client is
+ * pointed at the billing-gateway base URL; per-call billing headers are assembled
+ * from the `Session`. Embeds with OpenAI `text-embedding-3-small`.
+ */
+import OpenAI from "openai";
+import { ResultAsync, err, ok, okAsync } from "neverthrow";
+import { scopeWorkloadId } from "../auth/types.js";
+import { toProviderError } from "./errors.js";
+const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+/** Vector width of the default model — `text-embedding-3-small` emits 1536-dim vectors. */
+const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+export function createEmbeddingProvider(deps) {
+    const client = new OpenAI({
+        baseURL: deps.baseURL,
+        apiKey: deps.token,
+        ...(deps.fetch ? { fetch: deps.fetch } : {}),
+    });
+    const model = deps.model ?? DEFAULT_EMBEDDING_MODEL;
+    const dimensions = deps.dimensions ?? DEFAULT_EMBEDDING_DIMENSIONS;
+    function embed(texts, session) {
+        if (texts.length === 0)
+            return okAsync([]);
+        const workload = `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
+        const run = async () => {
+            try {
+                const headers = await deps.resolveBilling(session);
+                const response = await client.embeddings.create({ model, input: [...texts], encoding_format: "float" }, { headers });
+                // The API does not guarantee response order; re-key by `index`.
+                const rows = [...response.data].sort((a, b) => a.index - b.index).map((d) => d.embedding);
+                return ok(rows);
+            }
+            catch (e) {
+                return err(toProviderError(e, workload));
+            }
+        };
+        return new ResultAsync(run());
+    }
+    return { embed, dimensions };
+}

package/dist/providers/errors.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Provider error taxonomy.
+ *
+ * Callers (the agent loop, the chat route, DBOS steps) branch on error
+ * origin: a billing-gateway governance rejection is permanent and user-facing; a
+ * transient upstream hiccup is retryable. This module owns the
+ * classification so callers do not re-derive it.
+ *
+ * The billing-gateway convention is status-code driven (no dedicated error header
+ * is required to disambiguate): the gateway emits `402` exclusively for
+ * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
+ * failures (429, 5xx, connection) surface with their own status or as a
+ * network error with no status at all.
+ */
+export type ProviderErrorKind = "budget" | "tenant-blocked" | "provider";
+/**
+ * The provider error value channel — a `DomainError`-conforming
+ * discriminated union mirroring `ProviderErrorKind`. `chat` / `embed` return
+ * `err(ProviderError)` instead of throwing a typed Error; `toProviderError`
+ * is the sole constructor. `cause` carries the original SDK throwable so the
+ * cause-walking classifiers (`isBudgetExceeded`, `classifyProviderError`)
+ * still reach the `status` / `code` signals after `toThrowable` rethrows at a
+ * step boundary.
+ */
+export type ProviderError = {
+    readonly type: "budget";
+    readonly retryable: false;
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
+    readonly type: "tenant-blocked";
+    readonly retryable: false;
+    readonly message: string;
+    readonly cause?: unknown;
+} | {
+    readonly type: "provider";
+    readonly retryable: boolean;
+    readonly message: string;
+    readonly cause?: unknown;
+};
+/**
+ * Structural guard for an already-constructed `ProviderError` value. A
+ * `ProviderError` is a plain object, not an `Error`, so it cannot be
+ * recognized by `instanceof`; this checks the discriminant plus the two
+ * always-present fields. Used by `toProviderError` to stay idempotent.
+ */
+export declare function isProviderError(value: unknown): value is ProviderError;
+/**
+ * Turn a caught SDK throwable into a `ProviderError` value. Routes through
+ * `classifyProviderError` so the `provider` variant's `retryable` keeps the
+ * transient (429 / 5xx / connection) classification. `cause` is the original
+ * throwable verbatim — for the budget variant it MUST be the SDK error
+ * carrying status 402, which is what `isBudgetExceeded` walks.
+ *
+ * Idempotent: `chatStream` throws a `ProviderError` value, which
+ * `streaming-chat`'s `catch` re-wraps by calling this again. Returning an
+ * already-constructed `ProviderError` unchanged stops that second pass from
+ * `String()`-ing the object (a `ProviderError` is not an `Error`) into a
+ * `"[object Object]"` message that would bury the real inner one.
+ */
+export declare function toProviderError(e: unknown, workload: string): ProviderError;
+export interface ProviderErrorClassification {
+    readonly kind: ProviderErrorKind;
+    /**
+     * Whether re-issuing the same call could plausibly succeed. The Anthropic
+     * SDK already retries transient failures internally; a `retryable: true`
+     * classification on an error that still reached here tells the caller the
+     * failure is transient in nature, not that a retry is mandatory.
+     */
+    readonly retryable: boolean;
+}
+/**
+ * Classify a provider failure by origin.
+ *
+ * - Billing-gateway `402` → `budget`, not retryable.
+ * - Billing-gateway `403` → `tenant-blocked`, not retryable.
+ * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
+ * - Other `4xx` and parse / unknown errors → `provider`, not retryable.
+ */
+export declare function classifyProviderError(e: unknown): ProviderErrorClassification;

package/dist/providers/errors.js

@@ -0,0 +1,137 @@
+/**
+ * Provider error taxonomy.
+ *
+ * Callers (the agent loop, the chat route, DBOS steps) branch on error
+ * origin: a billing-gateway governance rejection is permanent and user-facing; a
+ * transient upstream hiccup is retryable. This module owns the
+ * classification so callers do not re-derive it.
+ *
+ * The billing-gateway convention is status-code driven (no dedicated error header
+ * is required to disambiguate): the gateway emits `402` exclusively for
+ * `budget_exceeded` and `403` for a blocked tenant. Provider-originated
+ * failures (429, 5xx, connection) surface with their own status or as a
+ * network error with no status at all.
+ */
+/**
+ * Structural guard for an already-constructed `ProviderError` value. A
+ * `ProviderError` is a plain object, not an `Error`, so it cannot be
+ * recognized by `instanceof`; this checks the discriminant plus the two
+ * always-present fields. Used by `toProviderError` to stay idempotent.
+ */
+export function isProviderError(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (v.type === "budget" || v.type === "tenant-blocked" || v.type === "provider") && typeof v.retryable === "boolean" && typeof v.message === "string";
+}
+/**
+ * Turn a caught SDK throwable into a `ProviderError` value. Routes through
+ * `classifyProviderError` so the `provider` variant's `retryable` keeps the
+ * transient (429 / 5xx / connection) classification. `cause` is the original
+ * throwable verbatim — for the budget variant it MUST be the SDK error
+ * carrying status 402, which is what `isBudgetExceeded` walks.
+ *
+ * Idempotent: `chatStream` throws a `ProviderError` value, which
+ * `streaming-chat`'s `catch` re-wraps by calling this again. Returning an
+ * already-constructed `ProviderError` unchanged stops that second pass from
+ * `String()`-ing the object (a `ProviderError` is not an `Error`) into a
+ * `"[object Object]"` message that would bury the real inner one.
+ */
+export function toProviderError(e, workload) {
+    if (isProviderError(e))
+        return e;
+    const { kind, retryable } = classifyProviderError(e);
+    const detail = e instanceof Error ? e.message : String(e);
+    if (kind === "budget") {
+        return {
+            type: "budget",
+            retryable: false,
+            message: `Billing budget exceeded for ${workload}: ${detail}`,
+            cause: e,
+        };
+    }
+    if (kind === "tenant-blocked") {
+        return {
+            type: "tenant-blocked",
+            retryable: false,
+            message: `Billing gateway blocked tenant for ${workload}: ${detail}`,
+            cause: e,
+        };
+    }
+    return { type: "provider", retryable, message: detail, cause: e };
+}
+/** Max links walked on the `cause` chain looking for a structured status. */
+const MAX_CAUSE_HOPS = 5;
+/** Node/undici error codes that mean "the connection itself failed". */
+const CONNECTION_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const CONNECTION_ERROR_PATTERN = /fetch failed|socket hang up|network error|connection (?:refused|reset|error|closed)|econnrefused|enotfound|etimedout|terminated/i;
+/** Walk the `cause` chain for the first numeric HTTP status. */
+function extractStatus(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const e = cursor;
+        if (typeof e.status === "number")
+            return e.status;
+        if (typeof e.statusCode === "number")
+            return e.statusCode;
+        cursor = e.cause;
+    }
+    return undefined;
+}
+/** Does any link of the `cause` chain look like a transport-level failure? */
+function looksLikeConnectionError(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const e = cursor;
+        if (typeof e.code === "string" && CONNECTION_ERROR_CODES.has(e.code)) {
+            return true;
+        }
+        if (typeof e.name === "string" && /^APIConnection/.test(e.name)) {
+            return true;
+        }
+        if (typeof e.message === "string" && CONNECTION_ERROR_PATTERN.test(e.message)) {
+            return true;
+        }
+        cursor = e.cause;
+    }
+    return false;
+}
+/**
+ * Classify a provider failure by origin.
+ *
+ * - Billing-gateway `402` → `budget`, not retryable.
+ * - Billing-gateway `403` → `tenant-blocked`, not retryable.
+ * - Provider `429` / `5xx` / connection errors → `provider`, retryable.
+ * - Other `4xx` and parse / unknown errors → `provider`, not retryable.
+ */
+export function classifyProviderError(e) {
+    const status = extractStatus(e);
+    if (status === 402)
+        return { kind: "budget", retryable: false };
+    if (status === 403)
+        return { kind: "tenant-blocked", retryable: false };
+    if (status === 429 || (status !== undefined && status >= 500)) {
+        return { kind: "provider", retryable: true };
+    }
+    if (status !== undefined) {
+        // A concrete 4xx (other than 402/403) — the request is wrong; retrying
+        // it unchanged will fail again.
+        return { kind: "provider", retryable: false };
+    }
+    // No status: a transport failure is retryable; anything else (parse
+    // errors, unexpected throws) is not.
+    return {
+        kind: "provider",
+        retryable: looksLikeConnectionError(e),
+    };
+}

package/dist/providers/llm-capabilities.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-model capability gates for harness provider calls.
+ *
+ * The harness `ChatRequest` is a passthrough of `MessageCreateParamsBase`,
+ * so callers already pass per-call overrides (`temperature`, `thinking`,
+ * tool config, …) as native fields. This module is the silent drop-on-reject
+ * gate at the provider edge: model-rejected fields are stripped before they
+ * hit the wire so the call still succeeds (e.g. `acceptsTemperature`).
+ *
+ * Classification is pattern-based on the bare model name (no provider
+ * prefix — the harness `createAnthropicProvider` already knows it is
+ * Anthropic). No network calls, no runtime probing.
+ */
+import type { Message } from "./types.js";
+/**
+ * Anthropic Opus/Sonnet/Haiku 4.7+ reject `temperature` with HTTP 400.
+ * 4.6 and earlier accept it.
+ */
+export declare function anthropicAcceptsTemperature(modelName: string): boolean;
+/**
+ * The model's true maximum output-token ceiling — the `max_tokens` the
+ * Anthropic provider sets per call (the API requires the field). Pattern-
+ * matched on the bare model name (no provider prefix). Ceilings per the
+ * current Anthropic model reference: Opus 4.x → 128K, Sonnet 4.6 → 64K,
+ * Haiku 4.5 → 64K.
+ */
+export declare function maxOutputTokens(modelName: string): number;
+/**
+ * Map an OpenAI `finish_reason` into the Anthropic `stop_reason` the harness
+ * loop branches on (see the harness-providers spec — every provider adapts into Anthropic shape).
+ * The imminent `openai.ts` adapter is the first caller.
+ */
+export declare function mapOpenAiFinishReason(finishReason: string | null): Message["stop_reason"];

package/dist/providers/llm-capabilities.js

@@ -0,0 +1,58 @@
+/**
+ * Per-model capability gates for harness provider calls.
+ *
+ * The harness `ChatRequest` is a passthrough of `MessageCreateParamsBase`,
+ * so callers already pass per-call overrides (`temperature`, `thinking`,
+ * tool config, …) as native fields. This module is the silent drop-on-reject
+ * gate at the provider edge: model-rejected fields are stripped before they
+ * hit the wire so the call still succeeds (e.g. `acceptsTemperature`).
+ *
+ * Classification is pattern-based on the bare model name (no provider
+ * prefix — the harness `createAnthropicProvider` already knows it is
+ * Anthropic). No network calls, no runtime probing.
+ */
+/**
+ * Anthropic Opus/Sonnet/Haiku 4.7+ reject `temperature` with HTTP 400.
+ * 4.6 and earlier accept it.
+ */
+export function anthropicAcceptsTemperature(modelName) {
+    return !/^claude-(opus|sonnet|haiku)-4-([7-9]|\d{2,})\b/.test(modelName.toLowerCase());
+}
+/**
+ * The model's true maximum output-token ceiling — the `max_tokens` the
+ * Anthropic provider sets per call (the API requires the field). Pattern-
+ * matched on the bare model name (no provider prefix). Ceilings per the
+ * current Anthropic model reference: Opus 4.x → 128K, Sonnet 4.6 → 64K,
+ * Haiku 4.5 → 64K.
+ */
+export function maxOutputTokens(modelName) {
+    const name = modelName.toLowerCase();
+    if (/^claude-opus-4-/.test(name))
+        return 128_000;
+    if (/^claude-sonnet-4-/.test(name))
+        return 64_000;
+    if (/^claude-haiku-4-/.test(name))
+        return 64_000;
+    // Unknown model — a generous default broadly accepted by current models;
+    // the loop recovers from truncation, so erring high is cheap.
+    return 32_768;
+}
+/**
+ * Map an OpenAI `finish_reason` into the Anthropic `stop_reason` the harness
+ * loop branches on (see the harness-providers spec — every provider adapts into Anthropic shape).
+ * The imminent `openai.ts` adapter is the first caller.
+ */
+export function mapOpenAiFinishReason(finishReason) {
+    switch (finishReason) {
+        case "length":
+            return "max_tokens";
+        case "tool_calls":
+            return "tool_use";
+        case "stop":
+            return "end_turn";
+        case "content_filter":
+            return "refusal";
+        default:
+            return "end_turn";
+    }
+}

package/dist/providers/streaming-chat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `createStreamingChat` — a streaming `AgentChat`.
+ *
+ * The agent loop depends on `AgentChat`: one request in, one collapsed
+ * `ChatResponse` out. A `ChatProvider` satisfies that directly — its `chat`
+ * collapses the stream silently. This builds a SECOND `AgentChat` from the
+ * same provider's `chatStream` primitive: its `chat` drives the stream,
+ * forwards every text delta to `onText`, and returns the same collapsed
+ * `ChatResponse`. `runAgent` calls `chat` and never knows it streamed.
+ *
+ * The chat route is the one caller — it is the single place token streaming
+ * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
+ * loops run on the plain `ChatProvider`, so they never stream.
+ */
+import type { AgentChat, ChatProvider } from "./types.js";
+/**
+ * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
+ * per text delta, in arrival order, as a side effect of `chat`. `chat` is
+ * Result-returning: it consumes the throwing `chatStream` and maps a thrown
+ * SDK failure to `err(ProviderError)`; a client abort is re-thrown verbatim
+ * (control-flow, never the error channel).
+ */
+export declare function createStreamingChat(provider: ChatProvider, onText: (text: string) => void): AgentChat;

package/dist/providers/streaming-chat.js

@@ -0,0 +1,61 @@
+/**
+ * `createStreamingChat` — a streaming `AgentChat`.
+ *
+ * The agent loop depends on `AgentChat`: one request in, one collapsed
+ * `ChatResponse` out. A `ChatProvider` satisfies that directly — its `chat`
+ * collapses the stream silently. This builds a SECOND `AgentChat` from the
+ * same provider's `chatStream` primitive: its `chat` drives the stream,
+ * forwards every text delta to `onText`, and returns the same collapsed
+ * `ChatResponse`. `runAgent` calls `chat` and never knows it streamed.
+ *
+ * The chat route is the one caller — it is the single place token streaming
+ * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
+ * loops run on the plain `ChatProvider`, so they never stream.
+ */
+import { ResultAsync, err, ok } from "neverthrow";
+import { scopeWorkloadId } from "../auth/types.js";
+import { toProviderError } from "./errors.js";
+/**
+ * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
+ * per text delta, in arrival order, as a side effect of `chat`. `chat` is
+ * Result-returning: it consumes the throwing `chatStream` and maps a thrown
+ * SDK failure to `err(ProviderError)`; a client abort is re-thrown verbatim
+ * (control-flow, never the error channel).
+ */
+export function createStreamingChat(provider, onText) {
+    return {
+        capabilities: provider.capabilities,
+        chat(req, session, signal) {
+            const workload = `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
+            const run = async () => {
+                let final;
+                try {
+                    for await (const event of provider.chatStream(req, session, signal)) {
+                        if (event.type === "text-delta") {
+                            onText(event.text);
+                        }
+                        else {
+                            final = event.response;
+                        }
+                    }
+                }
+                catch (e) {
+                    if (e instanceof DOMException && e.name === "AbortError")
+                        throw e;
+                    if (e instanceof Error && e.name === "AbortError")
+                        throw e;
+                    return err(toProviderError(e, workload));
+                }
+                if (final === undefined) {
+                    return err({
+                        type: "provider",
+                        retryable: false,
+                        message: "createStreamingChat: chatStream ended without a final message",
+                    });
+                }
+                return ok(final);
+            };
+            return new ResultAsync(run());
+        },
+    };
+}