@agentloop/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,825 @@
+//#region src/content.d.ts
+/** Plain text content. */
+interface TextPart {
+  /** Part discriminator. */
+  type: "text";
+  /** The text content. */
+  text: string;
+  /** Provider-specific signature for reasoning verification. */
+  signature?: string;
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** Structured JSON content. */
+interface JsonPart {
+  /** Part discriminator. */
+  type: "json";
+  /** The JSON payload. */
+  json: Record<string, unknown>;
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** Inline binary data (images, audio, video, documents, etc.). */
+interface BlobPart {
+  /** Part discriminator. */
+  type: "blob";
+  /** Raw binary content or a base64-encoded string. */
+  data: string | Uint8Array;
+  /** MIME type of the binary data (e.g. `"image/png"`, `"audio/wav"`). */
+  mediaType: string;
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** Reference to an external resource. */
+interface URLPart {
+  /** Part discriminator. */
+  type: "url";
+  /** The resource URL. */
+  url: string;
+  /** Optional MIME type hint for the referenced resource. */
+  mediaType?: string;
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** Model reasoning trace. */
+interface ThinkingPart {
+  /** Part discriminator. */
+  type: "thinking";
+  /** The model's internal reasoning text. */
+  thinking: string;
+  /** Provider-specific signature for thinking verification. */
+  signature?: string;
+  /** Whether the thinking content was redacted by the provider. */
+  redacted: boolean;
+}
+/** A request from the model to invoke a tool. */
+interface ToolCallPart {
+  /** Part discriminator. */
+  type: "tool_call";
+  /** Unique identifier for this tool call, used to match results. */
+  id: string;
+  /** The name of the tool to invoke. */
+  name: string;
+  /** The arguments to pass to the tool. */
+  arguments: Record<string, unknown>;
+  /** Provider-specific signature for tool call verification. */
+  signature?: string;
+}
+/** The result of a tool invocation. */
+interface ToolResultPart {
+  /** Part discriminator. */
+  type: "tool_result";
+  /** Identifier matching the originating {@link ToolCallPart.id}. */
+  id: string;
+  /** The name of the tool that was invoked. */
+  name: string;
+  /** The content returned by the tool. */
+  output: Content[];
+  /** Whether the tool invocation failed. */
+  isError?: boolean;
+}
+/** Renderable content: text, structured data, or binary/external media. */
+type Content = TextPart | JsonPart | BlobPart | URLPart;
+/** Content that can appear in a system message. */
+type SystemContent = TextPart;
+/** Content that can appear in a user message. */
+type UserContent = TextPart | JsonPart | BlobPart | URLPart;
+/** Content that can appear in an assistant message. */
+type AssistantContent = TextPart | ThinkingPart | ToolCallPart;
+/** Content that can appear in a tool message. */
+type ToolContent = ToolResultPart;
+/** Create a {@link TextPart}. */
+declare function text(value: string): TextPart;
+/** Create a {@link JsonPart}. */
+declare function json(value: Record<string, unknown>): JsonPart;
+/** Create a {@link BlobPart}. */
+declare function blob(data: string | Uint8Array, mediaType: string): BlobPart;
+/** Create a {@link URLPart}. */
+declare function url(value: string, mediaType?: string): URLPart;
+//#endregion
+//#region src/message.d.ts
+/** A system instruction that guides model behavior. */
+interface SystemMessage {
+  /** Message discriminator. */
+  role: "system";
+  /** The system instruction content. */
+  content: SystemContent[];
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** A message from the user. */
+interface UserMessage {
+  /** Message discriminator. */
+  role: "user";
+  /** User-provided content (text, media, structured data, etc.). */
+  content: UserContent[];
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** A response from the model. */
+interface AssistantMessage {
+  /** Message discriminator. */
+  role: "assistant";
+  /** Model-generated content (text, thinking, tool calls). */
+  content: AssistantContent[];
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** The result of one or more tool invocations. */
+interface ToolMessage {
+  /** Message discriminator. */
+  role: "tool";
+  /** Tool results to return to the model. */
+  content: ToolContent[];
+  /** Arbitrary key-value pairs for provider or application use. */
+  metadata?: Record<string, unknown>;
+}
+/** A message in a conversation. */
+type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
+/** Create a {@link SystemMessage}. Accepts a string or content array. */
+declare function system(content: string | SystemContent[]): SystemMessage;
+/** Create a {@link UserMessage}. Accepts a string or content array. */
+declare function user(content: string | UserContent[]): UserMessage;
+/** Create an {@link AssistantMessage}. Accepts a string or content array. */
+declare function assistant(content: string | AssistantContent[]): AssistantMessage;
+/** Flexible input type for agent invocations. A plain string is treated as a user message. */
+type Prompt = string | Message | Message[];
+/** Normalize a {@link Prompt} into a {@link Message} array. */
+declare function normalizePrompt(prompt: Prompt): Message[];
+//#endregion
+//#region src/schema.d.ts
+/**
+* Minimal schema interface for argument validation and type inference.
+*
+* Any validator with a compatible `safeParse` method works — Zod, Valibot,
+* ArkType, or a hand-rolled validator. No adapter needed.
+*
+* **Provider requirement:** When used in tool definitions, providers need to
+* extract a JSON Schema representation to send to the model API. Providers
+* use the [Standard Schema](https://github.com/standard-schema/standard-schema)
+* interface (`~standard.jsonSchema.input()`) for this conversion.
+*
+* Schemas from Standard Schema-compliant libraries (Zod v4+, Valibot v1+,
+* ArkType) work automatically with all providers. Hand-rolled schemas with
+* only `safeParse` will validate arguments correctly but will throw at
+* runtime when used with a provider that requires JSON Schema extraction.
+*/
+interface Schema<T = unknown> {
+  safeParse(value: unknown): {
+    success: true;
+    data: T;
+  } | {
+    success: false;
+    error: unknown;
+  };
+}
+/** Extract the output type from a {@link Schema}. */
+type Infer<S extends Schema> = S extends Schema<infer T> ? T : never;
+/**
+* Extract a JSON Schema object from a
+* [Standard Schema v1](https://github.com/standard-schema/standard-schema)
+* compatible validator.
+*
+* Throws if the schema does not expose `~standard.jsonSchema.input()`.
+*/
+declare function schemaToJsonSchema(schema: unknown): Record<string, unknown>;
+//#endregion
+//#region src/context.d.ts
+/** Shared context for the current agent run, passed to policies and hooks. */
+interface RunContext {
+  /** Unique identifier for the current run. */
+  readonly runId: string;
+  /** The current step number (zero-indexed). */
+  readonly step: number;
+  /** The name of the active agent, if applicable. */
+  readonly agent?: string;
+  /** Run-scoped key-value store shared across policies and tools. */
+  readonly state: Record<string, unknown>;
+  /** How many times the current step has been retried. Resets to zero on each new step. */
+  readonly retries: number;
+  /** Signal for cooperative cancellation. */
+  readonly signal: AbortSignal;
+}
+/** Extended context passed to tool executions. */
+interface ToolContext extends RunContext {
+  /** Identifier of the tool call being executed, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** Emit a progress update to observers during tool execution. */
+  update(data: Record<string, unknown>): void;
+}
+//#endregion
+//#region src/policy.d.ts
+/** Action returned from {@link Policy.beforeStep}. */
+type BeforeStepAction = {
+  action: "stop";
+  reason?: string;
+};
+/** Action returned from {@link Policy.afterResponse}. */
+type AfterResponseAction = {
+  action: "stop";
+  reason?: string;
+} | {
+  action: "replace";
+  message: AssistantMessage;
+  reason?: string;
+} | {
+  action: "retry";
+  messages?: Message[];
+  reason?: string;
+};
+/** Action returned from {@link Policy.beforeToolRun} and {@link Tool.before}. */
+type BeforeToolRunAction = {
+  action: "skip";
+  output?: Content[];
+  reason?: string;
+} | {
+  action: "stop";
+  output?: Content[];
+  reason?: string;
+};
+/** Action returned from {@link Policy.afterToolRun} and {@link Tool.after}. */
+type AfterToolRunAction = {
+  action: "rewrite";
+  output: Content[];
+  reason?: string;
+} | {
+  action: "retry";
+  arguments?: Record<string, unknown>;
+  reason?: string;
+} | {
+  action: "stop";
+  reason?: string;
+};
+/** Action returned from {@link Policy.afterStep}. */
+type AfterStepAction = {
+  action: "stop";
+  reason?: string;
+} | {
+  action: "retry";
+  messages?: Message[];
+  reason?: string;
+} | {
+  action: "inject";
+  messages: Message[];
+};
+/**
+* A mutable plan for the upcoming model call.
+*
+* The loop creates a shallow copy of the transcript for {@link StepPlan.messages},
+* so policies can safely add, remove, or reorder messages without affecting the
+* canonical transcript.
+*/
+interface StepPlan extends Partial<ModelConfig> {
+  /** The model to use for this step. Policies can swap this to route different steps to different models. */
+  model: Model;
+  /** System instructions for the model. Converted to a system message before calling the model. */
+  instructions?: string;
+  /** A draft copy of the transcript. Safe to mutate without affecting the canonical transcript. */
+  messages: Message[];
+  /** Tools available for this step. Policies can add or remove tools. */
+  tools: Tool[];
+}
+/** Information about the model's response, before tool execution. */
+interface ResponseInfo {
+  /** The assistant message. */
+  readonly message: AssistantMessage;
+  /** The full transcript including the new message. */
+  readonly messages: readonly Message[];
+  /** Token usage for this response. */
+  readonly usage: Usage;
+  /** Aggregated token usage across all steps so far. */
+  readonly totalUsage: Usage;
+  /** Why the model stopped generating. */
+  readonly finishReason: FinishReason;
+  /** Parsed structured output, if an output schema was provided. */
+  readonly object?: unknown;
+}
+/** Information about a tool call before execution. */
+interface ToolCallInfo {
+  /** The tool call ID. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** Parsed arguments. Mutable for sanitization by policies. */
+  arguments: Record<string, unknown>;
+}
+/** Information about a tool call after execution. */
+interface ToolResultInfo {
+  /** The tool call ID. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The arguments that were passed to the tool. */
+  readonly arguments: Record<string, unknown>;
+  /** The output content produced by the tool. */
+  readonly output: readonly Content[];
+  /** Whether the tool produced an error. */
+  readonly isError: boolean;
+}
+/** Information about a completed step. */
+interface StepInfo {
+  /** Messages produced during this step. */
+  readonly messages: readonly Message[];
+  /** The full transcript. */
+  readonly transcript: readonly Message[];
+  /** Token usage for this step. */
+  readonly usage: Usage;
+  /** Aggregated token usage across all steps so far. */
+  readonly totalUsage: Usage;
+  /** Why the model stopped in this step. */
+  readonly finishReason: FinishReason;
+  /** Parsed structured output, if an output schema was provided. */
+  readonly object?: unknown;
+}
+/**
+* Controls agent loop behavior at key decision points.
+*
+* Implement any combination of hooks — unimplemented hooks default to
+* continue with no side effects.
+*
+* Policies are evaluated in pipeline order: the first policy to return
+* a non-continue result short-circuits, and later policies are skipped.
+* If a hook returns an error, it is treated as a stop directive.
+*/
+interface Policy {
+  /** A human-readable name for this policy, used in error attribution and events. */
+  name: string;
+  /** Called before each model call. Can mutate the step plan or stop the run. */
+  beforeStep?(ctx: RunContext, plan: StepPlan): void | BeforeStepAction | Promise<void | BeforeStepAction>;
+  /** Called after the model responds, before tool execution. */
+  afterResponse?(ctx: RunContext, info: ResponseInfo): void | AfterResponseAction | Promise<void | AfterResponseAction>;
+  /** Called before each individual tool execution. */
+  beforeToolRun?(ctx: RunContext, call: ToolCallInfo): void | BeforeToolRunAction | Promise<void | BeforeToolRunAction>;
+  /** Called after each individual tool execution. */
+  afterToolRun?(ctx: RunContext, result: ToolResultInfo): void | AfterToolRunAction | Promise<void | AfterToolRunAction>;
+  /** Called after the complete step (model response + tool execution). */
+  afterStep?(ctx: RunContext, info: StepInfo): void | AfterStepAction | Promise<void | AfterStepAction>;
+}
+/** Create a {@link Policy}. */
+declare function definePolicy(config: Policy): Policy;
+//#endregion
+//#region src/tool.d.ts
+/** Flexible return type for tool execution. Strings and objects are auto-wrapped. */
+type ToolReturn = string | Record<string, unknown> | Content[];
+/** Declarative tool metadata shared between {@link Tool} and the model API. */
+interface ToolDefinition<T = unknown> {
+  /** The tool name exposed to the model. */
+  name: string;
+  /** Description of what the tool does, sent to the model. */
+  description: string;
+  /** Schema for argument validation and JSON Schema extraction. */
+  schema: Schema<T>;
+  /** Maximum execution time in milliseconds before the tool is aborted. */
+  timeout?: number;
+}
+/** A tool the model can invoke. */
+interface Tool<T = unknown> extends ToolDefinition<T> {
+  /** Called before execution. Can skip, stop, or modify arguments. */
+  before?(args: T, ctx: RunContext): void | BeforeToolRunAction | Promise<void | BeforeToolRunAction>;
+  /** Execute the tool with validated arguments. */
+  execute(args: T, ctx: ToolContext): ToolReturn | Promise<ToolReturn>;
+  /** Called after execution. Can rewrite output, retry, or stop the run. */
+  after?(args: T, output: Content[], ctx: RunContext): void | AfterToolRunAction | Promise<void | AfterToolRunAction>;
+}
+/** Create a type-safe {@link Tool}. Schema infers the argument type. */
+declare function defineTool<T>(config: Tool<T>): Tool<T>;
+/** Normalize a {@link ToolReturn} into a {@link Content} array. */
+declare function normalizeToolReturn(value: ToolReturn): Content[];
+//#endregion
+//#region src/model.d.ts
+/** Normalized reason the model stopped generating. */
+type FinishReason = "stop" | "tool_call" | "length" | "stop_sequence" | "cancelled" | "refused" | "error" | "unknown";
+/** Token usage statistics for a model call. */
+interface Usage {
+  /** Number of tokens in the input/prompt. */
+  inputTokens: number;
+  /** Number of tokens in the generated output. */
+  outputTokens: number;
+  /** Total tokens (input + output). */
+  totalTokens: number;
+  /** Tokens read from cache (e.g. Anthropic prompt caching, Google cached content). */
+  cacheReadTokens?: number;
+  /** Tokens written to cache (e.g. Anthropic cache creation). */
+  cacheWriteTokens?: number;
+}
+/** Individual chunks yielded by a model during streaming. */
+type StreamPart = {
+  type: "text_start";
+} | {
+  type: "text_delta";
+  text: string;
+} | {
+  type: "text_end";
+} | {
+  type: "thinking_start";
+  redacted?: boolean;
+} | {
+  type: "thinking_delta";
+  thinking: string;
+} | {
+  type: "thinking_end";
+  signature?: string;
+} | {
+  type: "tool_call_start";
+  id: string;
+  name: string;
+  signature?: string;
+} | {
+  type: "tool_call_delta";
+  id: string;
+  args: string;
+} | {
+  type: "tool_call_end";
+  id: string;
+} | {
+  type: "finish";
+  finishReason: FinishReason;
+  usage: Usage;
+} | {
+  type: "error";
+  error: Error;
+};
+/** Configuration knobs for a model call. */
+interface ModelConfig {
+  /** Maximum tokens to generate. */
+  maxTokens?: number;
+  /** Sampling temperature. */
+  temperature?: number;
+  /** Top-p (nucleus) sampling. */
+  topP?: number;
+  /** Top-k sampling. */
+  topK?: number;
+  /** Stop sequences. */
+  stopSequences?: string[];
+}
+/** A configured model instance returned by a {@link Provider}. */
+interface Model {
+  /** The model identifier (e.g. "claude-sonnet-4-20250514"). */
+  name: string;
+  /** Stream a response as incremental parts. */
+  stream(options: {
+    /** The conversation messages. */messages: Message[]; /** Tool definitions available to the model. */
+    tools?: ToolDefinition[]; /** Per-call config overrides. */
+    config?: ModelConfig; /** Schema for structured output. */
+    output?: Schema; /** Signal for cooperative cancellation. */
+    signal?: AbortSignal;
+  }): AsyncIterable<StreamPart>;
+}
+/** Configuration for a provider connection. */
+interface ProviderConfig {
+  /** API key for authentication. */
+  apiKey?: string;
+  /** Base URL for the API. */
+  baseUrl?: string;
+  /** Request timeout in milliseconds. */
+  timeout?: number;
+  /** Maximum number of retries on transient failures. */
+  maxRetries?: number;
+  /** Additional headers to include in requests. */
+  headers?: Record<string, string>;
+}
+/** Factory for creating {@link Model} instances. */
+interface Provider {
+  /** Create a model instance with optional default config. */
+  model(name: string, config?: ModelConfig): Model;
+}
+/** Create an empty {@link Usage}. */
+declare function emptyUsage(): Usage;
+/** Add two {@link Usage} objects together. */
+declare function addUsage(a: Usage, b: Usage): Usage;
+//#endregion
+//#region src/observer.d.ts
+/** Common fields present on every observer event. */
+interface BaseEvent {
+  /** Event discriminator. */
+  readonly type: string;
+  /** Unique identifier for the current run. */
+  readonly runId: string;
+  /** The current step number (zero-indexed). */
+  readonly step: number;
+  /** The name of the active agent, if applicable. */
+  readonly agent?: string;
+  /** Unix timestamp (ms) when the event was created. */
+  readonly timestamp: number;
+}
+/** Fired when a run begins. */
+interface RunStartEvent extends BaseEvent {
+  readonly type: "runStart";
+  /** The model being used for the run. */
+  readonly model: string;
+  /** System instructions, if provided. */
+  readonly instructions?: string;
+  /** The input prompt. */
+  readonly prompt?: Prompt;
+  /** Names of the tools available to the model. */
+  readonly tools: string[];
+}
+/** Fired when a run completes (successfully or with an error). */
+interface RunFinishEvent extends BaseEvent {
+  readonly type: "runFinish";
+  /** Convenience extraction of the final text output. */
+  readonly text: string;
+  /** The final assistant message. */
+  readonly response: AssistantMessage;
+  /** The full conversation transcript. */
+  readonly transcript: readonly Message[];
+  /** Parsed structured output, if an output schema was provided. */
+  readonly object?: unknown;
+  /** Total number of steps executed. */
+  readonly steps: number;
+  /** Aggregated token usage for the entire run. */
+  readonly usage: Usage;
+  /** Why the run ended. */
+  readonly finishReason: FinishReason;
+  /** The name of the policy that stopped the run, if applicable. */
+  readonly stoppedBy?: string;
+  /** The error, if the run ended due to a failure. */
+  readonly error?: Error;
+  /** Wall-clock duration of the run in milliseconds. */
+  readonly duration: number;
+}
+/** Fired when a step begins (one model call + tool execution cycle). */
+interface StepStartEvent extends BaseEvent {
+  readonly type: "stepStart";
+  /** The model being used for this step (may differ from run start if swapped by a policy). */
+  readonly model: string;
+}
+/** Fired when a step is retried. */
+interface StepRetryEvent extends BaseEvent {
+  readonly type: "stepRetry";
+  /** Why the step is being retried. */
+  readonly reason?: string;
+  /** How many times this step has been retried so far. */
+  readonly retries: number;
+}
+/** Fired when a step completes (model response + all tool executions). */
+interface StepFinishEvent extends BaseEvent {
+  readonly type: "stepFinish";
+  /** Messages produced during this step. */
+  readonly messages: readonly Message[];
+  /** Parsed structured output, if an output schema was provided. */
+  readonly object?: unknown;
+  /** Token usage for this step. */
+  readonly usage: Usage;
+  /** Aggregated token usage across all steps so far. */
+  readonly totalUsage: Usage;
+  /** Why the model stopped generating in this step. */
+  readonly finishReason: FinishReason;
+  /** Wall-clock duration of the step in milliseconds. */
+  readonly duration: number;
+}
+/** Fired after the model responds, before tool execution. */
+interface ResponseFinishEvent extends BaseEvent {
+  readonly type: "responseFinish";
+  /** The assistant message. */
+  readonly message: AssistantMessage;
+  /** Token usage for this response. */
+  readonly usage: Usage;
+  /** Aggregated token usage across all steps so far. */
+  readonly totalUsage: Usage;
+  /** Why the model stopped generating. */
+  readonly finishReason: FinishReason;
+  /** The error, if the response failed. */
+  readonly error?: Error;
+  /** Wall-clock duration of the model call in milliseconds. */
+  readonly duration: number;
+}
+/** Fired when the model begins producing text output. */
+interface TextStartEvent extends BaseEvent {
+  readonly type: "textStart";
+}
+/** Fired for each chunk of text output. */
+interface TextDeltaEvent extends BaseEvent {
+  readonly type: "textDelta";
+  /** The text chunk. */
+  readonly text: string;
+}
+/** Fired when the model finishes producing text output. */
+interface TextStopEvent extends BaseEvent {
+  readonly type: "textStop";
+}
+/** Fired when the model begins a reasoning trace. */
+interface ThinkingStartEvent extends BaseEvent {
+  readonly type: "thinkingStart";
+  /** Whether the thinking content is redacted by the provider. */
+  readonly redacted?: boolean;
+}
+/** Fired for each chunk of reasoning output. */
+interface ThinkingDeltaEvent extends BaseEvent {
+  readonly type: "thinkingDelta";
+  /** The reasoning text chunk. */
+  readonly text: string;
+}
+/** Fired when the model finishes a reasoning trace. */
+interface ThinkingStopEvent extends BaseEvent {
+  readonly type: "thinkingStop";
+}
+/** Fired when the model begins producing a tool call. */
+interface ToolCallStartEvent extends BaseEvent {
+  readonly type: "toolCallStart";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+}
+/** Fired for each chunk of tool call arguments. */
+interface ToolCallDeltaEvent extends BaseEvent {
+  readonly type: "toolCallDelta";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** Partial JSON arguments received so far. */
+  readonly partialArguments: string;
+}
+/** Fired when the model finishes producing a tool call. */
+interface ToolCallStopEvent extends BaseEvent {
+  readonly type: "toolCallStop";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The fully parsed tool call arguments, matching {@link ToolCallPart.arguments}. */
+  readonly arguments: Record<string, unknown>;
+}
+/** Fired when a tool begins executing. */
+interface ToolRunStartEvent extends BaseEvent {
+  readonly type: "toolRunStart";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The arguments passed to the tool. */
+  readonly arguments: Record<string, unknown>;
+}
+/** Fired when a tool emits a progress update via {@link ToolContext.update}. */
+interface ToolRunUpdateEvent extends BaseEvent {
+  readonly type: "toolRunUpdate";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The progress data emitted by the tool. */
+  readonly data: Record<string, unknown>;
+}
+/** Fired when a tool finishes executing. */
+interface ToolRunEndEvent extends BaseEvent {
+  readonly type: "toolRunEnd";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The content returned by the tool. */
+  readonly output: readonly Content[];
+  /** The error, if the tool failed. */
+  readonly error?: Error;
+  /** Wall-clock duration of the tool execution in milliseconds. */
+  readonly duration: number;
+}
+/** Fired when a tool call is skipped by a policy or the tool's own before hook. */
+interface ToolSkipEvent extends BaseEvent {
+  readonly type: "toolSkip";
+  /** The tool call ID, matching {@link ToolCallPart.id}. */
+  readonly id: string;
+  /** The tool name. */
+  readonly name: string;
+  /** The arguments the model passed to the tool. */
+  readonly arguments: Record<string, unknown>;
+  /** Whether the tool was skipped or the entire run was stopped. */
+  readonly action: "skip" | "stop";
+  /** What triggered the skip. */
+  readonly source: "policy" | "tool";
+  /** Human-readable reason for the skip. */
+  readonly reason?: string;
+}
+/** Fired when the run is aborted via the abort signal. */
+interface AbortEvent extends BaseEvent {
+  readonly type: "abort";
+  /** Human-readable reason for the abort. */
+  readonly reason?: string;
+}
+/** Fired when an error occurs during the run. */
+interface ErrorEvent extends BaseEvent {
+  readonly type: "error";
+  /** The error that occurred. */
+  readonly error: Error;
+  /** Where the error originated. */
+  readonly source: "provider" | "tool" | "policy" | "validation" | "observer";
+  /** The tool call that caused the error, if applicable. */
+  readonly toolCall?: ToolCallPart;
+  /** The name of the policy that caused the error, if applicable. */
+  readonly policy?: string;
+  /** The name of the observer that caused the error, if applicable. */
+  readonly observer?: string;
+}
+/** Discriminated union of all observer events. */
+type ObserverEvent = RunStartEvent | RunFinishEvent | StepStartEvent | StepRetryEvent | StepFinishEvent | ResponseFinishEvent | TextStartEvent | TextDeltaEvent | TextStopEvent | ThinkingStartEvent | ThinkingDeltaEvent | ThinkingStopEvent | ToolCallStartEvent | ToolCallDeltaEvent | ToolCallStopEvent | ToolRunStartEvent | ToolRunUpdateEvent | ToolRunEndEvent | ToolSkipEvent | AbortEvent | ErrorEvent;
+/** Auto-generated typed handler for each event (e.g. `onTextDelta`, `onRunFinish`). */
+type EventHandlers = { [E in ObserverEvent as `on${Capitalize<E["type"]>}`]?: (event: E) => void | Promise<void> };
+/**
+* Watches the agent loop and reacts to events.
+*
+* Implement individual `on*` handlers for specific events,
+* or a catch-all {@link Observer.handler} for everything.
+*/
+interface Observer extends EventHandlers {
+  /** A human-readable name for this observer. */
+  name: string;
+  /** Catch-all handler invoked for every event. */
+  handler?(event: ObserverEvent): void | Promise<void>;
+}
+/** Create an {@link Observer}. */
+declare function defineObserver(config: Observer): Observer;
+//#endregion
+//#region src/agent.d.ts
+/** Configuration for creating an agent. */
+interface AgentConfig {
+  /** Human-readable name for this agent, used in events and error attribution. */
+  name?: string;
+  /** The model instance to use. */
+  model: Model;
+  /** System instructions that guide model behavior. */
+  instructions?: string;
+  /** Tools available to the agent. */
+  tools?: Tool[];
+  /** Observers that watch the agent loop. */
+  observers?: Observer[];
+  /** Policies that govern the agent loop. */
+  policies?: Policy[];
+}
+/** Per-run overrides passed to {@link Agent.run} or {@link Agent.stream}. */
+interface RunOptions extends Partial<ModelConfig> {
+  /** Existing transcript to continue from. */
+  transcript?: Message[];
+  /** Additional observers merged with the agent's observers. */
+  observers?: Observer[];
+  /** Additional policies merged with the agent's policies. */
+  policies?: Policy[];
+  /** Schema for structured output. */
+  output?: Schema;
+  /** Initial state for the run context. */
+  state?: Record<string, unknown>;
+  /** Signal for cooperative cancellation. */
+  signal?: AbortSignal;
+}
+/** The result of an agent run. */
+interface AgentResult<TOutput = unknown> {
+  /** Convenience extraction of the final text output. */
+  readonly text: string;
+  /** The final assistant message. */
+  readonly response: AssistantMessage;
+  /** The full conversation transcript. */
+  readonly transcript: readonly Message[];
+  /** Total number of steps executed. */
+  readonly steps: number;
+  /** Aggregated token usage for the entire run. */
+  readonly usage: Usage;
+  /** Why the run ended. */
+  readonly finishReason: FinishReason;
+  /** The name of the policy that stopped the run, if applicable. */
+  readonly stoppedBy?: string;
+  /** The error, if the run ended due to a failure. */
+  readonly error?: Error;
+  /** Wall-clock duration of the run in milliseconds. */
+  readonly duration: number;
+  /** Parsed structured output, if an output schema was provided. */
+  readonly object?: TOutput | null;
+}
+/** An async iterable of observer events with access to the final result. */
+interface AgentStream<TOutput = unknown> extends AsyncIterable<ObserverEvent> {
+  /** Resolves to the final result when the run completes. */
+  readonly result: Promise<AgentResult<TOutput>>;
+}
+/** Configuration for converting an agent into a {@link Tool} via {@link Agent.asTool}. */
+interface AsToolConfig<TArgs> {
+  /** The tool name exposed to the parent agent. */
+  name: string;
+  /** Description of what this sub-agent does. */
+  description: string;
+  /** Schema for the tool's arguments. */
+  schema: Schema<TArgs>;
+  /** Build the prompt from the parsed arguments. */
+  prompt(args: TArgs): Prompt;
+  /** Transform the agent result into tool output. Defaults to returning the text. */
+  output?(result: AgentResult): ToolReturn;
+}
+/** An agent that runs a model loop with tools, policies, and observers. */
+interface Agent {
+  /** Run the agent to completion and return the result. */
+  run<T>(prompt: Prompt | undefined, options: RunOptions & {
+    output: Schema<T>;
+  }): Promise<AgentResult<T>>;
+  run(prompt?: Prompt, options?: RunOptions): Promise<AgentResult>;
+  /** Run the agent and stream observer events as they occur. */
+  stream<T>(prompt: Prompt | undefined, options: RunOptions & {
+    output: Schema<T>;
+  }): AgentStream<T>;
+  stream(prompt?: Prompt, options?: RunOptions): AgentStream;
+  /** Convert this agent into a tool for use by another agent. */
+  asTool<TArgs>(config: AsToolConfig<TArgs>): Tool;
+}
+/** Create an {@link Agent} from the given configuration. */
+declare function defineAgent(config: AgentConfig): Agent;
+//#endregion
+export { type AbortEvent, type AfterResponseAction, type AfterStepAction, type AfterToolRunAction, type Agent, type AgentConfig, type AgentResult, type AgentStream, type AsToolConfig, type AssistantContent, type AssistantMessage, type BaseEvent, type BeforeStepAction, type BeforeToolRunAction, type BlobPart, type Content, type ErrorEvent, type FinishReason, type Infer, type JsonPart, type Message, type Model, type ModelConfig, type Observer, type ObserverEvent, type Policy, type Prompt, type Provider, type ProviderConfig, type ResponseFinishEvent, type ResponseInfo, type RunContext, type RunFinishEvent, type RunOptions, type RunStartEvent, type Schema, type StepFinishEvent, type StepInfo, type StepPlan, type StepRetryEvent, type StepStartEvent, type StreamPart, type SystemContent, type SystemMessage, type TextDeltaEvent, type TextPart, type TextStartEvent, type TextStopEvent, type ThinkingDeltaEvent, type ThinkingPart, type ThinkingStartEvent, type ThinkingStopEvent, type Tool, type ToolCallDeltaEvent, type ToolCallInfo, type ToolCallPart, type ToolCallStartEvent, type ToolCallStopEvent, type ToolContent, type ToolContext, type ToolDefinition, type ToolMessage, type ToolResultInfo, type ToolResultPart, type ToolReturn, type ToolRunEndEvent, type ToolRunStartEvent, type ToolRunUpdateEvent, type ToolSkipEvent, type URLPart, type Usage, type UserContent, type UserMessage, addUsage, assistant, blob, defineAgent, defineObserver, definePolicy, defineTool, emptyUsage, json, normalizePrompt, normalizeToolReturn, schemaToJsonSchema, system, text, url, user };
+//# sourceMappingURL=index.d.mts.map