@funkai/agents 0.1.0

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

@@ -0,0 +1,273 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+
+describe("map()", () => {
+  it("maps items in parallel via Promise.all by default", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.map({
+      id: "map-all",
+      input: [1, 2, 3],
+      execute: async ({ item }) => item * 2,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual([2, 4, 6]);
+    expect(result.step.type).toBe("map");
+  });
+
+  it("respects concurrency limit", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const state = { maxConcurrent: 0, current: 0 };
+
+    await $.map({
+      id: "map-limited",
+      input: [1, 2, 3, 4, 5],
+      concurrency: 2,
+      execute: async ({ item }) => {
+        state.current++;
+        state.maxConcurrent = Math.max(state.maxConcurrent, state.current);
+        await new Promise((r) => setTimeout(r, 10));
+        state.current--;
+        return item;
+      },
+    });
+
+    expect(state.maxConcurrent).toBeLessThanOrEqual(2);
+  });
+
+  it("returns results in input order regardless of completion order", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.map({
+      id: "map-order",
+      input: [3, 1, 2],
+      concurrency: 2,
+      execute: async ({ item }) => {
+        await new Promise((r) => setTimeout(r, item * 5));
+        return item * 10;
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual([30, 10, 20]);
+  });
+
+  it("handles empty input array", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.map({
+      id: "map-empty",
+      input: [],
+      execute: async () => "should not be called",
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual([]);
+  });
+
+  it("handles single-item input", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.map({
+      id: "map-single",
+      input: ["only"],
+      execute: async ({ item }) => item.toUpperCase(),
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toEqual(["ONLY"]);
+  });
+
+  it("passes index to execute callback", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const indices: number[] = [];
+
+    await $.map({
+      id: "map-index",
+      input: ["a", "b", "c"],
+      execute: async ({ index }) => {
+        indices.push(index);
+        return index;
+      },
+    });
+
+    expect(indices).toContain(0);
+    expect(indices).toContain(1);
+    expect(indices).toContain(2);
+  });
+
+  it("returns ok: false when execute throws", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.map({
+      id: "map-err",
+      input: [1, 2, 3],
+      execute: async ({ item }) => {
+        if (item === 2) {
+          throw new Error("bad item");
+        }
+        return item;
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("bad item");
+    expect(result.error.stepId).toBe("map-err");
+  });
+
+  it("records input in trace", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.map({
+      id: "map-trace",
+      input: [10, 20],
+      execute: async ({ item }) => item,
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.input).toEqual([10, 20]);
+    expect(traceEntry.type).toBe("map");
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.map({
+      id: "map-hooks",
+      input: [1, 2],
+      onStart: () => {
+        order.push("onStart");
+      },
+      execute: async ({ item }) => {
+        order.push(`execute:${item}`);
+        return item;
+      },
+      onFinish: () => {
+        order.push("onFinish");
+      },
+    });
+
+    expect(order[0]).toBe("onStart");
+    expect(order[order.length - 1]).toBe("onFinish");
+  });
+
+  it("fires onError hook on failure", async () => {
+    const onError = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.map({
+      id: "map-onerror",
+      input: [1],
+      execute: async () => {
+        throw new Error("map failure");
+      },
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "map-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives the result array", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.map({
+      id: "map-finish-result",
+      input: [1, 2, 3],
+      execute: async ({ item }) => item * 2,
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "map-finish-result",
+        result: [2, 4, 6],
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("provides child $ for nested operations", async () => {
+    const ctx = createMockCtx();
+    const $$ = createStepBuilder({ ctx });
+
+    await $$.map({
+      id: "map-nested",
+      input: [1],
+      execute: async ({ item, $ }) => {
+        const inner = await $.step({
+          id: "inner",
+          execute: async () => item + 10,
+        });
+        if (!inner.ok) {
+          throw new Error("inner step failed");
+        }
+        return inner.value;
+      },
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.children).toHaveLength(1);
+  });
+
+  it("handles concurrency of 1 (sequential)", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const order: number[] = [];
+
+    await $.map({
+      id: "map-seq",
+      input: [1, 2, 3],
+      concurrency: 1,
+      execute: async ({ item }) => {
+        order.push(item);
+        await new Promise((r) => setTimeout(r, 5));
+        return item;
+      },
+    });
+
+    expect(order).toEqual([1, 2, 3]);
+  });
+});

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

@@ -0,0 +1,75 @@
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+
+/**
+ * Configuration for `$.map()` — parallel map with optional concurrency limit.
+ *
+ * Each item is processed as a tracked operation. All run concurrently
+ * (up to `concurrency` limit). Returns results in input order.
+ *
+ * @typeParam T - Input item type.
+ * @typeParam R - Output item type.
+ */
+export interface MapConfig<T, R> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace. Individual iterations appear
+   * as children of this entry.
+   */
+  id: string;
+
+  /**
+   * Array of items to process.
+   *
+   * Each item is passed to the `execute` callback along with its index.
+   */
+  input: readonly T[];
+
+  /**
+   * Maximum number of parallel executions.
+   *
+   * When set, limits how many `execute` callbacks run concurrently.
+   * Results are still returned in input order regardless.
+   *
+   * @default Infinity
+   */
+  concurrency?: number;
+
+  /**
+   * Process a single item.
+   *
+   * @param params - Execution parameters.
+   * @param params.item - The current item from the input array.
+   * @param params.index - The item's zero-based index in the input array.
+   * @param params.$ - The step builder for nesting further operations.
+   * @returns The processed result for this item.
+   */
+  execute: (params: { item: T; index: number; $: StepBuilder }) => Promise<R>;
+
+  /**
+   * Hook: fires when the map operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when all items are processed.
+   *
+   * @param event - Event containing the step id, results, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - Array of results in input order.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: { id: string; result: R[]; duration: number }) => void | Promise<void>;
+
+  /**
+   * Hook: fires if the map operation encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}

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

@@ -0,0 +1,290 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+
+describe("race()", () => {
+  it("returns first resolved value", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.race({
+      id: "race-first",
+      entries: [
+        () => new Promise((r) => setTimeout(() => r("slow"), 50)),
+        () => Promise.resolve("fast"),
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe("fast");
+    expect(result.step.type).toBe("race");
+  });
+
+  it("cancels losing entries via abort signal", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const signals: { loser: AbortSignal | undefined } = { loser: undefined };
+
+    const result = await $.race({
+      id: "race-cancel",
+      entries: [
+        () => Promise.resolve("winner"),
+        (signal) => {
+          signals.loser = signal;
+          return new Promise((r) => setTimeout(() => r("loser"), 500));
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe("winner");
+    if (signals.loser === undefined) {
+      throw new Error("Expected loser signal");
+    }
+    expect(signals.loser.aborted).toBe(true);
+  });
+
+  it("passes abort signal to all entry factories", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const receivedSignals: AbortSignal[] = [];
+
+    await $.race({
+      id: "race-signals",
+      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("all entries share the same abort signal", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const receivedSignals: AbortSignal[] = [];
+
+    await $.race({
+      id: "race-shared-signal",
+      entries: [
+        (signal) => {
+          receivedSignals.push(signal);
+          return Promise.resolve("first");
+        },
+        (signal) => {
+          receivedSignals.push(signal);
+          return new Promise((r) => setTimeout(() => r("second"), 100));
+        },
+      ],
+    });
+
+    expect(receivedSignals).toHaveLength(2);
+    expect(receivedSignals[0]).toBe(receivedSignals[1]);
+  });
+
+  it("returns ok: false when all entries reject", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.race({
+      id: "race-all-fail",
+      entries: [
+        () => Promise.reject(new Error("fail-1")),
+        () => Promise.reject(new Error("fail-2")),
+      ],
+    });
+
+    // Promise.race rejects with the first rejection
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.stepId).toBe("race-all-fail");
+  });
+
+  it("handles single entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.race({
+      id: "race-single",
+      entries: [() => Promise.resolve("only")],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe("only");
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.race({
+      id: "race-hooks",
+      entries: [() => Promise.resolve("done")],
+      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 $.race({
+      id: "race-onerror",
+      entries: [() => Promise.reject(new Error("race failure"))],
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "race-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives the winner result", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.race({
+      id: "race-finish",
+      entries: [() => Promise.resolve("winner")],
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "race-finish",
+        result: "winner",
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("records trace entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.race({
+      id: "race-trace",
+      entries: [() => Promise.resolve("traced")],
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.id).toBe("race-trace");
+    expect(traceEntry.type).toBe("race");
+    expect(traceEntry.output).toBe("traced");
+  });
+
+  it("passes child $ to entry factories", async () => {
+    const ctx = createMockCtx();
+    const $$ = createStepBuilder({ ctx });
+
+    await $$.race({
+      id: "race-child-$",
+      entries: [
+        async (_signal, $) => {
+          const inner = await $.step({
+            id: "inner-from-race",
+            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-race");
+  });
+
+  it("aborts signal on error too (finally block)", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const signals: { entry: AbortSignal | undefined } = { entry: undefined };
+
+    await $.race({
+      id: "race-abort-on-err",
+      entries: [
+        () => Promise.reject(new Error("fail")),
+        (signal) => {
+          signals.entry = signal;
+          return new Promise((r) => setTimeout(() => r("late"), 500));
+        },
+      ],
+    });
+
+    // The finally block in race() always aborts
+    if (signals.entry !== undefined) {
+      expect(signals.entry.aborted).toBe(true);
+    }
+  });
+
+  it("winner resolves before losers complete", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.race({
+      id: "race-timing",
+      entries: [
+        () => new Promise((r) => setTimeout(() => r("slow-1"), 100)),
+        () => new Promise((r) => setTimeout(() => r("slow-2"), 200)),
+        () => Promise.resolve("instant"),
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBe("instant");
+  });
+});

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

@@ -0,0 +1,59 @@
+import type { EntryFactory } from "@/core/agents/flow/steps/all.js";
+
+/**
+ * Configuration for `$.race()` — first-to-finish wins.
+ *
+ * Like `Promise.race` — takes an array of factory functions. Returns
+ * the first resolved value. Losers are cancelled via abort signal.
+ */
+export interface RaceConfig {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+
+  /**
+   * Array of factory functions to race.
+   *
+   * Each factory receives an `AbortSignal`. The first to resolve
+   * wins; losers are cancelled by aborting the signal.
+   *
+   * @example
+   * ```typescript
+   * entries: [
+   *   (signal) => $.step({ id: 'fast', execute: () => fetchFast(signal) }),
+   *   (signal) => $.step({ id: 'slow', execute: () => fetchSlow(signal) }),
+   * ]
+   * ```
+   */
+  entries: EntryFactory[];
+
+  /**
+   * Hook: fires when the race starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when the first entry completes.
+   *
+   * @param event - Event containing the step id, winner result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The first resolved value.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: { id: string; result: unknown; duration: number }) => void | Promise<void>;
+
+  /**
+   * Hook: fires if the race encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}