agents 0.24.0 → 0.25.0

package/dist/{tasks-V2lCT8ZV.d.ts → tasks-9YxYtByh.d.ts}

@@ -4,7 +4,7 @@ import {
   o as MemoryLimitContext,
   s as LifecycleCapability,
   v as LifecycleJobOutcome
-} from "./capability-runner-BUBa6Ake.js";
+} from "./capability-runner-DBAnGr6L.js";
 
 //#region src/tasks/duration.d.ts
 /**
@@ -514,4 +514,4 @@ export {
   TaskWaitReason as x,
   TaskStepConfig as y
 };
-//# sourceMappingURL=tasks-V2lCT8ZV.d.ts.map
+//# sourceMappingURL=tasks-9YxYtByh.d.ts.map

package/dist/transport-PfFnt-Ld.d.ts

@@ -0,0 +1,525 @@
+//#region src/models/core/catalog.d.ts
+/**
+ * Keys of the ambient `AiModels` interface (from `@cloudflare/workers-types`)
+ * whose model type extends `T`. Kept in step with the installed workers-types
+ * version rather than hand-maintained here.
+ */
+type WorkersAIModelIdsExtending<T> = {
+  [K in keyof AiModels]: AiModels[K] extends T ? K : never;
+}[keyof AiModels];
+/** The `inputs` shape a catalog entry declares. */
+type InputsOf<K extends keyof AiModels> = AiModels[K] extends {
+  inputs: infer I;
+}
+  ? I
+  : never;
+/** The `postProcessedOutputs` shape a catalog entry declares. */
+type OutputsOf<K extends keyof AiModels> = AiModels[K] extends {
+  postProcessedOutputs: infer O;
+}
+  ? O
+  : never;
+/**
+ * Catalog keys whose input takes a required `messages` array — every current
+ * chat model. Newer entries get their own generated class rather than
+ * extending `BaseAiTextGeneration`, so the base-class arm alone misses them.
+ */
+type ChatCatalogId = {
+  [K in keyof AiModels]: Extract<
+    InputsOf<K>,
+    {
+      messages: unknown;
+    }
+  > extends never
+    ? never
+    : K;
+}[keyof AiModels];
+/**
+ * Catalog keys that take text and answer with embedding vectors. Both halves
+ * matter: the input test alone also matches translation, classification and
+ * speech models, which take `text` but return something else entirely.
+ */
+type EmbeddingCatalogId = {
+  [K in keyof AiModels]: Extract<
+    InputsOf<K>,
+    {
+      text: unknown;
+    }
+  > extends never
+    ? never
+    : Extract<
+          OutputsOf<K>,
+          {
+            data?: number[][];
+          }
+        > extends never
+      ? never
+      : K;
+}[keyof AiModels];
+/**
+ * Catalog keys that take audio to transcribe. The `audio` key is required on
+ * every speech-recognition input and on no other input shape, so the test is
+ * exact rather than heuristic.
+ */
+type TranscriptionCatalogId = {
+  [K in keyof AiModels]: Extract<
+    InputsOf<K>,
+    {
+      audio: unknown;
+    }
+  > extends never
+    ? never
+    : K;
+}[keyof AiModels];
+/**
+ * Catalog keys that score a list of contexts against a query — rerankers.
+ * `contexts` is required on exactly those inputs.
+ */
+type RerankingCatalogId = {
+  [K in keyof AiModels]: Extract<
+    InputsOf<K>,
+    {
+      contexts: unknown;
+    }
+  > extends never
+    ? never
+    : K;
+}[keyof AiModels];
+/**
+ * A Workers AI model id.
+ *
+ * Workers AI is the one catalog this package keeps up with, so this is the
+ * only id shape it accepts: `@cf/<author>/<model>`. Autocomplete covers the
+ * text-generation catalog from the installed `@cloudflare/workers-types`; the
+ * template arm keeps every other `@cf/` slug assignable, because the catalog
+ * lives server-side and moves independently of these types.
+ *
+ * Third-party models are not ids here — they are model objects built by their
+ * own provider package and routed through AI Gateway.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type WorkersAIModelId =
+  | Extract<
+      | ChatCatalogId
+      | Exclude<
+          WorkersAIModelIdsExtending<BaseAiTextGeneration>,
+          WorkersAIModelIdsExtending<BaseAiTextToImage>
+        >,
+      `@cf/${string}`
+    >
+  | (`@cf/${string}` & {});
+/**
+ * A text-embedding model id accepted by `ai.embedding()`.
+ *
+ * The modality methods are Workers AI only — there is no vendor route for them
+ * — so, like {@link WorkersAIModelId}, they take `@cf/` ids and nothing else.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareEmbeddingModelId =
+  | Extract<
+      EmbeddingCatalogId | WorkersAIModelIdsExtending<BaseAiTextEmbeddings>,
+      `@cf/${string}`
+    >
+  | (`@cf/${string}` & {});
+/**
+ * Workers AI text-to-image ids that the generated `AiModels` entries do not
+ * classify as {@link BaseAiTextToImage} — the newer partner models get their
+ * own generated class instead. Curated for autocomplete only; the catalog
+ * lives server-side and any slug is accepted.
+ *
+ * The FLUX.2 family (`flux-2-dev`, `flux-2-klein-4b`, `flux-2-klein-9b`) is
+ * deliberately absent, for the reason {@link UnsupportedTranscriptionId}
+ * records for the Deepgram recognisers: its generated input takes a required
+ * `multipart` object body (`{ multipart: { body, contentType } }`) and no
+ * `prompt`, which the JSON run path cannot carry — live, the run path answers
+ * `400 Bad input: required properties at "/" are 'multipart'`. Suggesting an
+ * id that always 400s is worse than not suggesting it.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type KnownImageModelId =
+  | "@cf/black-forest-labs/flux-1-schnell"
+  | "@cf/leonardo/lucid-origin"
+  | "@cf/leonardo/phoenix-1.0";
+/**
+ * An image model id accepted by `ai.image()`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareImageModelId =
+  | Extract<
+      WorkersAIModelIdsExtending<BaseAiTextToImage> | KnownImageModelId,
+      `@cf/${string}`
+    >
+  | (`@cf/${string}` & {});
+/**
+ * Workers AI text-to-speech ids without a {@link BaseAiTextToSpeech} entry.
+ * Curated for autocomplete only.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type KnownSpeechModelId =
+  | "@cf/deepgram/aura-1"
+  | "@cf/deepgram/aura-2-en"
+  | "@cf/deepgram/aura-2-es";
+/**
+ * A text-to-speech model id accepted by `ai.speech()`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareSpeechModelId =
+  | Extract<
+      WorkersAIModelIdsExtending<BaseAiTextToSpeech> | KnownSpeechModelId,
+      `@cf/${string}`
+    >
+  | (`@cf/${string}` & {});
+/**
+ * Deepgram's recognition models want the audio as an object body
+ * (`audio: { body, contentType }`) rather than as base64, which the JSON run
+ * path cannot carry — every documented variant answered `400` live. They stay
+ * out of the suggested arm, and the transcription model answers a clear error
+ * for them.
+ */
+type UnsupportedTranscriptionId = "@cf/deepgram/nova-3" | "@cf/deepgram/flux";
+/**
+ * A speech-recognition model id accepted by `ai.transcription()`.
+ *
+ * Deepgram's recognition models (`@cf/deepgram/nova-3`, `@cf/deepgram/flux`)
+ * are deliberately not suggested: the run path rejects their documented input
+ * shape, so this provider answers a clear error for them rather than a 400.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareTranscriptionModelId =
+  | Extract<
+      | Exclude<TranscriptionCatalogId, UnsupportedTranscriptionId>
+      | Exclude<
+          WorkersAIModelIdsExtending<BaseAiAutomaticSpeechRecognition>,
+          UnsupportedTranscriptionId
+        >,
+      `@cf/${string}`
+    >
+  | (`@cf/${string}` & {});
+/**
+ * A reranking model id accepted by `ai.reranking()`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareRerankingModelId =
+  | Extract<RerankingCatalogId, `@cf/${string}`>
+  | (`@cf/${string}` & {});
+//#endregion
+//#region src/models/core/settings.d.ts
+/**
+ * AI Gateway settings for a request. The gateway is an option, not a separate
+ * product: every call goes through one, and `id` defaults to `"default"`,
+ * which Cloudflare creates on first use.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface GatewayOptions {
+  /** Gateway id. Defaults to `"default"` (auto-created on first use). */
+  id?: string;
+  /** Bypass the cache for this request. */
+  skipCache?: boolean;
+  /** Cache lifetime in seconds. */
+  cacheTtl?: number;
+  /** Explicit cache key, instead of the request-derived one. */
+  cacheKey?: string;
+  /** Whether the gateway stores the request/response in its log. */
+  collectLog?: boolean;
+  /** Arbitrary key/values attached to the gateway log entry. */
+  metadata?: Record<string, string | number | boolean | null>;
+  /** Correlates several requests into one gateway event. */
+  eventId?: string;
+  /** Upstream request timeout in milliseconds. */
+  requestTimeoutMs?: number;
+  /** Server-side retry policy for the upstream provider call. */
+  retries?: {
+    maxAttempts?: 1 | 2 | 3 | 4 | 5;
+    retryDelayMs?: number;
+    backoff?: "constant" | "linear" | "exponential";
+  };
+}
+/**
+ * How `createAI` reaches Cloudflare: the Workers AI binding, and nothing else.
+ * Workers AI models go through `env.AI.run`, vendor models through
+ * `env.AI.gateway(id).run` — both are the binding, so there is no HTTP
+ * transport, no account id and no API token to hold.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type AISettings = {
+  /** The `AI` binding from a Worker's env. */ binding: Ai;
+} & ProviderGatewaySettings;
+/**
+ * Provider-wide gateway defaults, in either spelling: nested under `gateway`,
+ * or flat (`{ id: "prod", cacheTtl: 60 }`). Both merge, the flat key winning.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface ProviderGatewaySettings extends GatewayOptions {
+  /** Gateway id or full gateway options. */
+  gateway?: string | GatewayOptions;
+}
+/**
+ * Per-model and per-call options. The flat gateway keys are sugar for
+ * `gateway: { ... }`; both forms merge, with the flat key winning.
+ *
+ * The same shape is accepted per call under
+ * `providerOptions.cloudflare`, where it takes precedence over the per-model
+ * options, which in turn take precedence over the `createAI` settings.
+ *
+ * `Leg` is what a framework module accepts as a fallback leg. Workers AI ids
+ * are the only kind this module can resolve on its own, so they are the
+ * default; a module whose legs may also be model objects says so
+ * (`ModelOptions<WorkersAIModelId | LanguageModelV4>`) rather than rebuilding
+ * the type.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface ModelOptions<Leg = WorkersAIModelId> extends ProviderGatewaySettings {
+  /**
+   * Models to try, in order, if the primary fails before any output is
+   * produced. A leg travels with the chain's gateway options — those win over
+   * a leg's own, and `metadata` merges — while everything a leg was built with
+   * itself stays its own. Client-side today; becomes server-side when the
+   * platform ships model-first routing.
+   */
+  fallback?: Leg[];
+  /** Extra request headers, merged last. */
+  headers?: Record<string, string>;
+  /**
+   * Workers AI only: route same-key requests to the same replica for
+   * prefix-cache hits. Sent as the `x-session-affinity` header.
+   */
+  sessionAffinity?: string;
+  /**
+   * Explicit reasoning effort. `null` disables reasoning on models that
+   * support toggling it. The unified AI SDK `reasoning` call option maps onto
+   * this when this is not set.
+   */
+  reasoningEffort?: "low" | "medium" | "high" | null;
+  /**
+   * Workers AI only: forwarded verbatim as `chat_template_kwargs`, e.g.
+   * `{ enable_thinking: false }`.
+   */
+  chatTemplateKwargs?: Record<string, unknown>;
+}
+/** A gateway config with the id filled in. */
+interface ResolvedGateway extends GatewayOptions {
+  id: string;
+}
+//#endregion
+//#region src/models/core/errors.d.ts
+/**
+ * Coarse classification of a failed Cloudflare AI call.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type CloudflareAIErrorCode =
+  | "auth"
+  | "rate-limit"
+  | "not-found"
+  | "bad-request"
+  | "provider-error"
+  | "gateway-error"
+  | "unknown";
+/**
+ * One leg of a {@link CloudflareAIError} fallback chain.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface CloudflareAIAttempt {
+  /** The model id that was tried. */
+  model: string;
+  /** The error that leg failed with. */
+  error: unknown;
+}
+/**
+ * Error thrown for every failed Cloudflare AI call, whether it came back as a
+ * non-2xx `Response` or as a thrown Workers AI binding error. Framework
+ * modules wrap it into their own error type at their boundary (the AI SDK
+ * module into an `APICallError`, so `ai`'s retry loop honours
+ * {@link CloudflareAIError.isRetryable}).
+ *
+ * @experimental This surface is experimental and may change.
+ */
+declare class CloudflareAIError extends Error {
+  /** HTTP status, when the failure carried one. */
+  readonly status: number | undefined;
+  /** Coarse classification used for routing and fallback decisions. */
+  readonly code: CloudflareAIErrorCode;
+  /** `cf-aig-log-id` of the failed request, when the response carried one. */
+  readonly logId: string | undefined;
+  /** The model id that produced this error. */
+  readonly model: string;
+  /** Which binding path the request went down, for error reporting. */
+  readonly url: string;
+  /** The request body that failed. */
+  readonly requestBodyValues: unknown;
+  /** Response headers, when there was a response. */
+  readonly responseHeaders: Record<string, string> | undefined;
+  /** Raw response body text, when there was a response. */
+  readonly responseBody: string | undefined;
+  /** Whether a retry is worth attempting. */
+  readonly isRetryable: boolean;
+  /** Parsed error envelope, or other structured detail. */
+  readonly data: unknown;
+  /** Every leg tried, when this error ends a fallback chain. */
+  readonly attempts: CloudflareAIAttempt[] | undefined;
+  readonly cause: unknown;
+  constructor(options: {
+    message: string;
+    model: string;
+    url: string;
+    requestBodyValues: unknown;
+    status?: number;
+    code: CloudflareAIErrorCode;
+    logId?: string;
+    responseHeaders?: Record<string, string>;
+    responseBody?: string;
+    isRetryable?: boolean;
+    data?: unknown;
+    cause?: unknown;
+    attempts?: CloudflareAIAttempt[];
+  });
+}
+//#endregion
+//#region src/models/core/gateway-providers.d.ts
+/**
+ * The AI Gateway provider table: which gateway provider slug a vendor's own
+ * base URL belongs to, and what the universal request's `endpoint` is for a
+ * given upstream URL.
+ *
+ * This is platform knowledge, not vendor knowledge — the gateway publishes the
+ * list, and every entry here appears in `AIGatewayProviders` from
+ * `@cloudflare/workers-types`. Nothing about a vendor's wire format, model ids
+ * or capabilities lives here: the vendor's own provider package builds the
+ * request, and this table only says where it goes.
+ *
+ * Adapted from `@cloudflare/ai-gateway-provider`'s `providers.ts`.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+/**
+ * The gateway provider slugs this table maps onto. A subset of the ambient
+ * `AIGatewayProviders` union; {@link GatewayProviderNameCheck} keeps it one.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+declare const GATEWAY_PROVIDER_NAMES: readonly [
+  "workers-ai",
+  "anthropic",
+  "openai",
+  "azure-openai",
+  "google-ai-studio",
+  "google-vertex-ai",
+  "grok",
+  "mistral",
+  "perplexity-ai",
+  "replicate",
+  "groq",
+  "deepseek",
+  "openrouter",
+  "cerebras",
+  "cohere",
+  "huggingface",
+  "aws-bedrock",
+  "elevenlabs",
+  "cartesia"
+];
+/**
+ * A gateway provider slug.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+type GatewayProviderName = (typeof GATEWAY_PROVIDER_NAMES)[number];
+//#endregion
+//#region src/models/core/transport.d.ts
+/** One request on the Cloudflare run path. */
+interface TransportRequest {
+  /** Model id — Workers AI slug or catalog `<author>/<model>`. */
+  model: string;
+  /** The provider-shaped request body (`input` on the run path). */
+  input: Record<string, unknown>;
+  /** Gateway options for this request. */
+  gateway: ResolvedGateway;
+  /** Extra request headers, merged last. */
+  headers: Record<string, string>;
+  /** Abort signal, forwarded to the binding or to `fetch`. */
+  signal?: AbortSignal;
+}
+/**
+ * One request on the universal AI Gateway path: a vendor's own request, routed
+ * by the gateway to that vendor. The body is the vendor's, untouched — nothing
+ * here knows the vendor's wire format.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface UniversalRequest {
+  /** The gateway provider slug the request is routed to. */
+  provider: GatewayProviderName | string;
+  /** The vendor path the gateway appends to that provider's base URL. */
+  endpoint: string;
+  /** The vendor's own request headers, minus its credential header. */
+  headers: Record<string, string>;
+  /** The vendor's request body, verbatim. */
+  query: unknown;
+  /** Gateway options for this request. */
+  gateway: ResolvedGateway;
+  /** Extra headers merged last, outside the vendor's own set. */
+  extraHeaders?: Record<string, string>;
+  /** Abort signal, forwarded to the binding or to `fetch`. */
+  signal?: AbortSignal;
+}
+/**
+ * The single code path both backends implement. Always resolves to a raw
+ * `Response`, so streaming and non-streaming calls share one path and nothing
+ * is buffered on the caller's behalf.
+ *
+ * @experimental This surface is experimental and may change.
+ */
+interface Transport {
+  /** A stable identifier for the endpoint, used in error reporting. */
+  readonly url: string;
+  run(request: TransportRequest): Promise<Response>;
+  /**
+   * Sends a vendor's own request through the gateway's universal endpoint.
+   * Always resolves to the vendor's raw `Response`, error responses included:
+   * only the gateway's own failures (a missing gateway, an unpaid account) are
+   * lifted into a {@link CloudflareAIError}, because the vendor's provider
+   * knows how to read its own errors and we do not.
+   */
+  universal(request: UniversalRequest): Promise<Response>;
+  /**
+   * A log id read off the backend itself when the response carried none. The
+   * Workers AI binding exposes the last gateway log id as a mutable property,
+   * so it is captured per response rather than read late.
+   */
+  logIdFallback(response: Response): string | undefined;
+}
+//#endregion
+export {
+  KnownSpeechModelId as _,
+  CloudflareAIError as a,
+  GatewayOptions as c,
+  CloudflareEmbeddingModelId as d,
+  CloudflareImageModelId as f,
+  KnownImageModelId as g,
+  CloudflareTranscriptionModelId as h,
+  CloudflareAIAttempt as i,
+  ModelOptions as l,
+  CloudflareSpeechModelId as m,
+  GATEWAY_PROVIDER_NAMES as n,
+  CloudflareAIErrorCode as o,
+  CloudflareRerankingModelId as p,
+  GatewayProviderName as r,
+  AISettings as s,
+  Transport as t,
+  ProviderGatewaySettings as u,
+  WorkersAIModelId as v
+};
+//# sourceMappingURL=transport-PfFnt-Ld.d.ts.map

package/dist/{types-DCD6BNZH.d.ts → types-BA4anrjI.d.ts}

@@ -1,4 +1,4 @@
-import { t as RetryOptions } from "./retries-D9B2UCq3.js";
+import { t as RetryOptions } from "./retries-CV6AkXmQ.js";
 
 //#region src/queue/types.d.ts
 /**
@@ -67,4 +67,4 @@ export {
   QueueHandlers as r,
   QueueCallbacks as t
 };
-//# sourceMappingURL=types-DCD6BNZH.d.ts.map
+//# sourceMappingURL=types-BA4anrjI.d.ts.map

package/dist/voice/index.d.ts

@@ -1,5 +1,5 @@
-import { x as Connection } from "../capability-runner-BUBa6Ake.js";
-import { c as Agent } from "../agent-routing-B2XLNMxq.js";
+import { x as Connection } from "../capability-runner-DBAnGr6L.js";
+import { c as Agent } from "../agent-routing-0DR0Tk2v.js";
 import {
   C as VoiceTransport,
   D as VoiceTurnSource,

package/dist/websockets/index.d.ts

@@ -4,7 +4,7 @@ import {
   r as CapabilityWebSocketUpgradeContext,
   s as LifecycleCapability,
   x as Connection
-} from "../capability-runner-BUBa6Ake.js";
+} from "../capability-runner-DBAnGr6L.js";
 import {
   a as capnWebTransportUrl,
   n as CAPNWEB_TRANSPORT_QUERY,
@@ -84,7 +84,8 @@ interface WebSocketsOptions {
    *   connect or via `broadcastState()`, but can still send and receive
    *   ordinary messages and use callables. For binary-only clients.
    * - `false`: the host drives the connect sequence itself with
-   *   `sendIdentity()` and `sendState()`, and applies client state frames
+   *   `sendConnectFrames()` (or `sendIdentity()` and `sendState()`
+   *   separately), and applies client state frames
    *   with `applyStateFrame()` — `Agent` does this, since it must decide
    *   whether a connection belongs to a facet before any frame is sent.
    */
@@ -211,10 +212,26 @@ declare class WebSockets extends LifecycleCapability {
   /** One connection on either wire, by id. */
   getConnection<TState = unknown>(id: string): Connection<TState> | undefined;
   /**
-   * Send the identity frame, unless the connection is no-protocol. The
-   * defaults are the Durable Object's routed name and host class; a host
-   * whose public identity differs — an `Agent` facet, whose routed name
-   * is an internal encoding of its logical name — passes its own.
+   * Send the connect sequence: the identity frame, then the current state
+   * when one is stored. The identity carries `stateFollows` in that case,
+   * so clients resolve `ready` only once the state has landed. Nothing is
+   * sent to a no-protocol connection. Identity defaults as for
+   * `sendIdentity()`.
+   */
+  sendConnectFrames(
+    connection: Connection,
+    identity?: {
+      name: string;
+      agent: string;
+    }
+  ): void;
+  /**
+   * Send the identity frame alone, unless the connection is no-protocol.
+   * Clients resolve `ready` on it, so a host that also pushes state on
+   * connect should use `sendConnectFrames()`. The defaults are the Durable
+   * Object's routed name and host class; a host whose public identity
+   * differs — an `Agent` facet, whose routed name is an internal encoding
+   * of its logical name — passes its own.
    */
   sendIdentity(
     connection: Connection,

package/dist/websockets/index.js

@@ -1,3 +1,3 @@
 import { a as isCapnWebTransportUpgrade, i as capnWebTransportUrl, r as CAPNWEB_TRANSPORT_VALUE, t as CAPNWEB_TRANSPORT_QUERY } from "../transport-protocol-BxyngQ_R.js";
-import { l as registerInternalConnectionKeys, n as CF_NO_PROTOCOL_KEY, r as CF_READONLY_KEY, t as WebSockets } from "../websockets-D7IzWbZb.js";
+import { l as registerInternalConnectionKeys, n as CF_NO_PROTOCOL_KEY, r as CF_READONLY_KEY, t as WebSockets } from "../websockets-Ci-LZFHH.js";
 export { CAPNWEB_TRANSPORT_QUERY, CAPNWEB_TRANSPORT_VALUE, CF_NO_PROTOCOL_KEY, CF_READONLY_KEY, WebSockets, capnWebTransportUrl, isCapnWebTransportUpgrade, registerInternalConnectionKeys };