@comma-agents/core 2.0.0-rc.0

package/dist/defaults/defaults.d.ts

@@ -0,0 +1,108 @@
+import type { CredentialStore } from "../credentials/credentials.types";
+import type { ProviderResolver } from "../model/model.types";
+import type { GlobalDefaults, ProviderRegistration } from "./defaults.types";
+/**
+ * Get the global credential store.
+ *
+ * If no custom store has been set via `setGlobalCredentialStore()`, a default
+ * store is lazily created using the platform-aware credentials file path.
+ *
+ * @example
+ * ```ts
+ * const store = getGlobalCredentialStore();
+ * const credential = await store.resolve("openai");
+ * ```
+ */
+export declare function getGlobalCredentialStore(): CredentialStore;
+/**
+ * Override the global credential store.
+ *
+ * All subsequent calls to `getGlobalCredentialStore()` (and any
+ * `loadStrategy()` / `loadAgent()` calls that rely on global defaults)
+ * will use this store instead of the platform-default file store.
+ *
+ * Pass `undefined` to revert to the default store.
+ *
+ * @example
+ * ```ts
+ * setGlobalCredentialStore(myCustomStore);
+ * ```
+ */
+export declare function setGlobalCredentialStore(store: CredentialStore | undefined): void;
+/**
+ * Set the directory where provider npm packages are auto-installed.
+ *
+ * When set, `resolveViaPackage()` will attempt to install missing provider
+ * packages into this directory (using `bun add`) before falling back to
+ * the standard module resolution. Pass `undefined` to disable auto-install.
+ *
+ * The daemon calls this on startup with its configured `providerCacheDir`.
+ *
+ * @example
+ * ```ts
+ * setProviderCacheDir("/Users/bot/.local/share/comma-agents/providers");
+ * ```
+ */
+export declare function setProviderCacheDir(dir: string | undefined): void;
+/**
+ * Register a custom provider with the global resolver.
+ *
+ * Registered providers take precedence over the models.dev catalog
+ * map and the default `@ai-sdk/<providerId>` dynamic import convention.
+ *
+ * @example
+ * ```ts
+ * import { registerProvider } from "@comma-agents/core";
+ *
+ * // Direct factory — full control over provider creation
+ * registerProvider("my-custom-llm", {
+ *   factory: (credential) => {
+ *     const apiKey = credential.type === "api" ? credential.key : undefined;
+ *     return (modelId) => myProvider({ apiKey, model: modelId });
+ *   },
+ * });
+ *
+ * // Package-based — dynamic import with custom export name
+ * registerProvider("deepinfra", {
+ *   packageName: "@deepinfra/ai-sdk",
+ *   factoryName: "createDeepInfra",
+ * });
+ * ```
+ */
+export declare function registerProvider(providerId: string, registration: ProviderRegistration): void;
+/**
+ * Remove a previously registered custom provider.
+ * Returns `true` if the provider was registered and removed.
+ */
+export declare function unregisterProvider(providerId: string): boolean;
+/**
+ * Get the global provider resolver.
+ *
+ * The resolver uses this resolution order for each provider ID:
+ * 1. Custom registration with direct `factory` (via `registerProvider()`)
+ * 2. Custom registration with `packageName`/`factoryName`
+ * 3. Special handling for `github-copilot` (uses `@ai-sdk/openai-compatible`)
+ * 4. models.dev catalog + built-in overrides (ollama, deepseek) — sync lookup
+ * 5. Last resort: attempt `@ai-sdk/<providerId>` as a guess
+ *
+ * @example
+ * ```ts
+ * const resolver = getGlobalProviderResolver();
+ * const factory = await resolver("openai", credential);
+ * const model = factory("gpt-4o");
+ * ```
+ */
+export declare function getGlobalProviderResolver(): ProviderResolver;
+/**
+ * Get a snapshot of the current global defaults state.
+ *
+ * Useful for inspection and testing.
+ */
+export declare function getGlobalDefaults(): GlobalDefaults;
+/**
+ * Reset all global defaults to initial state.
+ *
+ * Clears the provider registry, removes the custom credential store,
+ * and discards the lazily-created default store. Primarily for tests.
+ */
+export declare function resetGlobalDefaults(): void;

package/dist/defaults/defaults.types.d.ts

@@ -0,0 +1,51 @@
+import type { Credential, CredentialStore } from "../credentials/credentials.types";
+import type { ProviderFactory, ProviderResolver } from "../model/model.types";
+/**
+ * Configuration for registering a custom provider with the global resolver.
+ *
+ * Provide either a direct `factory` function or a `packageName` + optional
+ * `factoryName` for dynamic import resolution.
+ *
+ * @example
+ * ```ts
+ * // Direct factory — full control
+ * registerProvider("my-llm", {
+ *   factory: (credential) => (modelId) => myProvider({ apiKey: credential.key, model: modelId }),
+ * });
+ *
+ * // Package-based — dynamic import with custom names
+ * registerProvider("my-llm", {
+ *   packageName: "my-ai-sdk",
+ *   factoryName: "createMyLLM",
+ * });
+ * ```
+ */
+export interface ProviderRegistration {
+    /**
+     * Direct factory function — given a credential, returns a ProviderFactory.
+     * When set, `packageName` and `factoryName` are ignored.
+     */
+    readonly factory?: (credential: Credential) => ProviderFactory | Promise<ProviderFactory>;
+    /**
+     * npm package name to dynamically import.
+     * Defaults to `@ai-sdk/<providerId>` if omitted and `factory` is not set.
+     */
+    readonly packageName?: string;
+    /**
+     * Export name to look up on the imported module.
+     * Defaults to `create<ProviderId>` (AI SDK convention) if omitted.
+     */
+    readonly factoryName?: string;
+}
+/**
+ * Read-only view of the current global defaults state.
+ * Returned by `getGlobalDefaults()` for inspection/testing.
+ */
+export interface GlobalDefaults {
+    /** The current global credential store (lazily created if not overridden). */
+    readonly credentialStore: CredentialStore;
+    /** The current global provider resolver (uses registry + dynamic import fallback). */
+    readonly providerResolver: ProviderResolver;
+    /** Snapshot of registered provider IDs (does not include catalog-derived providers). */
+    readonly registeredProviderIds: readonly string[];
+}

package/dist/defaults/index.d.ts

@@ -0,0 +1,2 @@
+export { getGlobalCredentialStore, getGlobalDefaults, getGlobalProviderResolver, registerProvider, resetGlobalDefaults, setGlobalCredentialStore, setProviderCacheDir, unregisterProvider, } from "./defaults";
+export type { GlobalDefaults, ProviderRegistration } from "./defaults.types";

package/dist/errors/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Base error for all CommaAgents errors.
+ * Provides a consistent `code` field for programmatic handling.
+ */
+export declare class CommaAgentsError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a model string cannot be resolved to an AI SDK LanguageModel.
+ * Examples: unknown provider, missing API key, package not installed.
+ */
+export declare class ModelResolutionError extends CommaAgentsError {
+    readonly modelString: string;
+    constructor(modelString: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when an agent encounters an error during its call lifecycle.
+ */
+export declare class AgentCallError extends CommaAgentsError {
+    readonly agentName: string;
+    constructor(agentName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a flow encounters an error during execution.
+ */
+export declare class FlowExecutionError extends CommaAgentsError {
+    readonly flowName: string;
+    constructor(flowName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a tool execution fails.
+ */
+export declare class ToolExecutionError extends CommaAgentsError {
+    readonly toolName: string;
+    constructor(toolName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a strategy file fails validation.
+ */
+export declare class StrategyValidationError extends CommaAgentsError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a sandbox policy rejects a file-system operation.
+ *
+ * The `reason` field indicates why the operation was blocked:
+ * - `"jail"` — the resolved path escapes the sandbox cwd boundary.
+ * - `"read-denied"` — the read policy explicitly denies this path.
+ * - `"write-denied"` — the write policy explicitly denies this path.
+ * - `"ask-no-handler"` — policy is `"ask"` but no PermissionRequester is configured.
+ * - `"ask-aborted"` — the PermissionRequester threw or the AbortSignal fired.
+ * - `"forbidden-glob"` — the path matches a sandbox-level forbidden glob (e.g. `.git/**`, `.env*`).
+ *   These are always-deny patterns evaluated before the read/write policies and
+ *   cannot be overridden by `allow` patterns or session decisions.
+ * - `"absolute-path"` — the input was an absolute path while the sandbox has
+ *   `allowAbsolutePaths: false` (the default). Tools must use relative paths.
+ */
+export declare class SandboxViolationError extends CommaAgentsError {
+    readonly path: string;
+    readonly reason: "jail" | "read-denied" | "write-denied" | "ask-no-handler" | "ask-aborted" | "forbidden-glob" | "absolute-path";
+    constructor(path: string, reason: "jail" | "read-denied" | "write-denied" | "ask-no-handler" | "ask-aborted" | "forbidden-glob" | "absolute-path", message: string, options?: ErrorOptions);
+}
+/**
+ * Thrown when a hook function throws during execution.
+ */
+export declare class HookExecutionError extends CommaAgentsError {
+    readonly hookName: string;
+    constructor(hookName: string, message: string, options?: ErrorOptions);
+}

package/dist/flows/built-in/broadcast/broadcast-flow.constants.d.ts

@@ -0,0 +1,2 @@
+/** Default separator used to join step responses. */
+export declare const DEFAULT_SEPARATOR = "\n\n";

package/dist/flows/built-in/broadcast/broadcast-flow.d.ts

@@ -0,0 +1,30 @@
+import type { Agent } from "../../../agents/agent/agent.types";
+import type { BroadcastFlowConfig } from "../../flow/flow.types";
+/**
+ * Create a broadcast (fan-out) flow.
+ *
+ * The same input message is sent to every step. All responses are
+ * collected and joined with a separator into the final output.
+ *
+ * Steps are currently called sequentially (in order). Future versions
+ * may support parallel execution.
+ *
+ * @param config - Broadcast flow configuration.
+ * @returns An `Agent` implementing the broadcast flow.
+ *
+ * @example
+ * ```ts
+ * import { createBroadcastFlow } from "@comma-agents/core";
+ *
+ * const flow = createBroadcastFlow({
+ *   name: "multi-review",
+ *   steps: [reviewer1, reviewer2, reviewer3],
+ *   separator: "\n---\n",
+ * });
+ *
+ * // All three reviewers receive the same code
+ * const result = await flow.call("Review this function: ...");
+ * // result.text = reviewer1's output + "\n---\n" + reviewer2's output + "\n---\n" + reviewer3's output
+ * ```
+ */
+export declare function createBroadcastFlow(config: BroadcastFlowConfig): Agent;

package/dist/flows/built-in/cycle/cycle-flow.d.ts

@@ -0,0 +1,53 @@
+import type { Agent } from "../../../agents/agent/agent.types";
+import type { CycleFlowConfig } from "../../flow/flow.types";
+/**
+ * Check whether `observerOutput` contains any of the break signals
+ * under the chosen matching mode.
+ *
+ * Exposed for tests; not part of the public API.
+ *
+ * @internal
+ */
+export declare function matchesBreakSignal(observerOutput: string, signals: ReadonlyArray<string>, mode: "substring" | "first-line" | "any-line" | "exact"): boolean;
+/**
+ * Create a cycle flow that repeats a sequential pipeline N times.
+ *
+ * Each cycle runs all steps in sequence. The output of one cycle
+ * becomes the input of the next. Supports:
+ *
+ * - **Finite cycles**: `cycles: 3` runs the pipeline 3 times.
+ * - **Infinite cycles**: `cycles: Infinity` runs until externally cancelled.
+ * - **Observer**: An agent that processes each cycle's step output.
+ *   If the observer's response matches a break signal under the
+ *   configured match strategy (`breakCycleSignalMatch`), the cycle
+ *   breaks and returns the step output (before the observer ran).
+ * - **Cycle hooks**: `alterMessageBeforeCycle` / `alterMessageAfterCycle`
+ *   transform the message at cycle boundaries.
+ *
+ * @param config - Cycle flow configuration.
+ * @returns An `Agent` implementing the cycle flow.
+ *
+ * @example
+ * ```ts
+ * // Finite: run reviewer 3 times
+ * const flow = createCycleFlow({
+ *   name: "review-loop",
+ *   steps: [writer, reviewer],
+ *   cycles: 3,
+ * });
+ *
+ * // Infinite refine-until-good with a unique unambiguous break token.
+ * // First-line match means the reviewer's verdict is on line 1, with
+ * // optional reasoning below — and casual prose like "not done yet"
+ * // in the CONTINUE branch cannot accidentally trigger the break.
+ * const flow = createCycleFlow({
+ *   name: "refine-loop",
+ *   steps: [writer],
+ *   cycles: Infinity,
+ *   observer: critic,
+ *   breakCycleSignals: ["==CYCLE_DONE=="],
+ *   breakCycleSignalMatch: "first-line",
+ * });
+ * ```
+ */
+export declare function createCycleFlow(config: CycleFlowConfig): Agent;

package/dist/flows/built-in/sequential/sequential-flow.d.ts

@@ -0,0 +1,25 @@
+import type { Agent } from "../../../agents/agent/agent.types";
+import type { FlowConfig } from "../../flow/flow.types";
+/**
+ * Create a sequential (pipeline) flow.
+ *
+ * Agents are called one after another. The output of each agent becomes
+ * the input of the next. The final agent's output is the flow's result.
+ *
+ * @param config - Flow configuration with steps to run in sequence.
+ * @returns An `Agent` implementing the sequential pipeline.
+ *
+ * @example
+ * ```ts
+ * import { createSequentialFlow, createAgent } from "@comma-agents/core";
+ *
+ * const flow = createSequentialFlow({
+ *   name: "code-review",
+ *   steps: [writer, reviewer, editor],
+ * });
+ *
+ * // writer("Write a function") → reviewer(writer's output) → editor(reviewer's output)
+ * const result = await flow.call("Write a function that adds two numbers");
+ * ```
+ */
+export declare function createSequentialFlow(config: FlowConfig): Agent;

package/dist/flows/flow/flow.d.ts

@@ -0,0 +1,79 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { CustomFlowConfig, FlowConfig, FlowExecutor, FlowHooks } from "./flow.types";
+/**
+ * Mutable hook store backed by a hooks interface `H`.
+ *
+ * Removes the `readonly` modifier from property keys so values can be
+ * reassigned (replace-on-append), while preserving the original array
+ * types so no casts are needed when reading hooks.
+ *
+ * @example
+ * ```ts
+ * const store: HookStore<FlowHooks> = {};
+ * // store.beforeFlow is ReadonlyArray<SideEffectHook<string>> | undefined — typed correctly
+ * // store.beforeFlow = [...(store.beforeFlow ?? []), newHook]; — assignable
+ * ```
+ */
+export type HookStore<HookType extends FlowHooks = FlowHooks> = {
+    -readonly [HookKey in keyof HookType]: HookType[HookKey];
+};
+/**
+ * Build an `Agent` from a flow config, a hooks store, and an executor.
+ *
+ * This is the shared foundation for all flow types. It:
+ * 1. Validates that steps are non-empty.
+ * 2. Creates a `FlowContext` per call (tracks step results, fires step hooks).
+ * 3. Runs the flow-level hook lifecycle around the executor.
+ * 4. Returns an `Agent` with `name`, `call`, `reset`, and internal `appendHook`.
+ *
+ * The `store` is read on each call, so hooks appended via `appendHook` take
+ * effect on subsequent calls.
+ *
+ * @param config - Flow configuration (name, steps).
+ * @param typeName - Identifier for this flow type (for error messages).
+ * @param store - Mutable hooks store (starts empty; hooks are added via `hookIntoFlow`).
+ * @param executor - The orchestration function that defines step execution order.
+ * @param onReset - Optional callback fired after steps are reset (e.g. for observer cleanup).
+ * @returns An `Agent` implementing the flow.
+ *
+ * @example
+ * ```ts
+ * const agent = buildFlowAgent(
+ *   config,
+ *   "pipeline",
+ *   {},
+ *   async (steps, message, context) => {
+ *     let current = message;
+ *     for (const step of steps) {
+ *       const result = await context.runStep(step, current);
+ *       current = result.text;
+ *     }
+ *     return current;
+ *   },
+ * );
+ * ```
+ */
+export declare function buildFlowAgent<HookType extends FlowHooks = FlowHooks>(config: FlowConfig, typeName: string, store: HookStore<HookType>, executor: FlowExecutor, onReset?: () => void): Agent;
+/**
+ * Create a one-off custom flow with inline orchestration logic.
+ *
+ * For reusable flow types, use `buildFlowAgent()` directly.
+ *
+ * @param config - Flow configuration including the `execute` function.
+ * @returns An `Agent` implementing the custom flow.
+ *
+ * @example
+ * ```ts
+ * const flow = createFlow({
+ *   name: "my-custom",
+ *   steps: [agentA, agentB],
+ *   execute: async (steps, message, context) => {
+ *     const firstResult = await context.runStep(steps[0], message);
+ *     if (firstResult.text.includes("DONE")) return firstResult.text;
+ *     const secondResult = await context.runStep(steps[1], firstResult.text);
+ *     return secondResult.text;
+ *   },
+ * });
+ * ```
+ */
+export declare function createFlow(config: CustomFlowConfig): Agent;

package/dist/flows/flow/flow.types.d.ts

@@ -0,0 +1,179 @@
+import type { Agent, AgentCallResult } from "../../agents/agent/agent.types";
+import type { SideEffectHook, TransformHook } from "../../hooks";
+/**
+ * Flow lifecycle hooks.
+ *
+ * Execution order:
+ *   alterMessageBeforeFlow → beforeFlow → [execute steps] → afterFlow → alterMessageAfterFlow
+ *
+ * Per-step hooks fire inside each step execution:
+ *   beforeStep → [step.call()] → afterStep
+ */
+export interface FlowHooks {
+    /** Transform the message before the flow starts. */
+    readonly alterMessageBeforeFlow?: ReadonlyArray<TransformHook<string>>;
+    /** Side-effect before the flow starts. */
+    readonly beforeFlow?: ReadonlyArray<SideEffectHook<string>>;
+    /** Side-effect after the flow completes. */
+    readonly afterFlow?: ReadonlyArray<SideEffectHook<string>>;
+    /** Transform the final message after the flow completes. */
+    readonly alterMessageAfterFlow?: ReadonlyArray<TransformHook<string>>;
+    /** Side-effect before each step runs within the flow. */
+    readonly beforeStep?: ReadonlyArray<SideEffectHook<{
+        readonly stepName: string;
+        readonly message: string;
+    }>>;
+    /** Side-effect after each step completes within the flow. */
+    readonly afterStep?: ReadonlyArray<SideEffectHook<{
+        readonly stepName: string;
+        readonly message: string;
+        readonly result: AgentCallResult;
+    }>>;
+}
+/**
+ * Additional hooks for cycle-based flows.
+ */
+export interface CycleHooks extends FlowHooks {
+    /** Transform the message before each cycle iteration. */
+    readonly alterMessageBeforeCycle?: ReadonlyArray<TransformHook<string>>;
+    /** Transform the message after each cycle iteration. */
+    readonly alterMessageAfterCycle?: ReadonlyArray<TransformHook<string>>;
+}
+/**
+ * Result from a flow execution. Extends `AgentCallResult` with
+ * per-step details and aggregated token usage.
+ *
+ * Individual step results are available via `stepResults`.
+ *
+ * @example
+ * ```ts
+ * const result = await flow.call("hello") as FlowResult;
+ * console.log(result.text);             // final flow output
+ * console.log(result.stepResults[0]);   // first step's result
+ * console.log(result.usage);            // aggregated token usage
+ * ```
+ */
+export interface FlowResult extends AgentCallResult {
+    /** Results from each step execution, in the order they ran. */
+    readonly stepResults: ReadonlyArray<AgentCallResult>;
+}
+/**
+ * Context provided to the flow executor function.
+ *
+ * Provides utilities for running steps (which tracks results automatically)
+ * and access to flow metadata.
+ */
+export interface FlowContext {
+    /** Name of this flow. */
+    readonly name: string;
+    /**
+     * Run a step (agent or nested flow) with a message.
+     * Tracks the result internally for aggregation into `FlowResult`.
+     *
+     * @param step - The agent or nested flow to call.
+     * @param message - The message to pass to the step.
+     * @returns The step's result.
+     */
+    runStep(step: Agent, message: string): Promise<AgentCallResult>;
+    /** All results collected so far (for inspection mid-flow). */
+    readonly results: ReadonlyArray<AgentCallResult>;
+}
+/**
+ * The function that defines how a flow orchestrates its steps.
+ *
+ * Receives the list of steps, the input message, and a context object.
+ * Must return the final output text. Step results are tracked automatically
+ * via `flowContext.runStep()`.
+ *
+ * @example
+ * ```ts
+ * // A simple pipeline executor
+ * const pipelineExecutor: FlowExecutor = async (steps, message, flowContext) => {
+ *   let current = message;
+ *   for (const step of steps) {
+ *     const result = await flowContext.runStep(step, current);
+ *     current = result.text;
+ *   }
+ *   return current;
+ * };
+ * ```
+ */
+export type FlowExecutor = (steps: ReadonlyArray<Agent>, message: string, flowContext: FlowContext) => Promise<string>;
+/** Base configuration shared by all flow types. */
+export interface FlowConfig {
+    /** Unique name for this flow. */
+    readonly name: string;
+    /** The steps (agents or nested flows) this flow orchestrates. */
+    readonly steps: ReadonlyArray<Agent>;
+}
+/**
+ * Configuration for cycle-based flows.
+ *
+ * Supports finite cycles (`cycles: 3`), infinite cycles (`cycles: Infinity`),
+ * and an optional observer agent that runs after each cycle.
+ */
+export interface CycleFlowConfig extends FlowConfig {
+    /**
+     * Number of cycle iterations.
+     * Use `Infinity` for an infinite loop (requires `abort` signal).
+     * @default 1
+     */
+    readonly cycles?: number;
+    /**
+     * Observer agent that runs after each cycle's steps.
+     * The observer's output becomes the input for the next cycle,
+     * unless a break signal is detected.
+     */
+    readonly observer?: Agent;
+    /**
+     * Keywords that cause the observer to break the cycle loop. Matched
+     * against the observer's textual output using {@link breakCycleSignalMatch}.
+     *
+     * Pick tokens unlikely to appear by accident — `"==CYCLE_DONE=="` is
+     * far safer than `"done"`, which appears in casual prose like
+     * `"not done yet"` and false-fires the cycle.
+     *
+     * @default ["end cycle", "stop", "done"]
+     */
+    readonly breakCycleSignals?: ReadonlyArray<string>;
+    /**
+     * Strategy used to compare the observer's output against the break
+     * signals.
+     *
+     * - `"substring"` (default, legacy): the observer output (lowercased)
+     *   contains the signal (lowercased) anywhere. Permissive — `"done"`
+     *   matches `"not done yet"`. Backward compatible with existing
+     *   strategies; brittle for verbose observers.
+     * - `"first-line"`: the first non-blank line of the observer output
+     *   (after trim) equals the signal or starts with the signal followed
+     *   by whitespace. Recommended for LLM observers that emit a verdict
+     *   on line 1 and optional reasoning below. Case-insensitive.
+     * - `"any-line"`: any line of the observer output (after trim) equals
+     *   the signal or starts with the signal followed by whitespace.
+     *   Case-insensitive. Looser than `"first-line"`; useful when the
+     *   verdict isn't pinned to line 1.
+     * - `"exact"`: the entire observer output (after trim) equals the
+     *   signal. The strictest mode — the observer must output **only** the
+     *   signal token, nothing else. Use with tokens like `"DONE"` when
+     *   you want zero false positives.
+     *
+     * Matching is case-insensitive in every mode except `"exact"` (which
+     * is also case-insensitive — use a distinctive token if case matters).
+     *
+     * @default "substring"
+     */
+    readonly breakCycleSignalMatch?: "substring" | "first-line" | "any-line" | "exact";
+}
+/** Configuration for broadcast flows. */
+export interface BroadcastFlowConfig extends FlowConfig {
+    /**
+     * Separator used to join step responses.
+     * @default "\n\n"
+     */
+    readonly separator?: string;
+}
+/** Configuration for a one-off custom flow. */
+export interface CustomFlowConfig extends FlowConfig {
+    /** The orchestration function. */
+    readonly execute: FlowExecutor;
+}

package/dist/flows/flow/flow.utils.d.ts

@@ -0,0 +1,18 @@
+import type { AgentCallResult } from "../../agents/agent/agent.types";
+import type { FlowContext, FlowHooks, FlowResult } from "./flow.types";
+/**
+ * Build a `FlowResult` by aggregating individual step results.
+ *
+ * - `text` is provided by the caller (the executor's return value).
+ * - `usage` is summed across all step results.
+ * - `finishReason` is always `"stop"` for flows.
+ */
+export declare function buildFlowResult(text: string, stepResults: ReadonlyArray<AgentCallResult>): FlowResult;
+/**
+ * Create a `FlowContext` for a single flow execution.
+ *
+ * The context tracks step results via `runStep()` and exposes them
+ * as a readonly array. If step hooks are provided, `beforeStep` fires
+ * before each step and `afterStep` fires after.
+ */
+export declare function createFlowContext(name: string, hooks?: FlowHooks, abortSignal?: AbortSignal): FlowContext;

package/dist/flows/hook-into-flow/hook-into-flow.d.ts

@@ -0,0 +1,30 @@
+import type { Agent } from "../../agents/agent/agent.types";
+import type { FlowHooks } from "../flow/flow.types";
+/**
+ * Append hooks to an existing flow agent. Mutates the flow in-place.
+ *
+ * The flow must have been created by one of the flow factories
+ * (`createSequentialFlow`, `createCycleFlow`, `createBroadcastFlow`,
+ * `createFlow`, or `buildFlowAgent`), which provide the internal
+ * `appendHook` method. Throws if the flow doesn't support it.
+ *
+ * The generic parameter `HookType` allows passing extended hook types
+ * (e.g. `CycleHooks`) for cycle-specific hooks:
+ *
+ * @example
+ * ```ts
+ * // Basic flow hooks
+ * const flow = createSequentialFlow({ name: "pipe", steps: [a, b] });
+ * hookIntoFlow(flow, {
+ *   beforeFlow: [async (message) => console.log("starting:", message)],
+ *   afterFlow: [async (message) => console.log("done:", message)],
+ * });
+ *
+ * // Cycle-specific hooks
+ * const cycle = createCycleFlow({ name: "loop", steps: [a], cycles: 3 });
+ * hookIntoFlow<CycleHooks>(cycle, {
+ *   alterMessageBeforeCycle: [async (message) => `[cycle]${message}`],
+ * });
+ * ```
+ */
+export declare function hookIntoFlow<HookType extends FlowHooks = FlowHooks>(flow: Agent, hooks: HookType): void;

package/dist/flows/index.d.ts

@@ -0,0 +1,6 @@
+export { createBroadcastFlow } from "./built-in/broadcast/broadcast-flow";
+export { createCycleFlow } from "./built-in/cycle/cycle-flow";
+export { createSequentialFlow } from "./built-in/sequential/sequential-flow";
+export { buildFlowAgent, createFlow } from "./flow/flow";
+export type { BroadcastFlowConfig, CustomFlowConfig, CycleFlowConfig, CycleHooks, FlowConfig, FlowContext, FlowExecutor, FlowHooks, FlowResult, } from "./flow/flow.types";
+export { hookIntoFlow } from "./hook-into-flow/hook-into-flow";

package/dist/flows/loader/index.d.ts

@@ -0,0 +1,4 @@
+export { loadFlow, loadFlowFromString } from "./loader";
+export type { FlowDescription } from "./loader.schema";
+export { FlowDescriptionSchema } from "./loader.schema";
+export type { LoadFlowOptions } from "./loader.types";