@funkai/agents 0.1.0

package/src/core/agents/flow/steps/while.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+
+describe("while()", () => {
+  it("loops while condition is true", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.while({
+      id: "while-count",
+      condition: ({ index }) => index < 3,
+      execute: async ({ index }) => index,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe(2);
+    expect(result.step.type).toBe("while");
+  });
+
+  it("returns undefined when condition is initially false", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.while({
+      id: "while-none",
+      condition: () => false,
+      execute: async () => "should not run",
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBeUndefined();
+  });
+
+  it("does not call execute when condition is initially false", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const executeSpy = vi.fn(async () => "value");
+
+    await $.while({
+      id: "while-no-exec",
+      condition: () => false,
+      execute: executeSpy,
+    });
+
+    expect(executeSpy).not.toHaveBeenCalled();
+  });
+
+  it("executes exactly once when condition is true only for first iteration", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const iterations: number[] = [];
+
+    const result = await $.while({
+      id: "while-once",
+      condition: ({ index }) => index < 1,
+      execute: async ({ index }) => {
+        iterations.push(index);
+        return `iter-${index}`;
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe("iter-0");
+    expect(iterations).toEqual([0]);
+  });
+
+  it("passes previous value to condition", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const conditionValues: Array<number | undefined> = [];
+
+    await $.while<number>({
+      id: "while-val",
+      condition: ({ value, index }) => {
+        conditionValues.push(value);
+        return index < 3;
+      },
+      execute: async ({ index }) => (index + 1) * 10,
+    });
+
+    expect(conditionValues).toEqual([undefined, 10, 20, 30]);
+  });
+
+  it("returns ok: false when execute throws", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.while({
+      id: "while-err",
+      condition: () => true,
+      execute: async ({ index }) => {
+        if (index === 2) {
+          throw new Error("while error");
+        }
+        return index;
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("while error");
+    expect(result.error.stepId).toBe("while-err");
+  });
+
+  it("stops iteration on error", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const iterations: number[] = [];
+
+    await $.while({
+      id: "while-stop",
+      condition: () => true,
+      execute: async ({ index }) => {
+        iterations.push(index);
+        if (index === 1) {
+          throw new Error("stop");
+        }
+        return index;
+      },
+    });
+
+    expect(iterations).toEqual([0, 1]);
+  });
+
+  it("respects abort signal", async () => {
+    const controller = new AbortController();
+    const ctx = createMockCtx({ signal: controller.signal });
+    const $ = createStepBuilder({ ctx });
+
+    controller.abort();
+
+    const result = await $.while({
+      id: "while-aborted",
+      condition: () => true,
+      execute: async ({ index }) => index,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("Aborted");
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.while({
+      id: "while-hooks",
+      condition: ({ index }) => index < 2,
+      onStart: () => {
+        order.push("onStart");
+      },
+      execute: async ({ index }) => {
+        order.push(`execute:${index}`);
+        return index;
+      },
+      onFinish: () => {
+        order.push("onFinish");
+      },
+    });
+
+    expect(order).toEqual(["onStart", "execute:0", "execute:1", "onFinish"]);
+  });
+
+  it("fires onError hook on failure", async () => {
+    const onError = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.while({
+      id: "while-onerror",
+      condition: () => true,
+      execute: async () => {
+        throw new Error("while failure");
+      },
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "while-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives last value and duration", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.while({
+      id: "while-finish",
+      condition: ({ index }) => index < 3,
+      execute: async ({ index }) => index * 10,
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "while-finish",
+        result: 20,
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("onFinish receives undefined when condition is initially false", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.while({
+      id: "while-finish-none",
+      condition: () => false,
+      execute: async () => "never",
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "while-finish-none",
+        result: undefined,
+      }),
+    );
+  });
+
+  it("records trace entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.while({
+      id: "while-trace",
+      condition: ({ index }) => index < 2,
+      execute: async ({ index }) => index,
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.id).toBe("while-trace");
+    expect(traceEntry.type).toBe("while");
+    expect(traceEntry.output).toBe(1);
+  });
+
+  it("provides child $ for nested operations", async () => {
+    const ctx = createMockCtx();
+    const $$ = createStepBuilder({ ctx });
+
+    await $$.while({
+      id: "while-nested",
+      condition: ({ index }) => index < 1,
+      execute: async ({ index, $ }) => {
+        await $.step({ id: "inner", execute: async () => index });
+        return index;
+      },
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.children).toHaveLength(1);
+  });
+});

package/src/core/agents/flow/steps/while.ts

@@ -0,0 +1,75 @@
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+
+/**
+ * Configuration for `$.while()` — conditional loop.
+ *
+ * Runs while a condition holds. Each iteration is tracked. Returns
+ * the **last value** (`undefined` if the condition was false on
+ * first check).
+ *
+ * @typeParam T - The value type produced by each iteration.
+ */
+export interface WhileConfig<T> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace. Individual iterations appear
+   * as children of this entry.
+   */
+  id: string;
+
+  /**
+   * Loop condition — evaluated before each iteration.
+   *
+   * Called with the last iteration's value (or `undefined` before
+   * the first iteration) and the current iteration index.
+   *
+   * @param params - Condition parameters.
+   * @param params.value - The last iteration's value, or `undefined`
+   *   before the first iteration.
+   * @param params.index - The zero-based iteration index.
+   * @returns `true` to continue looping, `false` to stop.
+   */
+  condition: (params: { value: T | undefined; index: number }) => boolean;
+
+  /**
+   * Execute one iteration.
+   *
+   * @param params - Execution parameters.
+   * @param params.index - The zero-based iteration index.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The value for this iteration.
+   */
+  execute: (params: { index: number; $: StepBuilder }) => Promise<T>;
+
+  /**
+   * Hook: fires when the while loop starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when the while loop finishes.
+   *
+   * @param event - Event containing the step id, last value, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The last iteration's value, or `undefined`.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: T | undefined;
+    duration: number;
+  }) => void | Promise<void>;
+
+  /**
+   * Hook: fires if the while loop encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}

package/src/core/agents/flow/types.ts

@@ -0,0 +1,348 @@
+import type { ZodType } from "zod";
+
+import type { GenerateResult, Message, StreamResult } from "@/core/agents/base/types.js";
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+import type { Logger } from "@/core/logger.js";
+import type { TraceEntry, OperationType } from "@/lib/trace.js";
+import type { Result } from "@/utils/result.js";
+
+/**
+ * Information about a step in a flow agent execution.
+ *
+ * Passed to flow agent-level hooks (`onStepStart`, `onStepFinish`)
+ * and included in step events.
+ */
+export interface StepInfo {
+  /**
+   * The id from the `$` config.
+   *
+   * Matches the `id` field on the step config that produced this event.
+   */
+  id: string;
+
+  /**
+   * Auto-incrementing index within the flow agent execution.
+   *
+   * Starts at `0` for the first `$` call and increments for each
+   * subsequent tracked operation.
+   */
+  index: number;
+
+  /**
+   * What kind of `$` call produced this step.
+   *
+   * Discriminant for filtering or grouping step events.
+   */
+  type: OperationType;
+}
+
+/**
+ * Result of a completed flow agent generation.
+ *
+ * Extends `GenerateResult` with flow-specific fields (`trace`, `duration`).
+ * Consumers who only care about the `Runnable` / `Agent` contract see
+ * `{ output, messages, usage, finishReason }`. Consumers who know they
+ * have a `FlowAgent` can access `trace` and `duration`.
+ *
+ * @typeParam TOutput - The validated output type.
+ */
+export interface FlowAgentGenerateResult<TOutput> extends GenerateResult<TOutput> {
+  /**
+   * The full execution trace.
+   *
+   * A frozen tree of `TraceEntry` nodes representing every tracked `$`
+   * operation that ran during the flow.
+   */
+  trace: readonly TraceEntry[];
+
+  /**
+   * Total wall-clock time in milliseconds.
+   *
+   * Measured from the start of the flow to the completion
+   * of all operations.
+   */
+  duration: number;
+}
+
+/**
+ * Shared configuration fields for all flow agent variants.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ */
+export interface FlowAgentConfigBase<TInput> {
+  /**
+   * Unique flow agent name.
+   *
+   * Used in logging, trace entries, and hook events.
+   */
+  name: string;
+
+  /**
+   * Zod schema for validating flow agent input.
+   *
+   * The raw input passed to `.generate()` is validated against this
+   * schema before the handler is called.
+   */
+  input: ZodType<TInput>;
+
+  /**
+   * Pino-compatible logger.
+   *
+   * When omitted, the SDK creates a default console-based instance.
+   * The framework automatically creates scoped child loggers
+   * with contextual bindings (`flowAgentId`, `stepId`).
+   */
+  logger?: Logger;
+
+  /**
+   * Hook: fires when the flow agent starts execution.
+   *
+   * @param event - Event containing the validated input.
+   */
+  onStart?: (event: { input: TInput }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when the flow agent encounters an error.
+   *
+   * @param event - Event containing the input and error.
+   */
+  onError?: (event: { input: TInput; error: Error }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when any tracked `$` step starts.
+   *
+   * @param event - Event containing step info.
+   */
+  onStepStart?: (event: { step: StepInfo }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when any tracked `$` step finishes.
+   *
+   * @param event - Event containing step info, result, and duration.
+   */
+  onStepFinish?: (event: {
+    step: StepInfo;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+}
+
+/**
+ * Flow agent config with a structured output schema.
+ *
+ * The handler must return a value matching `TOutput`, which is
+ * validated against the `output` Zod schema before being returned.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ */
+export interface FlowAgentConfigWithOutput<TInput, TOutput> extends FlowAgentConfigBase<TInput> {
+  /**
+   * Zod schema for validating flow agent output.
+   *
+   * The handler's return value is validated against this schema
+   * before being returned to the caller.
+   */
+  output: ZodType<TOutput>;
+
+  /**
+   * Hook: fires when the flow agent finishes successfully.
+   *
+   * @param event - Event containing input, result, and duration.
+   */
+  onFinish?: (event: {
+    input: TInput;
+    result: FlowAgentGenerateResult<TOutput>;
+    duration: number;
+  }) => void | Promise<void>;
+}
+
+/**
+ * Flow agent config without an output schema.
+ *
+ * The handler returns `void` — it orchestrates sub-agents and steps
+ * without producing structured output. The collected text from
+ * sub-agent responses becomes the `string` output.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ */
+export interface FlowAgentConfigWithoutOutput<TInput> extends FlowAgentConfigBase<TInput> {
+  /**
+   * No output schema — the flow agent collects text from sub-agent
+   * responses and returns it as a `string`.
+   */
+  output?: undefined;
+
+  /**
+   * Hook: fires when the flow agent finishes successfully.
+   *
+   * @param event - Event containing input, result (with string output), and duration.
+   */
+  onFinish?: (event: {
+    input: TInput;
+    result: FlowAgentGenerateResult<string>;
+    duration: number;
+  }) => void | Promise<void>;
+}
+
+/**
+ * Configuration for creating a flow agent.
+ *
+ * Two variants:
+ * - **With output**: Provide an `output` Zod schema. The handler returns
+ *   `TOutput`, which is validated against the schema.
+ * - **Without output**: Omit `output`. The handler returns `void` and
+ *   the collected text from sub-agent responses becomes the `string` output.
+ *
+ * @typeParam TInput - Input type, inferred from the `input` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `output` Zod schema.
+ */
+export type FlowAgentConfig<TInput, TOutput = void> =
+  | FlowAgentConfigWithOutput<TInput, TOutput>
+  | FlowAgentConfigWithoutOutput<TInput>;
+
+/**
+ * Per-call overrides for flow agent generation.
+ *
+ * Passed as the optional second parameter to `.generate()` or `.stream()`.
+ */
+export interface FlowAgentOverrides {
+  /**
+   * Abort signal for cancellation.
+   *
+   * When fired, all in-flight operations should clean up and exit.
+   * Propagated through the entire execution tree.
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Override the logger for this call.
+   *
+   * When provided, replaces the logger configured at creation time.
+   */
+  logger?: Logger;
+
+  /**
+   * Per-call hook — fires after base `onStart`.
+   */
+  onStart?: (event: { input: unknown }) => void | Promise<void>;
+
+  /**
+   * Per-call hook — fires after base `onFinish`.
+   */
+  onFinish?: (event: {
+    input: unknown;
+    result: GenerateResult;
+    duration: number;
+  }) => void | Promise<void>;
+
+  /**
+   * Per-call hook — fires after base `onError`.
+   */
+  onError?: (event: { input: unknown; error: Error }) => void | Promise<void>;
+
+  /**
+   * Per-call hook — fires after base `onStepFinish`.
+   */
+  onStepFinish?: (event: {
+    step: StepInfo;
+    result: unknown;
+    duration: number;
+  }) => void | Promise<void>;
+}
+
+/**
+ * Parameters passed to the flow agent handler function.
+ *
+ * @typeParam TInput - The validated input type.
+ */
+export interface FlowAgentParams<TInput> {
+  /**
+   * Validated input.
+   */
+  input: TInput;
+
+  /**
+   * Composable step builder utilities.
+   *
+   * Provides tracked operations (`$.step`, `$.agent`, `$.map`, etc.)
+   * that register data flow for observability and produce synthetic
+   * tool-call messages.
+   */
+  $: StepBuilder;
+
+  /**
+   * Scoped logger for the current flow execution.
+   */
+  log: Logger;
+}
+
+/**
+ * The flow agent handler function.
+ *
+ * This IS the flow — no step arrays, no definition objects.
+ * State is just variables. `$` is passed in for tracked operations.
+ *
+ * @typeParam TInput - The validated input type.
+ * @typeParam TOutput - The output type to return.
+ */
+export type FlowAgentHandler<TInput, TOutput> = (
+  params: FlowAgentParams<TInput>,
+) => Promise<TOutput>;
+
+/**
+ * A created flow agent — exposes `.generate()`, `.stream()`, and `.fn()`.
+ *
+ * Flow agents are imperative handlers that use `$` for tracked operations.
+ * They satisfy the same `Runnable` interface as regular agents, so they
+ * can be used as sub-agents, tool-wrapped delegatees, etc.
+ *
+ * @typeParam TInput - Validated input type.
+ * @typeParam TOutput - Validated output type.
+ */
+export interface FlowAgent<TInput, TOutput> {
+  /**
+   * Run the flow agent to completion.
+   *
+   * Validates input, executes the handler, validates output, and
+   * returns the result with messages, trace, and timing.
+   *
+   * @param input - Raw input (validated against the `input` Zod schema).
+   * @param config - Optional per-call overrides.
+   * @returns A `Result` wrapping the `FlowAgentGenerateResult`.
+   */
+  generate(
+    input: TInput,
+    config?: FlowAgentOverrides,
+  ): Promise<Result<FlowAgentGenerateResult<TOutput>>>;
+
+  /**
+   * Run the flow agent with streaming step progress.
+   *
+   * Returns immediately with `fullStream` — an `AsyncIterableStream`
+   * of typed `StreamPart` events for each step. `output`, `messages`,
+   * and `usage` are promises that resolve after the flow completes.
+   *
+   * @param input - Raw input (validated against the `input` Zod schema).
+   * @param config - Optional per-call overrides.
+   * @returns A `Result` wrapping the `StreamResult`.
+   */
+  stream(input: TInput, config?: FlowAgentOverrides): Promise<Result<StreamResult<TOutput>>>;
+
+  /**
+   * Returns a plain function that calls `.generate()`.
+   */
+  fn(): (
+    input: TInput,
+    config?: FlowAgentOverrides,
+  ) => Promise<Result<FlowAgentGenerateResult<TOutput>>>;
+}
+
+/**
+ * @internal
+ * Options that the engine uses to inject custom step augmentation
+ * into flowAgent(). Not exported — only accessible within the package.
+ */
+export interface InternalFlowAgentOptions {
+  augment$?: ($: StepBuilder, ctx: import("@/lib/context.js").Context) => StepBuilder;
+}