@funkai/agents 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,2883 @@
+import { AsyncIterableStream, AsyncIterableStream as AsyncIterableStream$1, LanguageModel as LanguageModel$1, ModelMessage, Output, Output as Output$1, TextStreamPart, TextStreamPart as TextStreamPart$1, ToolSet, ToolSet as ToolSet$1, tool as tool$1 } from "ai";
+import { ZodType } from "zod";
+import { OpenRouterProvider, OpenRouterProviderSettings } from "@openrouter/ai-sdk-provider";
+import { LiteralUnion } from "type-fest";
+
+//#region src/core/tool.d.ts
+/**
+ * Configuration for creating a tool.
+ *
+ * @typeParam TInput - Input type, inferred from the `inputSchema` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `execute` return.
+ */
+interface ToolConfig<TInput, TOutput> {
+  /**
+   * Human-readable description of what the tool does.
+   *
+   * Shown to the model alongside the tool name. A good description
+   * helps the model decide when and how to call the tool.
+   */
+  description: string;
+  /**
+   * Display title for the tool.
+   *
+   * Optional human-readable title shown in UIs and logs.
+   */
+  title?: string;
+  /**
+   * Zod schema for validating and typing tool input.
+   *
+   * The schema is serialized to JSON Schema and sent to the model.
+   * Input from the model is validated against it before `execute`
+   * is called.
+   */
+  inputSchema: ZodType<TInput>;
+  /**
+   * Zod schema for validating tool output.
+   *
+   * When provided, the return value of `execute` is validated
+   * against this schema before being sent back to the model.
+   */
+  outputSchema?: ZodType<TOutput>;
+  /**
+   * Example inputs to guide the model.
+   *
+   * Helps the model understand expected input structure. Natively
+   * supported by Anthropic; for other providers, use
+   * `addToolInputExamplesMiddleware` to inject examples into the
+   * tool description.
+   */
+  inputExamples?: Array<{
+    input: TInput;
+  }>;
+  /**
+   * Execute the tool with validated input.
+   *
+   * Called by the framework after the model requests a tool call and
+   * the input passes schema validation.
+   *
+   * @param input - The validated tool input.
+   * @returns The tool output returned to the model.
+   */
+  execute: (input: TInput) => Promise<TOutput>;
+}
+/**
+ * A tool instance — the return type of `tool()` / `ai.tool()`.
+ *
+ * Defaults use `any` so `Record<string, Tool>` accepts concrete
+ * typed tools without contravariance issues (same pattern as
+ * {@link SubAgents}).
+ *
+ * @typeParam TInput - Tool input type.
+ * @typeParam TOutput - Tool output type.
+ */
+type Tool<TInput = any, TOutput = any> = ReturnType<typeof tool$1<TInput, TOutput>>;
+/**
+ * Create a tool for AI agent function calling.
+ *
+ * Wraps the AI SDK's `tool()` helper. The `inputSchema` (and optional
+ * `outputSchema`) are wrapped via `zodSchema()` so the AI SDK can
+ * convert them to JSON Schema and validate model I/O at runtime.
+ *
+ * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/tool
+ *
+ * @example
+ * ```typescript
+ * const fetchPage = tool({
+ *   description: 'Fetch the contents of a web page by URL',
+ *   inputSchema: z.object({
+ *     url: z.url(),
+ *   }),
+ *   execute: async ({ url }) => {
+ *     const res = await fetch(url)
+ *     return {
+ *       url,
+ *       status: res.status,
+ *       body: await res.text(),
+ *     }
+ *   },
+ * })
+ * ```
+ */
+declare function tool<TInput, TOutput>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+//#endregion
+//#region src/core/agents/base/output.d.ts
+/**
+ * Base constraint for AI SDK output strategies.
+ *
+ * Reaches through the `Output` namespace to the underlying
+ * `Output<OUTPUT, PARTIAL, ELEMENT>` interface. Use this as the
+ * type for any field that accepts `Output.text()`, `Output.object()`, etc.
+ */
+type OutputSpec = Output$1.Output<unknown, unknown>;
+/**
+ * Accepted values for the `output` config field.
+ *
+ * Allows either:
+ * - An AI SDK `Output` strategy (`Output.text()`, `Output.object()`, etc.)
+ * - A raw Zod schema — automatically wrapped in `Output.object()` or
+ *   `Output.array()` depending on the schema type.
+ */
+type OutputParam = OutputSpec | ZodType;
+/**
+ * Resolve an `OutputParam` into an `OutputSpec`.
+ *
+ * If the value is already an `OutputSpec`, it is returned as-is.
+ * If it is a raw Zod schema:
+ * - `z.array(...)` → `Output.array({ element: innerSchema })`
+ * - Anything else → `Output.object({ schema })`
+ *
+ * @internal
+ */
+declare function resolveOutput(output: OutputParam): OutputSpec;
+//#endregion
+//#region src/core/logger.d.ts
+/**
+ * Pino-compatible leveled logger with child logger support.
+ *
+ * Consumers inject a pino instance (or any compatible logger);
+ * the SDK defines only the interface. Each method supports both
+ * `(msg, meta?)` and `(meta, msg)` call signatures to match pino's API.
+ *
+ * Child loggers accumulate bindings from parents — the framework
+ * uses `child()` at each scope boundary (workflow, step, agent)
+ * so log output automatically includes execution context.
+ */
+interface Logger {
+  /**
+   * Log a message at the DEBUG level.
+   *
+   * Use for verbose diagnostic output that is typically silenced
+   * in production (e.g. intermediate state, resolved config).
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the DEBUG level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  debug(meta: Record<string, unknown>, msg: string): void;
+  /**
+   * Log a message at the INFO level.
+   *
+   * Use for routine operational events worth recording — step
+   * transitions, successful completions, and notable state changes.
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  info(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the INFO level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  info(meta: Record<string, unknown>, msg: string): void;
+  /**
+   * Log a message at the WARN level.
+   *
+   * Use for recoverable problems that do not halt execution but
+   * may indicate degraded behavior (e.g. retries, fallback paths).
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the WARN level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  warn(meta: Record<string, unknown>, msg: string): void;
+  /**
+   * Log a message at the ERROR level.
+   *
+   * Use for failures that prevent an operation from completing
+   * successfully — unhandled exceptions, rejected promises, or
+   * invariant violations.
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  error(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the ERROR level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  error(meta: Record<string, unknown>, msg: string): void;
+  /**
+   * Create a child logger that inherits all parent bindings.
+   *
+   * The returned logger automatically includes the merged bindings
+   * in every log entry. The framework calls `child()` at each scope
+   * boundary (workflow, step, agent) so downstream logs carry full
+   * execution context without manual threading.
+   *
+   * @param bindings - Key-value pairs merged into every log entry
+   *   produced by the child (and its descendants).
+   * @returns A new {@link Logger} with the accumulated bindings.
+   */
+  child(bindings: Record<string, unknown>): Logger;
+}
+/**
+ * Create a minimal console-based logger satisfying the {@link Logger} interface.
+ *
+ * Supports `child()` by merging bindings into a prefix object.
+ * Each log call prepends the accumulated bindings to the output.
+ *
+ * Used as the default when no pino-compatible logger is injected.
+ */
+declare function createDefaultLogger(bindings?: Record<string, unknown>): Logger;
+//#endregion
+//#region src/core/models/index.d.ts
+declare const GENERATED_MODELS: readonly [{
+  readonly id: "openai/gpt-5.2-codex";
+  readonly category: "coding";
+  readonly pricing: {
+    readonly prompt: 0.00000175;
+    readonly completion: 0.000014;
+    readonly inputCacheRead: 1.75e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-5.2";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 0.00000175;
+    readonly completion: 0.000014;
+    readonly inputCacheRead: 1.75e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-5.1";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 0.00000125;
+    readonly completion: 0.00001;
+    readonly inputCacheRead: 1.25e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-5";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 0.00000125;
+    readonly completion: 0.00001;
+    readonly inputCacheRead: 1.25e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-5-mini";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 2.5e-7;
+    readonly completion: 0.000002;
+    readonly inputCacheRead: 2.5e-8;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-5-nano";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 5e-8;
+    readonly completion: 4e-7;
+    readonly inputCacheRead: 5e-9;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-4.1";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 0.000002;
+    readonly completion: 0.000008;
+    readonly inputCacheRead: 5e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-4.1-mini";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 4e-7;
+    readonly completion: 0.0000016;
+    readonly inputCacheRead: 1e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-4.1-nano";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 1e-7;
+    readonly completion: 4e-7;
+    readonly inputCacheRead: 2.5e-8;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/gpt-4o";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 0.0000025;
+    readonly completion: 0.00001;
+    readonly inputCacheRead: 0.00000125;
+  };
+}, {
+  readonly id: "openai/gpt-4o-mini";
+  readonly category: "chat";
+  readonly pricing: {
+    readonly prompt: 1.5e-7;
+    readonly completion: 6e-7;
+    readonly inputCacheRead: 7.5e-8;
+  };
+}, {
+  readonly id: "openai/o3";
+  readonly category: "reasoning";
+  readonly pricing: {
+    readonly prompt: 0.000002;
+    readonly completion: 0.000008;
+    readonly inputCacheRead: 5e-7;
+    readonly webSearch: 0.01;
+  };
+}, {
+  readonly id: "openai/o3-mini";
+  readonly category: "reasoning";
+  readonly pricing: {
+    readonly prompt: 0.0000011;
+    readonly completion: 0.0000044;
+    readonly inputCacheRead: 5.5e-7;
+  };
+}, {
+  readonly id: "openai/o4-mini";
+  readonly category: "reasoning";
+  readonly pricing: {
+    readonly prompt: 0.0000011;
+    readonly completion: 0.0000044;
+    readonly inputCacheRead: 2.75e-7;
+    readonly webSearch: 0.01;
+  };
+}];
+/**
+ * Supported OpenRouter model identifiers, derived from the generated {@link MODELS} array.
+ */
+type OpenRouterLanguageModelId = (typeof GENERATED_MODELS)[number]["id"];
+/**
+ * A model identifier that suggests known OpenRouter models but accepts any string.
+ *
+ * Provides autocomplete for cataloged models while allowing arbitrary
+ * model IDs for new or custom models not yet in the catalog.
+ */
+type ModelId = LiteralUnion<OpenRouterLanguageModelId, string>;
+/**
+ * Model category for classification and filtering.
+ */
+type ModelCategory = "chat" | "coding" | "reasoning";
+/**
+ * Per-model pricing in USD per token.
+ *
+ * Field names match the OpenRouter API convention. All values are
+ * per-token (or per-unit) rates as numbers. Optional fields are
+ * omitted when the provider does not support them.
+ */
+interface ModelPricing {
+  /** Cost per input (prompt) token. */
+  prompt: number;
+  /** Cost per output (completion) token. */
+  completion: number;
+  /** Cost per cached input token (read). */
+  inputCacheRead?: number;
+  /** Cost per cached input token (write). */
+  inputCacheWrite?: number;
+  /** Cost per web search request. */
+  webSearch?: number;
+  /** Cost per internal reasoning token. */
+  internalReasoning?: number;
+  /** Cost per image input token. */
+  image?: number;
+  /** Cost per audio input second. */
+  audio?: number;
+  /** Cost per audio output second. */
+  audioOutput?: number;
+}
+/**
+ * Model definition with metadata and pricing.
+ */
+interface ModelDefinition {
+  /** OpenRouter model identifier (e.g. `"openai/gpt-5.2-codex"`). */
+  id: string;
+  /** Model category for classification. */
+  category: ModelCategory;
+  /** Token pricing rates. */
+  pricing: ModelPricing;
+}
+/**
+ * Look up a model definition by its identifier.
+ *
+ * @param id - The model identifier to look up.
+ * @returns The matching model definition.
+ * @throws {Error} If no model matches the given ID.
+ *
+ * @example
+ * ```typescript
+ * const m = model('openai/gpt-5.2-codex')
+ * console.log(m.pricing.prompt) // 0.00000175
+ * console.log(m.category)       // 'coding'
+ * ```
+ */
+declare function model(id: ModelId): ModelDefinition;
+/**
+ * Look up a model definition by its identifier, returning `undefined` if not found.
+ *
+ * Unlike {@link model}, this does not throw for unknown IDs — useful when
+ * the caller can gracefully handle missing pricing (e.g. non-OpenRouter models).
+ *
+ * @param id - The model identifier to look up.
+ * @returns The matching model definition, or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const m = tryModel('anthropic/claude-sonnet-4-20250514')
+ * if (m) {
+ *   console.log(m.pricing.prompt)
+ * }
+ * ```
+ */
+declare function tryModel(id: ModelId): ModelDefinition | undefined;
+/**
+ * Return supported model definitions, optionally filtered.
+ *
+ * @param filter - Optional predicate to filter models.
+ * @returns A readonly array of matching model definitions.
+ *
+ * @example
+ * ```typescript
+ * const all = models()
+ * const reasoning = models((m) => m.category === 'reasoning')
+ * ```
+ */
+declare function models(filter?: (m: ModelDefinition) => boolean): readonly ModelDefinition[];
+//#endregion
+//#region src/core/provider/types.d.ts
+/**
+ * AI SDK v3 language model type.
+ *
+ * Narrowed to the v3 specification version for type safety.
+ * All models created via `openrouter()` or `wrapModel()` satisfy this type.
+ */
+type LanguageModel = Extract<LanguageModel$1, {
+  specificationVersion: "v3";
+}>;
+/**
+ * Base token counts shared by raw tracking records and final output.
+ *
+ * All fields are resolved `number` (0 when absent).
+ */
+interface TokenUsage {
+  /** Number of input (prompt) tokens. */
+  readonly inputTokens: number;
+  /** Number of output (completion) tokens. */
+  readonly outputTokens: number;
+  /** Total tokens (input + output). */
+  readonly totalTokens: number;
+  /** Tokens served from the provider's prompt cache. */
+  readonly cacheReadTokens: number;
+  /** Tokens written into the provider's prompt cache. */
+  readonly cacheWriteTokens: number;
+  /** Tokens consumed by the model's internal reasoning (e.g. o3/o4). */
+  readonly reasoningTokens: number;
+}
+/**
+ * Raw tracking record from a single AI model invocation.
+ *
+ * Fields are `number | undefined` because providers may not report all fields.
+ * Carries `modelId` so that consumers can look up pricing if needed.
+ */
+interface TokenUsageRecord {
+  /**
+   * The model identifier that produced this usage
+   * (e.g. `"openai/gpt-5.2-codex"`).
+   */
+  readonly modelId: ModelId;
+  /** Number of input (prompt) tokens. */
+  readonly inputTokens: number | undefined;
+  /** Number of output (completion) tokens. */
+  readonly outputTokens: number | undefined;
+  /** Total tokens (input + output). */
+  readonly totalTokens: number | undefined;
+  /** Tokens served from the provider's prompt cache. */
+  readonly cacheReadTokens: number | undefined;
+  /** Tokens written into the provider's prompt cache. */
+  readonly cacheWriteTokens: number | undefined;
+  /** Tokens consumed by the model's internal reasoning (e.g. o3/o4). */
+  readonly reasoningTokens: number | undefined;
+  /**
+   * Populated by the framework — identifies which component produced this usage.
+   */
+  readonly source?: {
+    readonly workflowId?: string;
+    readonly stepId?: string;
+    readonly agentId: string;
+    readonly scope: readonly string[];
+  };
+}
+/**
+ * Final agent-level usage — tokens flat, with agentId.
+ *
+ * Produced by `agentUsage()` at the end of an agent's execution.
+ */
+interface AgentTokenUsage extends TokenUsage {
+  /** The agent that produced this usage. */
+  readonly agentId: string;
+}
+/**
+ * Final flow agent-level usage — per-agent breakdown.
+ *
+ * Produced by `flowAgentUsage()` at the end of a flow agent's execution.
+ */
+interface FlowAgentTokenUsage {
+  /** Per-agent usage entries. */
+  readonly usages: readonly AgentTokenUsage[];
+}
+//#endregion
+//#region src/utils/result.d.ts
+/**
+ * Error information returned when an SDK operation fails.
+ *
+ * Every public method returns `Result<T>` instead of throwing.
+ * When `ok` is `false`, the error details are available on this interface.
+ */
+interface ResultError {
+  /**
+   * Machine-readable error code.
+   *
+   * Identifies the category of failure. Stable across versions —
+   * safe to match against in application code.
+   *
+   * @example
+   * ```typescript
+   * switch (result.error.code) {
+   *   case 'VALIDATION_ERROR': // input schema failed
+   *   case 'ABORT_ERROR':      // signal was aborted
+   *   case 'AGENT_ERROR':      // agent execution failed
+   * }
+   * ```
+   */
+  code: string;
+  /**
+   * Human-readable error description.
+   *
+   * Suitable for logging but not for programmatic matching —
+   * use `code` for that.
+   */
+  message: string;
+  /**
+   * Original thrown error, if any.
+   *
+   * Preserved so callers can inspect the root cause when the
+   * SDK catches and wraps an exception.
+   */
+  cause?: Error;
+}
+/**
+ * Discriminated union for SDK operation results.
+ *
+ * Success fields are **flat on the object** — no `.value` wrapper.
+ * Callers pattern-match on `ok` instead of using try/catch.
+ *
+ * @typeParam T - The success payload shape. All fields from `T` are
+ *   spread directly onto the success branch alongside `ok: true`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate({ topic: 'TypeScript' })
+ *
+ * if (!result.ok) {
+ *   // Error branch — only `ok` and `error` are present.
+ *   console.error(result.error.code, result.error.message)
+ *   return
+ * }
+ *
+ * // Success branch — all fields from T are directly on result.
+ * console.log(result.output)
+ * console.log(result.duration)
+ * console.log(result.trace)
+ * ```
+ */
+type Result<T> = (T & {
+  ok: true;
+}) | {
+  ok: false;
+  error: ResultError;
+};
+/**
+ * Create a success `Result`.
+ *
+ * Spreads the payload flat onto the object alongside `ok: true`.
+ *
+ * @param value - The success payload.
+ * @returns A success `Result<T>`.
+ *
+ * @example
+ * ```typescript
+ * return ok({ output: 'hello', messages: [] })
+ * // → { ok: true, output: 'hello', messages: [] }
+ * ```
+ */
+declare function ok<T extends Record<string, unknown>>(value: T): T & {
+  ok: true;
+};
+/**
+ * Create a failure `Result`.
+ *
+ * @param code - Machine-readable error code.
+ * @param message - Human-readable error description.
+ * @param cause - Optional original thrown error.
+ * @returns A failure `Result` for any `T`.
+ *
+ * @example
+ * ```typescript
+ * return err('VALIDATION_ERROR', 'Name is required')
+ * return err('AGENT_ERROR', error.message, error)
+ * ```
+ */
+declare function err(code: string, message: string, cause?: Error): {
+  ok: false;
+  error: ResultError;
+};
+/**
+ * Narrow a `Result<T>` to its success branch.
+ *
+ * @param result - The result to check.
+ * @returns `true` when `result.ok` is `true`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate('hello')
+ * if (isOk(result)) {
+ *   console.log(result.output)
+ * }
+ * ```
+ */
+declare function isOk<T>(result: Result<T>): result is T & {
+  ok: true;
+};
+/**
+ * Narrow a `Result<T>` to its failure branch.
+ *
+ * @param result - The result to check.
+ * @returns `true` when `result.ok` is `false`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate('hello')
+ * if (isErr(result)) {
+ *   console.error(result.error.code, result.error.message)
+ * }
+ * ```
+ */
+declare function isErr<T>(result: Result<T>): result is {
+  ok: false;
+  error: ResultError;
+};
+//#endregion
+//#region src/core/types.d.ts
+/**
+ * A model reference.
+ *
+ * Accepts either:
+ * - A **string model ID** (e.g. `'openai/gpt-4.1'`) resolved via
+ *   OpenRouter at runtime.
+ * - An **AI SDK `LanguageModel` instance** — including models wrapped
+ *   with middleware via `wrapLanguageModel()`.
+ *
+ * @example
+ * ```typescript
+ * // String ID — resolved via OpenRouter
+ * const agent1 = agent({
+ *   name: 'my-agent',
+ *   model: 'openai/gpt-4.1',
+ *   system: 'You are helpful.',
+ * })
+ *
+ * // AI SDK provider instance
+ * import { openai } from '@ai-sdk/openai'
+ * const agent2 = agent({
+ *   name: 'my-agent',
+ *   model: openai('gpt-4.1'),
+ *   system: 'You are helpful.',
+ * })
+ *
+ * // Middleware-wrapped model
+ * import { wrapLanguageModel, extractReasoningMiddleware } from 'ai'
+ * import { anthropic } from '@ai-sdk/anthropic'
+ * const agent3 = agent({
+ *   name: 'reasoner',
+ *   model: wrapLanguageModel({
+ *     model: anthropic('claude-sonnet-4-5-20250929'),
+ *     middleware: extractReasoningMiddleware({ tagName: 'think' }),
+ *   }),
+ *   system: 'Think step by step.',
+ * })
+ * ```
+ */
+type Model = string | LanguageModel$1;
+/** @deprecated Use `Model` instead. */
+type ModelRef = Model;
+/**
+ * A value that can be generated against — the shared contract
+ * between Agent and Workflow.
+ *
+ * Both `Agent` and `Workflow` satisfy this interface. Any API that
+ * accepts a `Runnable` works with either.
+ */
+interface Runnable<TInput = unknown, TOutput = unknown> {
+  generate(input: TInput, config?: any): Promise<Result<{
+    output: TOutput;
+  }>>;
+  stream(input: TInput, config?: any): Promise<Result<{
+    output: Promise<TOutput>;
+    fullStream: AsyncIterableStream$1<StreamPart>;
+  }>>;
+  fn(): (input: TInput, config?: any) => Promise<Result<{
+    output: TOutput;
+  }>>;
+}
+//#endregion
+//#region src/core/agents/base/types.d.ts
+/**
+ * Concrete stream event type re-exported from the Vercel AI SDK.
+ *
+ * This is `TextStreamPart<ToolSet>` — the discriminated union of all
+ * possible stream events (`text-delta`, `tool-call`, `tool-result`,
+ * `finish`, `error`, etc.). Use `part.type` to discriminate.
+ */
+type StreamPart = TextStreamPart$1<ToolSet$1>;
+type SubAgents = Record<string, Agent<any, any, any, any>>;
+/**
+ * Chat message type.
+ *
+ * Re-exported from the Vercel AI SDK (`ModelMessage`). Used for
+ * multi-turn conversations, message arrays, and tool-call history.
+ */
+type Message = ModelMessage;
+/**
+ * Result of a completed agent generation.
+ *
+ * Mirrors the AI SDK's `GenerateTextResult`. The `output` field is
+ * typed based on the agent's configured Output variant.
+ *
+ * @typeParam TOutput - The output type.
+ *   - `string` for `Output.text()` (the default).
+ *   - `T` for `Output.object({ schema })`.
+ *   - `T[]` for `Output.array({ element })`.
+ *   - `T` for `Output.choice({ options })`.
+ */
+interface GenerateResult<TOutput = string> {
+  /**
+   * The generation output.
+   *
+   * Type depends on the configured `Output` variant:
+   * - `string` when using `Output.text()` (default).
+   * - `T` when using `Output.object<T>({ schema })`.
+   * - `T[]` when using `Output.array<T>({ element })`.
+   * - One of the option strings when using `Output.choice()`.
+   */
+  output: TOutput;
+  /**
+   * Full message history including tool calls.
+   *
+   * Contains the complete conversation from the generation,
+   * including system messages, user prompts, assistant responses,
+   * and tool call/result pairs.
+   */
+  messages: Message[];
+  /**
+   * Aggregated token usage across all tool-loop steps.
+   *
+   * Includes input, output, cache, and reasoning token counts.
+   * All fields are resolved numbers (0 when the provider does not
+   * report a given field).
+   */
+  usage: TokenUsage;
+  /**
+   * The reason the model stopped generating.
+   *
+   * Common values: `"stop"`, `"length"`, `"content-filter"`,
+   * `"tool-calls"`, `"error"`, `"other"`.
+   */
+  finishReason: string;
+}
+/**
+ * Result of a streaming agent generation.
+ *
+ * The `fullStream` emits typed `StreamPart` events as they arrive —
+ * text deltas, tool calls, tool results, step boundaries, finish,
+ * and errors. Implements both `AsyncIterable` and `ReadableStream`
+ * so consumers can use `for await...of` or `.getReader()`.
+ *
+ * `output` and `messages` are promises that resolve once the stream
+ * has been fully consumed.
+ *
+ * @typeParam TOutput - The output type (available after stream completes).
+ */
+interface StreamResult<TOutput = string> {
+  /**
+   * The generation output.
+   *
+   * Resolves after the stream completes. Same typing rules as
+   * `GenerateResult.output`.
+   */
+  output: Promise<TOutput>;
+  /**
+   * Full message history.
+   *
+   * Resolves after the stream completes. Contains the complete
+   * conversation including tool calls.
+   */
+  messages: Promise<Message[]>;
+  /**
+   * Aggregated token usage across all tool-loop steps.
+   *
+   * Resolves after the stream completes. Includes input, output,
+   * cache, and reasoning token counts.
+   */
+  usage: Promise<TokenUsage>;
+  /**
+   * The reason the model stopped generating.
+   *
+   * Resolves after the stream completes. Common values: `"stop"`,
+   * `"length"`, `"content-filter"`, `"tool-calls"`, `"error"`, `"other"`.
+   */
+  finishReason: Promise<string>;
+  /**
+   * The full stream of typed events.
+   *
+   * Emits `StreamPart` events (a discriminated union from the AI SDK)
+   * including `text-delta`, `tool-call`, `tool-result`, `finish`,
+   * `error`, and more. Use `part.type` to discriminate.
+   *
+   * Supports both `for await (const part of fullStream)` and
+   * `fullStream.getReader()`.
+   */
+  fullStream: AsyncIterableStream$1<StreamPart>;
+}
+/**
+ * Per-call overrides for agent generation.
+ *
+ * Passed as the optional second parameter to `.generate()` or `.stream()`.
+ * Override fields replace the base config for that call only. Per-call
+ * hooks **merge** with base hooks — base fires first, then call-level.
+ *
+ * @typeParam TTools - The agent's tool record type.
+ * @typeParam TSubAgents - The agent's subagent record type.
+ */
+interface AgentOverrides<TTools extends Record<string, Tool> = Record<string, Tool>, TSubAgents extends SubAgents = Record<string, never>> {
+  /**
+   * Override the logger for this call.
+   *
+   * When an agent runs inside a workflow step (`$.agent()`), the
+   * framework passes the step's scoped logger so agent logs include
+   * workflow and step context bindings.
+   */
+  logger?: Logger;
+  /**
+   * Abort signal for cancellation.
+   *
+   * When fired, the agent should stop generation and clean up.
+   */
+  signal?: AbortSignal;
+  /**
+   * Override the model for this call.
+   *
+   * Accepts a string model ID or an AI SDK `LanguageModel` instance.
+   */
+  model?: Model;
+  /**
+   * Override the system prompt for this call.
+   *
+   * Can be a static string or a function that receives the input
+   * and returns the system prompt.
+   */
+  system?: string | ((params: {
+    input: unknown;
+  }) => string);
+  /**
+   * Override or extend tools for this call.
+   *
+   * Merged with the agent's base tools. Use `Partial<TTools>` to
+   * replace specific tools, or add new ones via the index signature.
+   */
+  tools?: Partial<TTools> & Record<string, Tool>;
+  /**
+   * Override or extend subagents for this call.
+   *
+   * Merged with the agent's base subagents.
+   */
+  agents?: Partial<TSubAgents> & Record<string, Agent>;
+  /**
+   * Override max tool-loop steps for this call.
+   *
+   * Controls how many tool-loop iterations the agent will run
+   * before stopping.
+   */
+  maxSteps?: number;
+  /**
+   * Override or set the output type for this call.
+   *
+   * Accepts an AI SDK `Output` strategy or a raw Zod schema:
+   * - `Output.text()`, `Output.object()`, `Output.array()`, `Output.choice()`
+   * - `z.object({ ... })` → auto-wrapped as `Output.object({ schema })`
+   * - `z.array(z.object({ ... }))` → auto-wrapped as `Output.array({ element })`
+   */
+  output?: OutputParam;
+  /**
+   * Per-call hook — fires after base `onStart`.
+   *
+   * @param event - Event containing the input.
+   * @param event.input - The input passed to `.generate()` or `.stream()`.
+   */
+  onStart?: (event: {
+    input: unknown;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onFinish`.
+   *
+   * @param event - Event containing the input, result, and duration.
+   * @param event.input - The input passed to `.generate()` or `.stream()`.
+   * @param event.result - The generation result.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    input: unknown;
+    result: GenerateResult;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onError`.
+   *
+   * @param event - Event containing the input and error.
+   * @param event.input - The input passed to `.generate()` or `.stream()`.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    input: unknown;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onStepFinish`.
+   *
+   * @param event - Event containing the step ID.
+   * @param event.stepId - The ID of the tool-loop step that completed.
+   */
+  onStepFinish?: (event: {
+    stepId: string;
+    toolCalls: readonly {
+      toolName: string;
+      argsTextLength: number;
+    }[];
+    toolResults: readonly {
+      toolName: string;
+      resultTextLength: number;
+    }[];
+    usage: {
+      inputTokens: number;
+      outputTokens: number;
+      totalTokens: number;
+    };
+  }) => void | Promise<void>;
+}
+/**
+ * Configuration for creating an agent.
+ *
+ * Supports two modes:
+ *
+ * | Config | `.generate()` first param | How prompt is built |
+ * |---|---|---|
+ * | `input` + `prompt` provided | Typed `TInput` | `prompt({ input })` renders it |
+ * | Both omitted | `string \| Message[]` | Passed directly to the model |
+ *
+ * @typeParam TInput - Agent input type (default: `string | Message[]`).
+ * @typeParam TOutput - Agent output type (default: `string`).
+ * @typeParam TTools - Record of tools available to this agent.
+ * @typeParam TSubAgents - Record of subagents available to this agent.
+ */
+interface AgentConfig<TInput, TOutput, TTools extends Record<string, Tool>, TSubAgents extends SubAgents> {
+  /**
+   * Unique agent name.
+   *
+   * Used in logging, trace entries, and hook events.
+   */
+  name: string;
+  /**
+   * Model to use for generation.
+   *
+   * Accepts a string model ID (resolved via OpenRouter) or an
+   * AI SDK `LanguageModel` instance — including middleware-wrapped models.
+   *
+   * @see {@link Model}
+   */
+  model: Model;
+  /**
+   * Zod schema for the agent's typed input.
+   *
+   * When provided alongside `prompt`, `.generate()` accepts `TInput`
+   * as its first param and validates it against this schema.
+   *
+   * When omitted, `.generate()` accepts a raw `string` or `Message[]`
+   * instead (simple mode).
+   */
+  input?: ZodType<TInput>;
+  /**
+   * Map typed input to the prompt sent to the model.
+   *
+   * Required when `input` is provided. Ignored when `input` is
+   * omitted (the raw string/messages are used directly in simple mode).
+   *
+   * @param params - Object containing the validated input.
+   * @param params.input - The validated input value.
+   * @returns The prompt string or message array to send to the model.
+   */
+  prompt?: (params: {
+    input: TInput;
+  }) => string | Message[];
+  /**
+   * System prompt.
+   *
+   * Can be a static string or a function that receives the validated
+   * input and returns the system prompt dynamically.
+   */
+  system?: string | ((params: {
+    input: TInput;
+  }) => string);
+  /**
+   * Tools available to this agent for function calling.
+   *
+   * Each tool is exposed to the model in the tool-loop. The model
+   * can call these tools to gather information or perform actions.
+   */
+  tools?: TTools;
+  /**
+   * Subagents — automatically wrapped as tools the agent can delegate to.
+   *
+   * Each subagent becomes a callable tool that the parent agent can
+   * invoke. Abort signals propagate automatically from parent to child.
+   */
+  agents?: TSubAgents;
+  /**
+   * Maximum tool-loop iterations.
+   *
+   * Controls how many times the agent will call tools before stopping.
+   * Set higher for complex multi-step tasks, lower for simple queries.
+   *
+   * @default 20
+   */
+  maxSteps?: number;
+  /**
+   * Output type strategy.
+   *
+   * Controls the shape of the generation output. Accepts an AI SDK
+   * `Output` strategy or a raw Zod schema:
+   * - `Output.text()` — plain string (default).
+   * - `Output.object({ schema })` — validated structured object.
+   * - `Output.array({ element })` — validated array of elements.
+   * - `Output.choice({ options })` — enum/classification.
+   * - `z.object({ ... })` — auto-wrapped as `Output.object({ schema })`.
+   * - `z.array(z.object({ ... }))` — auto-wrapped as `Output.array({ element })`.
+   *
+   * @default Output.text()
+   */
+  output?: OutputParam;
+  /**
+   * Pino-compatible logger.
+   *
+   * When omitted, the SDK creates a default pino instance at `info`
+   * level. The framework automatically creates scoped child loggers
+   * with contextual bindings (`agentId`).
+   */
+  logger?: Logger;
+  /**
+   * Hook: fires when the agent starts execution.
+   *
+   * @param event - Event containing the input.
+   * @param event.input - The validated input value.
+   */
+  onStart?: (event: {
+    input: TInput;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when the agent finishes successfully.
+   *
+   * @param event - Event containing the input, result, and duration.
+   * @param event.input - The validated input value.
+   * @param event.result - The generation result.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    input: TInput;
+    result: GenerateResult<TOutput>;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when the agent encounters an error.
+   *
+   * @param event - Event containing the input and error.
+   * @param event.input - The validated input value.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    input: TInput;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires after each tool-loop step completes.
+   *
+   * @param event - Event containing the step ID.
+   * @param event.stepId - The ID of the completed tool-loop step.
+   */
+  onStepFinish?: (event: {
+    stepId: string;
+    toolCalls: readonly {
+      toolName: string;
+      argsTextLength: number;
+    }[];
+    toolResults: readonly {
+      toolName: string;
+      resultTextLength: number;
+    }[];
+    usage: {
+      inputTokens: number;
+      outputTokens: number;
+      totalTokens: number;
+    };
+  }) => void | Promise<void>;
+}
+/**
+ * A created agent — exposes `.generate()`, `.stream()`, and `.fn()`.
+ *
+ * Under the hood, agents run a tool loop (like `generateText` with tools)
+ * until a stop condition is met. Everything is wrapped in `Result`
+ * so callers never need try/catch.
+ *
+ * @typeParam TInput - Agent input type.
+ * @typeParam TOutput - Agent output type.
+ * @typeParam TTools - Record of tools.
+ * @typeParam TSubAgents - Record of subagents.
+ */
+interface Agent<TInput = string | Message[], TOutput = string, TTools extends Record<string, Tool> = Record<string, Tool>, TSubAgents extends SubAgents = Record<string, never>> {
+  /**
+   * Run the agent to completion.
+   *
+   * Executes the tool loop until the model produces a final response
+   * or `maxSteps` is reached. Returns a `Result` wrapping the
+   * generation result.
+   *
+   * @param input - Typed input (when `input` schema is configured)
+   *   or `string | Message[]` in simple mode.
+   * @param config - Optional per-call overrides for model, tools,
+   *   output, hooks, etc.
+   * @returns A `Result` wrapping the `GenerateResult`. On success,
+   *   `result.ok` is `true` and generation fields are flat on the object.
+   */
+  generate(input: TInput, config?: AgentOverrides<TTools, TSubAgents>): Promise<Result<GenerateResult<TOutput>>>;
+  /**
+   * Run the agent with streaming output.
+   *
+   * Returns immediately with `fullStream` — an `AsyncIterableStream`
+   * of typed `StreamPart` events. `output` and `messages` are
+   * promises that resolve after the stream completes.
+   *
+   * @param input - Typed input (when `input` schema is configured)
+   *   or `string | Message[]` in simple mode.
+   * @param config - Optional per-call overrides.
+   * @returns A `Result` wrapping the `StreamResult`. On success,
+   *   consume `result.fullStream` for typed events; await
+   *   `result.output` / `result.messages` after the stream ends.
+   */
+  stream(input: TInput, config?: AgentOverrides<TTools, TSubAgents>): Promise<Result<StreamResult<TOutput>>>;
+  /**
+   * Returns a plain function that calls `.generate()`.
+   *
+   * Use for clean single-function exports where you want to hide
+   * the agent object and just expose a callable.
+   *
+   * @returns A function with the same signature as `.generate()`.
+   *
+   * @example
+   * ```typescript
+   * export const analyzeFile = fileAnalyzer.fn()
+   * // Usage: const result = await analyzeFile({ filePath: '...' })
+   * ```
+   */
+  fn(): (input: TInput, config?: AgentOverrides<TTools, TSubAgents>) => Promise<Result<GenerateResult<TOutput>>>;
+}
+//#endregion
+//#region src/core/agents/base/agent.d.ts
+/**
+ * Create an agent with typed input, tools, subagents, and hooks.
+ *
+ * Agents run a tool loop (via the AI SDK's `generateText`) until a
+ * stop condition is met. They support:
+ * - **Typed input** via Zod schema + prompt template.
+ * - **Simple mode** — pass a string or messages directly.
+ * - **Tools** for function calling.
+ * - **Subagents** auto-wrapped as delegatable tools.
+ * - **Inline overrides** per call.
+ * - **Hooks** for observability.
+ * - **Result return type** that never throws.
+ *
+ * @typeParam TInput - Agent input type (default: `string | Message[]`).
+ * @typeParam TOutput - Agent output type (default: `string`).
+ * @typeParam TTools - Record of tools.
+ * @typeParam TSubAgents - Record of subagents.
+ * @param config - Agent configuration including name, model, schemas,
+ *   tools, subagents, hooks, and logger.
+ * @returns An `Agent` instance with `.generate()`, `.stream()`, and `.fn()`.
+ *
+ * @example
+ * ```typescript
+ * // Simple mode — pass a string directly
+ * const helper = agent({
+ *   name: 'helper',
+ *   model: 'openai/gpt-4.1',
+ *   system: 'You are a helpful assistant.',
+ * })
+ * await helper.generate('What is TypeScript?')
+ *
+ * // Typed mode — input schema + prompt template
+ * const summarizer = agent({
+ *   name: 'summarizer',
+ *   input: z.object({ text: z.string() }),
+ *   model: 'openai/gpt-4.1',
+ *   prompt: ({ input }) => `Summarize:\n\n${input.text}`,
+ * })
+ * await summarizer.generate({ text: '...' })
+ *
+ * // Export as a plain function
+ * export const summarize = summarizer.fn()
+ * ```
+ */
+declare function agent<TInput = string | Message[], TOutput = string, TTools extends Record<string, Tool> = {}, TSubAgents extends SubAgents = {}>(config: AgentConfig<TInput, TOutput, TTools, TSubAgents>): Agent<TInput, TOutput, TTools, TSubAgents>;
+//#endregion
+//#region src/lib/trace.d.ts
+/**
+ * Known trace operation types.
+ *
+ * Each `$` method registers a specific operation type in the execution
+ * trace. This discriminant allows consumers to filter or group trace
+ * entries by kind.
+ */
+type OperationType = "step" | "agent" | "map" | "each" | "reduce" | "while" | "all" | "race";
+/** @deprecated Use `OperationType` instead. */
+type TraceType = OperationType;
+/**
+ * A single entry in the execution trace.
+ *
+ * Every tracked `$` operation produces a TraceEntry. Nested operations
+ * (e.g. agent calls inside a map iteration) appear as children,
+ * forming a tree that represents the full execution graph.
+ *
+ * @internal
+ *   Part of the internal execution context. Exposed on
+ *   `WorkflowResult.trace` for observability but not directly
+ *   constructed by user code.
+ */
+interface TraceEntry {
+  /**
+   * Unique id of this operation.
+   *
+   * Corresponds to the `id` field from the `$` config that
+   * produced this entry.
+   */
+  id: string;
+  /**
+   * What kind of operation produced this entry.
+   *
+   * Discriminant for filtering or grouping trace entries.
+   */
+  type: OperationType;
+  /**
+   * Input snapshot.
+   *
+   * Captured when the operation starts. May be `undefined` for
+   * operations that have no meaningful input (e.g. `$.all`).
+   */
+  input?: unknown;
+  /**
+   * Output snapshot.
+   *
+   * Captured when the operation completes successfully. `undefined`
+   * if the operation is still running or failed.
+   */
+  output?: unknown;
+  /**
+   * Start time in Unix milliseconds.
+   *
+   * Set when the operation begins execution.
+   */
+  startedAt: number;
+  /**
+   * End time in Unix milliseconds.
+   *
+   * Set when the operation completes (success or failure).
+   * `undefined` while the operation is still running.
+   */
+  finishedAt?: number;
+  /**
+   * Error instance if the operation failed.
+   *
+   * `undefined` on success or while still running.
+   */
+  error?: Error;
+  /**
+   * Token usage from this operation.
+   *
+   * Populated for `agent` type entries that complete successfully.
+   * `undefined` for non-agent steps or failed operations.
+   */
+  usage?: TokenUsage;
+  /**
+   * Nested trace entries for child operations.
+   *
+   * Present when this operation spawns sub-operations
+   * (e.g. individual iterations inside `$.map`, or nested
+   * `$.step` calls inside a step's `execute` callback).
+   */
+  children?: readonly TraceEntry[];
+}
+/**
+ * Recursively collect all {@link TokenUsage} values from a trace tree.
+ *
+ * Walks every entry (including nested children) and returns a flat
+ * array of usage objects. Entries without usage are skipped.
+ *
+ * @param trace - The trace array to collect from.
+ * @returns Flat array of {@link TokenUsage} values found in the tree.
+ */
+declare function collectUsages(trace: readonly TraceEntry[]): TokenUsage[];
+//#endregion
+//#region src/lib/context.d.ts
+/**
+ * Public execution context for custom step factories.
+ *
+ * Provides the abort signal and scoped logger — the minimal surface
+ * needed to integrate with framework cancellation and logging.
+ * The mutable trace is internal-only.
+ */
+interface ExecutionContext {
+  readonly signal: AbortSignal;
+  readonly log: Logger;
+}
+/**
+ * Internal execution context.
+ *
+ * Created by the framework when a workflow or flow agent starts.
+ * Threaded through every `$` call automatically. Users never create,
+ * pass, or interact with this directly.
+ *
+ * @internal
+ *   Only accessible to framework internals. Custom step factories
+ *   receive {@link ExecutionContext} instead.
+ */
+interface Context extends ExecutionContext {
+  /**
+   * Execution trace — every tracked operation is recorded here.
+   *
+   * The framework appends entries as `$` operations start and complete.
+   * Read this after workflow/flow agent completion to inspect the full
+   * execution graph.
+   */
+  readonly trace: TraceEntry[];
+  /**
+   * Synthetic messages produced by `$` steps.
+   *
+   * Each tracked operation pushes a tool-call (assistant) message when
+   * it starts and a tool-result (tool) message when it finishes.
+   * The array is flat — nested steps push to the same array so messages
+   * appear in execution order.
+   *
+   * Used by `flowAgent` to populate `GenerateResult.messages`.
+   */
+  readonly messages: Message[];
+}
+//#endregion
+//#region src/core/agents/flow/steps/agent.d.ts
+/**
+ * Configuration for `$.agent()` — execute an agent call as a tracked operation.
+ *
+ * The `input` field matches whatever the agent accepts — typed `TInput`
+ * if the agent has a schema, or `string | Message[]` for simple agents.
+ *
+ * @typeParam TInput - The agent's input type.
+ */
+interface AgentStepConfig<TInput> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace, hook events, and error messages.
+   */
+  id: string;
+  /**
+   * The agent to invoke.
+   *
+   * The framework calls `agent.generate()` internally with the
+   * provided `input` and optional `config` overrides.
+   */
+  agent: Runnable<TInput>;
+  /**
+   * Input to pass to the agent.
+   *
+   * Same as what you'd pass to `agent.generate()` — typed `TInput`
+   * for agents with an input schema, or `string | Message[]` for
+   * simple agents.
+   */
+  input: TInput;
+  /**
+   * Optional inline overrides for this agent call.
+   *
+   * Accepts the same fields as `AgentOverrides` — model, output,
+   * tools, hooks, etc.
+   */
+  config?: AgentOverrides;
+  /**
+   * When `true`, call `agent.stream()` instead of `agent.generate()`
+   * and pipe the agent's text output through the parent flow's stream.
+   *
+   * Only has an effect when the flow agent is streaming (i.e., when
+   * a stream writer is available). Falls back to `agent.generate()`
+   * when the flow agent is not streaming.
+   *
+   * @default false
+   */
+  stream?: boolean;
+  /**
+   * Hook: fires when this agent step starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when this agent step finishes.
+   *
+   * @param event - Event containing the step id, result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The agent's `GenerateResult`.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: GenerateResult;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when this agent step encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/all.d.ts
+/**
+ * A factory that receives an abort signal and returns a promise.
+ *
+ * Used by `$.all()` and `$.race()` so the framework controls when
+ * work starts and can cancel entries via the signal.
+ *
+ * The optional `$` parameter provides a child step builder whose
+ * trace entries nest under the parent `all`/`race` step. Using it
+ * is recommended for correct trace hierarchy.
+ */
+type EntryFactory = (signal: AbortSignal, $: StepBuilder) => Promise<unknown>;
+/**
+ * Configuration for `$.all()` — concurrent heterogeneous operations.
+ *
+ * Like `Promise.all` — takes an array of factory functions that the
+ * framework starts concurrently. Returns results as a tuple in the
+ * same order. Fails fast on the first error.
+ */
+interface AllConfig {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+  /**
+   * Array of factory functions to run concurrently.
+   *
+   * Each factory receives an `AbortSignal` and should return a
+   * promise. The framework starts all factories at the same time
+   * so timing and traces are accurate.
+   *
+   * @example
+   * ```typescript
+   * entries: [
+   *   (signal) => $.step({ id: 'a', execute: () => fetchA(signal) }),
+   *   (signal) => $.step({ id: 'b', execute: () => fetchB(signal) }),
+   * ]
+   * ```
+   */
+  entries: EntryFactory[];
+  /**
+   * Hook: fires when the all operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when all entries complete.
+   *
+   * @param event - Event containing the step id, results, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - Array of results in entry order.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: unknown[];
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if any entry encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/each.d.ts
+/**
+ * Configuration for `$.each()` — sequential side effects.
+ *
+ * Runs items one at a time in order. Returns `void`. If you need
+ * accumulated results from sequential iteration, use `$.reduce()`.
+ *
+ * @typeParam T - Input item type.
+ */
+interface EachConfig<T> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+  /**
+   * Array of items to process sequentially.
+   *
+   * Each item is passed to the `execute` callback in order.
+   */
+  input: readonly T[];
+  /**
+   * Process a single item (side effect).
+   *
+   * @param params - Execution parameters.
+   * @param params.item - The current item from the input array.
+   * @param params.index - The item's zero-based index in the input array.
+   * @param params.$ - The step builder for nesting further operations.
+   */
+  execute: (params: {
+    item: T;
+    index: number;
+    $: StepBuilder;
+  }) => Promise<void>;
+  /**
+   * Hook: fires when the each operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when all items are processed.
+   *
+   * @param event - Event containing the step id and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if the each operation encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/map.d.ts
+/**
+ * Configuration for `$.map()` — parallel map with optional concurrency limit.
+ *
+ * Each item is processed as a tracked operation. All run concurrently
+ * (up to `concurrency` limit). Returns results in input order.
+ *
+ * @typeParam T - Input item type.
+ * @typeParam R - Output item type.
+ */
+interface MapConfig<T, R> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace. Individual iterations appear
+   * as children of this entry.
+   */
+  id: string;
+  /**
+   * Array of items to process.
+   *
+   * Each item is passed to the `execute` callback along with its index.
+   */
+  input: readonly T[];
+  /**
+   * Maximum number of parallel executions.
+   *
+   * When set, limits how many `execute` callbacks run concurrently.
+   * Results are still returned in input order regardless.
+   *
+   * @default Infinity
+   */
+  concurrency?: number;
+  /**
+   * Process a single item.
+   *
+   * @param params - Execution parameters.
+   * @param params.item - The current item from the input array.
+   * @param params.index - The item's zero-based index in the input array.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The processed result for this item.
+   */
+  execute: (params: {
+    item: T;
+    index: number;
+    $: StepBuilder;
+  }) => Promise<R>;
+  /**
+   * Hook: fires when the map operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when all items are processed.
+   *
+   * @param event - Event containing the step id, results, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - Array of results in input order.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: R[];
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if the map operation encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/race.d.ts
+/**
+ * Configuration for `$.race()` — first-to-finish wins.
+ *
+ * Like `Promise.race` — takes an array of factory functions. Returns
+ * the first resolved value. Losers are cancelled via abort signal.
+ */
+interface RaceConfig {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+  /**
+   * Array of factory functions to race.
+   *
+   * Each factory receives an `AbortSignal`. The first to resolve
+   * wins; losers are cancelled by aborting the signal.
+   *
+   * @example
+   * ```typescript
+   * entries: [
+   *   (signal) => $.step({ id: 'fast', execute: () => fetchFast(signal) }),
+   *   (signal) => $.step({ id: 'slow', execute: () => fetchSlow(signal) }),
+   * ]
+   * ```
+   */
+  entries: EntryFactory[];
+  /**
+   * Hook: fires when the race starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when the first entry completes.
+   *
+   * @param event - Event containing the step id, winner result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The first resolved value.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if the race encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/reduce.d.ts
+/**
+ * Configuration for `$.reduce()` — sequential accumulation.
+ *
+ * Each step depends on the previous result. Returns the final
+ * accumulated value.
+ *
+ * @typeParam T - Input item type.
+ * @typeParam R - Accumulator/result type.
+ */
+interface ReduceConfig<T, R> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+  /**
+   * Array of items to reduce over.
+   *
+   * Each item is passed to the `execute` callback along with the
+   * current accumulator value.
+   */
+  input: readonly T[];
+  /**
+   * Initial accumulator value.
+   *
+   * Used as the `accumulator` parameter for the first `execute` call.
+   */
+  initial: R;
+  /**
+   * Reduce function — processes one item and returns the new accumulator.
+   *
+   * @param params - Execution parameters.
+   * @param params.item - The current item from the input array.
+   * @param params.accumulator - The current accumulated value.
+   * @param params.index - The item's zero-based index in the input array.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The updated accumulator value.
+   */
+  execute: (params: {
+    item: T;
+    accumulator: R;
+    index: number;
+    $: StepBuilder;
+  }) => Promise<R>;
+  /**
+   * Hook: fires when the reduce operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when all items are reduced.
+   *
+   * @param event - Event containing the step id, final result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The final accumulated value.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: R;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if the reduce operation encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/result.d.ts
+/**
+ * Error information for a failed step.
+ *
+ * Extends {@link ResultError} with the step's `id` so error handlers
+ * can correlate failures back to a specific `$` call.
+ */
+interface StepError extends ResultError {
+  /**
+   * The `id` from the step config that failed.
+   */
+  stepId: string;
+}
+/**
+ * Discriminated union for step operation results.
+ *
+ * The success value is available via `.value`. Callers pattern-match
+ * on `ok` instead of using try/catch.
+ *
+ * @typeParam T - The success payload type.
+ */
+type StepResult<T> = {
+  ok: true;
+  value: T;
+  step: StepInfo;
+  duration: number;
+} | {
+  ok: false;
+  error: StepError;
+  step: StepInfo;
+  duration: number;
+};
+//#endregion
+//#region src/core/agents/flow/steps/step.d.ts
+/**
+ * Configuration for `$.step()` — execute and register a unit of work.
+ *
+ * @typeParam T - The return type of the step's execute function.
+ */
+interface StepConfig<T> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace, hook events, and error messages.
+   */
+  id: string;
+  /**
+   * Execute the step's logic.
+   *
+   * @param params - Execution parameters.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The step result.
+   */
+  execute: (params: {
+    $: StepBuilder;
+  }) => Promise<T>;
+  /**
+   * Hook: fires when this step starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when this step finishes successfully.
+   *
+   * @param event - Event containing the step id, result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The value returned by `execute`.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: T;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when this step encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/while.d.ts
+/**
+ * Configuration for `$.while()` — conditional loop.
+ *
+ * Runs while a condition holds. Each iteration is tracked. Returns
+ * the **last value** (`undefined` if the condition was false on
+ * first check).
+ *
+ * @typeParam T - The value type produced by each iteration.
+ */
+interface WhileConfig<T> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace. Individual iterations appear
+   * as children of this entry.
+   */
+  id: string;
+  /**
+   * Loop condition — evaluated before each iteration.
+   *
+   * Called with the last iteration's value (or `undefined` before
+   * the first iteration) and the current iteration index.
+   *
+   * @param params - Condition parameters.
+   * @param params.value - The last iteration's value, or `undefined`
+   *   before the first iteration.
+   * @param params.index - The zero-based iteration index.
+   * @returns `true` to continue looping, `false` to stop.
+   */
+  condition: (params: {
+    value: T | undefined;
+    index: number;
+  }) => boolean;
+  /**
+   * Execute one iteration.
+   *
+   * @param params - Execution parameters.
+   * @param params.index - The zero-based iteration index.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The value for this iteration.
+   */
+  execute: (params: {
+    index: number;
+    $: StepBuilder;
+  }) => Promise<T>;
+  /**
+   * Hook: fires when the while loop starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: {
+    id: string;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when the while loop finishes.
+   *
+   * @param event - Event containing the step id, last value, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The last iteration's value, or `undefined`.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: T | undefined;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires if the while loop encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: {
+    id: string;
+    error: Error;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/core/agents/flow/steps/builder.d.ts
+/**
+ * The `$` object — composable step utilities.
+ *
+ * Provides tracked operations that register data flow for observability.
+ * Every call through `$` becomes an entry in the execution trace.
+ *
+ * `$` is passed into every callback, enabling composition and nesting.
+ * You can always skip `$` and use plain imperative code — it just
+ * won't appear in the trace.
+ */
+interface StepBuilder {
+  /**
+   * Execute and register a single unit of work.
+   *
+   * @typeParam T - The return type of the step.
+   * @param config - Step configuration with id, execute function,
+   *   and optional hooks.
+   * @returns A `StepResult` with `.value` containing the step's
+   *   return value on success, or a `StepError` on failure.
+   */
+  step<T>(config: StepConfig<T>): Promise<StepResult<T>>;
+  /**
+   * Execute an agent call as a tracked operation.
+   *
+   * The framework records the agent name, input, and output in the
+   * trace. Calls `agent.generate()` internally and unwraps the result —
+   * agent errors become `StepError`, agent success becomes
+   * `StepResult<GenerateResult>`.
+   *
+   * @typeParam TInput - The agent's input type.
+   * @param config - Agent step configuration with id, agent, input,
+   *   optional overrides, and optional hooks.
+   * @returns A `StepResult` wrapping the agent's `GenerateResult`.
+   */
+  agent<TInput>(config: AgentStepConfig<TInput>): Promise<StepResult<GenerateResult>>;
+  /**
+   * Parallel map — each item is a tracked operation.
+   *
+   * All items run concurrently (up to `concurrency` limit).
+   * Returns results in input order.
+   *
+   * @typeParam T - Input item type.
+   * @typeParam R - Output item type.
+   * @param config - Map configuration with id, input array, execute
+   *   function, optional concurrency, and optional hooks.
+   * @returns A `StepResult` wrapping the array of results in input order.
+   */
+  map<T, R>(config: MapConfig<T, R>): Promise<StepResult<R[]>>;
+  /**
+   * Sequential side effects — runs one item at a time.
+   *
+   * Returns `void`. Use `$.reduce()` if you need accumulated results.
+   *
+   * @typeParam T - Input item type.
+   * @param config - Each configuration with id, input array, execute
+   *   function, and optional hooks.
+   * @returns A `StepResult` wrapping void when all items are processed.
+   */
+  each<T>(config: EachConfig<T>): Promise<StepResult<void>>;
+  /**
+   * Sequential accumulation — each step depends on the previous result.
+   *
+   * @typeParam T - Input item type.
+   * @typeParam R - Accumulator/result type.
+   * @param config - Reduce configuration with id, input array, initial
+   *   value, execute function, and optional hooks.
+   * @returns A `StepResult` wrapping the final accumulated value.
+   */
+  reduce<T, R>(config: ReduceConfig<T, R>): Promise<StepResult<R>>;
+  /**
+   * Conditional loop — runs while a condition holds.
+   *
+   * Returns the last value, or `undefined` if the condition was
+   * false on the first check.
+   *
+   * @typeParam T - The value type produced by each iteration.
+   * @param config - While configuration with id, condition, execute
+   *   function, and optional hooks.
+   * @returns A `StepResult` wrapping the last iteration's value, or `undefined`.
+   */
+  while<T>(config: WhileConfig<T>): Promise<StepResult<T | undefined>>;
+  /**
+   * Run heterogeneous operations concurrently — like `Promise.all`.
+   *
+   * Entries are factory functions that receive an `AbortSignal` and
+   * return a promise. The framework starts all factories at the same
+   * time so timing and traces are accurate.
+   *
+   * @param config - All configuration with id, entry factories,
+   *   and optional hooks.
+   * @returns A `StepResult` wrapping the array of results in entry order.
+   */
+  all(config: AllConfig): Promise<StepResult<unknown[]>>;
+  /**
+   * Run operations concurrently — first to finish wins.
+   *
+   * Entries are factory functions that receive an `AbortSignal`.
+   * The first to resolve wins; losers are cancelled by aborting
+   * the signal.
+   *
+   * @param config - Race configuration with id, entry factories,
+   *   and optional hooks.
+   * @returns A `StepResult` wrapping the first resolved value.
+   */
+  race(config: RaceConfig): Promise<StepResult<unknown>>;
+}
+//#endregion
+//#region src/core/agents/flow/types.d.ts
+/**
+ * Information about a step in a flow agent execution.
+ *
+ * Passed to flow agent-level hooks (`onStepStart`, `onStepFinish`)
+ * and included in step events.
+ */
+interface StepInfo {
+  /**
+   * The id from the `$` config.
+   *
+   * Matches the `id` field on the step config that produced this event.
+   */
+  id: string;
+  /**
+   * Auto-incrementing index within the flow agent execution.
+   *
+   * Starts at `0` for the first `$` call and increments for each
+   * subsequent tracked operation.
+   */
+  index: number;
+  /**
+   * What kind of `$` call produced this step.
+   *
+   * Discriminant for filtering or grouping step events.
+   */
+  type: OperationType;
+}
+/**
+ * Result of a completed flow agent generation.
+ *
+ * Extends `GenerateResult` with flow-specific fields (`trace`, `duration`).
+ * Consumers who only care about the `Runnable` / `Agent` contract see
+ * `{ output, messages, usage, finishReason }`. Consumers who know they
+ * have a `FlowAgent` can access `trace` and `duration`.
+ *
+ * @typeParam TOutput - The validated output type.
+ */
+interface FlowAgentGenerateResult<TOutput> extends GenerateResult<TOutput> {
+  /**
+   * The full execution trace.
+   *
+   * A frozen tree of `TraceEntry` nodes representing every tracked `$`
+   * operation that ran during the flow.
+   */
+  trace: readonly TraceEntry[];
+  /**
+   * Total wall-clock time in milliseconds.
+   *
+   * Measured from the start of the flow to the completion
+   * of all operations.
+   */
+  duration: number;
+}
+/**
+ * Shared configuration fields for all flow agent variants.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ */
+interface FlowAgentConfigBase<TInput> {
+  /**
+   * Unique flow agent name.
+   *
+   * Used in logging, trace entries, and hook events.
+   */
+  name: string;
+  /**
+   * Zod schema for validating flow agent input.
+   *
+   * The raw input passed to `.generate()` is validated against this
+   * schema before the handler is called.
+   */
+  input: ZodType<TInput>;
+  /**
+   * Pino-compatible logger.
+   *
+   * When omitted, the SDK creates a default console-based instance.
+   * The framework automatically creates scoped child loggers
+   * with contextual bindings (`flowAgentId`, `stepId`).
+   */
+  logger?: Logger;
+  /**
+   * Hook: fires when the flow agent starts execution.
+   *
+   * @param event - Event containing the validated input.
+   */
+  onStart?: (event: {
+    input: TInput;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when the flow agent encounters an error.
+   *
+   * @param event - Event containing the input and error.
+   */
+  onError?: (event: {
+    input: TInput;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when any tracked `$` step starts.
+   *
+   * @param event - Event containing step info.
+   */
+  onStepStart?: (event: {
+    step: StepInfo;
+  }) => void | Promise<void>;
+  /**
+   * Hook: fires when any tracked `$` step finishes.
+   *
+   * @param event - Event containing step info, result, and duration.
+   */
+  onStepFinish?: (event: {
+    step: StepInfo;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+}
+/**
+ * Flow agent config with a structured output schema.
+ *
+ * The handler must return a value matching `TOutput`, which is
+ * validated against the `output` Zod schema before being returned.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ */
+interface FlowAgentConfigWithOutput<TInput, TOutput> extends FlowAgentConfigBase<TInput> {
+  /**
+   * Zod schema for validating flow agent output.
+   *
+   * The handler's return value is validated against this schema
+   * before being returned to the caller.
+   */
+  output: ZodType<TOutput>;
+  /**
+   * Hook: fires when the flow agent finishes successfully.
+   *
+   * @param event - Event containing input, result, and duration.
+   */
+  onFinish?: (event: {
+    input: TInput;
+    result: FlowAgentGenerateResult<TOutput>;
+    duration: number;
+  }) => void | Promise<void>;
+}
+/**
+ * Flow agent config without an output schema.
+ *
+ * The handler returns `void` — it orchestrates sub-agents and steps
+ * without producing structured output. The collected text from
+ * sub-agent responses becomes the `string` output.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ */
+interface FlowAgentConfigWithoutOutput<TInput> extends FlowAgentConfigBase<TInput> {
+  /**
+   * No output schema — the flow agent collects text from sub-agent
+   * responses and returns it as a `string`.
+   */
+  output?: undefined;
+  /**
+   * Hook: fires when the flow agent finishes successfully.
+   *
+   * @param event - Event containing input, result (with string output), and duration.
+   */
+  onFinish?: (event: {
+    input: TInput;
+    result: FlowAgentGenerateResult<string>;
+    duration: number;
+  }) => void | Promise<void>;
+}
+/**
+ * Configuration for creating a flow agent.
+ *
+ * Two variants:
+ * - **With output**: Provide an `output` Zod schema. The handler returns
+ *   `TOutput`, which is validated against the schema.
+ * - **Without output**: Omit `output`. The handler returns `void` and
+ *   the collected text from sub-agent responses becomes the `string` output.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ */
+type FlowAgentConfig<TInput, TOutput = void> = FlowAgentConfigWithOutput<TInput, TOutput> | FlowAgentConfigWithoutOutput<TInput>;
+/**
+ * Per-call overrides for flow agent generation.
+ *
+ * Passed as the optional second parameter to `.generate()` or `.stream()`.
+ */
+interface FlowAgentOverrides {
+  /**
+   * Abort signal for cancellation.
+   *
+   * When fired, all in-flight operations should clean up and exit.
+   * Propagated through the entire execution tree.
+   */
+  signal?: AbortSignal;
+  /**
+   * Override the logger for this call.
+   *
+   * When provided, replaces the logger configured at creation time.
+   */
+  logger?: Logger;
+  /**
+   * Per-call hook — fires after base `onStart`.
+   */
+  onStart?: (event: {
+    input: unknown;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onFinish`.
+   */
+  onFinish?: (event: {
+    input: unknown;
+    result: GenerateResult;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onError`.
+   */
+  onError?: (event: {
+    input: unknown;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Per-call hook — fires after base `onStepFinish`.
+   */
+  onStepFinish?: (event: {
+    step: StepInfo;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+}
+/**
+ * Parameters passed to the flow agent handler function.
+ *
+ * @typeParam TInput - The validated input type.
+ */
+interface FlowAgentParams<TInput> {
+  /**
+   * Validated input.
+   */
+  input: TInput;
+  /**
+   * Composable step builder utilities.
+   *
+   * Provides tracked operations (`$.step`, `$.agent`, `$.map`, etc.)
+   * that register data flow for observability and produce synthetic
+   * tool-call messages.
+   */
+  $: StepBuilder;
+  /**
+   * Scoped logger for the current flow execution.
+   */
+  log: Logger;
+}
+/**
+ * The flow agent handler function.
+ *
+ * This IS the flow — no step arrays, no definition objects.
+ * State is just variables. `$` is passed in for tracked operations.
+ *
+ * @typeParam TInput - The validated input type.
+ * @typeParam TOutput - The output type to return.
+ */
+type FlowAgentHandler<TInput, TOutput> = (params: FlowAgentParams<TInput>) => Promise<TOutput>;
+/**
+ * A created flow agent — exposes `.generate()`, `.stream()`, and `.fn()`.
+ *
+ * Flow agents are imperative handlers that use `$` for tracked operations.
+ * They satisfy the same `Runnable` interface as regular agents, so they
+ * can be used as sub-agents, tool-wrapped delegatees, etc.
+ *
+ * @typeParam TInput - Validated input type.
+ * @typeParam TOutput - Validated output type.
+ */
+interface FlowAgent<TInput, TOutput> {
+  /**
+   * Run the flow agent to completion.
+   *
+   * Validates input, executes the handler, validates output, and
+   * returns the result with messages, trace, and timing.
+   *
+   * @param input - Raw input (validated against the `input` Zod schema).
+   * @param config - Optional per-call overrides.
+   * @returns A `Result` wrapping the `FlowAgentGenerateResult`.
+   */
+  generate(input: TInput, config?: FlowAgentOverrides): Promise<Result<FlowAgentGenerateResult<TOutput>>>;
+  /**
+   * Run the flow agent with streaming step progress.
+   *
+   * Returns immediately with `fullStream` — an `AsyncIterableStream`
+   * of typed `StreamPart` events for each step. `output`, `messages`,
+   * and `usage` are promises that resolve after the flow completes.
+   *
+   * @param input - Raw input (validated against the `input` Zod schema).
+   * @param config - Optional per-call overrides.
+   * @returns A `Result` wrapping the `StreamResult`.
+   */
+  stream(input: TInput, config?: FlowAgentOverrides): Promise<Result<StreamResult<TOutput>>>;
+  /**
+   * Returns a plain function that calls `.generate()`.
+   */
+  fn(): (input: TInput, config?: FlowAgentOverrides) => Promise<Result<FlowAgentGenerateResult<TOutput>>>;
+}
+/**
+ * @internal
+ * Options that the engine uses to inject custom step augmentation
+ * into flowAgent(). Not exported — only accessible within the package.
+ */
+interface InternalFlowAgentOptions {
+  augment$?: ($: StepBuilder, ctx: Context) => StepBuilder;
+}
+//#endregion
+//#region src/core/agents/flow/flow-agent.d.ts
+/**
+ * Create a flow agent with typed input/output, tracked steps, and hooks.
+ *
+ * A flow agent is an agent whose behavior is defined by code, not by an LLM.
+ * You write the orchestration logic — calling sub-agents, running steps,
+ * using concurrency primitives — and the framework wraps it in the same
+ * API surface as a regular `agent`.
+ *
+ * To consumers, a `FlowAgent` IS an `Agent`. Same `.generate()`, same
+ * `.stream()`, same `.fn()`. Same `GenerateResult` return type. Same
+ * `messages` array. The only difference is internal: an `agent` runs
+ * an LLM tool loop, a `flowAgent` runs your handler function.
+ *
+ * Each `$` step is modeled as a synthetic tool call in the message history.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ * @param config - Flow agent configuration including name, schemas,
+ *   hooks, and logger.
+ * @param handler - The flow agent handler function that receives
+ *   validated input and the `$` step builder.
+ * @param _internal - Internal options used by the engine. Not public API.
+ * @returns A `FlowAgent` instance with `.generate()`, `.stream()`,
+ *   and `.fn()`.
+ *
+ * @example
+ * ```typescript
+ * const pipeline = flowAgent({
+ *   name: 'doc-pipeline',
+ *   input: z.object({ repo: z.string() }),
+ *   output: z.object({ docs: z.array(z.string()) }),
+ * }, async ({ input, $ }) => {
+ *   const files = await $.step({
+ *     id: 'scan-repo',
+ *     execute: () => scanRepo(input.repo),
+ *   })
+ *
+ *   if (!files.ok) throw files.error
+ *
+ *   const docs = await $.map({
+ *     id: 'generate-docs',
+ *     input: files.value,
+ *     execute: async ({ item, $ }) => {
+ *       const result = await $.agent({
+ *         id: 'write-doc',
+ *         agent: writerAgent,
+ *         input: item,
+ *       })
+ *       return result.ok ? result.value.output : ''
+ *     },
+ *     concurrency: 3,
+ *   })
+ *
+ *   return { docs: docs.ok ? docs.value : [] }
+ * })
+ * ```
+ */
+/**
+ * Create a flow agent with structured output.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ */
+declare function flowAgent<TInput, TOutput>(config: FlowAgentConfigWithOutput<TInput, TOutput>, handler: FlowAgentHandler<TInput, TOutput>, _internal?: InternalFlowAgentOptions): FlowAgent<TInput, TOutput>;
+/**
+ * Create a flow agent without structured output.
+ *
+ * The handler returns `void` — sub-agent text is collected as the
+ * `string` output. Ideal for orchestration-only flows where the
+ * sub-agents produce the final text.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ */
+declare function flowAgent<TInput>(config: FlowAgentConfigWithoutOutput<TInput>, handler: FlowAgentHandler<TInput, void>, _internal?: InternalFlowAgentOptions): FlowAgent<TInput, string>;
+//#endregion
+//#region src/core/agents/flow/engine.d.ts
+/**
+ * Factory function for a custom step type.
+ *
+ * Receives the internal context (for signal, logging) and the
+ * user-provided config. Returns the step result.
+ *
+ * @typeParam TConfig - The config shape users pass to `$.myStep({ ... })`.
+ * @typeParam TResult - The return type of the step.
+ */
+type CustomStepFactory<TConfig, TResult> = (params: {
+  /**
+   * Execution context.
+   */
+  ctx: ExecutionContext;
+  /**
+   * The config object the user passed to the custom step.
+   */
+  config: TConfig;
+}) => Promise<TResult>;
+/**
+ * Map of custom step names to their factory functions.
+ *
+ * Uses `config: never` as the base constraint so that any concrete
+ * `CustomStepFactory<TConfig, TResult>` is assignable via function
+ * parameter contravariance — `never extends TConfig` is always true.
+ */
+type CustomStepDefinitions = Record<string, (params: {
+  ctx: ExecutionContext;
+  config: never;
+}) => Promise<unknown>>;
+/**
+ * Derive typed custom step methods from a definitions map.
+ *
+ * @typeParam T - The `CustomStepDefinitions` map.
+ */
+type TypedCustomSteps<T extends CustomStepDefinitions> = { [K in keyof T]: T[K] extends CustomStepFactory<infer TConfig, infer TResult> ? (config: TConfig) => Promise<TResult> : never };
+/**
+ * Configuration for creating a custom flow engine.
+ *
+ * @typeParam TCustomSteps - The custom step definitions map.
+ */
+interface FlowEngineConfig<TCustomSteps extends CustomStepDefinitions> {
+  /**
+   * Custom step types to add to `$`.
+   */
+  $?: TCustomSteps;
+  /**
+   * Default hook: fires when any flow agent starts.
+   */
+  onStart?: (event: {
+    input: unknown;
+  }) => void | Promise<void>;
+  /**
+   * Default hook: fires when any flow agent finishes.
+   */
+  onFinish?: (event: {
+    input: unknown;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+  /**
+   * Default hook: fires when any flow agent errors.
+   */
+  onError?: (event: {
+    input: unknown;
+    error: Error;
+  }) => void | Promise<void>;
+  /**
+   * Default hook: fires when any step starts.
+   */
+  onStepStart?: (event: {
+    step: StepInfo;
+  }) => void | Promise<void>;
+  /**
+   * Default hook: fires when any step finishes.
+   */
+  onStepFinish?: (event: {
+    step: StepInfo;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+}
+/**
+ * A `flowAgent` factory with custom steps merged into `$`.
+ *
+ * @typeParam TCustomSteps - The custom step definitions map.
+ */
+type FlowFactory<TCustomSteps extends CustomStepDefinitions> = <TInput, TOutput>(config: FlowAgentConfigWithOutput<TInput, TOutput>, handler: (params: {
+  input: TInput;
+  $: StepBuilder & TypedCustomSteps<TCustomSteps>;
+  log: Logger;
+}) => Promise<TOutput>) => FlowAgent<TInput, TOutput>;
+/**
+ * Create a custom flow engine with additional step types
+ * and/or default hooks.
+ *
+ * Returns a `flowAgent()`-like factory. Any custom steps defined
+ * in `$` are merged into the handler's `$` parameter and fully typed.
+ *
+ * @typeParam TCustomSteps - The custom step definitions map.
+ * @param config - Engine configuration including custom steps
+ *   and default hooks.
+ * @returns A `FlowFactory` that creates flow agents with custom
+ *   `$` steps and engine-level default hooks.
+ *
+ * @example
+ * ```typescript
+ * const engine = createFlowEngine({
+ *   $: {
+ *     retry: async ({ ctx, config }) => {
+ *       let lastError: Error | undefined
+ *       for (let attempt = 0; attempt < config.attempts; attempt++) {
+ *         try {
+ *           return await config.execute({ attempt })
+ *         } catch (err) {
+ *           lastError = err as Error
+ *         }
+ *       }
+ *       throw lastError
+ *     },
+ *   },
+ *   onStart: ({ input }) => telemetry.trackStart(input),
+ * })
+ *
+ * const myFlow = engine({
+ *   name: 'my-flow',
+ *   input: MyInput,
+ *   output: MyOutput,
+ * }, async ({ input, $ }) => {
+ *   const data = await $.retry({
+ *     attempts: 3,
+ *     execute: async () => fetch('https://api.example.com/data'),
+ *   })
+ *   return data
+ * })
+ * ```
+ */
+declare function createFlowEngine<TCustomSteps extends CustomStepDefinitions = Record<string, never>>(engineConfig: FlowEngineConfig<TCustomSteps>): FlowFactory<TCustomSteps>;
+//#endregion
+//#region src/core/provider/provider.d.ts
+/**
+ * Create an OpenRouter provider instance with automatic API key resolution.
+ *
+ * Falls back to the `OPENROUTER_API_KEY` environment variable when
+ * no explicit `apiKey` is provided in the options.
+ *
+ * @param options - Provider settings forwarded to `@openrouter/ai-sdk-provider`.
+ * @returns A configured {@link OpenRouterProvider} instance.
+ *
+ * @example
+ * ```typescript
+ * const openrouter = createOpenRouter({ apiKey: 'sk-...' })
+ * const m = openrouter('openai/gpt-5.2-codex')
+ * ```
+ */
+declare function createOpenRouter(options?: OpenRouterProviderSettings): OpenRouterProvider;
+/**
+ * Shorthand for creating a single OpenRouter language model.
+ *
+ * Resolves the API key from the environment and returns a ready-to-use
+ * {@link LanguageModel} that can be passed directly to AI SDK functions.
+ *
+ * The provider instance is cached at module scope and reused across
+ * calls. If `OPENROUTER_API_KEY` changes at runtime, the cache is
+ * invalidated and a new provider is created.
+ *
+ * @param modelId - An OpenRouter model identifier (e.g. `"openai/gpt-5.2-codex"`).
+ * @returns A configured {@link LanguageModel} instance.
+ *
+ * @example
+ * ```typescript
+ * const m = openrouter('openai/gpt-5.2-codex')
+ * ```
+ */
+declare const openrouter: (modelId: ModelId) => LanguageModel;
+//#endregion
+//#region src/core/provider/usage.d.ts
+/**
+ * Compute final usage for a single agent call.
+ *
+ * Aggregates token counts from one or more raw tracking records.
+ * Returns a flat object with tokens + agentId.
+ *
+ * @param agentId - The agent that produced these records.
+ * @param records - Raw tracking records from the agent's execution.
+ * @returns Flat {@link AgentTokenUsage} with resolved token counts.
+ */
+declare function agentUsage(agentId: string, records: TokenUsageRecord | TokenUsageRecord[]): AgentTokenUsage;
+/**
+ * Compute final usage for a flow agent with multiple agent calls.
+ *
+ * Groups raw tracking records by `source.agentId`, computes per-agent
+ * usage via {@link agentUsage}.
+ *
+ * @param records - Raw tracking records from all agents in the flow.
+ * @returns {@link FlowAgentTokenUsage} with per-agent breakdown.
+ */
+declare function flowAgentUsage(records: TokenUsageRecord[]): FlowAgentTokenUsage;
+/**
+ * Sum multiple {@link TokenUsage} objects field-by-field.
+ *
+ * Pure function — returns a new object without mutating any input.
+ * Returns zero-valued usage when given an empty array.
+ *
+ * @param usages - Array of usage objects to sum.
+ * @returns A new `TokenUsage` with each field summed.
+ */
+declare function sumTokenUsage(usages: TokenUsage[]): TokenUsage;
+//#endregion
+//#region src/core/agents/flow/steps/factory.d.ts
+/**
+ * Options for {@link createStepBuilder}.
+ */
+interface StepBuilderOptions {
+  /**
+   * Internal execution context.
+   *
+   * Provides the abort signal, logger, and trace array.
+   */
+  ctx: Context;
+  /**
+   * Parent flow agent hooks forwarded to each step.
+   *
+   * These fire after the step's own hooks, giving the flow agent
+   * visibility into every `$` call.
+   */
+  parentHooks?: {
+    onStepStart?: (event: {
+      step: StepInfo;
+    }) => void | Promise<void>;
+    onStepFinish?: (event: {
+      step: StepInfo;
+      result: unknown;
+      duration: number;
+    }) => void | Promise<void>;
+  };
+  /**
+   * Stream writer for emitting typed `StreamPart` events.
+   *
+   * When provided, step start/finish events are written as typed
+   * AI SDK stream events. Used by `flowAgent.stream()` to pipe
+   * step events through the readable stream.
+   */
+  writer?: WritableStreamDefaultWriter<StreamPart>;
+}
+/**
+ * Create a `StepBuilder` (`$`) instance.
+ *
+ * The returned builder is the `$` object passed into every flow agent
+ * handler and step callback. It owns the full step lifecycle:
+ * trace registration, hook firing, error wrapping,
+ * and `StepResult<T>` construction.
+ *
+ * @param options - Factory configuration with context, optional parent
+ *   hooks, and optional stream writer.
+ * @returns A `StepBuilder` instance.
+ */
+declare function createStepBuilder(options: StepBuilderOptions): StepBuilder;
+//#endregion
+//#region src/utils/error.d.ts
+/**
+ * Coerces an unknown thrown value into a proper `Error` instance.
+ *
+ * Handles the common cases where libraries throw non-`Error` values
+ * (e.g. plain API response bodies, arrays, Maps) that would otherwise
+ * serialize as `[object Object]` in error messages.
+ *
+ * @param thrown - The caught value from a `catch` block.
+ * @returns An `Error` with a meaningful `.message`. If `thrown` is
+ *   already an `Error`, it is returned as-is. The original value is
+ *   preserved as `.cause` for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyCall()
+ * } catch (thrown) {
+ *   const error = toError(thrown)
+ *   console.error(error.message)
+ * }
+ * ```
+ */
+declare function toError(thrown: unknown): Error;
+/**
+ * Produce a human-readable string from any unknown value.
+ *
+ * Uses `JSON.stringify` for structured types (plain objects, arrays)
+ * so the message contains actual content instead of `[object Object]`.
+ * Maps and Sets are converted to their array representation first.
+ * Falls back to `String()` for primitives or when serialization fails
+ * (e.g. circular references).
+ *
+ * @param value - The value to stringify.
+ * @returns A meaningful string representation.
+ *
+ * @example
+ * ```typescript
+ * safeStringify({ status: 400 })          // '{"status":400}'
+ * safeStringify(new Map([['k', 'v']]))    // '[["k","v"]]'
+ * safeStringify(null)                     // 'null'
+ * safeStringify(42)                       // '42'
+ * ```
+ */
+declare function safeStringify(value: unknown): string;
+/**
+ * Safely serializes a value to a JSON string without throwing.
+ *
+ * Converts types that `JSON.stringify` handles poorly (Maps, Sets)
+ * into serializable equivalents before stringifying. Returns an empty
+ * string when serialization fails (e.g. circular references).
+ *
+ * @param value - The value to serialize.
+ * @returns The JSON string, or an empty string if serialization fails.
+ *
+ * @example
+ * ```typescript
+ * safeStringifyJSON({ status: 400 })        // '{"status":400}'
+ * safeStringifyJSON(new Map([['k', 'v']]))   // '[["k","v"]]'
+ * safeStringifyJSON(circularObj)              // ''
+ * ```
+ */
+declare function safeStringifyJSON(value: unknown): string;
+//#endregion
+//#region src/utils/resolve.d.ts
+/**
+ * A value that is either static or dynamically resolved from context.
+ *
+ * Use this for agent/workflow definition fields that may depend on
+ * runtime state (e.g. tools, instructions, prompt).
+ *
+ * @typeParam T - The resolved value type.
+ * @typeParam TCtx - The context type passed when resolving dynamically.
+ *
+ * @example
+ * ```typescript
+ * // Static
+ * instructions: 'You are a helpful assistant'
+ *
+ * // Dynamic (sync)
+ * instructions: (ctx) => `Analyze ${ctx.input.repoName}`
+ *
+ * // Dynamic (async)
+ * instructions: async (ctx) => fetchPrompt(ctx.input.repoName)
+ * ```
+ */
+type ResolveParam<T, TCtx> = T | ((ctx: TCtx) => T | Promise<T>);
+//#endregion
+export { type Agent, type AgentConfig, type AgentOverrides, type AgentStepConfig, type AgentTokenUsage, type AllConfig, type AsyncIterableStream, type Context, type EachConfig, type EntryFactory, type ExecutionContext, type FlowAgent, type FlowAgentConfig, type FlowAgentConfigBase, type FlowAgentConfigWithOutput, type FlowAgentConfigWithoutOutput, type FlowAgentGenerateResult, type FlowAgentHandler, type FlowAgentOverrides, type FlowAgentParams, type FlowAgentTokenUsage, type CustomStepDefinitions as FlowCustomStepDefinitions, type CustomStepFactory as FlowCustomStepFactory, type FlowEngineConfig, type FlowFactory, type TypedCustomSteps as FlowTypedCustomSteps, type GenerateResult, type LanguageModel, type Logger, type MapConfig, type Message, type Model, type ModelCategory, type ModelDefinition, type ModelId, type ModelPricing, type ModelRef, type OpenRouterLanguageModelId, type OperationType, type Output, type OutputParam, type OutputSpec, type RaceConfig, type ReduceConfig, type ResolveParam, type Result, type ResultError, type Runnable, type StepBuilder, type StepBuilderOptions, type StepConfig, type StepError, type StepInfo, type StepResult, type StreamPart, type StreamResult, type SubAgents, type TextStreamPart, type TokenUsage, type TokenUsageRecord, type Tool, type ToolConfig, type ToolSet, type TraceEntry, type TraceType, type WhileConfig, agent, agentUsage, collectUsages, createDefaultLogger, createFlowEngine, createOpenRouter, createStepBuilder, err, flowAgent, flowAgentUsage, isErr, isOk, model, models, ok, openrouter, resolveOutput, safeStringify, safeStringifyJSON, sumTokenUsage, toError, tool, tryModel };
+//# sourceMappingURL=index.d.mts.map