@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -1,9 +1,11 @@
-import { type LanguageModel } from "ai";
+import { type LanguageModelUsage, type ProviderMetadata } from "ai";
+import { type LanguageModelV4 } from "@ai-sdk/provider";
+import { type RetryFunction } from "@ai-sdk/provider-utils";
 import { type AgentSession } from "../auth/types.js";
 import type { Logger } from "../lib/logger.js";
 import { type ProviderError, type SuspendOn } from "./errors.js";
 import { type ResolveRequestHeaders } from "./request-headers.js";
-import type { ChatProvider, FetchLike, ProviderCapabilities, ProviderOptions, ReasoningPolicy } from "./types.js";
+import type { ChatProvider, ChatUsage, ModelRetry, ProviderCapabilities, ProviderOptions, ReasoningPolicy } 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
@@ -32,17 +34,17 @@ export declare const RETRY_MAX_DELAY_MS = 30000;
  */
 export declare const DEFAULT_MAX_OUTPUT_TOKENS = 64000;
 /** With no `suspendOn`, a provider uses {@link DEFAULT_SUSPEND_ON}. */
-export interface ProviderHostPolicy {
+export type ProviderHostPolicy = {
     readonly resolveRequestHeaders?: ResolveRequestHeaders;
     readonly suspendOn?: SuspendOn;
-}
+};
 /** The call facts that `providerOptionsFor` uses to build provider options. */
-export interface ProviderCall {
+export type ProviderCall = {
     readonly session: AgentSession;
     readonly reasoning: ReasoningPolicy;
-}
-export interface AiSdkProviderDeps extends ProviderHostPolicy {
-    readonly model: LanguageModel;
+};
+export type AiSdkProviderDeps = ProviderHostPolicy & {
+    readonly model: LanguageModelV4;
     readonly capabilities?: Partial<ProviderCapabilities>;
     readonly logger?: Logger;
     /**
@@ -56,47 +58,45 @@ export interface AiSdkProviderDeps extends ProviderHostPolicy {
     /** The retry limit of the harness envelope. Defaults to {@link RETRY_MAX_RETRIES}. */
     readonly maxRetries?: number;
     /**
-     * The bound for each silent interval of a request attempt, in milliseconds.
-     * The provider hands the value to the SDK as the bound for each gap between
-     * two content chunks of a stream. The value also names itself in the error of
-     * a stream that the bound stopped. When the field is absent, the provider
-     * hands the SDK no bound.
+     * The bound for each silent interval of a request attempt, in milliseconds:
+     * the wait for the first content part, and each gap between two content
+     * parts. The value also names itself in the error of an attempt that the
+     * bound stopped. When the field is absent, the provider bounds nothing.
      */
     readonly requestTimeoutMs?: number;
-    /** Fallback effort when a request sets none. Defaults to {@link DEFAULT_REASONING}. */
+    /** Fallback effort when a run sets none. Defaults to {@link DEFAULT_REASONING}. */
     readonly reasoning?: ReasoningPolicy;
     /**
-     * Builds provider options once per call, before the retry envelope, so
+     * Builds provider options once per run, before the retry envelope, so
      * every attempt reuses the same options.
      */
     readonly providerOptionsFor?: (call: ProviderCall) => ProviderOptions | undefined;
-}
+};
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
  * wire protocol (`anthropic` | `openai` | `openai-compatible`). The `model` is the wire
- * model bound into the provider at construction: `ChatRequest` carries no model
- * field (see `./types.ts`), so a config value describes exactly one model over
- * one connection. An embedder running distinct models builds one provider per
- * model from configs that share the connection (same `baseURL`/`apiKey`) and
- * differ only in `model` — a single provider cannot be retargeted to another
- * model per request.
+ * model bound into the provider at construction, so a config value describes
+ * exactly one model over one connection. An embedder running distinct models
+ * builds one provider per model from configs that share the connection (same
+ * `baseURL`/`apiKey`) and differ only in `model`.
  */
 export type AiSdkProviderConfig = {
     readonly kind: "anthropic";
     readonly baseURL?: string;
     readonly apiKey: string;
     readonly model: string;
-    readonly fetch?: FetchLike;
+    readonly fetch?: typeof fetch;
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
     /**
      * The bound for each silent interval of a request attempt, in
-     * milliseconds. The value bounds the wait until the response starts, and
-     * each gap between two content chunks of a stream, per attempt. A chunk
-     * that carries no content, for example a keep-alive comment, does not
-     * reset the gap bound. When the field is absent, the provider installs no
-     * guard, and its behavior does not change.
+     * milliseconds. The value bounds the wait until the response starts, the
+     * wait for the first content part, and each gap between two content
+     * parts, per attempt. A chunk that carries no content, for example a
+     * keep-alive comment, does not reset the gap bound. When the field is
+     * absent, the provider installs no guard, and its behavior does not
+     * change.
      *
      * The harness lifts the transport floor of Bun: the guard adds
      * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
@@ -111,7 +111,7 @@ export type AiSdkProviderConfig = {
      * keeps the default of 10.
      */
     readonly maxRetries?: number;
-    /** Fallback effort when a request sets none. Defaults to {@link DEFAULT_REASONING}. */
+    /** Fallback effort when a run sets none. Defaults to {@link DEFAULT_REASONING}. */
     readonly reasoning?: ReasoningPolicy;
     /**
      * How the API handles a signed thinking block whose prefix changed.
@@ -123,7 +123,7 @@ export type AiSdkProviderConfig = {
     readonly baseURL?: string;
     readonly apiKey: string;
     readonly model: string;
-    readonly fetch?: FetchLike;
+    readonly fetch?: typeof fetch;
     readonly capabilities?: Partial<ProviderCapabilities>;
     /**
      * Output-token ceiling per request. An unset value sends no ceiling, and
@@ -134,11 +134,12 @@ export type AiSdkProviderConfig = {
     readonly maxOutputTokens?: number;
     /**
      * The bound for each silent interval of a request attempt, in
-     * milliseconds. The value bounds the wait until the response starts, and
-     * each gap between two content chunks of a stream, per attempt. A chunk
-     * that carries no content, for example a keep-alive comment, does not
-     * reset the gap bound. When the field is absent, the provider installs no
-     * guard, and its behavior does not change.
+     * milliseconds. The value bounds the wait until the response starts, the
+     * wait for the first content part, and each gap between two content
+     * parts, per attempt. A chunk that carries no content, for example a
+     * keep-alive comment, does not reset the gap bound. When the field is
+     * absent, the provider installs no guard, and its behavior does not
+     * change.
      *
      * The harness lifts the transport floor of Bun: the guard adds
      * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
@@ -153,7 +154,7 @@ export type AiSdkProviderConfig = {
      * keeps the default of 10.
      */
     readonly maxRetries?: number;
-    /** Fallback effort when a request sets none. Defaults to {@link DEFAULT_REASONING}. */
+    /** Fallback effort when a run sets none. Defaults to {@link DEFAULT_REASONING}. */
     readonly reasoning?: ReasoningPolicy;
     /**
      * NOTICE: this value is the retention directive of the Responses wire.
@@ -193,17 +194,25 @@ export type AiSdkProviderConfig = {
     readonly baseURL: string;
     readonly apiKey?: string;
     readonly model: string;
-    readonly fetch?: FetchLike;
+    readonly fetch?: typeof fetch;
     readonly capabilities?: Partial<ProviderCapabilities>;
+    /**
+     * The endpoint takes a tool message whose content is a list of parts, for example a text part and an
+     * image part. The standard wire takes a string only, thus the package then sends a tool result as
+     * JSON text. Set the flag only for a backend that takes the parts. It also asserts `imageToolResults`,
+     * which `capabilities` can override.
+     */
+    readonly supportsMultiPartToolContent?: boolean;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
     /**
      * The bound for each silent interval of a request attempt, in
-     * milliseconds. The value bounds the wait until the response starts, and
-     * each gap between two content chunks of a stream, per attempt. A chunk
-     * that carries no content, for example a keep-alive comment, does not
-     * reset the gap bound. When the field is absent, the provider installs no
-     * guard, and its behavior does not change.
+     * milliseconds. The value bounds the wait until the response starts, the
+     * wait for the first content part, and each gap between two content
+     * parts, per attempt. A chunk that carries no content, for example a
+     * keep-alive comment, does not reset the gap bound. When the field is
+     * absent, the provider installs no guard, and its behavior does not
+     * change.
      *
      * The harness lifts the transport floor of Bun: the guard adds
      * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
@@ -218,13 +227,13 @@ export type AiSdkProviderConfig = {
      * keeps the default of 10.
      */
     readonly maxRetries?: number;
-    /** Fallback effort when a request sets none. Defaults to {@link DEFAULT_REASONING}. */
+    /** Fallback effort when a run sets none. Defaults to {@link DEFAULT_REASONING}. */
     readonly reasoning?: ReasoningPolicy;
 };
-export interface ConfiguredAiSdkProviderDeps extends ProviderHostPolicy {
+export type ConfiguredAiSdkProviderDeps = ProviderHostPolicy & {
     readonly config: AiSdkProviderConfig;
     readonly logger?: Logger;
-}
+};
 /**
  * Identifiers only, never a name or address. The run frame wins over the
  * thread so parallel steps of one run keep separate gateway cache accounts.
@@ -236,6 +245,31 @@ export declare function sessionKeyOf(session: Pick<AgentSession, "scope" | "runF
  * non-retryable 400.
  */
 export declare function sessionKeyDigestOf(session: Pick<AgentSession, "scope" | "runFrame">): string;
+/**
+ * The model that answered after a server-side fallback hop, `""` when the hop is
+ * reported without one, and `undefined` when no hop happened.
+ *
+ * A model can refuse a request by category — a biology prompt is one such category —
+ * and the API then re-serves it on another model. It reports the hop TWICE: as a
+ * `fallback` content block inside the assistant turn, and on
+ * `providerMetadata.anthropic.iterations`. `@ai-sdk/anthropic` keeps only the second,
+ * because the AI SDK has no part for a model hop, and it drops the block from the
+ * content it returns (`anthropic-messages-language-model`, the `content_block_start`
+ * case). Thus the turn the harness holds is not the turn the API produced, and every
+ * signed thinking block of that turn is rejected from the next request on.
+ *
+ * The API holds the whole turn against the signature of each of its thinking blocks, so
+ * echoing that turn earns `thinking ... blocks in the latest assistant message cannot be
+ * modified`, which is a 400 that no retry can pass. A thinking block is optional on the
+ * way back, thus the loop records the reply of a hop with no thinking block, and the next
+ * request continues. The cost is the reasoning of this one turn and the cache write that
+ * its new prefix pays for.
+ *
+ * The response metadata of the package carries `message_start.message.model`, and that
+ * field keeps the REQUESTED model across a hop. The iteration names the model that
+ * answered, thus it wins for the usage record.
+ */
+export declare function fallbackModelOf(metadata: ProviderMetadata | undefined): string | undefined;
 /**
  * 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
@@ -252,9 +286,9 @@ export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDe
  * this flag marks the rejection: it stays set when the hook call of the attempt
  * did not settle as a value.
  */
-export interface HookCall {
+export type HookCall = {
     unsettled: boolean;
-}
+};
 /** A refusal of the hook throws `HeadersRefused`. */
 export declare function headersForAttempt(hook: ResolveRequestHeaders | undefined, session: AgentSession, call: HookCall): Promise<Record<string, string>>;
 export declare function failureOf(e: unknown, workload: string, suspendOn: SuspendOn): ProviderError;
@@ -276,7 +310,26 @@ export declare function failureOf(e: unknown, workload: string, suspendOn: Suspe
  * timeout. Without this guard the envelope would loop an expiry that the caller
  * itself declared.
  */
-export declare function createRetry(signal: AbortSignal | undefined, logger: Logger, maxRetries: number, suspendOn: SuspendOn, hookCall: HookCall): import("@ai-sdk/provider-utils").RetryFunction;
+export declare function createRetry(signal: AbortSignal | undefined, logger: Logger, maxRetries: number, suspendOn: SuspendOn, hookCall: HookCall, onRetry?: (retry: ModelRetry) => void): RetryFunction;
+/**
+ * Map AI SDK token accounting onto the harness's neutral `ChatUsage`.
+ *
+ * The cache breakdown rides on the SDK's *vendor-neutral* `inputTokenDetails`,
+ * not in `providerMetadata` — both installed providers normalize into it:
+ * `@ai-sdk/anthropic` maps `cache_read_input_tokens` → `cacheReadTokens` and
+ * `cache_creation_input_tokens` → `cacheWriteTokens`, and
+ * `@ai-sdk/openai-compatible` maps `prompt_tokens_details.cached_tokens` →
+ * `cacheReadTokens` (it never reports a write — that family caches
+ * server-side, with no billed write step). Reading the neutral field is
+ * therefore both correct and vendor-agnostic.
+ *
+ * `inputTokens` is the total billed prefix, cache reads included.
+ *
+ * `reasoningTokens` rides the neutral `outputTokenDetails` beside the text
+ * count and is copied verbatim: providers disagree on whether reasoning tokens
+ * are already inside the output total, so the harness reconciles nothing.
+ */
+export declare function toChatUsage(usage: LanguageModelUsage | undefined): ChatUsage | undefined;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
 /**
  * Wrap a fetch so that the wait until the response starts does not exceed
@@ -287,28 +340,26 @@ export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvid
  * signal through `AbortSignal.any`. Thus the caller signal keeps its normal
  * effect, and a caller abort stays a cancellation.
  *
- * The guard bounds the response start only. The SDK bounds each later gap of a
- * streamed body with its own `chunkMs` setting, thus no timer of the wrapper
- * survives the headers. Thus a stream with steady content does not trip the
- * guard, whatever its total length. One fetch call is one attempt, because the
- * SDK retries are off, thus the window is per attempt.
+ * The guard bounds the response start only. The retry envelope bounds each later
+ * gap of a streamed body, thus no timer of the wrapper survives the headers. One
+ * fetch call is one attempt, because the SDK retries are off, thus the window is
+ * per attempt.
  *
  * When the field is absent, `createConfiguredAiSdkProvider` installs no wrapper,
  * and the behavior stays byte-identical.
  */
-export declare function wrapFetchWithRequestTimeout(fetchImpl: FetchLike, requestTimeoutMs: number): FetchLike;
+export declare function wrapFetchWithRequestTimeout(fetchImpl: typeof fetch, requestTimeoutMs: number): typeof fetch;
 export declare function hostPolicyOf(deps: ProviderHostPolicy): ProviderHostPolicy;
 /**
  * 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.
+ * connection and model. The model is closed into the returned provider here, so
+ * N models require N provider instances over one shared connection
+ * configuration — one instance serves the single model it was built with.
  *
  * When the config sets `requestTimeoutMs`, the provider wraps the effective fetch
- * (`config.fetch ?? globalThis.fetch`) with the response-start guard, it hands
- * the value to the stream call as the SDK chunk bound, and it advertises the
- * value on the returned instance. When the field is absent, it installs no
- * wrapper, it hands the SDK no bound, and it advertises no value.
+ * (`config.fetch ?? globalThis.fetch`) with the response-start guard, the retry
+ * envelope bounds each later silent interval with the same value, and the
+ * provider advertises the value on the returned instance. When the field is
+ * absent, it installs no wrapper, it bounds nothing, and it advertises no value.
  */
 export declare function createConfiguredAiSdkProvider(deps: ConfiguredAiSdkProviderDeps): ChatProvider;