@funkai/agents 0.1.0

package/dist/index.mjs

@@ -0,0 +1,2312 @@
+import { Output, generateText, stepCountIs, streamText, tool as tool$1, wrapLanguageModel, zodSchema } from "ai";
+import { attempt, groupBy, isError, isFunction, isMap, isNil, isPrimitive, isSet, isString, sumBy } from "es-toolkit";
+import { has, isObject } from "es-toolkit/compat";
+import { P, match } from "ts-pattern";
+import { z } from "zod";
+import { createOpenRouter as createOpenRouter$1 } from "@openrouter/ai-sdk-provider";
+//#region src/core/tool.ts
+/**
+* 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(),
+*     }
+*   },
+* })
+* ```
+*/
+function tool(config) {
+	const resolvedOutputSchema = resolveOutputSchema(config.outputSchema);
+	const result = {
+		description: config.description,
+		title: config.title,
+		inputSchema: zodSchema(config.inputSchema),
+		outputSchema: resolvedOutputSchema,
+		inputExamples: config.inputExamples,
+		execute: async (data) => config.execute(data)
+	};
+	assertTool(result);
+	return tool$1(result);
+}
+/**
+* Resolve an optional Zod output schema into a zodSchema-wrapped value.
+*
+* @private
+*/
+function resolveOutputSchema(schema) {
+	return match(schema).with(P.nullish, () => void 0).otherwise((value) => zodSchema(value));
+}
+/**
+* Runtime assertion that narrows `value` to `Tool<TInput, TOutput>`.
+*
+* Validates structural shape at runtime — `inputSchema` is present and
+* `execute` is a function. Generic type parameters (`TInput`, `TOutput`)
+* are erased at runtime, so only the structural shape can be verified.
+*
+* This assertion exists because TypeScript cannot evaluate the AI SDK's
+* `NeverOptional<TOutput>` conditional type when `TOutput` is an
+* unresolved generic — a known limitation with higher-order conditional
+* types. Using `asserts` is TypeScript's endorsed narrowing mechanism
+* and provides a runtime safety net if the AI SDK's tool shape changes.
+*
+* @private
+*/
+/* v8 ignore start -- defensive guard; tool() always constructs a valid object */
+function assertTool(value) {
+	if (isNil(value) || !isObject(value)) throw new TypeError("Expected tool to be an object");
+	if (!has(value, "inputSchema")) throw new TypeError("Tool is missing required property: inputSchema");
+	if (!has(value, "execute") || !isFunction(value.execute)) throw new TypeError("Tool is missing required property: execute");
+}
+/* v8 ignore stop */
+//#endregion
+//#region src/utils/zod.ts
+/**
+* Convert a Zod schema to a JSON Schema object.
+*/
+function toJsonSchema(schema) {
+	return z.toJSONSchema(schema);
+}
+/**
+* Check if a Zod schema produces a JSON Schema with `type: 'array'`.
+*
+* Uses JSON Schema output rather than `instanceof` to correctly handle
+* wrapped schemas (transforms, refinements, pipes).
+*/
+function isZodArray(schema) {
+	return toJsonSchema(schema).type === "array";
+}
+//#endregion
+//#region src/core/agents/base/output.ts
+/**
+* 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
+*/
+function resolveOutput(output) {
+	return match("parseCompleteOutput" in output).with(true, () => output).otherwise(() => {
+		const schema = output;
+		return match(isZodArray(schema)).with(true, () => {
+			const def = schema._zod;
+			if (def != null && def.def.element != null) return Output.array({ element: def.def.element });
+			throw new Error("Failed to extract element schema from Zod array. Pass Output.array({ element: elementSchema }) explicitly.");
+		}).otherwise(() => Output.object({ schema }));
+	});
+}
+//#endregion
+//#region src/core/provider/provider.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')
+* ```
+*/
+function createOpenRouter(options) {
+	const apiKey = resolveApiKey(options);
+	return createOpenRouter$1({
+		...options,
+		apiKey
+	});
+}
+function resolveApiKey(options) {
+	if (options != null && options.apiKey != null) return options.apiKey;
+	return getOpenRouterApiKey();
+}
+/**
+* Create a cached OpenRouter model resolver.
+*
+* The returned function caches the underlying provider and invalidates
+* when the API key changes at runtime.
+*
+* @returns A function that resolves a model ID to a {@link LanguageModel}.
+*
+* @private
+*/
+function createCachedOpenRouter() {
+	const cache = {
+		provider: void 0,
+		apiKey: void 0
+	};
+	return (modelId) => {
+		const apiKey = getOpenRouterApiKey();
+		if (!cache.provider || cache.apiKey !== apiKey) {
+			cache.provider = createOpenRouter$1({ apiKey });
+			cache.apiKey = apiKey;
+		}
+		return cache.provider(modelId);
+	};
+}
+/**
+* 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')
+* ```
+*/
+const openrouter = createCachedOpenRouter();
+/**
+* Read the OpenRouter API key from the environment.
+*
+* @throws {Error} If `OPENROUTER_API_KEY` is not set.
+*/
+function getOpenRouterApiKey() {
+	const apiKey = process.env.OPENROUTER_API_KEY;
+	if (!apiKey) throw new Error("OPENROUTER_API_KEY environment variable is required. Set it in your .env file or environment.");
+	return apiKey;
+}
+//#endregion
+//#region src/lib/runnable.ts
+/**
+* Symbol key for internal runnable metadata.
+*
+* Stored on Agent and Workflow objects to enable composition:
+* `buildAITools()` reads this to wrap a Runnable as a delegatable
+* tool in parent agents.
+*
+* @internal
+*/
+const RUNNABLE_META = Symbol.for("agent-sdk:runnable-meta");
+//#endregion
+//#region src/core/agents/base/utils.ts
+/**
+* Resolve a display name for a sub-agent tool from its runnable
+* metadata, falling back to the provided name.
+*
+* @param meta - The runnable metadata, or undefined if not available.
+* @param fallback - The fallback name to use if metadata is missing.
+* @returns The resolved tool name.
+*
+* @private
+*/
+function resolveToolName(meta, fallback) {
+	if (meta != null && meta.name != null) return meta.name;
+	return fallback;
+}
+/**
+* Resolve a {@link Model} to an AI SDK `LanguageModel`.
+*/
+function resolveModel(ref) {
+	if (typeof ref === "string") return openrouter(ref);
+	return ref;
+}
+/**
+* Merge `Tool` records and wrap subagent `Runnable` objects into AI SDK
+* tool format for `generateText` / `streamText`.
+*
+* Tools created via `tool()` are already AI SDK tools and are
+* passed through directly. Only subagents need wrapping.
+*
+* Parent tools are automatically forwarded to sub-agents so they
+* can access the same capabilities (e.g. sandbox filesystem tools)
+* without explicit injection at each call site.
+*/
+function buildAITools(tools, agents) {
+	const hasTools = tools != null && Object.keys(tools).length > 0;
+	const hasAgents = agents != null && Object.keys(agents).length > 0;
+	if (!hasTools && !hasAgents) return;
+	const agentTools = agents ? Object.fromEntries(Object.entries(agents).map(([name, runnable]) => {
+		const meta = runnable[RUNNABLE_META];
+		const toolName = resolveToolName(meta, name);
+		return [`agent:${name}`, meta != null && meta.inputSchema != null ? tool$1({
+			description: `Delegate to ${toolName}`,
+			inputSchema: meta.inputSchema,
+			execute: async (input, { abortSignal }) => {
+				const r = await runnable.generate(input, {
+					signal: abortSignal,
+					tools
+				});
+				if (!r.ok) throw new Error(r.error.message);
+				return r.output;
+			}
+		}) : tool$1({
+			description: `Delegate to ${toolName}`,
+			inputSchema: z.object({ prompt: z.string().describe("The prompt to send") }),
+			execute: async (input, { abortSignal }) => {
+				const r = await runnable.generate(input.prompt, {
+					signal: abortSignal,
+					tools
+				});
+				if (!r.ok) throw new Error(r.error.message);
+				return r.output;
+			}
+		})];
+	})) : {};
+	return {
+		...tools,
+		...agentTools
+	};
+}
+/**
+* Resolve the system prompt from config or override.
+*/
+function resolveSystem(system, input) {
+	if (system == null) return;
+	if (typeof system === "function") return system({ input });
+	return system;
+}
+/**
+* Build the prompt/messages from input based on mode (typed vs simple).
+*
+* Returns a discriminated object: either `{ prompt }` or `{ messages }`,
+* never both — matching the AI SDK's `Prompt` union type.
+*/
+function buildPrompt(input, config) {
+	return match({
+		hasInput: Boolean(config.input),
+		hasPrompt: Boolean(config.prompt)
+	}).with({
+		hasInput: true,
+		hasPrompt: false
+	}, () => {
+		throw new Error("Agent has `input` schema but no `prompt` function — both are required for typed mode");
+	}).with({
+		hasInput: false,
+		hasPrompt: true
+	}, () => {
+		throw new Error("Agent has `prompt` function but no `input` schema — both are required for typed mode");
+	}).with({
+		hasInput: true,
+		hasPrompt: true
+	}, () => {
+		const promptFn = config.prompt;
+		const built = promptFn({ input });
+		return match(typeof built === "string").with(true, () => ({ prompt: built })).otherwise(() => ({ messages: built }));
+	}).otherwise(() => match(typeof input === "string").with(true, () => ({ prompt: input })).otherwise(() => ({ messages: input })));
+}
+/**
+* Convert AI SDK's `LanguageModelUsage` to our flat `TokenUsage`.
+*
+* Maps nested `inputTokenDetails` / `outputTokenDetails` to flat
+* fields, resolving `undefined` → `0`.
+*
+* @param usage - The AI SDK usage object (from `totalUsage`).
+* @returns A resolved {@link TokenUsage} with all fields as numbers.
+*/
+function toTokenUsage(usage) {
+	const inputDetails = match(usage.inputTokenDetails).with(P.nonNullable, (d) => ({
+		cacheReadTokens: d.cacheReadTokens ?? 0,
+		cacheWriteTokens: d.cacheWriteTokens ?? 0
+	})).otherwise(() => ({
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0
+	}));
+	const outputDetails = match(usage.outputTokenDetails).with(P.nonNullable, (d) => ({ reasoningTokens: d.reasoningTokens ?? 0 })).otherwise(() => ({ reasoningTokens: 0 }));
+	return {
+		inputTokens: usage.inputTokens ?? 0,
+		outputTokens: usage.outputTokens ?? 0,
+		totalTokens: usage.totalTokens ?? 0,
+		cacheReadTokens: inputDetails.cacheReadTokens,
+		cacheWriteTokens: inputDetails.cacheWriteTokens,
+		reasoningTokens: outputDetails.reasoningTokens
+	};
+}
+//#endregion
+//#region src/core/logger.ts
+/**
+* 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.
+*/
+function createDefaultLogger(bindings) {
+	const prefix = bindings ?? {};
+	return {
+		debug(first, second) {
+			writeLog(prefix, "debug", first, second);
+		},
+		info(first, second) {
+			writeLog(prefix, "info", first, second);
+		},
+		warn(first, second) {
+			writeLog(prefix, "warn", first, second);
+		},
+		error(first, second) {
+			writeLog(prefix, "error", first, second);
+		},
+		child(childBindings) {
+			return createDefaultLogger({
+				...prefix,
+				...childBindings
+			});
+		}
+	};
+}
+/**
+*
+* @param bindings
+* @param level
+* @param first
+* @param second
+* @private
+*/
+function writeLog(bindings, level, first, second) {
+	if (typeof first === "string") {
+		const meta = second;
+		console[level]({
+			...bindings,
+			...meta
+		}, first);
+	} else console[level]({
+		...bindings,
+		...first
+	}, second);
+}
+//#endregion
+//#region src/lib/hooks.ts
+const formatHookError = (err) => match(err).when((e) => e instanceof Error, (e) => e.message).otherwise((e) => String(e));
+/**
+* Wrap a nullable hook into a callback for `fireHooks`, avoiding
+* optional chaining, ternaries, and non-null assertions.
+*
+* @param hookFn - The hook callback, or undefined if not configured.
+* @param event - The event payload to pass to the hook.
+* @returns A thunk that calls the hook with the event, or undefined.
+*
+* @private
+*/
+function wrapHook(hookFn, event) {
+	if (hookFn !== void 0) return () => hookFn(event);
+}
+/**
+* Run hook callbacks sequentially, logging errors at warn level.
+*
+* Unlike `attemptEachAsync`, this function surfaces errors via the
+* logger so hook failures are visible in diagnostic output.
+*
+* @param log - Logger for warning about hook errors.
+* @param handlers - Callbacks to execute in order. `undefined` entries are skipped.
+*/
+async function fireHooks(log, ...handlers) {
+	for (const h of handlers) if (h != null) try {
+		await h();
+	} catch (err) {
+		const errorMessage = formatHookError(err);
+		log.warn("hook error", { error: errorMessage });
+	}
+}
+//#endregion
+//#region src/lib/middleware.ts
+/**
+* Wrap a language model with middleware.
+*
+* In development (`NODE_ENV === 'development'`), the AI SDK devtools
+* middleware is appended automatically. Any additional middleware
+* provided in the options is applied first (outermost).
+*
+* @param options - The model and optional middleware configuration.
+* @returns A wrapped language model with middleware applied.
+*/
+async function withModelMiddleware(options) {
+	const useDevtools = options.devtools === true || options.devtools !== false && process.env.NODE_ENV === "development";
+	const defaultMiddleware = [];
+	if (useDevtools) {
+		const { devToolsMiddleware } = await import("@ai-sdk/devtools");
+		defaultMiddleware.push(devToolsMiddleware());
+	}
+	const middleware = [];
+	if (options.middleware) middleware.push(...options.middleware, ...defaultMiddleware);
+	else middleware.push(...defaultMiddleware);
+	if (middleware.length === 0) return options.model;
+	return wrapLanguageModel({
+		model: options.model,
+		middleware
+	});
+}
+//#endregion
+//#region src/utils/error.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)
+* }
+* ```
+*/
+function toError(thrown) {
+	if (isError(thrown)) return thrown;
+	if (isString(thrown)) return new Error(thrown, { cause: thrown });
+	return new Error(safeStringify(thrown), { cause: thrown });
+}
+/**
+* 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'
+* ```
+*/
+function safeStringify(value) {
+	if (isNil(value) || isPrimitive(value)) return String(value);
+	return safeStringifyJSON(value) || String(value);
+}
+/**
+* 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)              // ''
+* ```
+*/
+function safeStringifyJSON(value) {
+	const serializable = toSerializable(value);
+	const [error, json] = attempt(() => JSON.stringify(serializable));
+	if (!isNil(error) || isNil(json)) return "";
+	return json;
+}
+/**
+* Convert types that `JSON.stringify` handles poorly into
+* serializable equivalents.
+*
+* - `Map` → array of `[key, value]` entries
+* - `Set` → array of values
+* - Everything else → passed through unchanged
+*
+* @private
+* @param value - The value to normalize.
+* @returns A JSON-friendly representation.
+*/
+function toSerializable(value) {
+	if (isMap(value)) return Array.from(value.entries());
+	if (isSet(value)) return Array.from(value);
+	return value;
+}
+//#endregion
+//#region src/core/agents/base/agent.ts
+/**
+* Safely read a property from `overrides`, which may be undefined.
+* Replaces `overrides?.prop` optional chaining.
+*
+* @private
+*/
+function readOverride(overrides, key) {
+	if (overrides !== void 0) return overrides[key];
+}
+/**
+* Safely compute the JSON-serialized length of a value.
+* Returns 0 if serialization fails (e.g. circular refs, BigInt).
+*
+* @private
+*/
+function safeSerializedLength(value) {
+	try {
+		const json = JSON.stringify(value);
+		return typeof json === "string" ? json.length : 0;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Return the value if the predicate is true, otherwise undefined.
+* Replaces `predicate ? value : undefined` ternary.
+*
+* @private
+*/
+function valueOrUndefined(predicate, value) {
+	if (predicate) return value;
+}
+/**
+* Resolve an optional output param. Returns `resolveOutput(param)` if
+* param is defined, otherwise undefined.
+*
+* @private
+*/
+function resolveOptionalOutput(param) {
+	if (param !== void 0) return resolveOutput(param);
+}
+/**
+* Safely extract a property from an object, returning `{}` if the
+* property does not exist. Replaces `'key' in obj ? obj[key] : {}` ternary.
+*
+* @private
+*/
+function extractProperty(obj, key) {
+	if (key in obj) return obj[key];
+	return {};
+}
+/**
+* Extract token usage from a step's usage object, defaulting to 0
+* when usage is undefined. Replaces optional chaining on `step.usage`.
+*
+* @private
+*/
+function extractUsage(usage) {
+	if (usage !== void 0) {
+		const inputTokens = usage.inputTokens ?? 0;
+		const outputTokens = usage.outputTokens ?? 0;
+		return {
+			inputTokens,
+			outputTokens,
+			totalTokens: usage.totalTokens ?? inputTokens + outputTokens
+		};
+	}
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0
+	};
+}
+/**
+* Return `ifOutput` when `output` is defined, `ifText` otherwise.
+* Replaces `output ? aiResult.output : aiResult.text` ternary.
+*
+* @private
+*/
+function pickByOutput(output, ifOutput, ifText) {
+	if (output !== void 0) return ifOutput;
+	return ifText;
+}
+/**
+* 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()
+* ```
+*/
+function agent(config) {
+	const baseLogger = config.logger ?? createDefaultLogger();
+	/**
+	* Validate raw input against the config schema, if present.
+	*
+	* Returns a discriminated union: `{ ok: true, input }` on success,
+	* `{ ok: false, error }` when validation fails.
+	*
+	* @private
+	*/
+	function validateInput(rawInput) {
+		if (!config.input) return {
+			ok: true,
+			input: rawInput
+		};
+		const parsed = config.input.safeParse(rawInput);
+		if (!parsed.success) return {
+			ok: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: `Input validation failed: ${parsed.error.message}`
+			}
+		};
+		return {
+			ok: true,
+			input: parsed.data
+		};
+	}
+	async function generate(rawInput, overrides) {
+		const validated = validateInput(rawInput);
+		if (!validated.ok) return {
+			ok: false,
+			error: validated.error
+		};
+		const input = validated.input;
+		const log = (readOverride(overrides, "logger") ?? baseLogger).child({ agentId: config.name });
+		const startedAt = Date.now();
+		try {
+			const model = await withModelMiddleware({ model: resolveModel(readOverride(overrides, "model") ?? config.model) });
+			const overrideTools = readOverride(overrides, "tools");
+			const overrideAgents = readOverride(overrides, "agents");
+			const mergedTools = {
+				...config.tools,
+				...overrideTools
+			};
+			const mergedAgents = {
+				...config.agents,
+				...overrideAgents
+			};
+			const hasTools = Object.keys(mergedTools).length > 0;
+			const hasAgents = Object.keys(mergedAgents).length > 0;
+			const aiTools = buildAITools(valueOrUndefined(hasTools, mergedTools), valueOrUndefined(hasAgents, mergedAgents));
+			const system = resolveSystem(readOverride(overrides, "system") ?? config.system, input);
+			const promptParams = buildPrompt(input, config);
+			const output = resolveOptionalOutput(readOverride(overrides, "output") ?? config.output);
+			await fireHooks(log, wrapHook(config.onStart, { input }), wrapHook(readOverride(overrides, "onStart"), { input }));
+			log.debug("agent.generate start", { name: config.name });
+			const maxSteps = readOverride(overrides, "maxSteps") ?? config.maxSteps ?? 20;
+			const overrideSignal = readOverride(overrides, "signal");
+			const stepCounter = { value: 0 };
+			const aiResult = await generateText({
+				model,
+				system,
+				...promptParams,
+				tools: aiTools,
+				output,
+				stopWhen: stepCountIs(maxSteps),
+				abortSignal: overrideSignal,
+				onStepFinish: async (step) => {
+					const event = {
+						stepId: `${config.name}:${stepCounter.value++}`,
+						toolCalls: (step.toolCalls ?? []).map((tc) => {
+							const args = extractProperty(tc, "args");
+							return {
+								toolName: tc.toolName,
+								argsTextLength: safeSerializedLength(args)
+							};
+						}),
+						toolResults: (step.toolResults ?? []).map((tr) => {
+							const result = extractProperty(tr, "result");
+							return {
+								toolName: tr.toolName,
+								resultTextLength: safeSerializedLength(result)
+							};
+						}),
+						usage: extractUsage(step.usage)
+					};
+					await fireHooks(log, wrapHook(config.onStepFinish, event), wrapHook(readOverride(overrides, "onStepFinish"), event));
+				}
+			});
+			const duration = Date.now() - startedAt;
+			const generateResult = {
+				output: pickByOutput(output, aiResult.output, aiResult.text),
+				messages: aiResult.response.messages,
+				usage: toTokenUsage(aiResult.totalUsage),
+				finishReason: aiResult.finishReason
+			};
+			await fireHooks(log, wrapHook(config.onFinish, {
+				input,
+				result: generateResult,
+				duration
+			}), wrapHook(readOverride(overrides, "onFinish"), {
+				input,
+				result: generateResult,
+				duration
+			}));
+			log.debug("agent.generate finish", {
+				name: config.name,
+				duration
+			});
+			return {
+				ok: true,
+				...generateResult
+			};
+		} catch (thrown) {
+			const error = toError(thrown);
+			const duration = Date.now() - startedAt;
+			log.error("agent.generate error", {
+				name: config.name,
+				error: error.message,
+				duration
+			});
+			await fireHooks(log, wrapHook(config.onError, {
+				input,
+				error
+			}), wrapHook(readOverride(overrides, "onError"), {
+				input,
+				error
+			}));
+			return {
+				ok: false,
+				error: {
+					code: "AGENT_ERROR",
+					message: error.message,
+					cause: error
+				}
+			};
+		}
+	}
+	async function stream(rawInput, overrides) {
+		const validated = validateInput(rawInput);
+		if (!validated.ok) return {
+			ok: false,
+			error: validated.error
+		};
+		const input = validated.input;
+		const log = (readOverride(overrides, "logger") ?? baseLogger).child({ agentId: config.name });
+		const startedAt = Date.now();
+		try {
+			const model = await withModelMiddleware({ model: resolveModel(readOverride(overrides, "model") ?? config.model) });
+			const overrideTools = readOverride(overrides, "tools");
+			const overrideAgents = readOverride(overrides, "agents");
+			const mergedTools = {
+				...config.tools,
+				...overrideTools
+			};
+			const mergedAgents = {
+				...config.agents,
+				...overrideAgents
+			};
+			const hasTools = Object.keys(mergedTools).length > 0;
+			const hasAgents = Object.keys(mergedAgents).length > 0;
+			const aiTools = buildAITools(valueOrUndefined(hasTools, mergedTools), valueOrUndefined(hasAgents, mergedAgents));
+			const system = resolveSystem(readOverride(overrides, "system") ?? config.system, input);
+			const promptParams = buildPrompt(input, config);
+			const output = resolveOptionalOutput(readOverride(overrides, "output") ?? config.output);
+			await fireHooks(log, wrapHook(config.onStart, { input }), wrapHook(readOverride(overrides, "onStart"), { input }));
+			log.debug("agent.stream start", { name: config.name });
+			const maxSteps = readOverride(overrides, "maxSteps") ?? config.maxSteps ?? 20;
+			const overrideSignal = readOverride(overrides, "signal");
+			const stepCounter = { value: 0 };
+			const aiResult = streamText({
+				model,
+				system,
+				...promptParams,
+				tools: aiTools,
+				output,
+				stopWhen: stepCountIs(maxSteps),
+				abortSignal: overrideSignal,
+				onStepFinish: async (step) => {
+					const event = {
+						stepId: `${config.name}:${stepCounter.value++}`,
+						toolCalls: (step.toolCalls ?? []).map((tc) => {
+							const args = extractProperty(tc, "args");
+							return {
+								toolName: tc.toolName,
+								argsTextLength: safeSerializedLength(args)
+							};
+						}),
+						toolResults: (step.toolResults ?? []).map((tr) => {
+							const result = extractProperty(tr, "result");
+							return {
+								toolName: tr.toolName,
+								resultTextLength: safeSerializedLength(result)
+							};
+						}),
+						usage: extractUsage(step.usage)
+					};
+					await fireHooks(log, wrapHook(config.onStepFinish, event), wrapHook(readOverride(overrides, "onStepFinish"), event));
+				}
+			});
+			const { readable, writable } = new TransformStream();
+			const done = (async () => {
+				const writer = writable.getWriter();
+				try {
+					for await (const part of aiResult.fullStream) await writer.write(part);
+					await writer.close();
+				} catch (error) {
+					await writer.abort(error).catch(() => {});
+					throw error;
+				}
+				const finalOutput = pickByOutput(output, await aiResult.output, await aiResult.text);
+				const finalMessages = (await aiResult.response).messages;
+				const finalUsage = toTokenUsage(await aiResult.totalUsage);
+				const finalFinishReason = await aiResult.finishReason;
+				const duration = Date.now() - startedAt;
+				const generateResult = {
+					output: finalOutput,
+					messages: finalMessages,
+					usage: finalUsage,
+					finishReason: finalFinishReason
+				};
+				await fireHooks(log, wrapHook(config.onFinish, {
+					input,
+					result: generateResult,
+					duration
+				}), wrapHook(readOverride(overrides, "onFinish"), {
+					input,
+					result: generateResult,
+					duration
+				}));
+				log.debug("agent.stream finish", {
+					name: config.name,
+					duration
+				});
+				return {
+					output: finalOutput,
+					messages: finalMessages,
+					usage: finalUsage,
+					finishReason: finalFinishReason
+				};
+			})();
+			done.catch(async (thrown) => {
+				const error = toError(thrown);
+				const duration = Date.now() - startedAt;
+				log.error("agent.stream error", {
+					name: config.name,
+					error: error.message,
+					duration
+				});
+				await fireHooks(log, wrapHook(config.onError, {
+					input,
+					error
+				}), wrapHook(readOverride(overrides, "onError"), {
+					input,
+					error
+				}));
+			});
+			return {
+				ok: true,
+				output: done.then((r) => r.output),
+				messages: done.then((r) => r.messages),
+				usage: done.then((r) => r.usage),
+				finishReason: done.then((r) => r.finishReason),
+				fullStream: readable
+			};
+		} catch (thrown) {
+			const error = toError(thrown);
+			const duration = Date.now() - startedAt;
+			log.error("agent.stream error", {
+				name: config.name,
+				error: error.message,
+				duration
+			});
+			await fireHooks(log, wrapHook(config.onError, {
+				input,
+				error
+			}), wrapHook(readOverride(overrides, "onError"), {
+				input,
+				error
+			}));
+			return {
+				ok: false,
+				error: {
+					code: "AGENT_ERROR",
+					message: error.message,
+					cause: error
+				}
+			};
+		}
+	}
+	const agent = {
+		generate,
+		stream,
+		fn: () => generate
+	};
+	agent[RUNNABLE_META] = {
+		name: config.name,
+		inputSchema: config.input
+	};
+	return agent;
+}
+//#endregion
+//#region src/core/agents/flow/messages.ts
+/**
+* Build the `toolCallId` for a step.
+*
+* Combines the step id with the global step index to produce a unique
+* identifier that correlates tool-call and tool-result messages.
+*
+* @param stepId - The step's user-provided id.
+* @param index - The step's global index within the flow.
+* @returns A unique tool call identifier.
+*/
+function buildToolCallId(stepId, index) {
+	return `${stepId}-${index}`;
+}
+/**
+* Create an assistant message containing a synthetic tool-call part.
+*
+* Emitted when a `$` step starts execution. The `input` field captures
+* the step's input snapshot (or `{}` when no input is available).
+*
+* @param toolCallId - Unique tool call identifier.
+* @param toolName - The step id used as the tool name.
+* @param args - The step's input snapshot.
+* @returns A `Message` with role `assistant` and a `tool-call` content part.
+*/
+function createToolCallMessage(toolCallId, toolName, args) {
+	return {
+		role: "assistant",
+		content: [{
+			type: "tool-call",
+			toolCallId,
+			toolName,
+			input: args ?? {}
+		}]
+	};
+}
+/**
+* Create a tool message containing a synthetic tool-result part.
+*
+* Emitted when a `$` step finishes execution. The `result` field captures
+* the step's output. When `isError` is true, the result represents an
+* error message.
+*
+* @param toolCallId - Unique tool call identifier (must match the paired tool-call).
+* @param toolName - The step id used as the tool name.
+* @param result - The step's output snapshot.
+* @param isError - Whether this result represents an error.
+* @returns A `Message` with role `tool` and a `tool-result` content part.
+*/
+function createToolResultMessage(toolCallId, toolName, result, isError) {
+	return {
+		role: "tool",
+		content: [{
+			type: "tool-result",
+			toolCallId,
+			toolName,
+			output: result ?? {},
+			...isError ? { isError: true } : {}
+		}]
+	};
+}
+/**
+* Safely serialize a value to a string for message content.
+*
+* Returns the value as-is when it's already a string. Otherwise
+* delegates to {@link safeStringify} which handles circular refs,
+* Maps, Sets, bigints, and other non-JSON-serializable types.
+*
+* @param value - The value to serialize.
+* @returns A string representation of the value.
+*/
+function serializeMessageContent(value) {
+	if (typeof value === "string") return value;
+	return safeStringify(value ?? null);
+}
+/**
+* Create a user message from flow agent input.
+*
+* This is the first message in the flow's message array, representing
+* the input passed to `flowAgent.generate()` or `flowAgent.stream()`.
+*
+* @param input - The flow agent input.
+* @returns A `Message` with role `user`.
+*/
+function createUserMessage(input) {
+	return {
+		role: "user",
+		content: serializeMessageContent(input)
+	};
+}
+/**
+* Create a final assistant message from flow agent output.
+*
+* This is the last message in the flow's message array, representing
+* the validated output returned by the handler.
+*
+* @param output - The flow agent output.
+* @returns A `Message` with role `assistant`.
+*/
+function createAssistantMessage(output) {
+	return {
+		role: "assistant",
+		content: serializeMessageContent(output)
+	};
+}
+/**
+* Collect text content from assistant messages in the message array.
+*
+* Used for flow agents without an output schema — the output is
+* the concatenated text from sub-agent responses. Only considers
+* messages with string content (tool-call messages have array content
+* and are skipped).
+*
+* @param messages - The flow's message array.
+* @returns The concatenated assistant text, trimmed.
+*/
+function collectTextFromMessages(messages) {
+	return messages.filter((m) => m.role === "assistant" && typeof m.content === "string").map((m) => m.content).join("\n").trim();
+}
+//#endregion
+//#region src/core/agents/flow/steps/factory.ts
+/**
+* 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.
+*/
+function createStepBuilder(options) {
+	return createStepBuilderInternal(options, { current: 0 });
+}
+/**
+* Internal factory that accepts a shared index ref.
+*
+* Child builders (created for nested `$` in callbacks) share
+* the same ref so step indices are globally unique.
+*/
+function createStepBuilderInternal(options, indexRef) {
+	const { ctx, parentHooks, writer } = options;
+	/**
+	* Core step primitive — every other method delegates here.
+	*/
+	async function step(config) {
+		const onFinishHandler = buildOnFinishHandler(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "step",
+			execute: config.execute,
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	/**
+	* Shared lifecycle for all step types.
+	*/
+	async function executeStep(params) {
+		const { id, type, execute, input, onStart, onFinish, onError } = params;
+		const stepInfo = {
+			id,
+			index: indexRef.current++,
+			type
+		};
+		const startedAt = Date.now();
+		const childTrace = [];
+		const child$ = createStepBuilderInternal({
+			ctx: {
+				signal: ctx.signal,
+				log: ctx.log.child({ stepId: id }),
+				trace: childTrace,
+				messages: ctx.messages
+			},
+			parentHooks,
+			writer
+		}, indexRef);
+		const toolCallId = buildToolCallId(id, stepInfo.index);
+		ctx.messages.push(createToolCallMessage(toolCallId, id, input));
+		if (writer != null) writer.write({
+			type: "tool-call",
+			toolCallId,
+			toolName: id,
+			input: input ?? {}
+		}).catch((err) => {
+			ctx.log.warn({
+				err,
+				toolCallId
+			}, "failed to write tool-call event to stream");
+		});
+		const onStartHook = buildHookCallback(onStart, (fn) => fn({ id }));
+		const parentOnStepStartHook = buildParentHookCallback(parentHooks, "onStepStart", (fn) => fn({ step: stepInfo }));
+		await fireHooks(ctx.log, onStartHook, parentOnStepStartHook);
+		try {
+			const value = await execute({ $: child$ });
+			const finishedAt = Date.now();
+			const duration = finishedAt - startedAt;
+			const usage = value != null && typeof value === "object" && "usage" in value ? value.usage : void 0;
+			ctx.trace.push({
+				id,
+				type,
+				input,
+				startedAt,
+				finishedAt,
+				children: childTrace,
+				output: value,
+				...usage != null ? { usage } : {}
+			});
+			ctx.messages.push(createToolResultMessage(toolCallId, id, value));
+			if (writer != null) writer.write({
+				type: "tool-result",
+				toolCallId,
+				toolName: id,
+				input: input ?? {},
+				output: value ?? null
+			}).catch((err) => {
+				ctx.log.warn({
+					err,
+					toolCallId
+				}, "failed to write tool-result event to stream");
+			});
+			const onFinishHook = buildHookCallback(onFinish, (fn) => fn({
+				id,
+				result: value,
+				duration
+			}));
+			const parentOnStepFinishHook = buildParentHookCallback(parentHooks, "onStepFinish", (fn) => fn({
+				step: stepInfo,
+				result: value,
+				duration
+			}));
+			await fireHooks(ctx.log, onFinishHook, parentOnStepFinishHook);
+			return {
+				ok: true,
+				value,
+				step: stepInfo,
+				duration
+			};
+		} catch (thrown) {
+			const error = toError(thrown);
+			const finishedAt = Date.now();
+			const duration = finishedAt - startedAt;
+			ctx.trace.push({
+				id,
+				type,
+				input,
+				startedAt,
+				finishedAt,
+				children: childTrace,
+				error
+			});
+			const stepError = {
+				code: "STEP_ERROR",
+				message: error.message,
+				cause: error,
+				stepId: id
+			};
+			ctx.messages.push(createToolResultMessage(toolCallId, id, { error: error.message }, true));
+			if (writer != null) writer.write({
+				type: "tool-result",
+				toolCallId,
+				toolName: id,
+				input: input ?? {},
+				output: { error: error.message }
+			}).catch((err) => {
+				ctx.log.warn({
+					err,
+					toolCallId
+				}, "failed to write error tool-result event to stream");
+			});
+			const onErrorHook = buildHookCallback(onError, (fn) => fn({
+				id,
+				error
+			}));
+			const parentOnStepFinishHook = buildParentHookCallback(parentHooks, "onStepFinish", (fn) => fn({
+				step: stepInfo,
+				result: void 0,
+				duration
+			}));
+			await fireHooks(ctx.log, onErrorHook, parentOnStepFinishHook);
+			return {
+				ok: false,
+				error: stepError,
+				step: stepInfo,
+				duration
+			};
+		}
+	}
+	async function agent(config) {
+		const onFinishHandler = buildOnFinishHandlerWithCast(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "agent",
+			input: config.input,
+			execute: async () => {
+				const agentConfig = {
+					signal: ctx.signal,
+					...config.config,
+					logger: ctx.log.child({ stepId: config.id })
+				};
+				if (config.stream && writer != null) {
+					const streamResult = await config.agent.stream(config.input, agentConfig);
+					if (!streamResult.ok) throw streamResult.error.cause ?? new Error(streamResult.error.message);
+					const full = streamResult;
+					for await (const part of full.fullStream) if (part.type === "text-delta") await writer.write(part);
+					return {
+						output: await full.output,
+						messages: await full.messages,
+						usage: await full.usage,
+						finishReason: await full.finishReason
+					};
+				}
+				const result = await config.agent.generate(config.input, agentConfig);
+				if (!result.ok) throw result.error.cause ?? new Error(result.error.message);
+				const full = result;
+				return {
+					output: full.output,
+					messages: full.messages,
+					usage: full.usage,
+					finishReason: full.finishReason
+				};
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function map(config) {
+		const onFinishHandler = buildOnFinishHandlerWithCast(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "map",
+			input: config.input,
+			execute: async ({ $ }) => {
+				const concurrency = config.concurrency;
+				if (concurrency != null && concurrency !== Infinity) return poolMap(config.input, concurrency, ctx.signal, (item, index) => config.execute({
+					item,
+					index,
+					$
+				}));
+				return Promise.all(config.input.map((item, index) => config.execute({
+					item,
+					index,
+					$
+				})));
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function each(config) {
+		const onFinishHandler = buildOnFinishHandlerVoid(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "each",
+			input: config.input,
+			execute: async ({ $ }) => {
+				for (const [i, item] of config.input.entries()) {
+					if (ctx.signal.aborted) throw new Error("Aborted");
+					await config.execute({
+						item,
+						index: i,
+						$
+					});
+				}
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function reduce(config) {
+		const onFinishHandler = buildOnFinishHandlerWithCast(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "reduce",
+			input: config.input,
+			execute: async ({ $ }) => {
+				return await reduceSequential(config.input, config.initial, ctx.signal, (item, accumulator, index) => config.execute({
+					item,
+					accumulator,
+					index,
+					$
+				}));
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function whileStep(config) {
+		const onFinishHandler = buildOnFinishHandlerWithCast(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "while",
+			execute: async ({ $ }) => {
+				return await whileSequential(config.condition, ctx.signal, (index) => config.execute({
+					index,
+					$
+				}));
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function all(config) {
+		const onFinishHandler = buildOnFinishHandlerWithCast(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "all",
+			execute: async ({ $ }) => {
+				const ac = new AbortController();
+				const onAbort = () => ac.abort();
+				ctx.signal.addEventListener("abort", onAbort, { once: true });
+				try {
+					return await Promise.all(config.entries.map((factory) => factory(ac.signal, $)));
+				} catch (err) {
+					ac.abort();
+					throw err;
+				} finally {
+					ctx.signal.removeEventListener("abort", onAbort);
+				}
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	async function race(config) {
+		const onFinishHandler = buildOnFinishHandlerRace(config.onFinish);
+		return executeStep({
+			id: config.id,
+			type: "race",
+			execute: async ({ $ }) => {
+				const ac = new AbortController();
+				const onAbort = () => ac.abort();
+				ctx.signal.addEventListener("abort", onAbort, { once: true });
+				try {
+					return await Promise.race(config.entries.map((factory) => factory(ac.signal, $)));
+				} finally {
+					ac.abort();
+					ctx.signal.removeEventListener("abort", onAbort);
+				}
+			},
+			onStart: config.onStart,
+			onFinish: onFinishHandler,
+			onError: config.onError
+		});
+	}
+	return {
+		step,
+		agent,
+		map,
+		each,
+		reduce,
+		while: whileStep,
+		all,
+		race
+	};
+}
+function buildHookCallback(handler, invoke) {
+	if (handler != null) return () => invoke(handler);
+}
+function buildParentHookCallback(hooks, key, invoke) {
+	if (hooks == null) return;
+	const fn = hooks[key];
+	if (fn == null) return;
+	return () => invoke(fn);
+}
+function buildOnFinishHandler(onFinish) {
+	if (onFinish == null) return;
+	return (event) => onFinish({
+		id: event.id,
+		result: event.result,
+		duration: event.duration
+	});
+}
+function buildOnFinishHandlerWithCast(onFinish) {
+	if (onFinish == null) return;
+	return (event) => onFinish({
+		id: event.id,
+		result: event.result,
+		duration: event.duration
+	});
+}
+function buildOnFinishHandlerVoid(onFinish) {
+	if (onFinish == null) return;
+	return (event) => onFinish({
+		id: event.id,
+		duration: event.duration
+	});
+}
+function buildOnFinishHandlerRace(onFinish) {
+	if (onFinish == null) return;
+	return (event) => onFinish({
+		id: event.id,
+		result: event.result,
+		duration: event.duration
+	});
+}
+async function reduceSequential(items, initial, signal, fn) {
+	async function loop(accumulator, index) {
+		if (index >= items.length) return accumulator;
+		if (signal.aborted) throw new Error("Aborted");
+		return loop(await fn(items[index], accumulator, index), index + 1);
+	}
+	return loop(initial, 0);
+}
+async function whileSequential(condition, signal, fn) {
+	async function loop(value, index) {
+		if (!condition({
+			value,
+			index
+		})) return value;
+		if (signal.aborted) throw new Error("Aborted");
+		return loop(await fn(index), index + 1);
+	}
+	return loop(void 0, 0);
+}
+/**
+* Worker-pool map with bounded concurrency.
+*
+* Runs `fn` over `items` with at most `concurrency` concurrent
+* executions. Results are returned in input order.
+*/
+async function poolMap(items, concurrency, signal, fn) {
+	const results = Array.from({ length: items.length });
+	const indexRef = { current: 0 };
+	async function worker() {
+		while (indexRef.current < items.length) {
+			if (signal.aborted) throw new Error("Aborted");
+			const i = indexRef.current++;
+			results[i] = await fn(items[i], i);
+		}
+	}
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+	await Promise.all(workers);
+	return results;
+}
+//#endregion
+//#region src/core/provider/usage.ts
+/**
+* Aggregate token counts across multiple raw tracking records.
+*
+* Sums each field, treating `undefined` as `0`.
+*/
+function aggregateTokens(usages) {
+	return {
+		inputTokens: sumBy(usages, (u) => u.inputTokens ?? 0),
+		outputTokens: sumBy(usages, (u) => u.outputTokens ?? 0),
+		totalTokens: sumBy(usages, (u) => u.totalTokens ?? 0),
+		cacheReadTokens: sumBy(usages, (u) => u.cacheReadTokens ?? 0),
+		cacheWriteTokens: sumBy(usages, (u) => u.cacheWriteTokens ?? 0),
+		reasoningTokens: sumBy(usages, (u) => u.reasoningTokens ?? 0)
+	};
+}
+/**
+* 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.
+*/
+function agentUsage(agentId, records) {
+	return {
+		agentId,
+		...aggregateTokens(match(records).when(Array.isArray, (r) => r).otherwise((r) => [r]))
+	};
+}
+/**
+* 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.
+*/
+function flowAgentUsage(records) {
+	const grouped = groupBy(records, (r) => match(r.source).with(P.nonNullable, (s) => match(s.agentId).with(P.string, (id) => id).otherwise(() => "unknown")).otherwise(() => "unknown"));
+	return { usages: Object.entries(grouped).map(([id, group]) => agentUsage(id, group)) };
+}
+/**
+* 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.
+*/
+function sumTokenUsage(usages) {
+	return {
+		inputTokens: sumBy(usages, (u) => u.inputTokens),
+		outputTokens: sumBy(usages, (u) => u.outputTokens),
+		totalTokens: sumBy(usages, (u) => u.totalTokens),
+		cacheReadTokens: sumBy(usages, (u) => u.cacheReadTokens),
+		cacheWriteTokens: sumBy(usages, (u) => u.cacheWriteTokens),
+		reasoningTokens: sumBy(usages, (u) => u.reasoningTokens)
+	};
+}
+//#endregion
+//#region src/lib/trace.ts
+/**
+* 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.
+*/
+function collectUsages(trace) {
+	return trace.flatMap((entry) => {
+		const usages = match(entry.usage).with(P.nonNullable, (u) => [u]).otherwise(() => []);
+		if (entry.children != null && entry.children.length > 0) return [...usages, ...collectUsages(entry.children)];
+		return usages;
+	});
+}
+/**
+* Recursively deep-clone and freeze a trace array.
+*
+* Returns a structurally identical tree that is `Object.freeze`d at
+* every level, preventing post-run mutation of the result trace.
+*
+* @internal
+*/
+function snapshotTrace(trace) {
+	return Object.freeze(trace.map((entry) => {
+		const childSpread = match(match(entry.children).with(P.nonNullable, (c) => snapshotTrace(c)).otherwise(() => void 0)).with(P.nonNullable, (c) => ({ children: c })).otherwise(() => ({}));
+		return Object.freeze({
+			...entry,
+			...childSpread
+		});
+	}));
+}
+//#endregion
+//#region src/core/agents/flow/flow-agent.ts
+/**
+* Resolve the logger for a single flow agent execution.
+*
+* @private
+*/
+function resolveFlowAgentLogger(base, flowAgentId, overrides) {
+	return ((overrides && overrides.logger) ?? base).child({ flowAgentId });
+}
+/**
+* Augment the step builder with custom steps from the engine.
+*
+* @private
+*/
+function augmentStepBuilder(base, ctx, internal) {
+	if (internal && internal.augment$) return internal.augment$(base, ctx);
+	return base;
+}
+function flowAgent(config, handler, _internal) {
+	const baseLogger = config.logger ?? createDefaultLogger();
+	/**
+	* Resolve the handler output into a final value, validating against
+	* the output schema when present. Also pushes the assistant message.
+	*
+	* Returns `{ ok: true, value }` on success, or `{ ok: false, message }`
+	* when output validation fails.
+	*
+	* @private
+	*/
+	function resolveFlowOutput(output, messages) {
+		if (config.output !== void 0) {
+			const outputParsed = config.output.safeParse(output);
+			if (!outputParsed.success) return {
+				ok: false,
+				message: `Output validation failed: ${outputParsed.error.message}`
+			};
+			messages.push(createAssistantMessage(outputParsed.data));
+			return {
+				ok: true,
+				value: outputParsed.data
+			};
+		}
+		const text = collectTextFromMessages(messages);
+		messages.push(createAssistantMessage(text));
+		return {
+			ok: true,
+			value: text
+		};
+	}
+	async function generate(input, overrides) {
+		const inputParsed = config.input.safeParse(input);
+		if (!inputParsed.success) return {
+			ok: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: `Input validation failed: ${inputParsed.error.message}`
+			}
+		};
+		const parsedInput = inputParsed.data;
+		const startedAt = Date.now();
+		const log = resolveFlowAgentLogger(baseLogger, config.name, overrides);
+		const signal = overrides && overrides.signal || new AbortController().signal;
+		const trace = [];
+		const messages = [];
+		const ctx = {
+			signal,
+			log,
+			trace,
+			messages
+		};
+		const $ = augmentStepBuilder(createStepBuilder({
+			ctx,
+			parentHooks: {
+				onStepStart: config.onStepStart,
+				onStepFinish: config.onStepFinish
+			}
+		}), ctx, _internal);
+		messages.push(createUserMessage(parsedInput));
+		await fireHooks(log, wrapHook(config.onStart, { input: parsedInput }), wrapHook(overrides && overrides.onStart, { input: parsedInput }));
+		log.debug("flowAgent.generate start", { name: config.name });
+		try {
+			const outputResult = resolveFlowOutput(await handler({
+				input: parsedInput,
+				$,
+				log
+			}), messages);
+			if (!outputResult.ok) return {
+				ok: false,
+				error: {
+					code: "VALIDATION_ERROR",
+					message: outputResult.message
+				}
+			};
+			const resolvedOutput = outputResult.value;
+			const duration = Date.now() - startedAt;
+			const usage = sumTokenUsage(collectUsages(trace));
+			const frozenTrace = snapshotTrace(trace);
+			const result = {
+				output: resolvedOutput,
+				messages: [...messages],
+				usage,
+				finishReason: "stop",
+				trace: frozenTrace,
+				duration
+			};
+			await fireHooks(log, wrapHook(config.onFinish, {
+				input: parsedInput,
+				result,
+				duration
+			}), wrapHook(overrides && overrides.onFinish, {
+				input: parsedInput,
+				result,
+				duration
+			}));
+			log.debug("flowAgent.generate finish", {
+				name: config.name,
+				duration
+			});
+			return {
+				ok: true,
+				...result
+			};
+		} catch (thrown) {
+			const error = toError(thrown);
+			const duration = Date.now() - startedAt;
+			log.error("flowAgent.generate error", {
+				name: config.name,
+				error: error.message,
+				duration
+			});
+			await fireHooks(log, wrapHook(config.onError, {
+				input: parsedInput,
+				error
+			}), wrapHook(overrides && overrides.onError, {
+				input: parsedInput,
+				error
+			}));
+			return {
+				ok: false,
+				error: {
+					code: "FLOW_AGENT_ERROR",
+					message: error.message,
+					cause: error
+				}
+			};
+		}
+	}
+	async function stream(input, overrides) {
+		const inputParsed = config.input.safeParse(input);
+		if (!inputParsed.success) return {
+			ok: false,
+			error: {
+				code: "VALIDATION_ERROR",
+				message: `Input validation failed: ${inputParsed.error.message}`
+			}
+		};
+		const parsedInput = inputParsed.data;
+		const startedAt = Date.now();
+		const log = resolveFlowAgentLogger(baseLogger, config.name, overrides);
+		const signal = overrides && overrides.signal || new AbortController().signal;
+		const trace = [];
+		const messages = [];
+		const ctx = {
+			signal,
+			log,
+			trace,
+			messages
+		};
+		const { readable, writable } = new TransformStream();
+		const writer = writable.getWriter();
+		const $ = augmentStepBuilder(createStepBuilder({
+			ctx,
+			parentHooks: {
+				onStepStart: config.onStepStart,
+				onStepFinish: config.onStepFinish
+			},
+			writer
+		}), ctx, _internal);
+		messages.push(createUserMessage(parsedInput));
+		await fireHooks(log, wrapHook(config.onStart, { input: parsedInput }), wrapHook(overrides && overrides.onStart, { input: parsedInput }));
+		log.debug("flowAgent.stream start", { name: config.name });
+		const done = (async () => {
+			try {
+				const outputResult = resolveFlowOutput(await handler({
+					input: parsedInput,
+					$,
+					log
+				}), messages);
+				if (!outputResult.ok) throw new Error(outputResult.message);
+				const resolvedOutput = outputResult.value;
+				const duration = Date.now() - startedAt;
+				const usage = sumTokenUsage(collectUsages(trace));
+				const result = {
+					output: resolvedOutput,
+					messages: [...messages],
+					usage,
+					finishReason: "stop",
+					trace: snapshotTrace(trace),
+					duration
+				};
+				await fireHooks(log, wrapHook(config.onFinish, {
+					input: parsedInput,
+					result,
+					duration
+				}), wrapHook(overrides && overrides.onFinish, {
+					input: parsedInput,
+					result,
+					duration
+				}));
+				log.debug("flowAgent.stream finish", {
+					name: config.name,
+					duration
+				});
+				await writer.write({
+					type: "finish",
+					finishReason: "stop",
+					rawFinishReason: void 0,
+					totalUsage: {
+						inputTokens: usage.inputTokens,
+						outputTokens: usage.outputTokens,
+						totalTokens: usage.totalTokens
+					}
+				});
+				await writer.close();
+				return result;
+			} catch (thrown) {
+				const error = toError(thrown);
+				const duration = Date.now() - startedAt;
+				log.error("flowAgent.stream error", {
+					name: config.name,
+					error: error.message,
+					duration
+				});
+				/* v8 ignore start -- defensive; writer rarely rejects in practice */
+				await writer.write({
+					type: "error",
+					error
+				}).catch((err) => {
+					log.debug("failed to write error event to stream", { err });
+				});
+				await writer.close().catch((err) => {
+					log.debug("failed to close stream writer", { err });
+				});
+				/* v8 ignore stop */
+				await fireHooks(log, wrapHook(config.onError, {
+					input: parsedInput,
+					error
+				}), wrapHook(overrides && overrides.onError, {
+					input: parsedInput,
+					error
+				}));
+				throw error;
+			}
+		})();
+		done.catch(() => {});
+		return {
+			ok: true,
+			output: done.then((r) => r.output),
+			messages: done.then((r) => r.messages),
+			usage: done.then((r) => r.usage),
+			finishReason: done.then((r) => r.finishReason),
+			fullStream: readable
+		};
+	}
+	const agent = {
+		generate,
+		stream,
+		fn: () => generate
+	};
+	agent[RUNNABLE_META] = {
+		name: config.name,
+		inputSchema: config.input
+	};
+	return agent;
+}
+//#endregion
+//#region src/core/agents/flow/engine.ts
+/**
+* Wrap a hook callback so it can be passed to `fireHooks`.
+*
+* Generic over `TEvent` so the hook is called with the correct
+* event type without resorting to `any`.
+*/
+function createHookCaller(hook, event) {
+	if (hook) return () => hook(event);
+}
+/**
+* Build a merged hook that runs engine and flow agent hooks sequentially.
+*
+* The `(event: never)` constraint is the widest function type under
+* strict mode — any single-argument function is assignable via
+* contravariance (`never extends T` for all `T`).
+*/
+function buildMergedHook(log, engineHook, flowHook) {
+	if (!engineHook && !flowHook) return;
+	const merged = async (event) => {
+		await fireHooks(log, createHookCaller(engineHook, event), createHookCaller(flowHook, event));
+	};
+	return merged;
+}
+/**
+* Built-in StepBuilder method names that custom steps must not shadow.
+*
+* @private
+*/
+const RESERVED_STEP_NAMES = new Set([
+	"step",
+	"agent",
+	"map",
+	"each",
+	"reduce",
+	"while",
+	"all",
+	"race"
+]);
+/**
+* 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
+* })
+* ```
+*/
+function createFlowEngine(engineConfig) {
+	for (const name of Object.keys(engineConfig.$ ?? {})) if (RESERVED_STEP_NAMES.has(name)) throw new Error(`Custom step "${name}" conflicts with a built-in StepBuilder method`);
+	return function engineCreateFlowAgent(flowConfig, handler) {
+		const hookLog = (flowConfig.logger ?? createDefaultLogger()).child({ source: "engine" });
+		const { onStart: engineOnStart } = engineConfig;
+		const { onStart: flowOnStart } = flowConfig;
+		const { onFinish: engineOnFinish } = engineConfig;
+		const { onFinish: flowOnFinish } = flowConfig;
+		const { onError: engineOnError } = engineConfig;
+		const { onError: flowOnError } = flowConfig;
+		const { onStepStart: engineOnStepStart } = engineConfig;
+		const { onStepStart: flowOnStepStart } = flowConfig;
+		const { onStepFinish: engineOnStepFinish } = engineConfig;
+		const { onStepFinish: flowOnStepFinish } = flowConfig;
+		const mergedConfig = {
+			...flowConfig,
+			onStart: buildMergedHook(hookLog, engineOnStart, flowOnStart),
+			onFinish: buildMergedHook(hookLog, engineOnFinish, flowOnFinish),
+			onError: buildMergedHook(hookLog, engineOnError, flowOnError),
+			onStepStart: buildMergedHook(hookLog, engineOnStepStart, flowOnStepStart),
+			onStepFinish: buildMergedHook(hookLog, engineOnStepFinish, flowOnStepFinish)
+		};
+		const wrappedHandler = async (params) => {
+			return handler({
+				input: params.input,
+				$: params.$,
+				log: params.log
+			});
+		};
+		return flowAgent(mergedConfig, wrappedHandler, { augment$: ($, ctx) => {
+			const customSteps = {};
+			for (const [name, factory] of Object.entries(engineConfig.$ ?? {})) customSteps[name] = (config) => factory({
+				ctx: {
+					signal: ctx.signal,
+					log: ctx.log
+				},
+				config
+			});
+			return {
+				...$,
+				...customSteps
+			};
+		} });
+	};
+}
+/**
+* Supported OpenRouter models with pricing data.
+*/
+const MODELS = [...[
+	{
+		id: "openai/gpt-5.2-codex",
+		category: "coding",
+		pricing: {
+			prompt: 175e-8,
+			completion: 14e-6,
+			inputCacheRead: 175e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-5.2",
+		category: "chat",
+		pricing: {
+			prompt: 175e-8,
+			completion: 14e-6,
+			inputCacheRead: 175e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-5.1",
+		category: "chat",
+		pricing: {
+			prompt: 125e-8,
+			completion: 1e-5,
+			inputCacheRead: 125e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-5",
+		category: "chat",
+		pricing: {
+			prompt: 125e-8,
+			completion: 1e-5,
+			inputCacheRead: 125e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-5-mini",
+		category: "chat",
+		pricing: {
+			prompt: 25e-8,
+			completion: 2e-6,
+			inputCacheRead: 25e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-5-nano",
+		category: "chat",
+		pricing: {
+			prompt: 5e-8,
+			completion: 4e-7,
+			inputCacheRead: 5e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-4.1",
+		category: "chat",
+		pricing: {
+			prompt: 2e-6,
+			completion: 8e-6,
+			inputCacheRead: 5e-7,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-4.1-mini",
+		category: "chat",
+		pricing: {
+			prompt: 4e-7,
+			completion: 16e-7,
+			inputCacheRead: 1e-7,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-4.1-nano",
+		category: "chat",
+		pricing: {
+			prompt: 1e-7,
+			completion: 4e-7,
+			inputCacheRead: 25e-9,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/gpt-4o",
+		category: "chat",
+		pricing: {
+			prompt: 25e-7,
+			completion: 1e-5,
+			inputCacheRead: 125e-8
+		}
+	},
+	{
+		id: "openai/gpt-4o-mini",
+		category: "chat",
+		pricing: {
+			prompt: 15e-8,
+			completion: 6e-7,
+			inputCacheRead: 75e-9
+		}
+	},
+	{
+		id: "openai/o3",
+		category: "reasoning",
+		pricing: {
+			prompt: 2e-6,
+			completion: 8e-6,
+			inputCacheRead: 5e-7,
+			webSearch: .01
+		}
+	},
+	{
+		id: "openai/o3-mini",
+		category: "reasoning",
+		pricing: {
+			prompt: 11e-7,
+			completion: 44e-7,
+			inputCacheRead: 55e-8
+		}
+	},
+	{
+		id: "openai/o4-mini",
+		category: "reasoning",
+		pricing: {
+			prompt: 11e-7,
+			completion: 44e-7,
+			inputCacheRead: 275e-9,
+			webSearch: .01
+		}
+	}
+]];
+/**
+* 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'
+* ```
+*/
+function model(id) {
+	const found = MODELS.find((m) => m.id === id);
+	if (!found) throw new Error(`Unknown model: ${id}`);
+	return found;
+}
+/**
+* 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)
+* }
+* ```
+*/
+function tryModel(id) {
+	return MODELS.find((m) => m.id === id);
+}
+/**
+* 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')
+* ```
+*/
+function models(filter) {
+	return match(filter).with(P.nullish, () => MODELS).otherwise((fn) => MODELS.filter(fn));
+}
+//#endregion
+//#region src/utils/result.ts
+/**
+* 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: [] }
+* ```
+*/
+function ok(value) {
+	return {
+		...value,
+		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)
+* ```
+*/
+function err(code, message, cause) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message,
+			cause
+		}
+	};
+}
+/**
+* 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)
+* }
+* ```
+*/
+function isOk(result) {
+	return result.ok;
+}
+/**
+* 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)
+* }
+* ```
+*/
+function isErr(result) {
+	return !result.ok;
+}
+//#endregion
+export { 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.mjs.map