@funkai/agents 0.1.0

package/src/lib/trace.ts

@@ -0,0 +1,145 @@
+import { match, P } from "ts-pattern";
+
+import type { TokenUsage } from "@/core/provider/types.js";
+
+/**
+ * Known trace operation types.
+ *
+ * Each `$` method registers a specific operation type in the execution
+ * trace. This discriminant allows consumers to filter or group trace
+ * entries by kind.
+ */
+export type OperationType = "step" | "agent" | "map" | "each" | "reduce" | "while" | "all" | "race";
+
+/** @deprecated Use `OperationType` instead. */
+export type TraceType = OperationType;
+
+/**
+ * A single entry in the execution trace.
+ *
+ * Every tracked `$` operation produces a TraceEntry. Nested operations
+ * (e.g. agent calls inside a map iteration) appear as children,
+ * forming a tree that represents the full execution graph.
+ *
+ * @internal
+ *   Part of the internal execution context. Exposed on
+ *   `WorkflowResult.trace` for observability but not directly
+ *   constructed by user code.
+ */
+export interface TraceEntry {
+  /**
+   * Unique id of this operation.
+   *
+   * Corresponds to the `id` field from the `$` config that
+   * produced this entry.
+   */
+  id: string;
+
+  /**
+   * What kind of operation produced this entry.
+   *
+   * Discriminant for filtering or grouping trace entries.
+   */
+  type: OperationType;
+
+  /**
+   * Input snapshot.
+   *
+   * Captured when the operation starts. May be `undefined` for
+   * operations that have no meaningful input (e.g. `$.all`).
+   */
+  input?: unknown;
+
+  /**
+   * Output snapshot.
+   *
+   * Captured when the operation completes successfully. `undefined`
+   * if the operation is still running or failed.
+   */
+  output?: unknown;
+
+  /**
+   * Start time in Unix milliseconds.
+   *
+   * Set when the operation begins execution.
+   */
+  startedAt: number;
+
+  /**
+   * End time in Unix milliseconds.
+   *
+   * Set when the operation completes (success or failure).
+   * `undefined` while the operation is still running.
+   */
+  finishedAt?: number;
+
+  /**
+   * Error instance if the operation failed.
+   *
+   * `undefined` on success or while still running.
+   */
+  error?: Error;
+
+  /**
+   * Token usage from this operation.
+   *
+   * Populated for `agent` type entries that complete successfully.
+   * `undefined` for non-agent steps or failed operations.
+   */
+  usage?: TokenUsage;
+
+  /**
+   * Nested trace entries for child operations.
+   *
+   * Present when this operation spawns sub-operations
+   * (e.g. individual iterations inside `$.map`, or nested
+   * `$.step` calls inside a step's `execute` callback).
+   */
+  children?: readonly TraceEntry[];
+}
+
+/**
+ * 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.
+ */
+export function collectUsages(trace: readonly TraceEntry[]): TokenUsage[] {
+  return trace.flatMap((entry) => {
+    const usages: TokenUsage[] = 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
+ */
+export function snapshotTrace(trace: readonly TraceEntry[]): readonly TraceEntry[] {
+  return Object.freeze(
+    trace.map((entry) => {
+      const children = match(entry.children)
+        .with(P.nonNullable, (c) => snapshotTrace(c))
+        .otherwise(() => undefined);
+      const childSpread = match(children)
+        .with(P.nonNullable, (c) => ({ children: c }))
+        .otherwise(() => ({}));
+      return Object.freeze({
+        ...entry,
+        ...childSpread,
+      });
+    }),
+  );
+}

package/src/models/index.ts

@@ -0,0 +1,123 @@
+// ──────────────────────────────────────────────────────────────
+//  █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+// ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+// ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+// ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+// ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+// ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
+//
+// AUTO-GENERATED — DO NOT EDIT
+// Update: pnpm --filter=@pkg/agent-sdk generate:models
+// ──────────────────────────────────────────────────────────────
+
+import { match } from "ts-pattern";
+
+import { MODELS as GENERATED_MODELS } from "./providers/index.js";
+
+/**
+ * Supported OpenRouter model identifiers, derived from the generated {@link MODELS} array.
+ */
+export type OpenRouterLanguageModelId = (typeof GENERATED_MODELS)[number]["id"];
+
+/**
+ * Model category for classification and filtering.
+ */
+export type ModelCategory = "chat" | "coding" | "reasoning";
+
+/**
+ * Per-model pricing in USD per token.
+ *
+ * Field names match the OpenRouter API convention. All values are
+ * per-token (or per-unit) rates as numbers. Optional fields are
+ * omitted when the provider does not support them.
+ */
+export interface ModelPricing {
+  /** Cost per input (prompt) token. */
+  prompt: number;
+
+  /** Cost per output (completion) token. */
+  completion: number;
+
+  /** Cost per cached input token (read). */
+  inputCacheRead?: number;
+
+  /** Cost per cached input token (write). */
+  inputCacheWrite?: number;
+
+  /** Cost per web search request. */
+  webSearch?: number;
+
+  /** Cost per internal reasoning token. */
+  internalReasoning?: number;
+
+  /** Cost per image input token. */
+  image?: number;
+
+  /** Cost per audio input second. */
+  audio?: number;
+
+  /** Cost per audio output second. */
+  audioOutput?: number;
+}
+
+/**
+ * Model definition with metadata and pricing.
+ */
+export interface ModelDefinition {
+  /** OpenRouter model identifier (e.g. `"openai/gpt-5.2-codex"`). */
+  id: string;
+
+  /** Model category for classification. */
+  category: ModelCategory;
+
+  /** Token pricing rates. */
+  pricing: ModelPricing;
+}
+
+/**
+ * Supported OpenRouter models with pricing data.
+ */
+export const MODELS = GENERATED_MODELS satisfies readonly ModelDefinition[];
+
+/**
+ * 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'
+ * ```
+ */
+export function model(id: OpenRouterLanguageModelId): ModelDefinition {
+  const found = MODELS.find((m) => m.id === id);
+  if (!found) {
+    throw new Error(`Unknown model: ${id}`);
+  }
+  return found;
+}
+
+/**
+ * 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')
+ * ```
+ */
+export function models(filter?: (m: ModelDefinition) => boolean): readonly ModelDefinition[] {
+  return match(filter)
+    .when(
+      (f): f is (m: ModelDefinition) => boolean => f != null,
+      (f) => MODELS.filter(f),
+    )
+    .otherwise(() => MODELS);
+}

package/src/models/providers/index.ts

@@ -0,0 +1,15 @@
+// ──────────────────────────────────────────────────────────────
+//  █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+// ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+// ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+// ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+// ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+// ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
+//
+// AUTO-GENERATED — DO NOT EDIT
+// Update: pnpm --filter=@pkg/agent-sdk generate:models
+// ──────────────────────────────────────────────────────────────
+
+import { OPENAI_MODELS } from "./openai.js";
+
+export const MODELS = [...OPENAI_MODELS] as const;

package/src/models/providers/openai.ts

@@ -0,0 +1,84 @@
+// ──────────────────────────────────────────────────────────────
+//  █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+// ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+// ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+// ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+// ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+// ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
+//
+// AUTO-GENERATED — DO NOT EDIT
+// Update: pnpm --filter=@pkg/agent-sdk generate:models
+// ──────────────────────────────────────────────────────────────
+
+export const OPENAI_MODELS = [
+  {
+    id: "openai/gpt-5.2-codex",
+    category: "coding",
+    pricing: { prompt: 0.00000175, completion: 0.000014, inputCacheRead: 1.75e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5.2",
+    category: "chat",
+    pricing: { prompt: 0.00000175, completion: 0.000014, inputCacheRead: 1.75e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5.1",
+    category: "chat",
+    pricing: { prompt: 0.00000125, completion: 0.00001, inputCacheRead: 1.25e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5",
+    category: "chat",
+    pricing: { prompt: 0.00000125, completion: 0.00001, inputCacheRead: 1.25e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5-mini",
+    category: "chat",
+    pricing: { prompt: 2.5e-7, completion: 0.000002, inputCacheRead: 2.5e-8, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5-nano",
+    category: "chat",
+    pricing: { prompt: 5e-8, completion: 4e-7, inputCacheRead: 5e-9, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1",
+    category: "chat",
+    pricing: { prompt: 0.000002, completion: 0.000008, inputCacheRead: 5e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1-mini",
+    category: "chat",
+    pricing: { prompt: 4e-7, completion: 0.0000016, inputCacheRead: 1e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1-nano",
+    category: "chat",
+    pricing: { prompt: 1e-7, completion: 4e-7, inputCacheRead: 2.5e-8, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4o",
+    category: "chat",
+    pricing: { prompt: 0.0000025, completion: 0.00001, inputCacheRead: 0.00000125 },
+  },
+  {
+    id: "openai/gpt-4o-mini",
+    category: "chat",
+    pricing: { prompt: 1.5e-7, completion: 6e-7, inputCacheRead: 7.5e-8 },
+  },
+  {
+    id: "openai/o3",
+    category: "reasoning",
+    pricing: { prompt: 0.000002, completion: 0.000008, inputCacheRead: 5e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/o3-mini",
+    category: "reasoning",
+    pricing: { prompt: 0.0000011, completion: 0.0000044, inputCacheRead: 5.5e-7 },
+  },
+  {
+    id: "openai/o4-mini",
+    category: "reasoning",
+    pricing: { prompt: 0.0000011, completion: 0.0000044, inputCacheRead: 2.75e-7, webSearch: 0.01 },
+  },
+] as const;

package/src/testing/context.ts

@@ -0,0 +1,32 @@
+import type { Context, ExecutionContext } from "@/lib/context.js";
+import { createMockLogger } from "@/testing/logger.js";
+
+/**
+ * Create a mock {@link ExecutionContext} with a mock logger
+ * and a live (non-aborted) signal.
+ *
+ * Pass `overrides` to replace individual fields.
+ */
+export function createMockExecutionCtx(overrides?: Partial<ExecutionContext>): ExecutionContext {
+  return {
+    signal: new AbortController().signal,
+    log: createMockLogger(),
+    ...overrides,
+  };
+}
+
+/**
+ * Create a mock {@link Context} with an empty trace, a mock logger,
+ * and a live (non-aborted) signal.
+ *
+ * Pass `overrides` to replace individual fields.
+ */
+export function createMockCtx(overrides?: Partial<Context>): Context {
+  return {
+    signal: new AbortController().signal,
+    log: createMockLogger(),
+    trace: [],
+    messages: [],
+    ...overrides,
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export { createMockLogger } from "@/testing/logger.js";
+export { createMockCtx, createMockExecutionCtx } from "@/testing/context.js";

package/src/testing/logger.ts

@@ -0,0 +1,19 @@
+import { vi } from "vitest";
+
+import type { Logger } from "@/core/logger.js";
+
+/**
+ * Create a mock {@link Logger} backed by `vi.fn()` stubs.
+ *
+ * Every method is a no-op spy. `child()` returns a fresh mock
+ * logger so nested scopes work without blowing up.
+ */
+export function createMockLogger(): Logger {
+  return {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    child: vi.fn(() => createMockLogger()),
+  } as unknown as Logger;
+}

package/src/utils/attempt.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+
+import { attemptEach, attemptEachAsync } from "@/utils/attempt.js";
+
+describe("attemptEach", () => {
+  it("returns success tuples for handlers that succeed", () => {
+    const results = attemptEach(
+      () => 1,
+      () => 2,
+    );
+    expect(results).toEqual([
+      [null, 1],
+      [null, 2],
+    ]);
+  });
+
+  it("returns error tuples for handlers that throw", () => {
+    const results = attemptEach(
+      () => {
+        throw new Error("boom");
+      },
+      () => 42,
+    );
+
+    expect(results).toHaveLength(2);
+    const first = results[0];
+    if (first == null) {
+      throw new Error("Expected first result to be defined");
+    }
+    expect(first[0]).toBeInstanceOf(Error);
+    expect((first[0] as Error).message).toBe("boom");
+    expect(first[1]).toBeNull();
+    expect(results[1]).toEqual([null, 42]);
+  });
+
+  it("skips undefined handlers", () => {
+    const results = attemptEach(
+      undefined,
+      () => "a",
+      undefined,
+      () => "b",
+      undefined,
+    );
+    expect(results).toEqual([
+      [null, "a"],
+      [null, "b"],
+    ]);
+  });
+
+  it("returns an empty array when all handlers are undefined", () => {
+    const results = attemptEach(undefined, undefined);
+    expect(results).toEqual([]);
+  });
+
+  it("returns an empty array when called with no arguments", () => {
+    const results = attemptEach();
+    expect(results).toEqual([]);
+  });
+});
+
+describe("attemptEachAsync", () => {
+  it("returns success tuples for async handlers that succeed", async () => {
+    const results = await attemptEachAsync(
+      async () => "a",
+      async () => "b",
+    );
+    expect(results).toEqual([
+      [null, "a"],
+      [null, "b"],
+    ]);
+  });
+
+  it("returns error tuples for async handlers that reject", async () => {
+    const results = await attemptEachAsync(
+      async () => {
+        throw new Error("async boom");
+      },
+      async () => "ok",
+    );
+
+    expect(results).toHaveLength(2);
+    const first = results[0];
+    if (first == null) {
+      throw new Error("Expected first result to be defined");
+    }
+    expect(first[0]).toBeInstanceOf(Error);
+    expect((first[0] as Error).message).toBe("async boom");
+    expect(first[1]).toBeNull();
+    expect(results[1]).toEqual([null, "ok"]);
+  });
+
+  it("handles sync handlers passed to the async variant", async () => {
+    const results = await attemptEachAsync(() => "sync");
+    expect(results).toEqual([[null, "sync"]]);
+  });
+
+  it("skips undefined handlers", async () => {
+    const results = await attemptEachAsync(undefined, async () => 1, undefined);
+    expect(results).toEqual([[null, 1]]);
+  });
+
+  it("returns an empty array when all handlers are undefined", async () => {
+    const results = await attemptEachAsync(undefined);
+    expect(results).toEqual([]);
+  });
+
+  it("returns an empty array when called with no arguments", async () => {
+    const results = await attemptEachAsync();
+    expect(results).toEqual([]);
+  });
+
+  it("executes handlers sequentially", async () => {
+    const order: number[] = [];
+    await attemptEachAsync(
+      async () => {
+        order.push(1);
+      },
+      async () => {
+        order.push(2);
+      },
+      async () => {
+        order.push(3);
+      },
+    );
+    expect(order).toEqual([1, 2, 3]);
+  });
+});

package/src/utils/attempt.ts

@@ -0,0 +1,38 @@
+import { attempt, attemptAsync } from "es-toolkit";
+
+/**
+ * Run N callbacks sequentially, swallowing errors.
+ *
+ * Returns an array of `[error, result]` tuples following the
+ * same convention as `attempt` from es-toolkit.
+ *
+ * @param handlers - Callbacks to execute in order. `undefined` entries are skipped.
+ * @returns An array of attempt results for each non-undefined handler.
+ */
+export function attemptEach<T = void, E = Error>(
+  ...handlers: Array<(() => T) | undefined>
+): Array<[null, T] | [E, null]> {
+  return handlers.filter((h): h is () => T => h != null).map((h) => attempt<T, E>(h));
+}
+
+/**
+ * Run N async callbacks sequentially, swallowing errors.
+ *
+ * Returns an array of `[error, result]` tuples following the
+ * same convention as `attemptAsync` from es-toolkit.
+ *
+ * @param handlers - Callbacks to execute in order. `undefined` entries are skipped.
+ * @returns An array of attempt results for each non-undefined handler.
+ */
+export async function attemptEachAsync<T = void, E = Error>(
+  ...handlers: Array<(() => T | Promise<T>) | undefined>
+): Promise<Array<[null, T] | [E, null]>> {
+  const results: Array<[null, T] | [E, null]> = [];
+  for (const h of handlers) {
+    if (h != null) {
+      // oxlint-disable-next-line no-await-in-loop - sequential by design
+      results.push(await attemptAsync<T, E>(async () => h()));
+    }
+  }
+  return results;
+}