@alvin0/ai-agent-sdk-core 0.1.0

package/dist/contract/adapter.d.ts

@@ -0,0 +1,91 @@
+import { StreamChunk } from "../stream/chunk.js";
+import { ModelInvocationContext } from "../observation/report.js";
+import { GenerateOptions } from "./generate-options.js";
+import { ModelCatalogOptions, ModelCatalogSnapshot, ModelInfo, ProviderInfo, ResolvedModelInfo } from "./model-info.js";
+import { ResolvedRetryPolicy } from "./retry-policy.js";
+//#region src/contract/adapter.d.ts
+/**
+ * One adapter-owned model-resolution generation, bound to its eventual stream call.
+ *
+ * This exists to close a real gap. Between "what can this model do?" and "send
+ * the request", configuration can change. Without binding, a caller could resolve
+ * capabilities against one endpoint and dispatch to another  Ecombining one
+ * generation's answers with another's connection. The pair travels together here
+ * so that cannot happen.
+ */
+interface PreparedAdapterCall {
+  /** Exact model metadata from the SAME generation as {@link stream}. */
+  readonly model: ResolvedModelInfo;
+  /** Dispatch through that generation, without re-reading dynamic connection facts. */
+  stream(options: GenerateOptions, context?: ModelInvocationContext): AsyncIterable<StreamChunk>;
+}
+/**
+ * Provider-wire adapter for this SDK's message and stream vocabulary.
+ *
+ * Register implementations with `registry.registerAdapter(routes, adapter)`.
+ *
+ * Contract obligations on implementations:
+ * - honour `options.signal` promptly;
+ * - emit chunks per the protocol documented on {@link StreamChunk};
+ * - include `attributionHeaders()` on every provider HTTP request.
+ */
+declare abstract class ModelAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route this instance was registered under.
+   * @returns detached display metadata whose `id` MUST equal `provider`.
+   */
+  providerInfo(provider: string): ProviderInfo;
+  /**
+   * The retry policy this route owns.
+   * @param _provider - a route this instance was registered under.
+   * @returns a resolved policy, or `undefined` to accept the defaults.
+   */
+  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;
+  /**
+   * List models this adapter can currently advertise for one route.
+   *
+   * ADVISORY only: an adapter may accept unlisted ids, and consumers must not
+   * turn absence from this list into a request rejection.
+   * @param _provider - one route owned by this adapter.
+   * @returns discoverable models, in adapter-preferred order.
+   */
+  listModels(_provider: string, _signal?: AbortSignal): Promise<readonly ModelInfo[]>;
+  /** Uncached adapter-level catalog; the composition runtime owns refresh policy. */
+  modelCatalog(provider: string, options?: ModelCatalogOptions): Promise<ModelCatalogSnapshot>;
+  /**
+   * Resolve all metadata available for one exact model.
+   *
+   * Independent of the advisory catalog, and NOT request validation  Ean unknown
+   * id resolves to a minimal descriptor rather than an error.
+   * @param provider - one route owned by this adapter.
+   * @param model - exact model id.
+   * @param _signal - cancellation; async implementations must settle promptly after abort.
+   * @returns identity plus any context, default, and reasoning metadata.
+   */
+  resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<ResolvedModelInfo>;
+  /**
+   * Bind exact model metadata and the eventual dispatch to one generation.
+   *
+   * Adapters whose connection facts come from mutable configuration override this
+   * and snapshot those facts here; the default is sufficient for a static one.
+   * @param provider - registered route.
+   * @param model - exact model id.
+   * @param signal - cancellation for model resolution.
+   * @returns metadata plus a one-generation stream entry point.
+   */
+  prepareCall(provider: string, model: string, signal?: AbortSignal, context?: ModelInvocationContext): Promise<PreparedAdapterCall>;
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   *
+   * There is deliberately no non-streaming counterpart. A single code path cannot
+   * drift from itself, and a caller wanting one value awaits the assembled
+   * message instead.
+   * @param options - the fully assembled request.
+   * @returns the chunk stream, obeying the {@link StreamChunk} protocol.
+   */
+  abstract stream(options: GenerateOptions, context?: ModelInvocationContext): AsyncIterable<StreamChunk>;
+}
+//#endregion
+export { ModelAdapter, PreparedAdapterCall };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/contract/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../src/contract/adapter.ts"],"mappings":";;;;;;;;;;;;;;;UAiCiB;;WAEN,OAAO;;EAEhB,OAAO,SAAS,iBAAiB,UAAU,yBAAyB,cAAc;;;;;;;;;;;;uBAa9D;;;;;;EAMpB,aAAa,mBAAmB;;;;;;EAShC,oBAAoB,oBAAoB;;;;;;;;;EAYxC,WAAW,mBAAmB,UAAU,cAAc,iBAAiB;;EAKjE,aAAa,kBAAkB,UAAS,sBAA2B,QAAQ;;;;;;;;;;;EAkBjF,aACE,kBACA,eACA,UAAU,cACT,QAAQ;;;;;;;;;;;EAcL,YACJ,kBACA,eACA,SAAS,aACT,UAAU,yBACT,QAAQ;;;;;;;;;;WAgBF,OAAO,SAAS,iBAAiB,UAAU,yBAAyB,cAAc"}

package/dist/contract/adapter.js

@@ -0,0 +1,2 @@
+var e=class{providerInfo(e){return{id:e,name:e}}providerRetryPolicy(e){}listModels(e,t){return Promise.resolve([])}async modelCatalog(e,t={}){let n=await this.listModels(e,t.signal),r=new Date().toISOString();return Object.freeze({provider:Object.freeze({...this.providerInfo(e)}),state:n.length===0?`empty`:`fresh`,revision:`adapter-uncached`,models:Object.freeze([...n]),observedAt:r})}resolveModel(e,t,n){return Promise.resolve({provider:e,id:t,name:t})}async prepareCall(e,t,n,r){return{model:await this.resolveModel(e,t,n),stream:(e,t=r)=>this.stream(e,t)}}};export{e as ModelAdapter};
+//# sourceMappingURL=adapter.js.map

package/dist/contract/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":[],"sources":["../../src/contract/adapter.ts"],"sourcesContent":["/**\n * The contract a provider backend implements.\n *\n * Shape worth noting: ONE abstract method. Everything else has a working default,\n * so a minimal adapter is a single `stream()` implementation, while a fully\n * featured one overrides metadata, catalog, and generation binding. That keeps the\n * barrier to a new provider low without capping what a mature one can express.\n *\n * Also note that every metadata method takes the route key as its first argument\n * rather than reading instance state. One adapter instance can therefore serve\n * many routes  Ethe same Anthropic adapter can back both a first-party route and\n * a proxy route with different endpoints and credentials.\n *\n * @module ai-agent-sdk/core/contract/adapter\n */\n\nimport type { StreamChunk } from '../stream/chunk.ts'\nimport type { ModelInvocationContext } from '../observation/report.ts'\nimport type { GenerateOptions } from './generate-options.ts'\nimport type {\n  ModelCatalogOptions, ModelCatalogSnapshot, ModelInfo, ProviderInfo, ResolvedModelInfo,\n} from './model-info.ts'\nimport type { ResolvedRetryPolicy } from './retry-policy.ts'\n\n/**\n * One adapter-owned model-resolution generation, bound to its eventual stream call.\n *\n * This exists to close a real gap. Between \"what can this model do?\" and \"send\n * the request\", configuration can change. Without binding, a caller could resolve\n * capabilities against one endpoint and dispatch to another  Ecombining one\n * generation's answers with another's connection. The pair travels together here\n * so that cannot happen.\n */\nexport interface PreparedAdapterCall {\n  /** Exact model metadata from the SAME generation as {@link stream}. */\n  readonly model: ResolvedModelInfo\n  /** Dispatch through that generation, without re-reading dynamic connection facts. */\n  stream(options: GenerateOptions, context?: ModelInvocationContext): AsyncIterable<StreamChunk>\n}\n\n/**\n * Provider-wire adapter for this SDK's message and stream vocabulary.\n *\n * Register implementations with `registry.registerAdapter(routes, adapter)`.\n *\n * Contract obligations on implementations:\n * - honour `options.signal` promptly;\n * - emit chunks per the protocol documented on {@link StreamChunk};\n * - include `attributionHeaders()` on every provider HTTP request.\n */\nexport abstract class ModelAdapter {\n  /**\n   * Describe one provider route owned by this adapter.\n   * @param provider - a route this instance was registered under.\n   * @returns detached display metadata whose `id` MUST equal `provider`.\n   */\n  providerInfo(provider: string): ProviderInfo {\n    return { id: provider, name: provider }\n  }\n\n  /**\n   * The retry policy this route owns.\n   * @param _provider - a route this instance was registered under.\n   * @returns a resolved policy, or `undefined` to accept the defaults.\n   */\n  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined {\n    return undefined\n  }\n\n  /**\n   * List models this adapter can currently advertise for one route.\n   *\n   * ADVISORY only: an adapter may accept unlisted ids, and consumers must not\n   * turn absence from this list into a request rejection.\n   * @param _provider - one route owned by this adapter.\n   * @returns discoverable models, in adapter-preferred order.\n   */\n  listModels(_provider: string, _signal?: AbortSignal): Promise<readonly ModelInfo[]> {\n    return Promise.resolve([])\n  }\n\n  /** Uncached adapter-level catalog; the composition runtime owns refresh policy. */\n  async modelCatalog(provider: string, options: ModelCatalogOptions = {}): Promise<ModelCatalogSnapshot> {\n    const models = await this.listModels(provider, options.signal)\n    const observedAt = new Date().toISOString()\n    return Object.freeze({ provider: Object.freeze({ ...this.providerInfo(provider) }),\n      state: models.length === 0 ? 'empty' : 'fresh', revision: 'adapter-uncached',\n      models: Object.freeze([...models]), observedAt })\n  }\n\n  /**\n   * Resolve all metadata available for one exact model.\n   *\n   * Independent of the advisory catalog, and NOT request validation  Ean unknown\n   * id resolves to a minimal descriptor rather than an error.\n   * @param provider - one route owned by this adapter.\n   * @param model - exact model id.\n   * @param _signal - cancellation; async implementations must settle promptly after abort.\n   * @returns identity plus any context, default, and reasoning metadata.\n   */\n  resolveModel(\n    provider: string,\n    model: string,\n    _signal?: AbortSignal,\n  ): Promise<ResolvedModelInfo> {\n    return Promise.resolve({ provider, id: model, name: model })\n  }\n\n  /**\n   * Bind exact model metadata and the eventual dispatch to one generation.\n   *\n   * Adapters whose connection facts come from mutable configuration override this\n   * and snapshot those facts here; the default is sufficient for a static one.\n   * @param provider - registered route.\n   * @param model - exact model id.\n   * @param signal - cancellation for model resolution.\n   * @returns metadata plus a one-generation stream entry point.\n   */\n  async prepareCall(\n    provider: string,\n    model: string,\n    signal?: AbortSignal,\n    context?: ModelInvocationContext,\n  ): Promise<PreparedAdapterCall> {\n    return {\n      model: await this.resolveModel(provider, model, signal),\n      stream: (options, invocation = context) => this.stream(options, invocation),\n    }\n  }\n\n  /**\n   * Stream one model call as raw chunks. The only required method.\n   *\n   * There is deliberately no non-streaming counterpart. A single code path cannot\n   * drift from itself, and a caller wanting one value awaits the assembled\n   * message instead.\n   * @param options - the fully assembled request.\n   * @returns the chunk stream, obeying the {@link StreamChunk} protocol.\n   */\n  abstract stream(options: GenerateOptions, context?: ModelInvocationContext): AsyncIterable<StreamChunk>\n}\n"],"mappings":"AAkDA,IAAsB,EAAtB,KAAmC,CAMjC,aAAa,EAAgC,CAC3C,MAAO,CAAE,GAAI,EAAU,KAAM,CAAS,CACxC,CAOA,oBAAoB,EAAoD,CAExE,CAUA,WAAW,EAAmB,EAAsD,CAClF,OAAO,QAAQ,QAAQ,CAAC,CAAC,CAC3B,CAGA,MAAM,aAAa,EAAkB,EAA+B,CAAC,EAAkC,CACrG,IAAM,EAAS,MAAM,KAAK,WAAW,EAAU,EAAQ,MAAM,EACvD,EAAa,IAAI,KAAK,CAAA,CAAE,YAAY,EAC1C,OAAO,OAAO,OAAO,CAAE,SAAU,OAAO,OAAO,CAAE,GAAG,KAAK,aAAa,CAAQ,CAAE,CAAC,EAC/E,MAAO,EAAO,SAAW,EAAI,QAAU,QAAS,SAAU,mBAC1D,OAAQ,OAAO,OAAO,CAAC,GAAG,CAAM,CAAC,EAAG,YAAW,CAAC,CACpD,CAYA,aACE,EACA,EACA,EAC4B,CAC5B,OAAO,QAAQ,QAAQ,CAAE,WAAU,GAAI,EAAO,KAAM,CAAM,CAAC,CAC7D,CAYA,MAAM,YACJ,EACA,EACA,EACA,EAC8B,CAC9B,MAAO,CACL,MAAO,MAAM,KAAK,aAAa,EAAU,EAAO,CAAM,EACtD,QAAS,EAAS,EAAa,IAAY,KAAK,OAAO,EAAS,CAAU,CAC5E,CACF,CAYF"}

package/dist/contract/call-config.d.ts

@@ -0,0 +1,36 @@
+import { ReasoningEffortId } from "../primitives/brand.js";
+//#region src/contract/call-config.d.ts
+/**
+ * Route, model, effort, and sampling scalars of one request. Every field maps
+ * 1:1 onto the same-named {@link GenerateOptions} field.
+ */
+interface CallConfig {
+  provider: string;
+  model: string;
+  reasoningEffort?: ReasoningEffortId;
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  stop?: readonly string[];
+}
+/**
+ * Which effective config fields came from adapter resolution rather than from
+ * the caller's request.
+ *
+ * Reported so a caller can tell "I chose 4096 output tokens" from "the adapter
+ * chose 4096 for me", which matters when surfacing effective settings.
+ */
+interface CallConfigAdapterDefaults {
+  reasoningEffort?: true;
+  maxTokens?: true;
+}
+/**
+ * Field-wise equality over {@link CallConfig}.
+ * @param a - one configuration.
+ * @param b - the other.
+ * @returns whether every field matches, comparing `stop` element-wise.
+ */
+declare function callConfigEquals(a: CallConfig, b: CallConfig): boolean;
+//#endregion
+export { CallConfig, CallConfigAdapterDefaults, callConfigEquals };
+//# sourceMappingURL=call-config.d.ts.map

package/dist/contract/call-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-config.d.ts","names":[],"sources":["../../src/contract/call-config.ts"],"mappings":";;;;;;UAiBiB;EACf;EACA;EACA,kBAAkB;EAClB;EACA;EACA;EACA;;;;;;;;;UAUe;EACf;EACA;;;;;;;;iBASc,iBAAiB,GAAG,YAAY,GAAG"}

package/dist/contract/call-config.js

@@ -0,0 +1,2 @@
+function e(e,t){return e.provider!==t.provider||e.model!==t.model||e.reasoningEffort!==t.reasoningEffort||e.temperature!==t.temperature||e.topP!==t.topP||e.maxTokens!==t.maxTokens?!1:e.stop===void 0||t.stop===void 0?e.stop===t.stop:e.stop.length===t.stop.length&&e.stop.every((e,n)=>e===t.stop?.[n])}export{e as callConfigEquals};
+//# sourceMappingURL=call-config.js.map

package/dist/contract/call-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-config.js","names":[],"sources":["../../src/contract/call-config.ts"],"sourcesContent":["/**\n * The subset of a request that behaves like connection state rather than\n * per-message content: route, model, effort, and sampling scalars.\n *\n * Isolating these is what makes the prepare/dispatch split in the registry\n * meaningful  Ethe registry can prove that the configuration it resolved\n * capabilities against is the same one being dispatched.\n *\n * @module ai-agent-sdk/core/contract/call-config\n */\n\nimport type { ReasoningEffortId } from '../primitives/brand.ts'\n\n/**\n * Route, model, effort, and sampling scalars of one request. Every field maps\n * 1:1 onto the same-named {@link GenerateOptions} field.\n */\nexport interface CallConfig {\n  provider: string\n  model: string\n  reasoningEffort?: ReasoningEffortId\n  temperature?: number\n  topP?: number\n  maxTokens?: number\n  stop?: readonly string[]\n}\n\n/**\n * Which effective config fields came from adapter resolution rather than from\n * the caller's request.\n *\n * Reported so a caller can tell \"I chose 4096 output tokens\" from \"the adapter\n * chose 4096 for me\", which matters when surfacing effective settings.\n */\nexport interface CallConfigAdapterDefaults {\n  reasoningEffort?: true\n  maxTokens?: true\n}\n\n/**\n * Field-wise equality over {@link CallConfig}.\n * @param a - one configuration.\n * @param b - the other.\n * @returns whether every field matches, comparing `stop` element-wise.\n */\nexport function callConfigEquals(a: CallConfig, b: CallConfig): boolean {\n  if (\n    a.provider !== b.provider\n    || a.model !== b.model\n    || a.reasoningEffort !== b.reasoningEffort\n    || a.temperature !== b.temperature\n    || a.topP !== b.topP\n    || a.maxTokens !== b.maxTokens\n  ) return false\n  if (a.stop === undefined || b.stop === undefined) return a.stop === b.stop\n  return a.stop.length === b.stop.length && a.stop.every((value, index) => value === b.stop?.[index])\n}\n"],"mappings":"AA6CA,SAAgB,EAAiB,EAAe,EAAwB,CAUtE,OARE,EAAE,WAAa,EAAE,UACd,EAAE,QAAU,EAAE,OACd,EAAE,kBAAoB,EAAE,iBACxB,EAAE,cAAgB,EAAE,aACpB,EAAE,OAAS,EAAE,MACb,EAAE,YAAc,EAAE,UACd,GACL,EAAE,OAAS,IAAA,IAAa,EAAE,OAAS,IAAA,GAAkB,EAAE,OAAS,EAAE,KAC/D,EAAE,KAAK,SAAW,EAAE,KAAK,QAAU,EAAE,KAAK,OAAO,EAAO,IAAU,IAAU,EAAE,OAAO,EAAM,CACpG"}

package/dist/contract/generate-options.d.ts

@@ -0,0 +1,41 @@
+import { ReasoningEffortId } from "../primitives/brand.js";
+import { Message } from "../message/message.js";
+import { ModelToolSchema, ToolChoice } from "./tool.js";
+import { ModelOutputFormat } from "./output-format.js";
+//#region src/contract/generate-options.d.ts
+/** One fully assembled model request. */
+interface GenerateOptions {
+  /** strict rejects known text-only models when request history contains images; project permits lossy conversion. */
+  readonly imagePolicy?: 'strict' | 'project';
+  /** Registered provider route, selecting the adapter instance. */
+  provider: string;
+  /**
+   * Exact model id, passed to the provider verbatim.
+   *
+   * Required, with no SDK-side default. Provider model lineups turn over faster
+   * than this package's release cadence, so any built-in default would eventually
+   * name a retired model and break for everyone who trusted it.
+   */
+  model: string;
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId;
+  /** Ordered conversation messages, exactly as the provider will see them. */
+  messages: readonly Message[];
+  /** System prompt text; adapters map it to the provider's system slot. */
+  system?: string;
+  /** Host functions and provider-native tools offered to the model. */
+  tools?: readonly ModelToolSchema[];
+  /** Tool-selection constraint; omission means the provider's own default. */
+  toolChoice?: ToolChoice;
+  /** Visible response format; omission uses the provider's ordinary text default. */
+  outputFormat?: ModelOutputFormat;
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  /** Stop sequences; generation halts on any of them, and the string is excluded from output. */
+  stop?: readonly string[];
+  signal?: AbortSignal;
+}
+//#endregion
+export { GenerateOptions };
+//# sourceMappingURL=generate-options.d.ts.map

package/dist/contract/generate-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-options.d.ts","names":[],"sources":["../../src/contract/generate-options.ts"],"mappings":";;;;;;UAYiB;;WAEN;;EAET;;;;;;;;EAQA;;EAEA,kBAAkB;;EAElB,mBAAmB;;EAEnB;;EAEA,iBAAiB;;EAEjB,aAAa;;EAEb,eAAe;EACf;EACA;EACA;;EAEA;EACA,SAAS"}

package/dist/contract/model-info.d.ts

@@ -0,0 +1,99 @@
+import { ReasoningEffortId } from "../primitives/brand.js";
+import { NativeToolName } from "./tool.js";
+import { SupportSafeError } from "../support-safe/error.js";
+//#region src/contract/model-info.d.ts
+/** Display metadata for one registered provider route. */
+interface ProviderInfo {
+  /** Route key used by {@link GenerateOptions.provider}. */
+  id: string;
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string;
+}
+/** Merge-extensible model input-modality vocabulary. */
+interface ModelModalityMap {
+  text: 'text';
+  image: 'image';
+}
+/** Any declared model input modality. */
+type ModelModality = ModelModalityMap[keyof ModelModalityMap];
+/**
+ * One model an adapter can advertise.
+ *
+ * Catalog membership is ADVISORY. An adapter may accept an id it does not list —
+ * new models ship faster than this package can — so a consumer must never turn
+ * absence from this list into a request rejection.
+ */
+interface ModelInfo {
+  /** Provider route that owns this entry. */
+  provider: string;
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string;
+  /** Human-readable name for selectors. */
+  name: string;
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string;
+  /**
+   * Accepted request modalities.
+   *
+   * Absent means UNKNOWN; an explicit list that omits a modality is a negative
+   * capability claim, and the registry acts on it by projecting images to text.
+   */
+  inputModalities?: readonly ModelModality[];
+  /** Modalities this model route may return, directly or through native tools. */
+  outputModalities?: readonly ModelModality[];
+  /** Provider-native tools explicitly supported; omission means unknown. */
+  nativeTools?: readonly NativeToolName[];
+}
+/** Provider-owned context capacity for one exact model route. */
+interface ModelContext {
+  /** Maximum combined request and response tokens. */
+  contextWindow: number;
+}
+/** Display metadata for one adapter-owned reasoning effort. */
+interface ReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId;
+  /** Human-readable effort name. */
+  name: string;
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string;
+}
+/** Selectable reasoning efforts for one exact model route. */
+interface ModelReasoningInfo {
+  /** Supported efforts, in adapter-preferred display order. */
+  efforts: readonly ReasoningEffortInfo[];
+  /**
+   * Effort materialized into requests when the caller omits one.
+   * Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId;
+}
+/** Exact-route model metadata, resolved by the adapter that owns the route. */
+interface ResolvedModelInfo extends ModelInfo {
+  /** Provider-owned context capacity, when known. */
+  context?: ModelContext;
+  /** Per-request output cap materialized when the caller omits one. */
+  defaultMaxTokens?: number;
+  /** Hard provider/model output ceiling; explicit requests above it are rejected. */
+  maxOutputTokens?: number;
+  /** Selectable reasoning levels, when the route exposes any. */
+  reasoning?: ModelReasoningInfo;
+}
+type ModelCatalogState = 'static' | 'fresh' | 'empty' | 'stale' | 'unavailable';
+interface ModelCatalogOptions {
+  readonly signal?: AbortSignal;
+  readonly refresh?: 'if-stale' | 'force';
+}
+interface ModelCatalogSnapshot {
+  readonly provider: ProviderInfo;
+  readonly state: ModelCatalogState;
+  readonly revision: string;
+  readonly models: readonly ModelInfo[];
+  readonly observedAt: string;
+  readonly expiresAt?: string;
+  readonly retryAt?: string;
+  readonly error?: SupportSafeError;
+}
+//#endregion
+export { ModelCatalogOptions, ModelCatalogSnapshot, ModelCatalogState, ModelContext, ModelInfo, ModelModality, ModelModalityMap, ModelReasoningInfo, ProviderInfo, ReasoningEffortInfo, ResolvedModelInfo };
+//# sourceMappingURL=model-info.d.ts.map

package/dist/contract/model-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-info.d.ts","names":[],"sources":["../../src/contract/model-info.ts"],"mappings":";;;;;UAWiB;;EAEf;;EAEA;;;UAIe;EACf;EACA;;;KAIU,gBAAgB,uBAAuB;;;;;;;;UASlC;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;EAOA,2BAA2B;;EAE3B,4BAA4B;;EAE5B,uBAAuB;;;UAIR;;EAEf;;;UAIe;;EAEf,IAAI;;EAEJ;;EAEA;;;UAIe;;EAEf,kBAAkB;;;;;EAKlB,gBAAgB;;;UAID,0BAA0B;;EAEzC,UAAU;;EAEV;;EAEA;;EAEA,YAAY;;KAGF;UAEK;WACN,SAAS;WACT;;UAGM;WACN,UAAU;WACV,OAAO;WACP;WACA,iBAAiB;WACjB;WACA;WACA;WACA,QAAQ"}

package/dist/contract/output-format.d.ts

@@ -0,0 +1,18 @@
+import { JsonObject } from "../primitives/json.js";
+//#region src/contract/output-format.d.ts
+/** Ordinary unconstrained model text. */
+interface TextOutputFormat {
+  readonly type: 'text';
+}
+/** JSON text constrained by a caller-owned JSON Schema. */
+interface JsonSchemaOutputFormat {
+  readonly type: 'json_schema';
+  /** Stable schema identifier. Required by providers such as OpenAI Responses. */
+  readonly name: string;
+  /** Provider-supported JSON Schema. Provider-specific subsets still apply. */
+  readonly schema: Readonly<JsonObject>;
+}
+type ModelOutputFormat = TextOutputFormat | JsonSchemaOutputFormat;
+//#endregion
+export { JsonSchemaOutputFormat, ModelOutputFormat, TextOutputFormat };
+//# sourceMappingURL=output-format.d.ts.map

package/dist/contract/output-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-format.d.ts","names":[],"sources":["../../src/contract/output-format.ts"],"mappings":";;;UAKiB;WACN;;;UAIM;WACN;;WAEA;;WAEA,QAAQ,SAAS;;KAGhB,oBAAoB,mBAAmB"}

package/dist/contract/retry-policy.d.ts

@@ -0,0 +1,104 @@
+//#region src/contract/retry-policy.d.ts
+/**
+ * Retry policy as PURE DATA plus validation. Nothing here executes a retry.
+ *
+ * The separation is deliberate and is the load-bearing idea: an adapter's job is
+ * to assign a stable `code` at the wire boundary, and the policy's job is to
+ * decide which codes are eligible. Adapters never decide retry. That is what
+ * lets a caller widen or narrow retry behaviour per route without touching  Eor
+ * even understanding  Eany provider's error mapping.
+ *
+ * @module ai-agent-sdk/core/contract/retry-policy
+ */
+/**
+ * Largest delay a timer can hold (`2**31 - 1` ms, ~24.9 days).
+ *
+ * Beyond this, `setTimeout` overflows to a 1 ms delay  Ea scheduled retry would
+ * fire immediately instead of much later, which is the opposite of the intent.
+ */
+declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Bounded exponential backoff with symmetric jitter around each local delay. */
+interface BackoffConfig {
+  /** First local backoff delay in milliseconds (default 500). */
+  initialDelayMs?: number;
+  /** Ceiling on any locally scheduled or accepted provider delay (default 10000). */
+  maxDelayMs?: number;
+  /** Symmetric random multiplier range around one (default 0.1). */
+  jitterRatio?: number;
+}
+/** Bounded transient retry behaviour for one route. */
+interface NormalRetryPolicyConfig {
+  /** Retry only the configured transient failure codes. */
+  mode: 'normal';
+  /** Maximum retries AFTER the first attempt (default 5). */
+  maxRetries?: number;
+  /** Failure codes eligible under this policy. */
+  retryableCodes?: readonly string[];
+  backoff?: BackoffConfig;
+}
+/**
+ * Unbounded retry for every failure on one route.
+ *
+ * For long-running unattended work where giving up is worse than waiting.
+ * Bounded only by cancellation. The retry decorator therefore requires the
+ * model request to carry an AbortSignal when this mode is selected.
+ */
+interface AlwaysRetryPolicyConfig {
+  mode: 'always';
+  backoff?: BackoffConfig;
+}
+/** Retry policy configuration for one provider route. */
+type RetryPolicyConfig = NormalRetryPolicyConfig | AlwaysRetryPolicyConfig;
+/** Fully resolved backoff shared by both modes. */
+interface ResolvedRetryBackoff {
+  readonly initialDelayMs: number;
+  readonly maxDelayMs: number;
+  readonly jitterRatio: number;
+}
+/** Fully resolved bounded transient retry policy. */
+interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {
+  readonly mode: 'normal';
+  readonly maxRetries: number;
+  readonly retryableCodes: readonly string[];
+}
+/** Fully resolved unbounded retry policy. */
+interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {
+  readonly mode: 'always';
+}
+/** Immutable policy, captured when a route is registered. */
+type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;
+/**
+ * Validate, default, and detach one retry policy.
+ *
+ * Everything returned is frozen, because a policy is captured at registration
+ * and read on every failure; a mutable one could be edited between the decision
+ * to retry and the wait itself.
+ * @param config - optional configuration; omission selects the normal defaults.
+ * @param path - diagnostic path naming the setting that owns the value.
+ * @returns an immutable policy, safe to capture in registration state.
+ */
+declare function resolveRetryPolicy(config: RetryPolicyConfig | undefined, path: string): ResolvedRetryPolicy;
+/**
+ * The delay before one retry attempt: bounded exponential growth with symmetric
+ * jitter.
+ *
+ * Jitter matters more than it looks. Without it, every client that failed
+ * against the same overloaded provider retries at the same instant, and the
+ * synchronized wave reproduces the outage it was meant to ride out.
+ * @param policy - the resolved policy supplying growth and bounds.
+ * @param attempt - 1-based retry number.
+ * @param random - sample in `[0, 1)`; injectable so tests can be deterministic.
+ * @returns the delay in milliseconds, never above `policy.maxDelayMs`.
+ */
+declare function backoffDelayMs(policy: ResolvedRetryPolicy, attempt: number, random?: () => number): number;
+/**
+ * Whether a policy admits one more attempt for a given failure code.
+ * @param policy - the resolved policy.
+ * @param code - the failure code assigned by the adapter.
+ * @param attemptsSoFar - retries already performed, excluding the first attempt.
+ * @returns true when another retry is permitted.
+ */
+declare function isRetryable(policy: ResolvedRetryPolicy, code: string, attemptsSoFar: number): boolean;
+//#endregion
+export { AlwaysRetryPolicyConfig, BackoffConfig, MAX_TIMER_DELAY_MS, NormalRetryPolicyConfig, ResolvedAlwaysRetryPolicy, ResolvedNormalRetryPolicy, ResolvedRetryBackoff, ResolvedRetryPolicy, RetryPolicyConfig, backoffDelayMs, isRetryable, resolveRetryPolicy };
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/contract/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","names":[],"sources":["../../src/contract/retry-policy.ts"],"mappings":";;;;;;;;;;;;;;;;;;cAqBa;;UAyBI;;EAEf;;EAEA;;EAEA;;;UAIe;;EAEf;;EAEA;;EAEA;EACA,UAAU;;;;;;;;;UAUK;EACf;EACA,UAAU;;;KAIA,oBAAoB,0BAA0B;;UAGzC;WACN;WACA;WACA;;;UAIM,kCAAkC;WACxC;WACA;WACA;;;UAIM,kCAAkC;WACxC;;;KAIC,sBAAsB,4BAA4B;;;;;;;;;;;iBA+C9C,mBACd,QAAQ,+BACR,eACC;;;;;;;;;;;;;iBA2Da,eACd,QAAQ,qBACR,iBACA;;;;;;;;iBAiBc,YACd,QAAQ,qBACR,cACA"}

package/dist/contract/retry-policy.js

@@ -0,0 +1,2 @@
+import{EMPTY_RESPONSE_CODE as e}from"../errors/agent-sdk-error.js";import{MODEL_ERROR_CODES as t}from"../errors/model-error.js";const n=2147483647,r=Object.freeze([e,t.RATE_LIMIT,t.SERVER,t.TIMEOUT,t.TRANSPORT]),i=new Set([`mode`,`maxRetries`,`retryableCodes`,`backoff`]),a=i,o=new Set([`initialDelayMs`,`maxDelayMs`,`jitterRatio`]);function s(e,t,n){for(let r of Object.keys(e))if(!t.has(r))throw Error(`${n}: unknown key "${r}"`)}function c(e,t){e!==void 0&&s(e,o,t);let r=e?.initialDelayMs??500,i=e?.maxDelayMs??1e4,a=e?.jitterRatio??.1;if(!Number.isFinite(r)||r<=0||r>2147483647)throw Error(`${t}.initialDelayMs must be a positive finite number no greater than ${n}`);if(!Number.isFinite(i)||i<=0||i>2147483647)throw Error(`${t}.maxDelayMs must be a positive finite number no greater than ${n}`);if(r>i)throw Error(`${t}.initialDelayMs must be less than or equal to maxDelayMs`);if(!Number.isFinite(a)||a<0||a>1)throw Error(`${t}.jitterRatio must be between 0 and 1`);return Object.freeze({initialDelayMs:r,maxDelayMs:i,jitterRatio:a})}function l(e,t){if(e===void 0)return Object.freeze({mode:`normal`,maxRetries:5,retryableCodes:r,...c(void 0,`${t}.backoff`)});switch(e.mode){case`normal`:{s(e,i,t);let n=e.maxRetries??5,a=e.retryableCodes??r;if(!Number.isSafeInteger(n)||n<0)throw Error(`${t}.maxRetries must be a non-negative safe integer`);if(a.length===0)throw Error(`${t}.retryableCodes must not be empty`);if(a.some(e=>typeof e!=`string`||e.length===0))throw Error(`${t}.retryableCodes must contain only non-empty strings`);if(new Set(a).size!==a.length)throw Error(`${t}.retryableCodes must not contain duplicates`);return Object.freeze({mode:`normal`,maxRetries:n,retryableCodes:Object.freeze([...a]),...c(e.backoff,`${t}.backoff`)})}case`always`:return s(e,a,t),Object.freeze({mode:`always`,...c(e.backoff,`${t}.backoff`)});default:throw Error(`${t}.mode must be "normal" or "always"`)}}function u(e,t,n=Math.random){let r=Math.min(Math.max(t-1,0),1024),i=Math.min(e.initialDelayMs*2**r,e.maxDelayMs),a=1-e.jitterRatio+2*e.jitterRatio*n();return Math.min(i*a,e.maxDelayMs)}function d(e,t,n){return e.mode===`always`||e.retryableCodes.includes(t)&&n<e.maxRetries}export{n as MAX_TIMER_DELAY_MS,u as backoffDelayMs,d as isRetryable,l as resolveRetryPolicy};
+//# sourceMappingURL=retry-policy.js.map

package/dist/contract/retry-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.js","names":[],"sources":["../../src/contract/retry-policy.ts"],"sourcesContent":["/**\n * Retry policy as PURE DATA plus validation. Nothing here executes a retry.\n *\n * The separation is deliberate and is the load-bearing idea: an adapter's job is\n * to assign a stable `code` at the wire boundary, and the policy's job is to\n * decide which codes are eligible. Adapters never decide retry. That is what\n * lets a caller widen or narrow retry behaviour per route without touching  Eor\n * even understanding  Eany provider's error mapping.\n *\n * @module ai-agent-sdk/core/contract/retry-policy\n */\n\nimport { EMPTY_RESPONSE_CODE } from '../errors/agent-sdk-error.ts'\nimport { MODEL_ERROR_CODES } from '../errors/model-error.ts'\n\n/**\n * Largest delay a timer can hold (`2**31 - 1` ms, ~24.9 days).\n *\n * Beyond this, `setTimeout` overflows to a 1 ms delay  Ea scheduled retry would\n * fire immediately instead of much later, which is the opposite of the intent.\n */\nexport const MAX_TIMER_DELAY_MS = 2_147_483_647\n\nconst DEFAULT_MAX_RETRIES = 5\nconst DEFAULT_INITIAL_DELAY_MS = 500\nconst DEFAULT_MAX_DELAY_MS = 10_000\nconst DEFAULT_JITTER_RATIO = 0.1\n\n/**\n * Codes eligible for retry by default.\n *\n * The exclusions are the interesting part. `AUTH`, `INVALID_REQUEST`, `QUOTA`,\n * `INVALID_CREDENTIAL`, and `CONTEXT_WINDOW_EXCEEDED` are absent because they\n * fail IDENTICALLY on every attempt  Eretrying them only burns latency and, for\n * quota, money. `EMPTY_RESPONSE` is present for the opposite reason: nothing\n * durable was produced, so repeating the call is safe and usually works.\n */\nconst DEFAULT_RETRYABLE_CODES: readonly string[] = Object.freeze([\n  EMPTY_RESPONSE_CODE,\n  MODEL_ERROR_CODES.RATE_LIMIT,\n  MODEL_ERROR_CODES.SERVER,\n  MODEL_ERROR_CODES.TIMEOUT,\n  MODEL_ERROR_CODES.TRANSPORT,\n])\n\n/** Bounded exponential backoff with symmetric jitter around each local delay. */\nexport interface BackoffConfig {\n  /** First local backoff delay in milliseconds (default 500). */\n  initialDelayMs?: number\n  /** Ceiling on any locally scheduled or accepted provider delay (default 10000). */\n  maxDelayMs?: number\n  /** Symmetric random multiplier range around one (default 0.1). */\n  jitterRatio?: number\n}\n\n/** Bounded transient retry behaviour for one route. */\nexport interface NormalRetryPolicyConfig {\n  /** Retry only the configured transient failure codes. */\n  mode: 'normal'\n  /** Maximum retries AFTER the first attempt (default 5). */\n  maxRetries?: number\n  /** Failure codes eligible under this policy. */\n  retryableCodes?: readonly string[]\n  backoff?: BackoffConfig\n}\n\n/**\n * Unbounded retry for every failure on one route.\n *\n * For long-running unattended work where giving up is worse than waiting.\n * Bounded only by cancellation. The retry decorator therefore requires the\n * model request to carry an AbortSignal when this mode is selected.\n */\nexport interface AlwaysRetryPolicyConfig {\n  mode: 'always'\n  backoff?: BackoffConfig\n}\n\n/** Retry policy configuration for one provider route. */\nexport type RetryPolicyConfig = NormalRetryPolicyConfig | AlwaysRetryPolicyConfig\n\n/** Fully resolved backoff shared by both modes. */\nexport interface ResolvedRetryBackoff {\n  readonly initialDelayMs: number\n  readonly maxDelayMs: number\n  readonly jitterRatio: number\n}\n\n/** Fully resolved bounded transient retry policy. */\nexport interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {\n  readonly mode: 'normal'\n  readonly maxRetries: number\n  readonly retryableCodes: readonly string[]\n}\n\n/** Fully resolved unbounded retry policy. */\nexport interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {\n  readonly mode: 'always'\n}\n\n/** Immutable policy, captured when a route is registered. */\nexport type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy\n\nconst NORMAL_POLICY_KEYS: ReadonlySet<string> = new Set([\n  'mode', 'maxRetries', 'retryableCodes', 'backoff',\n])\n// Layered configuration can retain normal-only fields after a mode switch, so\n// `always` tolerates those inactive values while still rejecting typos.\nconst ALWAYS_POLICY_KEYS: ReadonlySet<string> = NORMAL_POLICY_KEYS\nconst BACKOFF_KEYS: ReadonlySet<string> = new Set(['initialDelayMs', 'maxDelayMs', 'jitterRatio'])\n\nfunction validateKeys(value: object, allowed: ReadonlySet<string>, path: string): void {\n  for (const key of Object.keys(value)) {\n    if (!allowed.has(key)) throw new Error(`${path}: unknown key \"${key}\"`)\n  }\n}\n\nfunction resolveBackoff(config: BackoffConfig | undefined, path: string): ResolvedRetryBackoff {\n  if (config !== undefined) validateKeys(config, BACKOFF_KEYS, path)\n  const initialDelayMs = config?.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS\n  const maxDelayMs = config?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS\n  const jitterRatio = config?.jitterRatio ?? DEFAULT_JITTER_RATIO\n\n  if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {\n    throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)\n  }\n  if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {\n    throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)\n  }\n  if (initialDelayMs > maxDelayMs) {\n    throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`)\n  }\n  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) {\n    throw new Error(`${path}.jitterRatio must be between 0 and 1`)\n  }\n  return Object.freeze({ initialDelayMs, maxDelayMs, jitterRatio })\n}\n\n/**\n * Validate, default, and detach one retry policy.\n *\n * Everything returned is frozen, because a policy is captured at registration\n * and read on every failure; a mutable one could be edited between the decision\n * to retry and the wait itself.\n * @param config - optional configuration; omission selects the normal defaults.\n * @param path - diagnostic path naming the setting that owns the value.\n * @returns an immutable policy, safe to capture in registration state.\n */\nexport function resolveRetryPolicy(\n  config: RetryPolicyConfig | undefined,\n  path: string,\n): ResolvedRetryPolicy {\n  if (config === undefined) {\n    return Object.freeze({\n      mode: 'normal' as const,\n      maxRetries: DEFAULT_MAX_RETRIES,\n      retryableCodes: DEFAULT_RETRYABLE_CODES,\n      ...resolveBackoff(undefined, `${path}.backoff`),\n    })\n  }\n\n  switch (config.mode) {\n    case 'normal': {\n      validateKeys(config, NORMAL_POLICY_KEYS, path)\n      const maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES\n      const retryableCodes = config.retryableCodes ?? DEFAULT_RETRYABLE_CODES\n      if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) {\n        throw new Error(`${path}.maxRetries must be a non-negative safe integer`)\n      }\n      if (retryableCodes.length === 0) {\n        // An empty list is almost certainly a mistake rather than \"never retry\";\n        // `maxRetries: 0` says that unambiguously.\n        throw new Error(`${path}.retryableCodes must not be empty`)\n      }\n      if (retryableCodes.some(code => typeof code !== 'string' || code.length === 0)) {\n        throw new Error(`${path}.retryableCodes must contain only non-empty strings`)\n      }\n      if (new Set(retryableCodes).size !== retryableCodes.length) {\n        throw new Error(`${path}.retryableCodes must not contain duplicates`)\n      }\n      return Object.freeze({\n        mode: 'normal' as const,\n        maxRetries,\n        retryableCodes: Object.freeze([...retryableCodes]),\n        ...resolveBackoff(config.backoff, `${path}.backoff`),\n      })\n    }\n    case 'always':\n      validateKeys(config, ALWAYS_POLICY_KEYS, path)\n      return Object.freeze({\n        mode: 'always' as const,\n        ...resolveBackoff(config.backoff, `${path}.backoff`),\n      })\n    default:\n      throw new Error(`${path}.mode must be \"normal\" or \"always\"`)\n  }\n}\n\n/**\n * The delay before one retry attempt: bounded exponential growth with symmetric\n * jitter.\n *\n * Jitter matters more than it looks. Without it, every client that failed\n * against the same overloaded provider retries at the same instant, and the\n * synchronized wave reproduces the outage it was meant to ride out.\n * @param policy - the resolved policy supplying growth and bounds.\n * @param attempt - 1-based retry number.\n * @param random - sample in `[0, 1)`; injectable so tests can be deterministic.\n * @returns the delay in milliseconds, never above `policy.maxDelayMs`.\n */\nexport function backoffDelayMs(\n  policy: ResolvedRetryPolicy,\n  attempt: number,\n  random: () => number = Math.random,\n): number {\n  // Clamp the exponent before shifting: 2 ** 100000 is Infinity, and\n  // Infinity * jitter would defeat the Math.min bound below.\n  const exponent = Math.min(Math.max(attempt - 1, 0), 1024)\n  const exponential = Math.min(policy.initialDelayMs * 2 ** exponent, policy.maxDelayMs)\n  const jitter = 1 - policy.jitterRatio + 2 * policy.jitterRatio * random()\n  return Math.min(exponential * jitter, policy.maxDelayMs)\n}\n\n/**\n * Whether a policy admits one more attempt for a given failure code.\n * @param policy - the resolved policy.\n * @param code - the failure code assigned by the adapter.\n * @param attemptsSoFar - retries already performed, excluding the first attempt.\n * @returns true when another retry is permitted.\n */\nexport function isRetryable(\n  policy: ResolvedRetryPolicy,\n  code: string,\n  attemptsSoFar: number,\n): boolean {\n  if (policy.mode === 'always') return true\n  return policy.retryableCodes.includes(code) && attemptsSoFar < policy.maxRetries\n}\n"],"mappings":"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"}

package/dist/contract/tool.d.ts

@@ -0,0 +1,65 @@
+//#region src/contract/tool.d.ts
+/**
+ * How tools are described to a model and how its choice among them is constrained.
+ *
+ * @module ai-agent-sdk/core/contract/tool
+ */
+/** JSON-Schema description of one application function executed by the host. */
+interface ToolSchema {
+  readonly name: string;
+  readonly description: string;
+  /** JSON Schema object describing the arguments. */
+  readonly parameters: Readonly<Record<string, unknown>>;
+}
+/** Approximate user location used to improve a provider-native web search. */
+interface WebSearchLocation {
+  readonly city?: string;
+  readonly region?: string;
+  readonly country?: string;
+  readonly timezone?: string;
+}
+/** Web search executed inside the provider response, not by the host scheduler. */
+interface NativeWebSearchTool {
+  readonly type: 'native';
+  readonly name: 'web-search';
+  readonly searchContextSize?: 'low' | 'medium' | 'high';
+  readonly allowedDomains?: readonly string[];
+  readonly blockedDomains?: readonly string[];
+  readonly userLocation?: WebSearchLocation;
+  readonly maxUses?: number;
+}
+/** Image generation executed inside the provider response. */
+interface NativeImageGenerationTool {
+  readonly type: 'native';
+  readonly name: 'image-generation';
+  readonly size?: 'auto' | '1024x1024' | '1536x1024' | '1024x1536';
+  readonly quality?: 'auto' | 'low' | 'medium' | 'high';
+  readonly format?: 'png' | 'jpeg' | 'webp';
+  readonly background?: 'auto' | 'transparent' | 'opaque';
+  /** Number of progressive images requested while generation is in flight. */
+  readonly partialImages?: number;
+}
+/** Merge-extensible semantic vocabulary for tools executed by a provider. */
+interface NativeToolSchemaMap {
+  'web-search': NativeWebSearchTool;
+  'image-generation': NativeImageGenerationTool;
+}
+type NativeToolName = keyof NativeToolSchemaMap;
+type NativeToolSchema = NativeToolSchemaMap[NativeToolName];
+type ModelToolSchema = ToolSchema | NativeToolSchema;
+declare function isNativeToolSchema(tool: ModelToolSchema): tool is NativeToolSchema;
+/**
+ * How the model should choose among the supplied tools.
+ *
+ * `required` means "call some tool"; `{ type: 'tool' }` names exactly one.
+ */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+  type: 'tool';
+  name: string;
+} | {
+  type: 'native';
+  name: NativeToolName;
+};
+//#endregion
+export { ModelToolSchema, NativeImageGenerationTool, NativeToolName, NativeToolSchema, NativeToolSchemaMap, NativeWebSearchTool, ToolChoice, ToolSchema, WebSearchLocation, isNativeToolSchema };
+//# sourceMappingURL=tool.d.ts.map

package/dist/contract/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/contract/tool.ts"],"mappings":";;;;;;;UAOiB;WACN;WACA;;WAEA,YAAY,SAAS;;;UAIf;WACN;WACA;WACA;WACA;;;UAIM;WACN;WACA;WACA;WACA;WACA;WACA,eAAe;WACf;;;UAIM;WACN;WACA;WACA;WACA;WACA;WACA;;WAEA;;;UAIM;EACf,cAAc;EACd,oBAAoB;;KAGV,uBAAuB;KACvB,mBAAmB,oBAAoB;KACvC,kBAAkB,aAAa;iBAE3B,mBAAmB,MAAM,kBAAkB,QAAQ;;;;;;KASvD;EAIN;EAAc;;EACd;EAAgB,MAAM"}

package/dist/contract/tool.js

@@ -0,0 +1,2 @@
+function e(e){return`type`in e&&e.type===`native`}export{e as isNativeToolSchema};
+//# sourceMappingURL=tool.js.map

package/dist/contract/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","names":[],"sources":["../../src/contract/tool.ts"],"sourcesContent":["/**\n * How tools are described to a model and how its choice among them is constrained.\n *\n * @module ai-agent-sdk/core/contract/tool\n */\n\n/** JSON-Schema description of one application function executed by the host. */\nexport interface ToolSchema {\n  readonly name: string\n  readonly description: string\n  /** JSON Schema object describing the arguments. */\n  readonly parameters: Readonly<Record<string, unknown>>\n}\n\n/** Approximate user location used to improve a provider-native web search. */\nexport interface WebSearchLocation {\n  readonly city?: string\n  readonly region?: string\n  readonly country?: string\n  readonly timezone?: string\n}\n\n/** Web search executed inside the provider response, not by the host scheduler. */\nexport interface NativeWebSearchTool {\n  readonly type: 'native'\n  readonly name: 'web-search'\n  readonly searchContextSize?: 'low' | 'medium' | 'high'\n  readonly allowedDomains?: readonly string[]\n  readonly blockedDomains?: readonly string[]\n  readonly userLocation?: WebSearchLocation\n  readonly maxUses?: number\n}\n\n/** Image generation executed inside the provider response. */\nexport interface NativeImageGenerationTool {\n  readonly type: 'native'\n  readonly name: 'image-generation'\n  readonly size?: 'auto' | '1024x1024' | '1536x1024' | '1024x1536'\n  readonly quality?: 'auto' | 'low' | 'medium' | 'high'\n  readonly format?: 'png' | 'jpeg' | 'webp'\n  readonly background?: 'auto' | 'transparent' | 'opaque'\n  /** Number of progressive images requested while generation is in flight. */\n  readonly partialImages?: number\n}\n\n/** Merge-extensible semantic vocabulary for tools executed by a provider. */\nexport interface NativeToolSchemaMap {\n  'web-search': NativeWebSearchTool\n  'image-generation': NativeImageGenerationTool\n}\n\nexport type NativeToolName = keyof NativeToolSchemaMap\nexport type NativeToolSchema = NativeToolSchemaMap[NativeToolName]\nexport type ModelToolSchema = ToolSchema | NativeToolSchema\n\nexport function isNativeToolSchema(tool: ModelToolSchema): tool is NativeToolSchema {\n  return 'type' in tool && tool.type === 'native'\n}\n\n/**\n * How the model should choose among the supplied tools.\n *\n * `required` means \"call some tool\"; `{ type: 'tool' }` names exactly one.\n */\nexport type ToolChoice =\n  | 'auto'\n  | 'none'\n  | 'required'\n  | { type: 'tool'; name: string }\n  | { type: 'native'; name: NativeToolName }\n"],"mappings":"AAuDA,SAAgB,EAAmB,EAAiD,CAClF,MAAO,SAAU,GAAQ,EAAK,OAAS,QACzC"}