agents 0.26.0 → 0.27.0

package/dist/tool-BPJEbwaX.d.ts

@@ -0,0 +1,278 @@
+//#region src/websearch/contract.d.ts
+/**
+ * The `web_search` tool contract: its name, what it tells the model, what the
+ * model passes in, what comes back, and how results are rendered for the
+ * model. Shared by every executor of the tool — the harness-executed
+ * adapters in `agents/websearch/*` today, and a gateway-executed variant in
+ * `agents/models/*` once AI Gateway server tools ship — so a `web_search` call
+ * looks the same in a transcript whoever ran it.
+ */
+/**
+ * The tool's name, as the model calls it and as it appears in transcripts.
+ * `web_search` is the name models know from Anthropic's and OpenAI's built-in
+ * search tools.
+ */
+declare const WEB_SEARCH_TOOL_NAME = "web_search";
+/** The default number of results when the model doesn't ask for a count. */
+declare const DEFAULT_WEB_SEARCH_LIMIT = 5;
+/** The most results one search can return; the API rejects more. */
+declare const MAX_WEB_SEARCH_LIMIT = 10;
+/** The longest query the API accepts, in characters. */
+declare const MAX_WEB_SEARCH_QUERY_LENGTH = 1024;
+/**
+ * Per-result description length in the model's view, in characters. Provider
+ * descriptions run to ~8,000 characters (Ceramic returns page text), which at
+ * ten results is 80 KB of context per search. The full text stays in the
+ * host-side output.
+ */
+declare const DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS = 600;
+/** What the model says when it wants a search. */
+type WebSearchToolInput = {
+  /** The search query. */ query: string /** How many results to return, 1–10. Defaults to the host's `limit`. */;
+  limit?: number;
+};
+/**
+ * One search result. `url` and `title` are always present; the rest only
+ * when the provider returns them (Exa adds `imageUrl` and
+ * `lastModifiedDate`, Linkup adds `faviconUrl`, Ceramic adds neither).
+ */
+type WebSearchResult = {
+  url: string;
+  title: string /** A snippet or extract of the page. Length and style vary by provider. */;
+  description?: string /** ISO 8601 timestamp of the page's last modification. */;
+  lastModifiedDate?: string;
+  imageUrl?: string;
+  faviconUrl?: string;
+};
+/** The Web Search API's response: results plus request metadata. */
+type WebSearchResponse = {
+  items: WebSearchResult[];
+  metadata: {
+    /** The query as the provider saw it. */ query: string /** AI Gateway request id, for the gateway log. */;
+    requestId: string /** Provider latency in milliseconds. */;
+    latencyMs: number;
+  };
+};
+/**
+ * What one `web_search` run produces for the host: the full API response and
+ * which provider served it. The model sees {@link renderWebSearchResults}
+ * of this.
+ */
+type WebSearchToolOutput = WebSearchResponse & {
+  /** The provider that ran the search, when the source knows. */ provider?: string;
+};
+declare const WEB_SEARCH_TOOL_DESCRIPTION: string;
+interface RenderWebSearchResultsOptions {
+  /**
+   * Trim each description to this many characters in the model's view.
+   * Defaults to {@link DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS}; `Infinity`
+   * disables trimming.
+   */
+  maxDescriptionChars?: number;
+}
+/**
+ * Render search results as the text the model reads: one numbered block per
+ * result, descriptions trimmed and whitespace collapsed.
+ */
+declare function renderWebSearchResults(
+  response: WebSearchResponse,
+  options?: RenderWebSearchResultsOptions
+): string;
+//#endregion
+//#region src/websearch/source.d.ts
+/**
+ * Search providers behind the Cloudflare Web Search API. `ceramic` is the
+ * platform default and the cheapest; `exa` and `linkup` cost more and, in our
+ * testing, ranked announcement-style queries noticeably better. Pricing and
+ * data-retention terms are in the Web Search docs.
+ */
+type WebSearchProvider = "ceramic" | "exa" | "linkup";
+/** One search request as a source receives it. */
+interface WebSearchRequest {
+  /** 1–1024 characters. */
+  query: string;
+  /** 1–10. Defaults to 5. */
+  limit?: number;
+}
+/** Per-call options a source receives alongside the request. */
+interface WebSearchCallOptions {
+  /** Abort the search. A source should reject with the signal's reason. */
+  signal?: AbortSignal;
+}
+/**
+ * Runs searches. The tool core calls `search` and renders what comes back.
+ * An object rather than a bare function so a wrapper (caching, logging)
+ * keeps `provider` by spreading the source it wraps.
+ */
+interface WebSearchSource {
+  search(
+    request: WebSearchRequest,
+    options?: WebSearchCallOptions
+  ): Promise<WebSearchResponse>;
+  /**
+   * The provider this source searches with, when known. Informational:
+   * recorded on the tool's host output.
+   */
+  readonly provider?: WebSearchProvider;
+}
+/** Options shared by the AI-binding and HTTP sources. */
+interface WebSearchGatewayOptions {
+  /** AI Gateway id. Defaults to `"default"`, which Cloudflare creates on first use. */
+  gateway?: string;
+  /**
+   * Which provider runs the search. Host-chosen; the model never picks.
+   * Defaults to the platform default (`ceramic`).
+   */
+  provider?: WebSearchProvider;
+  /**
+   * The BYOK key alias on the gateway to bill the provider with. When set
+   * and no such key exists the request fails rather than falling back to
+   * AI Gateway credits. When omitted, a key under the `default` alias is
+   * used if one exists, otherwise credits.
+   */
+  byokAlias?: string;
+}
+/** A search over the Workers AI binding (`env.AI.websearch`). */
+interface AIWebSearchOptions extends WebSearchGatewayOptions {
+  /** The Workers AI binding. Requires `"ai": { "binding": "AI" }` in wrangler.jsonc. */
+  binding: Ai;
+}
+/**
+ * Search through the Workers AI binding. The Worker's own account and the
+ * named gateway are billed.
+ */
+declare function createAIWebSearch(
+  options: AIWebSearchOptions
+): WebSearchSource;
+/** A search over the HTTP API, from any runtime with `fetch`. */
+interface HTTPWebSearchOptions extends WebSearchGatewayOptions {
+  /** The Cloudflare account the gateway belongs to. */
+  accountId: string;
+  /** An API token with `Workers AI: Read` and `AI Gateway: Read` on that account. */
+  apiToken: string;
+  /** Override for tests. Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** API origin. Defaults to `https://api.cloudflare.com`. */
+  baseUrl?: string;
+}
+/**
+ * Search through `POST /accounts/{account_id}/ai/websearch`. Use this
+ * outside Workers, or to search through a gateway in another account.
+ */
+declare function createHTTPWebSearch(
+  options: HTTPWebSearchOptions
+): WebSearchSource;
+/**
+ * Error codes a {@link WebSearchError} carries. The `web_search_*` codes the
+ * API returns pass through as-is; failures without one get a code from the
+ * HTTP status, so every error has a code to branch on.
+ */
+type WebSearchErrorCode =
+  /** No AI Gateway credits and no provider key for the search. */ | "web_search_payment_required" /** `byokAlias` names a key the gateway does not have. */
+    | "web_search_byok_not_configured" /** The query, limit, or provider was rejected. */
+    | "invalid_web_search_input" /** The gateway does not exist or is not set up. */
+    | "web_search_gateway_not_configured" /** The API token or binding is not allowed to search. */
+    | "web_search_unauthorized" /** Too many searches; retry later. */
+    | "web_search_rate_limited" /** The search took longer than the tool's `timeoutMs`. */
+    | "web_search_timeout" /** The API or the provider failed. */
+    | "web_search_unavailable" /** The Workers runtime has no `env.AI.websearch()`. */
+    | "web_search_unsupported_runtime" /** A code the API added after this release. */
+    | (string & {});
+/** Why a search failed, with what the API said. */
+declare class WebSearchError extends Error {
+  readonly name = "WebSearchError";
+  readonly status: number;
+  readonly code: WebSearchErrorCode;
+  /** Whether retrying the same search might succeed. */
+  readonly retryable: boolean;
+  /** AI Gateway's id for the failed request, for the gateway log. */
+  readonly requestId?: string;
+  /** The Cloudflare API's numeric error code, when it gave one. */
+  readonly apiCode?: number;
+  constructor(
+    message: string,
+    details: {
+      status: number;
+      code: WebSearchErrorCode;
+      retryable?: boolean;
+      requestId?: string;
+      apiCode?: number;
+      cause?: unknown;
+    }
+  );
+}
+//#endregion
+//#region src/websearch/tool.d.ts
+/** Search through the Workers AI binding; the tool builds the source. */
+type WebSearchToolBindingOptions = AIWebSearchOptions & {
+  source?: never;
+};
+/**
+ * Search through a source you built. Gateway, provider, and billing belong
+ * to the source, so the binding options are not accepted here.
+ */
+type WebSearchToolSourceOptions = {
+  /** Where searches run, instead of the Workers AI binding. */ source: WebSearchSource;
+  binding?: never;
+  gateway?: never;
+  provider?: never;
+  byokAlias?: never;
+};
+/**
+ * Options every `web_search` tool adapter accepts. Invalid values throw a
+ * `RangeError` when the tool is created.
+ */
+type WebSearchToolOptions = (
+  | WebSearchToolBindingOptions
+  | WebSearchToolSourceOptions
+) & {
+  /**
+   * Results per search when the model doesn't ask for a count, and the most
+   * it gets when it asks for more. An integer from 1 to 10; defaults to 5.
+   */
+  limit?: number /** Replaces the default tool description. */;
+  description?: string;
+  /**
+   * Per-result description length in the model's view. A positive integer;
+   * defaults to 600 characters. `Infinity` passes descriptions through whole.
+   */
+  maxDescriptionChars?: number;
+  /**
+   * Give up on a search after this many milliseconds, as a retryable
+   * `web_search_timeout` failure. A positive integer; defaults to 30 seconds.
+   */
+  timeoutMs?: number;
+};
+/** The default for {@link WebSearchToolOptions.timeoutMs}. */
+declare const DEFAULT_WEB_SEARCH_TIMEOUT_MS = 30000;
+//#endregion
+export {
+  WebSearchResponse as C,
+  renderWebSearchResults as D,
+  WebSearchToolOutput as E,
+  WEB_SEARCH_TOOL_NAME as S,
+  WebSearchToolInput as T,
+  DEFAULT_WEB_SEARCH_LIMIT as _,
+  AIWebSearchOptions as a,
+  RenderWebSearchResultsOptions as b,
+  WebSearchError as c,
+  WebSearchProvider as d,
+  WebSearchRequest as f,
+  DEFAULT_WEB_SEARCH_DESCRIPTION_CHARS as g,
+  createHTTPWebSearch as h,
+  WebSearchToolSourceOptions as i,
+  WebSearchErrorCode as l,
+  createAIWebSearch as m,
+  WebSearchToolBindingOptions as n,
+  HTTPWebSearchOptions as o,
+  WebSearchSource as p,
+  WebSearchToolOptions as r,
+  WebSearchCallOptions as s,
+  DEFAULT_WEB_SEARCH_TIMEOUT_MS as t,
+  WebSearchGatewayOptions as u,
+  MAX_WEB_SEARCH_LIMIT as v,
+  WebSearchResult as w,
+  WEB_SEARCH_TOOL_DESCRIPTION as x,
+  MAX_WEB_SEARCH_QUERY_LENGTH as y
+};
+//# sourceMappingURL=tool-BPJEbwaX.d.ts.map

package/dist/transport-k2mFrtL8.d.ts

@@ -0,0 +1,200 @@
+import { a as ResolvedGateway } from "./settings-NgGwF7Qt.js";
+
+//#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 {
+  CloudflareAIError as a,
+  CloudflareAIAttempt as i,
+  GATEWAY_PROVIDER_NAMES as n,
+  CloudflareAIErrorCode as o,
+  GatewayProviderName as r,
+  Transport as t
+};
+//# sourceMappingURL=transport-k2mFrtL8.d.ts.map