@better-agent/core 0.1.0-beta.1

package/dist/plugins/types.d.mts

@@ -0,0 +1,344 @@
+import { EventName } from "../events/constants.mjs";
+import { Awaitable } from "../internal/types.mjs";
+import { Capabilities, InstructionEnabled } from "../providers/types/capabilities.mjs";
+import { AgentToolDefinition, ToolSource } from "../tools/types.mjs";
+import { ToolChoice } from "../providers/types/tool-calls.mjs";
+import { GenerativeModelInputItem, GenerativeModelInputMessageContent } from "../providers/types/input.mjs";
+import { ConversationItem } from "../providers/types/conversation.mjs";
+import { GenerativeModelResponse } from "../providers/types/response.mjs";
+import { HttpMethod } from "../api.mjs";
+import { PreviousStepResult } from "../run/types.mjs";
+import { Event } from "../events/types.mjs";
+//#region src/plugins/types.d.ts
+/**
+ * Request mode passed to plugin guards.
+ *
+ * - `run`: one-shot non-streaming agent execution via the built-in run route.
+ * - `stream`: streaming agent execution via the built-in run route with SSE.
+ * - `load_conversation`: durable conversation history lookup.
+ * - `abort_run`: abort request for an active run id.
+ * - `resume_stream`: stream event resumption by known stream id.
+ * - `resume_conversation`: active conversation stream resumption by conversation id.
+ */
+type PluginGuardMode = "run" | "stream" | "load_conversation" | "abort_run" | "resume_stream" | "resume_conversation";
+/**
+ * Plugin definition.
+ *
+ * Plugin hook contexts are intentionally broad at authoring time. Some
+ * capability-sensitive controls may be omitted at runtime for models that do
+ * not support them. For example, tool-mutation helpers are only available
+ * during runs whose active model supports tools.
+ */
+interface Plugin {
+  /** Unique plugin id. */
+  id: string;
+  /** Event middleware configuration. */
+  events?: {
+    /** Event type filter. When omitted, receives all events. */subscribe?: EventName[]; /** Ordered middleware chain for matching events. */
+    middleware?: PluginEventMiddleware[];
+  };
+  /** Request guard functions. */
+  guards?: PluginGuard[];
+  /** Custom HTTP endpoints. */
+  endpoints?: PluginEndpoint[];
+  /** Event observer that cannot mutate or drop events. */
+  onEvent?: (event: Event, ctx: PluginEventContext) => Awaitable<void>;
+  /** Additional tools available to all agents. */
+  tools?: ToolSource<unknown>;
+  /** Called before each model call, before agent.onStep. */
+  onStep?: (ctx: PluginOnStepContext) => Awaitable<void>;
+  /** Transform model input just before the provider call. */
+  onBeforeModelCall?: (ctx: PluginModelCallContext) => Awaitable<void>;
+  /** Observe model response after the provider call, before tool execution. */
+  onAfterModelCall?: (ctx: PluginModelResponseContext) => Awaitable<void>;
+  /** Called before a tool executes. Can skip or modify args. */
+  onBeforeToolCall?: (ctx: PluginToolCallContext) => Awaitable<PluginToolCallDecision>;
+  /** Called after a tool executes. Can observe or modify result. */
+  onAfterToolCall?: (ctx: PluginToolResultContext) => Awaitable<void>;
+  /** Transform durable items before conversation persistence. */
+  onBeforeSave?: (ctx: PluginSaveContext) => Awaitable<void>;
+}
+/**
+ * Plugin endpoint definition.
+ *
+ * @example
+ * ```ts
+ * endpoints: [
+ *   {
+ *     method: "GET",
+ *     path: "/health",
+ *     public: true,
+ *     handler: () => Response.json({ ok: true }),
+ *   },
+ * ]
+ * ```
+ */
+interface PluginEndpoint {
+  /** HTTP method or methods. */
+  method: HttpMethod | HttpMethod[];
+  /** Route path pattern. Must start with `/`. */
+  path: string;
+  /**
+   * Bypasses the app's built-in bearer `secret` auth for this endpoint.
+   *
+   * This does not bypass auth outside Better Agent.
+   */
+  public?: boolean;
+  /** Endpoint handler. */
+  handler: PluginEndpointHandler;
+}
+/**
+ * Plugin endpoint handler.
+ */
+type PluginEndpointHandler = (ctx: {
+  request: Request;
+  params: Record<string, string>;
+  query: URLSearchParams;
+}) => Promise<Response> | Response;
+/**
+ * Plugin event middleware.
+ *
+ * Return the next event to continue, or `null` to drop it.
+ */
+type PluginEventMiddleware = (event: Event, ctx: PluginEventContext, next: (event: Event) => Promise<Event | null>) => Promise<Event | null>;
+/**
+ * Context passed to plugin event middleware.
+ */
+interface PluginEventContext {
+  /** Active run id. */
+  runId: string;
+  /** Agent name for this run. */
+  agentName: string;
+  /** Shared conversation id, if present. */
+  conversationId?: string;
+  /** Run control helpers. */
+  control: {
+    /** Aborts the active run. */abortRun: () => Promise<void>;
+  };
+}
+/**
+ * Shared base for plugin hook contexts tied to a live run.
+ */
+interface PluginBaseContext {
+  /** Active run id. */
+  runId: string;
+  /** Agent name for this run. */
+  agentName: string;
+  /** Shared conversation id, if present. */
+  conversationId?: string;
+}
+/**
+ * Context passed to plugin onStep hooks.
+ *
+ * Plugins always receive `context` as `unknown`.
+ */
+type PluginToolControlField<TModelCaps extends Capabilities = Capabilities> = TModelCaps["tools"] extends true ? {
+  setToolChoice(choice: ToolChoice): void;
+  setActiveTools(names: readonly string[]): void;
+} : Record<never, never>;
+type PluginInstructionControlField<TModelCaps extends Capabilities = Capabilities> = InstructionEnabled<TModelCaps> extends true ? {
+  setSystemInstruction(instruction: GenerativeModelInputMessageContent<TModelCaps>): void;
+} : Record<never, never>;
+type PluginOnStepContext<TModelCaps extends Capabilities = Capabilities> = PluginBaseContext & {
+  stepIndex: number;
+  maxSteps: number | undefined;
+  messages: GenerativeModelInputItem<TModelCaps>[]; /** Agent context as `unknown`. Plugins cannot assume its shape. */
+  context?: unknown;
+  previousStep?: PreviousStepResult;
+  updateMessages(updater: (messages: GenerativeModelInputItem<TModelCaps>[]) => GenerativeModelInputItem<TModelCaps>[]): void;
+} & PluginInstructionControlField<TModelCaps> & PluginToolControlField<TModelCaps>;
+/**
+ * Context passed to plugin `onBeforeModelCall` hooks.
+ */
+interface PluginModelCallContext extends PluginBaseContext {
+  stepIndex: number;
+  input: GenerativeModelInputItem[];
+  tools: AgentToolDefinition[];
+  toolChoice?: ToolChoice;
+  setInput(input: GenerativeModelInputItem[]): void;
+  setTools(tools: AgentToolDefinition[]): void;
+  setToolChoice(choice: ToolChoice | undefined): void;
+}
+/**
+ * Context passed to plugin `onAfterModelCall` hooks.
+ */
+interface PluginModelResponseContext extends PluginBaseContext {
+  stepIndex: number;
+  response: GenerativeModelResponse;
+}
+/**
+ * Context passed to plugin `onBeforeToolCall` hooks.
+ */
+interface PluginToolCallContext extends PluginBaseContext {
+  toolName: string;
+  toolCallId: string;
+  args: unknown;
+  setArgs(args: unknown): void;
+}
+/**
+ * Decision returned by plugin `onBeforeToolCall` hooks.
+ */
+type PluginToolCallDecision = undefined | {
+  skip: true;
+  result?: unknown;
+};
+/**
+ * Context passed to plugin `onAfterToolCall` hooks.
+ */
+interface PluginToolResultContext extends PluginBaseContext {
+  toolName: string;
+  toolCallId: string;
+  args: unknown;
+  result: unknown;
+  error?: string;
+  setResult(result: unknown): void;
+}
+/**
+ * Context passed to plugin `onBeforeSave` hooks.
+ */
+interface PluginSaveContext extends PluginBaseContext {
+  items: ConversationItem[];
+  setItems(items: ConversationItem[]): void;
+}
+/**
+ * Plugin guard.
+ *
+ * Return `null` to allow the request, or a `Response` to reject it.
+ */
+type PluginGuard = (ctx: PluginRunContext) => Promise<Response | null> | Response | null;
+/**
+ * Context passed to plugin guards.
+ */
+interface PluginRunContext {
+  /** Request mode. */
+  mode: PluginGuardMode;
+  /** Resolved agent name. */
+  agentName: string;
+  /** Parsed request body. */
+  input: Record<string, unknown>;
+  /** Original request object. */
+  request: Request;
+  /** Active plugins. */
+  plugins: readonly Plugin[];
+}
+/**
+ * Normalized plugin endpoint used at runtime.
+ */
+type PluginRuntimeEndpoint = {
+  /** Plugin id that owns this endpoint. */pluginId: string; /** HTTP method. */
+  method: HttpMethod; /** Route path pattern. */
+  path: string; /** When true, this endpoint bypasses the app's built-in bearer auth. */
+  public?: boolean; /** Endpoint handler. */
+  handler: PluginEndpointHandler;
+};
+/**
+ * Prepared plugin runtime consumed by the runner and server.
+ */
+interface PluginRuntime {
+  /** Original plugin list in registration order. */
+  plugins: readonly Plugin[];
+  /** Expanded endpoint routes with one method per entry. */
+  endpoints: readonly PluginRuntimeEndpoint[];
+  /** Fast flag used to skip event middleware when unused. */
+  hasEventMiddleware: boolean;
+  /** Fast flag used to skip `onEvent` hooks when unused. */
+  hasOnEvent: boolean;
+  /** Fast flag used to skip guards when unused. */
+  hasGuards: boolean;
+  /** Fast flag used to skip plugin-provided tools when unused. */
+  hasTools: boolean;
+  /** Fast flag used to skip `onStep` hooks when unused. */
+  hasOnStep: boolean;
+  /** Fast flag used to skip model hooks when unused. */
+  hasModelHooks: boolean;
+  /** Fast flag used to skip tool hooks when unused. */
+  hasToolHooks: boolean;
+  /** Fast flag used to skip `onBeforeSave` hooks when unused. */
+  hasOnBeforeSave: boolean;
+  /** Dispatches an event through plugin middleware. */
+  dispatchEvent(event: Event, ctx: PluginEventContext): Promise<Event | null>;
+  /** Notifies observing plugins after the event is committed. */
+  dispatchOnEvent(event: Event, ctx: PluginEventContext): Promise<void>;
+  /** Dispatches a run request through the guard chain. */
+  dispatchRun(ctx: PluginRunContext): Promise<Response | null>;
+  /** Resolves additional plugin-provided tools for one run. */
+  resolveTools<TContext>(context?: TContext): Promise<{
+    tools: AgentToolDefinition[];
+    runCleanup: () => Awaitable<void>;
+  }>;
+  /** Applies `onStep` hooks in registration order. */
+  applyOnStep<TContext, TToolName extends string = string, TModelCaps extends Capabilities = Capabilities>(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    stepIndex: number;
+    maxSteps: number | undefined;
+    messages: GenerativeModelInputItem<TModelCaps>[];
+    context?: TContext;
+    previousStep?: PreviousStepResult; /** Model capabilities used to determine which control helpers are valid. */
+    modelCaps?: TModelCaps;
+  }): Promise<{
+    messages: GenerativeModelInputItem<TModelCaps>[];
+    toolChoice?: ToolChoice;
+    activeTools?: TToolName[];
+    systemInstruction?: GenerativeModelInputMessageContent<TModelCaps>;
+  }>;
+  /** Applies `onBeforeModelCall` hooks in registration order. */
+  applyBeforeModelCall(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    stepIndex: number;
+    input: GenerativeModelInputItem[];
+    tools: AgentToolDefinition[];
+    toolChoice?: ToolChoice; /** Model capabilities used to determine which control helpers are valid. */
+    modelCaps?: Capabilities;
+  }): Promise<{
+    input: GenerativeModelInputItem[];
+    tools: AgentToolDefinition[];
+    toolChoice?: ToolChoice;
+  }>;
+  /** Notifies plugins after a model response is available. */
+  applyAfterModelCall(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    stepIndex: number;
+    response: GenerativeModelResponse;
+  }): Promise<void>;
+  /** Applies `onBeforeToolCall` hooks in registration order. */
+  applyBeforeToolCall(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    toolName: string;
+    toolCallId: string;
+    args: unknown;
+  }): Promise<{
+    args: unknown;
+    decision?: PluginToolCallDecision;
+  }>;
+  /** Notifies plugins after tool execution and allows result mutation. */
+  applyAfterToolCall(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    toolName: string;
+    toolCallId: string;
+    args: unknown;
+    result: unknown;
+    error?: string;
+  }): Promise<{
+    result: unknown;
+  }>;
+  /** Applies `onBeforeSave` hooks in registration order. */
+  applyBeforeSave(params: {
+    runId: string;
+    agentName: string;
+    conversationId?: string;
+    items: ConversationItem[];
+  }): Promise<ConversationItem[]>;
+}
+//#endregion
+export { Plugin, PluginBaseContext, PluginEndpoint, PluginEndpointHandler, PluginEventContext, PluginEventMiddleware, PluginGuard, PluginGuardMode, PluginModelCallContext, PluginModelResponseContext, PluginOnStepContext, PluginRunContext, PluginRuntime, PluginRuntimeEndpoint, PluginSaveContext, PluginToolCallContext, PluginToolCallDecision, PluginToolResultContext };
+//# sourceMappingURL=types.d.mts.map

package/dist/plugins/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/plugins/types.ts"],"mappings":"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"}

package/dist/providers/index.d.mts

@@ -0,0 +1,9 @@
+import { CapEnabled, Capabilities, IfCap, InferOutputSchema, InputEnabled, InputModalitySpec, InputShape, InstructionEnabled, ModalitiesField, ModalitiesParam, Modality, ModalityOptionsFor, OutputEnabled, OutputModalitySpec, OutputSchemaDefinition, OutputSchemaForCaps, OutputSchemaSource, ReplayMode, StructuredOutput } from "./types/capabilities.mjs";
+import { AudioContentBase, EmbeddingContentBase, FileContentBase, GenerativeModelAudioSource, GenerativeModelFileSource, GenerativeModelImageSource, GenerativeModelVideoSource, ImageContentBase, ReasoningContentBase, TextContentBase, TranscriptContentBase, VideoContentBase } from "./types/content.mjs";
+import { GenerativeModelProviderToolResult, GenerativeModelToolCallRequest, GenerativeModelToolCallResult, ToolChoice } from "./types/tool-calls.mjs";
+import { ChatInputMessage, GenerativeModelCallOptions, GenerativeModelInput, GenerativeModelInputItem, GenerativeModelInputMessage, GenerativeModelInputMessageContent, GenerativeModelInputMessagePart, GenerativeModelMessageRole, ModelOptions, PromptInputMessage } from "./types/input.mjs";
+import { ConversationItem, ConversationMessage, ConversationMessageContent, ConversationMessagePart } from "./types/conversation.mjs";
+import { GenerativeModelOutputItem, GenerativeModelOutputMessage, GenerativeModelOutputMessageContent, GenerativeModelOutputMessagePart } from "./types/output.mjs";
+import { GenerativeModelFinishReason, GenerativeModelResponse, GenerativeModelUsage } from "./types/response.mjs";
+import { GenerativeModel, GenerativeModelGenerateResult, ModelDescriptor } from "./types/model.mjs";
+export { AudioContentBase, CapEnabled, Capabilities, ChatInputMessage, ConversationItem, ConversationMessage, ConversationMessageContent, ConversationMessagePart, EmbeddingContentBase, FileContentBase, GenerativeModel, GenerativeModelAudioSource, GenerativeModelCallOptions, GenerativeModelFileSource, GenerativeModelFinishReason, GenerativeModelGenerateResult, GenerativeModelImageSource, GenerativeModelInput, GenerativeModelInputItem, GenerativeModelInputMessage, GenerativeModelInputMessageContent, GenerativeModelInputMessagePart, GenerativeModelMessageRole, GenerativeModelOutputItem, GenerativeModelOutputMessage, GenerativeModelOutputMessageContent, GenerativeModelOutputMessagePart, GenerativeModelProviderToolResult, GenerativeModelResponse, GenerativeModelToolCallRequest, GenerativeModelToolCallResult, GenerativeModelUsage, GenerativeModelVideoSource, IfCap, ImageContentBase, InferOutputSchema, InputEnabled, InputModalitySpec, InputShape, InstructionEnabled, ModalitiesField, ModalitiesParam, Modality, ModalityOptionsFor, ModelDescriptor, ModelOptions, OutputEnabled, OutputModalitySpec, OutputSchemaDefinition, OutputSchemaForCaps, OutputSchemaSource, PromptInputMessage, ReasoningContentBase, ReplayMode, StructuredOutput, TextContentBase, ToolChoice, TranscriptContentBase, VideoContentBase };

package/dist/providers/types/capabilities.d.mts

@@ -0,0 +1,153 @@
+import { IsAny, UnionToIntersection } from "../../internal/types.mjs";
+import { InferSchemaInput, ResolvableSchema } from "../../schema/types.mjs";
+//#region src/providers/types/capabilities.d.ts
+/**
+ * Supported input and output modalities.
+ */
+type Modality = "text" | "image" | "video" | "audio" | "file" | "embedding";
+/**
+ * How persisted conversation history should be treated on subsequent runs.
+ */
+type ReplayMode = "multi_turn" | "single_turn_persistent" | "single_turn_only";
+/**
+ * Capability spec for an input modality.
+ */
+type InputModalitySpec = boolean;
+/**
+ * Shape of input expected by a model.
+ */
+type InputShape = "chat" | "prompt";
+/**
+ * Capability spec for an output modality.
+ */
+type OutputModalitySpec = boolean | {
+  options?: Record<string, unknown>;
+};
+/**
+ * Model capability flags and modality support.
+ */
+interface Capabilities {
+  /**
+   * Supported input modalities and their capability extensions.
+   */
+  inputModalities?: Partial<Record<Modality, InputModalitySpec>>;
+  /**
+   * Supported output modalities and their capability extensions.
+   */
+  outputModalities?: Partial<Record<Modality, OutputModalitySpec>>;
+  /**
+   * Shape of the model input.
+   */
+  inputShape?: InputShape;
+  /**
+   * Whether stored conversation history should be replayed into future model calls.
+   */
+  replayMode?: ReplayMode;
+  /**
+   * Whether agent/system instruction controls are supported for this model.
+   */
+  supportsInstruction?: boolean;
+  /**
+   * Whether structured output is supported.
+   */
+  structured_output?: boolean | Record<string, unknown>;
+  /**
+   * Whether tool calling is supported.
+   */
+  tools?: boolean;
+  /**
+   * Additional message roles supported by the model, beyond `"system"`, `"user"`, and `"assistant"`.
+   */
+  additionalSupportedRoles?: readonly string[];
+}
+/**
+ * Schema accepted for requested structured output.
+ */
+type OutputSchemaSource = ResolvableSchema;
+/**
+ * User-facing structured output definition.
+ *
+ * Requires a text-output model.
+ */
+type OutputSchemaDefinition<TSchema extends OutputSchemaSource = OutputSchemaSource> = {
+  /** Schema that the model output should match. */schema: TSchema; /** Optional name forwarded to providers that support named structured outputs. */
+  name?: string; /** Whether strict schema adherence should be requested when supported. */
+  strict?: boolean;
+};
+/**
+ * Structured output definition gated by model capabilities.
+ */
+type OutputSchemaForCaps<TCaps extends Capabilities, TSchema extends OutputSchemaSource = OutputSchemaSource> = CapEnabled<TCaps["structured_output"]> extends true ? OutputSchemaDefinition<TSchema> : never;
+/**
+ * Infers the validated structured output type from a schema definition.
+ */
+type InferOutputSchema<TOutput> = TOutput extends {
+  schema: infer TSchema;
+} ? InferSchemaInput<NonNullable<TSchema>> : unknown;
+/**
+ * Determines whether a capability is enabled.
+ */
+type CapEnabled<C> = IsAny<C> extends true ? true : [C] extends [false | undefined] ? false : [Extract<C, true | boolean | Record<string, unknown>>] extends [never] ? false : true;
+/**
+ * Resolved structured output config sent to providers.
+ */
+interface StructuredOutput {
+  name: string;
+  schema: Record<string, unknown>;
+  strict?: boolean;
+}
+/**
+ * Tuple of enabled output modalities, or `undefined`.
+ */
+type ModalitiesParam<TCaps extends Capabilities> = undefined | readonly [EnabledOutputModality<TCaps>, ...EnabledOutputModality<TCaps>[]];
+/**
+ * Extracts output spec for a modality from model capabilities.
+ */
+type OutputSpec<TCaps extends Capabilities, M extends Modality> = TCaps["outputModalities"] extends infer O ? O extends Partial<Record<Modality, OutputModalitySpec>> ? O[M] : undefined : undefined;
+/**
+ * Extracts input spec for a modality from model capabilities.
+ */
+type InputSpec<TCaps extends Capabilities, M extends Modality> = TCaps["inputModalities"] extends infer I ? I extends Partial<Record<Modality, InputModalitySpec>> ? I[M] : undefined : undefined;
+/**
+ * Conditional object fields based on capability enablement.
+ */
+type IfCap<C, T extends object> = CapEnabled<C> extends true ? T : object;
+/**
+ * Whether a given output modality is enabled.
+ */
+type OutputEnabled<TCaps extends Capabilities, M extends Modality> = CapEnabled<OutputSpec<TCaps, M>> extends true ? true : false;
+/**
+ * Whether a given input modality is enabled.
+ */
+type InputEnabled<TCaps extends Capabilities, M extends Modality> = IsAny<TCaps> extends true ? true : M extends "text" ? TCaps["inputModalities"] extends Partial<Record<Modality, InputModalitySpec>> ? [InputSpec<TCaps, "text">] extends [false] ? false : true : true : TCaps["inputModalities"] extends Partial<Record<Modality, InputModalitySpec>> ? CapEnabled<InputSpec<TCaps, M>> : false;
+/**
+ * Whether system or instruction prompting is supported for a model.
+ */
+type InstructionEnabled<TCaps extends Capabilities> = IsAny<TCaps> extends true ? true : TCaps["supportsInstruction"] extends true ? true : false;
+/**
+ * Union of all enabled output modalities.
+ */
+type EnabledOutputModality<TCaps extends Capabilities> = (CapEnabled<OutputSpec<TCaps, "text">> extends true ? "text" : never) | (CapEnabled<OutputSpec<TCaps, "image">> extends true ? "image" : never) | (CapEnabled<OutputSpec<TCaps, "video">> extends true ? "video" : never) | (CapEnabled<OutputSpec<TCaps, "audio">> extends true ? "audio" : never) | (CapEnabled<OutputSpec<TCaps, "embedding">> extends true ? "embedding" : never);
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+/**
+ * Extracts provider-specific output options for a modality spec.
+ */
+type OutputOptionsOfSpec<S> = S extends {
+  options?: infer O;
+} ? O extends object ? O : object : object;
+type DefaultModalityOptionsFor<TCaps extends Capabilities> = [EnabledOutputModality<TCaps>] extends [never] ? object : IsUnion<EnabledOutputModality<TCaps>> extends true ? object : EnabledOutputModality<TCaps> extends infer K ? K extends keyof NonNullable<TCaps["outputModalities"]> ? OutputOptionsOfSpec<NonNullable<TCaps["outputModalities"]>[K]> : object : object;
+/**
+ * Aggregates output options for all selected modalities.
+ */
+type ModalityOptionsFor<TCaps extends Capabilities, T extends readonly unknown[] | undefined> = [T] extends [undefined] ? DefaultModalityOptionsFor<TCaps> : T extends readonly (infer K)[] ? UnionToIntersection<K extends keyof NonNullable<TCaps["outputModalities"]> ? OutputOptionsOfSpec<NonNullable<TCaps["outputModalities"]>[K]> : object> : object;
+/**
+ * Adds the `modalities` field when required.
+ */
+type ModalitiesField<TModalities> = undefined extends TModalities ? {
+  modalities?: TModalities;
+} : {
+  modalities: TModalities;
+};
+//#endregion
+export { CapEnabled, Capabilities, IfCap, InferOutputSchema, InputEnabled, InputModalitySpec, InputShape, InstructionEnabled, ModalitiesField, ModalitiesParam, Modality, ModalityOptionsFor, OutputEnabled, OutputModalitySpec, OutputSchemaDefinition, OutputSchemaForCaps, OutputSchemaSource, ReplayMode, StructuredOutput };
+//# sourceMappingURL=capabilities.d.mts.map

package/dist/providers/types/capabilities.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.mts","names":[],"sources":["../../../src/providers/types/capabilities.ts"],"mappings":"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"}

package/dist/providers/types/content.d.mts

@@ -0,0 +1,125 @@
+//#region src/providers/types/content.d.ts
+type GenerativeModelBinaryMediaSource = {
+  kind: "url";
+  url: string;
+} | {
+  kind: "base64";
+  data: string;
+  mimeType: string;
+};
+/**
+ * Image source supported by input and output content.
+ */
+type GenerativeModelImageSource = GenerativeModelBinaryMediaSource;
+/**
+ * Base text content shape.
+ */
+type TextContentBase = {
+  type: "text";
+  text: string;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Base image content shape.
+ */
+type ImageContentBase = {
+  type: "image";
+  source: GenerativeModelImageSource;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * File source supported by input content.
+ *
+ * Prefer `url` or `base64` when the content is portable across providers.
+ *
+ * Use `provider-file` as a deliberate escape hatch for provider-managed asset
+ * references when the upstream provider expects a previously uploaded file or
+ * asset id rather than inline bytes.
+ */
+type GenerativeModelFileSource = {
+  kind: "url";
+  url: string;
+  mimeType?: string;
+  filename?: string;
+} | {
+  kind: "base64";
+  data: string;
+  mimeType: string;
+  filename?: string;
+} | {
+  kind: "provider-file";
+  ref: {
+    provider: string;
+    id: string;
+  };
+  mimeType?: string;
+  filename?: string;
+};
+/**
+ * Base file content shape.
+ */
+type FileContentBase = {
+  type: "file";
+  source: GenerativeModelFileSource;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Audio source supported by input and output content.
+ */
+type GenerativeModelAudioSource = GenerativeModelBinaryMediaSource;
+/**
+ * Base audio content shape.
+ */
+type AudioContentBase = {
+  type: "audio";
+  source: GenerativeModelAudioSource;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Base embedding content shape.
+ */
+type EmbeddingContentBase = {
+  type: "embedding";
+  embedding: number[];
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Base transcript content shape.
+ */
+type TranscriptContentBase = {
+  type: "transcript";
+  text: string;
+  segments?: Array<{
+    id: string;
+    start: number;
+    end: number;
+    text: string;
+    speaker?: string;
+  }>;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Base reasoning content shape.
+ */
+type ReasoningContentBase = {
+  type: "reasoning";
+  text: string;
+  visibility: "summary" | "full";
+  provider?: string;
+  providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Video source supported by input and output content.
+ */
+type GenerativeModelVideoSource = GenerativeModelBinaryMediaSource;
+/**
+ * Base video content shape.
+ */
+type VideoContentBase = {
+  type: "video";
+  source: GenerativeModelVideoSource;
+  providerMetadata?: Record<string, unknown>;
+};
+//#endregion
+export { AudioContentBase, EmbeddingContentBase, FileContentBase, GenerativeModelAudioSource, GenerativeModelFileSource, GenerativeModelImageSource, GenerativeModelVideoSource, ImageContentBase, ReasoningContentBase, TextContentBase, TranscriptContentBase, VideoContentBase };
+//# sourceMappingURL=content.d.mts.map

package/dist/providers/types/content.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.mts","names":[],"sources":["../../../src/providers/types/content.ts"],"mappings":";KAAK,gCAAA;EAEK,IAAA;EACA,GAAA;AAAA;EAGA,IAAA;EACA,IAAA;EACA,QAAA;AAAA;;;;KAME,0BAAA,GAA6B,gCAAA;AAAzC;;;AAAA,KAKY,eAAA;EACR,IAAA;EACA,IAAA;EACA,gBAAA,GAAmB,MAAA;AAAA;;;;KAMX,gBAAA;EACR,IAAA;EACA,MAAA,EAAQ,0BAAA;EACR,gBAAA,GAAmB,MAAA;AAAA;;;;;;;;;;KAYX,yBAAA;EAEF,IAAA;EACA,GAAA;EACA,QAAA;EACA,QAAA;AAAA;EAGA,IAAA;EACA,IAAA;EACA,QAAA;EACA,QAAA;AAAA;EAGA,IAAA;EACA,GAAA;IACI,QAAA;IACA,EAAA;EAAA;EAEJ,QAAA;EACA,QAAA;AAAA;;;AAMV;KAAY,eAAA;EACR,IAAA;EACA,MAAA,EAAQ,yBAAA;EACR,gBAAA,GAAmB,MAAA;AAAA;;;;KAMX,0BAAA,GAA6B,gCAAA;;AAAzC;;KAKY,gBAAA;EACR,IAAA;EACA,MAAA,EAAQ,0BAAA;EACR,gBAAA,GAAmB,MAAA;AAAA;;;;KAMX,oBAAA;EACR,IAAA;EACA,SAAA;EACA,gBAAA,GAAmB,MAAA;AAAA;;AAHvB;;KASY,qBAAA;EACR,IAAA;EACA,IAAA;EACA,QAAA,GAAW,KAAA;IACP,EAAA;IACA,KAAA;IACA,GAAA;IACA,IAAA;IACA,OAAA;EAAA;EAEJ,gBAAA,GAAmB,MAAA;AAAA;;;;KAMX,oBAAA;EACR,IAAA;EACA,IAAA;EACA,UAAA;EACA,QAAA;EACA,gBAAA,GAAmB,MAAA;AAAA;;;;KAMX,0BAAA,GAA6B,gCAAA;;;;KAK7B,gBAAA;EACR,IAAA;EACA,MAAA,EAAQ,0BAAA;EACR,gBAAA,GAAmB,MAAA;AAAA"}