@funkai/agents 0.1.0

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

@@ -0,0 +1,300 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+
+describe("all()", () => {
+  it("resolves all entries concurrently", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-entries",
+      entries: [() => Promise.resolve("a"), () => Promise.resolve("b"), () => Promise.resolve("c")],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual(["a", "b", "c"]);
+    expect(result.step.type).toBe("all");
+  });
+
+  it("fails fast on first error", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-fail",
+      entries: [
+        () => Promise.resolve("a"),
+        () => Promise.reject(new Error("fail")),
+        () => Promise.resolve("c"),
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("fail");
+    expect(result.error.stepId).toBe("all-fail");
+  });
+
+  it("passes abort signal to entry factories", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const receivedSignals: AbortSignal[] = [];
+
+    await $.all({
+      id: "all-signal",
+      entries: [
+        (signal) => {
+          receivedSignals.push(signal);
+          return Promise.resolve("a");
+        },
+        (signal) => {
+          receivedSignals.push(signal);
+          return Promise.resolve("b");
+        },
+      ],
+    });
+
+    expect(receivedSignals).toHaveLength(2);
+    expect(receivedSignals[0]).toBeInstanceOf(AbortSignal);
+    expect(receivedSignals[1]).toBeInstanceOf(AbortSignal);
+  });
+
+  it("aborts signal on error", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const signals: { entry: AbortSignal | undefined } = { entry: undefined };
+
+    await $.all({
+      id: "all-abort-on-err",
+      entries: [
+        () => Promise.reject(new Error("fail fast")),
+        (signal) => {
+          signals.entry = signal;
+          return new Promise((r) => setTimeout(() => r("late"), 500));
+        },
+      ],
+    });
+
+    if (signals.entry === undefined) {
+      throw new Error("Expected entry signal");
+    }
+    expect(signals.entry.aborted).toBe(true);
+  });
+
+  it("handles empty entries array", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-empty",
+      entries: [],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual([]);
+  });
+
+  it("handles single entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-single",
+      entries: [() => Promise.resolve(42)],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual([42]);
+  });
+
+  it("returns results in entry order", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-order",
+      entries: [
+        () => new Promise((r) => setTimeout(() => r("slow"), 30)),
+        () => Promise.resolve("fast"),
+        () => new Promise((r) => setTimeout(() => r("medium"), 10)),
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual(["slow", "fast", "medium"]);
+  });
+
+  it("propagates parent abort signal to child abort controller", async () => {
+    const controller = new AbortController();
+    const ctx = createMockCtx({ signal: controller.signal });
+    const $ = createStepBuilder({ ctx });
+    const signals: { entry: AbortSignal | undefined } = { entry: undefined };
+
+    const result = await $.all({
+      id: "all-parent-abort",
+      entries: [
+        (signal) => {
+          signals.entry = signal;
+          // Abort the parent after the factory captures the child signal
+          controller.abort();
+          return Promise.resolve("done");
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (signals.entry === undefined) {
+      throw new Error("Expected entry signal");
+    }
+    expect(signals.entry.aborted).toBe(true);
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.all({
+      id: "all-hooks",
+      entries: [() => Promise.resolve("a")],
+      onStart: () => {
+        order.push("onStart");
+      },
+      onFinish: () => {
+        order.push("onFinish");
+      },
+    });
+
+    expect(order).toEqual(["onStart", "onFinish"]);
+  });
+
+  it("fires onError hook on failure", async () => {
+    const onError = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.all({
+      id: "all-onerror",
+      entries: [() => Promise.reject(new Error("all failure"))],
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "all-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives the results array", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.all({
+      id: "all-finish-result",
+      entries: [() => Promise.resolve(1), () => Promise.resolve(2)],
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "all-finish-result",
+        result: [1, 2],
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("records trace entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.all({
+      id: "all-trace",
+      entries: [() => Promise.resolve("traced")],
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.id).toBe("all-trace");
+    expect(traceEntry.type).toBe("all");
+    expect(traceEntry.output).toEqual(["traced"]);
+  });
+
+  it("passes child $ to entry factories", async () => {
+    const ctx = createMockCtx();
+    const $$ = createStepBuilder({ ctx });
+
+    await $$.all({
+      id: "all-child-$",
+      entries: [
+        async (_signal, $) => {
+          const inner = await $.step({
+            id: "inner-from-all",
+            execute: async () => "nested",
+          });
+          if (!inner.ok) {
+            throw new Error("inner failed");
+          }
+          return inner.value;
+        },
+      ],
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.children).toHaveLength(1);
+    if (traceEntry.children === undefined) {
+      throw new Error("Expected children");
+    }
+    const child = traceEntry.children[0];
+    if (child === undefined) {
+      throw new Error("Expected child entry");
+    }
+    expect(child.id).toBe("inner-from-all");
+  });
+
+  it("handles heterogeneous return types", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.all({
+      id: "all-hetero",
+      entries: [
+        () => Promise.resolve("string"),
+        () => Promise.resolve(42),
+        () => Promise.resolve({ key: "value" }),
+        () => Promise.resolve([1, 2, 3]),
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual(["string", 42, { key: "value" }, [1, 2, 3]]);
+  });
+});

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

@@ -0,0 +1,73 @@
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+
+/**
+ * A factory that receives an abort signal and returns a promise.
+ *
+ * Used by `$.all()` and `$.race()` so the framework controls when
+ * work starts and can cancel entries via the signal.
+ *
+ * The optional `$` parameter provides a child step builder whose
+ * trace entries nest under the parent `all`/`race` step. Using it
+ * is recommended for correct trace hierarchy.
+ */
+export type EntryFactory = (signal: AbortSignal, $: StepBuilder) => Promise<unknown>;
+
+/**
+ * Configuration for `$.all()` — concurrent heterogeneous operations.
+ *
+ * Like `Promise.all` — takes an array of factory functions that the
+ * framework starts concurrently. Returns results as a tuple in the
+ * same order. Fails fast on the first error.
+ */
+export interface AllConfig {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+
+  /**
+   * Array of factory functions to run concurrently.
+   *
+   * Each factory receives an `AbortSignal` and should return a
+   * promise. The framework starts all factories at the same time
+   * so timing and traces are accurate.
+   *
+   * @example
+   * ```typescript
+   * entries: [
+   *   (signal) => $.step({ id: 'a', execute: () => fetchA(signal) }),
+   *   (signal) => $.step({ id: 'b', execute: () => fetchB(signal) }),
+   * ]
+   * ```
+   */
+  entries: EntryFactory[];
+
+  /**
+   * Hook: fires when the all operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when all entries complete.
+   *
+   * @param event - Event containing the step id, results, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - Array of results in entry order.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: { id: string; result: unknown[]; duration: number }) => void | Promise<void>;
+
+  /**
+   * Hook: fires if any entry encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}

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

@@ -0,0 +1,124 @@
+import type { GenerateResult } from "@/core/agents/base/types.js";
+import type { AgentStepConfig } from "@/core/agents/flow/steps/agent.js";
+import type { AllConfig } from "@/core/agents/flow/steps/all.js";
+import type { EachConfig } from "@/core/agents/flow/steps/each.js";
+import type { MapConfig } from "@/core/agents/flow/steps/map.js";
+import type { RaceConfig } from "@/core/agents/flow/steps/race.js";
+import type { ReduceConfig } from "@/core/agents/flow/steps/reduce.js";
+import type { StepResult } from "@/core/agents/flow/steps/result.js";
+import type { StepConfig } from "@/core/agents/flow/steps/step.js";
+import type { WhileConfig } from "@/core/agents/flow/steps/while.js";
+
+/**
+ * The `$` object — composable step utilities.
+ *
+ * Provides tracked operations that register data flow for observability.
+ * Every call through `$` becomes an entry in the execution trace.
+ *
+ * `$` is passed into every callback, enabling composition and nesting.
+ * You can always skip `$` and use plain imperative code — it just
+ * won't appear in the trace.
+ */
+export interface StepBuilder {
+  /**
+   * Execute and register a single unit of work.
+   *
+   * @typeParam T - The return type of the step.
+   * @param config - Step configuration with id, execute function,
+   *   and optional hooks.
+   * @returns A `StepResult` with `.value` containing the step's
+   *   return value on success, or a `StepError` on failure.
+   */
+  step<T>(config: StepConfig<T>): Promise<StepResult<T>>;
+
+  /**
+   * Execute an agent call as a tracked operation.
+   *
+   * The framework records the agent name, input, and output in the
+   * trace. Calls `agent.generate()` internally and unwraps the result —
+   * agent errors become `StepError`, agent success becomes
+   * `StepResult<GenerateResult>`.
+   *
+   * @typeParam TInput - The agent's input type.
+   * @param config - Agent step configuration with id, agent, input,
+   *   optional overrides, and optional hooks.
+   * @returns A `StepResult` wrapping the agent's `GenerateResult`.
+   */
+  agent<TInput>(config: AgentStepConfig<TInput>): Promise<StepResult<GenerateResult>>;
+
+  /**
+   * Parallel map — each item is a tracked operation.
+   *
+   * All items run concurrently (up to `concurrency` limit).
+   * Returns results in input order.
+   *
+   * @typeParam T - Input item type.
+   * @typeParam R - Output item type.
+   * @param config - Map configuration with id, input array, execute
+   *   function, optional concurrency, and optional hooks.
+   * @returns A `StepResult` wrapping the array of results in input order.
+   */
+  map<T, R>(config: MapConfig<T, R>): Promise<StepResult<R[]>>;
+
+  /**
+   * Sequential side effects — runs one item at a time.
+   *
+   * Returns `void`. Use `$.reduce()` if you need accumulated results.
+   *
+   * @typeParam T - Input item type.
+   * @param config - Each configuration with id, input array, execute
+   *   function, and optional hooks.
+   * @returns A `StepResult` wrapping void when all items are processed.
+   */
+  each<T>(config: EachConfig<T>): Promise<StepResult<void>>;
+
+  /**
+   * Sequential accumulation — each step depends on the previous result.
+   *
+   * @typeParam T - Input item type.
+   * @typeParam R - Accumulator/result type.
+   * @param config - Reduce configuration with id, input array, initial
+   *   value, execute function, and optional hooks.
+   * @returns A `StepResult` wrapping the final accumulated value.
+   */
+  reduce<T, R>(config: ReduceConfig<T, R>): Promise<StepResult<R>>;
+
+  /**
+   * Conditional loop — runs while a condition holds.
+   *
+   * Returns the last value, or `undefined` if the condition was
+   * false on the first check.
+   *
+   * @typeParam T - The value type produced by each iteration.
+   * @param config - While configuration with id, condition, execute
+   *   function, and optional hooks.
+   * @returns A `StepResult` wrapping the last iteration's value, or `undefined`.
+   */
+  while<T>(config: WhileConfig<T>): Promise<StepResult<T | undefined>>;
+
+  /**
+   * Run heterogeneous operations concurrently — like `Promise.all`.
+   *
+   * Entries are factory functions that receive an `AbortSignal` and
+   * return a promise. The framework starts all factories at the same
+   * time so timing and traces are accurate.
+   *
+   * @param config - All configuration with id, entry factories,
+   *   and optional hooks.
+   * @returns A `StepResult` wrapping the array of results in entry order.
+   */
+  all(config: AllConfig): Promise<StepResult<unknown[]>>;
+
+  /**
+   * Run operations concurrently — first to finish wins.
+   *
+   * Entries are factory functions that receive an `AbortSignal`.
+   * The first to resolve wins; losers are cancelled by aborting
+   * the signal.
+   *
+   * @param config - Race configuration with id, entry factories,
+   *   and optional hooks.
+   * @returns A `StepResult` wrapping the first resolved value.
+   */
+  race(config: RaceConfig): Promise<StepResult<unknown>>;
+}