@funkai/agents 0.1.0

package/src/lib/hooks.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { fireHooks } from "@/lib/hooks.js";
+import { createMockLogger } from "@/testing/logger.js";
+
+describe("fireHooks", () => {
+  it("runs handlers sequentially", async () => {
+    const log = createMockLogger();
+    const order: number[] = [];
+
+    await fireHooks(
+      log,
+      () => {
+        order.push(1);
+      },
+      () => {
+        order.push(2);
+      },
+      () => {
+        order.push(3);
+      },
+    );
+
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  it("skips undefined handlers", async () => {
+    const log = createMockLogger();
+    const called = vi.fn();
+
+    await fireHooks(log, undefined, called, undefined);
+
+    expect(called).toHaveBeenCalledOnce();
+  });
+
+  it("swallows errors and logs them at warn level", async () => {
+    const log = createMockLogger();
+    const after = vi.fn();
+
+    await fireHooks(
+      log,
+      () => {
+        throw new Error("boom");
+      },
+      after,
+    );
+
+    expect(log.warn).toHaveBeenCalledWith("hook error", { error: "boom" });
+    expect(after).toHaveBeenCalledOnce();
+  });
+
+  it("logs non-Error thrown values as strings", async () => {
+    const log = createMockLogger();
+
+    await fireHooks(log, () => {
+      throw "string error";
+    });
+
+    expect(log.warn).toHaveBeenCalledWith("hook error", { error: "string error" });
+  });
+
+  it("handles async handlers", async () => {
+    const log = createMockLogger();
+    const order: number[] = [];
+
+    await fireHooks(
+      log,
+      async () => {
+        await Promise.resolve();
+        order.push(1);
+      },
+      async () => {
+        await Promise.resolve();
+        order.push(2);
+      },
+    );
+
+    expect(order).toEqual([1, 2]);
+  });
+
+  it("swallows async errors and continues", async () => {
+    const log = createMockLogger();
+    const after = vi.fn();
+
+    await fireHooks(
+      log,
+      async () => {
+        throw new Error("async boom");
+      },
+      after,
+    );
+
+    expect(log.warn).toHaveBeenCalledWith("hook error", { error: "async boom" });
+    expect(after).toHaveBeenCalledOnce();
+  });
+
+  it("does nothing with no handlers", async () => {
+    const log = createMockLogger();
+    await fireHooks(log);
+    expect(log.warn).not.toHaveBeenCalled();
+  });
+});

package/src/lib/hooks.ts

@@ -0,0 +1,59 @@
+import { match } from "ts-pattern";
+
+import type { Logger } from "@/core/logger.js";
+
+const formatHookError = (err: unknown): string =>
+  match(err)
+    .when(
+      (e): e is Error => e instanceof Error,
+      (e) => e.message,
+    )
+    .otherwise((e) => String(e));
+
+/**
+ * Wrap a nullable hook into a callback for `fireHooks`, avoiding
+ * optional chaining, ternaries, and non-null assertions.
+ *
+ * @param hookFn - The hook callback, or undefined if not configured.
+ * @param event - The event payload to pass to the hook.
+ * @returns A thunk that calls the hook with the event, or undefined.
+ *
+ * @private
+ */
+export function wrapHook<T>(
+  hookFn: ((event: T) => void | Promise<void>) | undefined,
+  event: T,
+): (() => void | Promise<void>) | undefined {
+  if (hookFn !== undefined) {
+    return () => hookFn(event);
+  }
+  return undefined;
+}
+
+/**
+ * Run hook callbacks sequentially, logging errors at warn level.
+ *
+ * Unlike `attemptEachAsync`, this function surfaces errors via the
+ * logger so hook failures are visible in diagnostic output.
+ *
+ * @param log - Logger for warning about hook errors.
+ * @param handlers - Callbacks to execute in order. `undefined` entries are skipped.
+ */
+export async function fireHooks(
+  log: Logger,
+  ...handlers: Array<(() => void | Promise<void>) | undefined>
+): Promise<void> {
+  for (const h of handlers) {
+    if (h != null) {
+      try {
+        // oxlint-disable-next-line no-await-in-loop - sequential by design
+        await h();
+      } catch (err) {
+        const errorMessage = formatHookError(err);
+        log.warn("hook error", {
+          error: errorMessage,
+        });
+      }
+    }
+  }
+}

package/src/lib/middleware.test.ts

@@ -0,0 +1,122 @@
+import { type LanguageModelMiddleware } from "ai";
+import { describe, expect, it, vi } from "vitest";
+
+import { withModelMiddleware } from "@/lib/middleware.js";
+
+// ---------------------------------------------------------------------------
+// Helpers — minimal model stubs
+// ---------------------------------------------------------------------------
+
+function createStubModel() {
+  return {
+    specificationVersion: "v3" as const,
+    provider: "test",
+    modelId: "test-model",
+    defaultObjectGenerationMode: "json" as const,
+    supportsImageUrls: false,
+    doGenerate: vi.fn(),
+    doStream: vi.fn(),
+  };
+}
+
+function createStubMiddleware(
+  overrides?: Partial<LanguageModelMiddleware>,
+): LanguageModelMiddleware {
+  return {
+    specificationVersion: "v2",
+    ...overrides,
+  } as LanguageModelMiddleware;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("withModelMiddleware", () => {
+  it("returns the model unchanged when there is no middleware and devtools is off", async () => {
+    const model = createStubModel();
+
+    const result = await withModelMiddleware({
+      model: model as never,
+      devtools: false,
+    });
+
+    expect(result).toBe(model);
+  });
+
+  it("wraps the model when custom middleware is provided", async () => {
+    const model = createStubModel();
+    const middleware = createStubMiddleware({ wrapGenerate: vi.fn() });
+
+    const result = await withModelMiddleware({
+      model: model as never,
+      middleware: [middleware],
+      devtools: false,
+    });
+
+    // The wrapped model should be a different object
+    expect(result).not.toBe(model);
+    // It should still expose the same model ID
+    expect(result.modelId).toBe("test-model");
+  });
+
+  it("applies multiple middleware in order", async () => {
+    const model = createStubModel();
+    const mw1 = createStubMiddleware({ wrapGenerate: vi.fn() });
+    const mw2 = createStubMiddleware({ wrapGenerate: vi.fn() });
+
+    const result = await withModelMiddleware({
+      model: model as never,
+      middleware: [mw1, mw2],
+      devtools: false,
+    });
+
+    expect(result).not.toBe(model);
+    expect(result.modelId).toBe("test-model");
+  });
+
+  it("returns a wrapped model when devtools is explicitly enabled", async () => {
+    const model = createStubModel();
+
+    const result = await withModelMiddleware({
+      model: model as never,
+      devtools: true,
+    });
+
+    // devtools middleware should wrap the model
+    expect(result).not.toBe(model);
+  });
+
+  it("respects devtools=false even in development", async () => {
+    const original = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+
+    const model = createStubModel();
+
+    const result = await withModelMiddleware({
+      model: model as never,
+      devtools: false,
+    });
+
+    expect(result).toBe(model);
+
+    process.env.NODE_ENV = original;
+  });
+
+  it("enables devtools automatically when NODE_ENV is development and devtools is not set", async () => {
+    const original = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+
+    const model = createStubModel();
+
+    const result = await withModelMiddleware({
+      model: model as never,
+    });
+
+    // devtools middleware should wrap the model automatically
+    expect(result).not.toBe(model);
+    expect(result.modelId).toBe("test-model");
+
+    process.env.NODE_ENV = original;
+  });
+});

package/src/lib/middleware.ts

@@ -0,0 +1,63 @@
+import { wrapLanguageModel, type LanguageModelMiddleware } from "ai";
+
+import { type LanguageModel } from "@/core/provider/types.js";
+
+/**
+ * Options for {@link withModelMiddleware}.
+ */
+interface WrapModelOptions {
+  /** The base language model to wrap. */
+  model: LanguageModel;
+
+  /**
+   * Additional middleware to apply before defaults (outermost).
+   * Middleware runs in array order — first entry wraps outermost.
+   */
+  middleware?: LanguageModelMiddleware[];
+
+  /**
+   * Whether to include the AI SDK devtools middleware.
+   *
+   * Defaults to `true` when `NODE_ENV === 'development'`.
+   * Set to `false` to disable in development, or `true` to force-enable.
+   */
+  devtools?: boolean;
+}
+
+/**
+ * Wrap a language model with middleware.
+ *
+ * In development (`NODE_ENV === 'development'`), the AI SDK devtools
+ * middleware is appended automatically. Any additional middleware
+ * provided in the options is applied first (outermost).
+ *
+ * @param options - The model and optional middleware configuration.
+ * @returns A wrapped language model with middleware applied.
+ */
+export async function withModelMiddleware(options: WrapModelOptions): Promise<LanguageModel> {
+  const useDevtools =
+    options.devtools === true ||
+    (options.devtools !== false && process.env.NODE_ENV === "development");
+
+  const defaultMiddleware: LanguageModelMiddleware[] = [];
+  if (useDevtools) {
+    const { devToolsMiddleware } = await import("@ai-sdk/devtools");
+    defaultMiddleware.push(devToolsMiddleware());
+  }
+
+  const middleware: LanguageModelMiddleware[] = [];
+  if (options.middleware) {
+    middleware.push(...options.middleware, ...defaultMiddleware);
+  } else {
+    middleware.push(...defaultMiddleware);
+  }
+
+  if (middleware.length === 0) {
+    return options.model;
+  }
+
+  return wrapLanguageModel({
+    model: options.model,
+    middleware,
+  });
+}

package/src/lib/runnable.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { RUNNABLE_META, type RunnableMeta } from "@/lib/runnable.js";
+
+// ---------------------------------------------------------------------------
+// RUNNABLE_META symbol
+// ---------------------------------------------------------------------------
+
+describe("RUNNABLE_META", () => {
+  it("is a symbol", () => {
+    expect(typeof RUNNABLE_META).toBe("symbol");
+  });
+
+  it("is globally registered via Symbol.for", () => {
+    expect(RUNNABLE_META).toBe(Symbol.for("agent-sdk:runnable-meta"));
+  });
+
+  it("can be used as a property key on plain objects", () => {
+    const meta: RunnableMeta = { name: "test-agent" };
+    const obj: Record<symbol, RunnableMeta> = { [RUNNABLE_META]: meta };
+    // eslint-disable-next-line security/detect-object-injection -- Symbol-keyed property access; symbols cannot be user-controlled
+    expect(obj[RUNNABLE_META]).toBe(meta);
+  });
+
+  it("stores name and inputSchema", () => {
+    const schema = z.object({ query: z.string() });
+    const meta: RunnableMeta = { name: "search-agent", inputSchema: schema };
+    const obj: Record<symbol, RunnableMeta> = { [RUNNABLE_META]: meta };
+
+    // eslint-disable-next-line security/detect-object-injection -- Symbol-keyed property access; symbols cannot be user-controlled
+    const stored = obj[RUNNABLE_META] as RunnableMeta;
+    expect(stored.name).toBe("search-agent");
+    expect(stored.inputSchema).toBe(schema);
+  });
+
+  it("allows inputSchema to be omitted", () => {
+    const meta: RunnableMeta = { name: "simple-agent" };
+    expect(meta.inputSchema).toBeUndefined();
+  });
+});

package/src/lib/runnable.ts

@@ -0,0 +1,22 @@
+import type { ZodType } from "zod";
+
+/**
+ * Symbol key for internal runnable metadata.
+ *
+ * Stored on Agent and Workflow objects to enable composition:
+ * `buildAITools()` reads this to wrap a Runnable as a delegatable
+ * tool in parent agents.
+ *
+ * @internal
+ */
+export const RUNNABLE_META: unique symbol = Symbol.for("agent-sdk:runnable-meta");
+
+/**
+ * Metadata stored on Agent and Workflow objects via {@link RUNNABLE_META}.
+ *
+ * @internal
+ */
+export interface RunnableMeta {
+  name: string;
+  inputSchema?: ZodType;
+}

package/src/lib/trace.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "vitest";
+
+import type { TokenUsage } from "@/core/provider/types.js";
+import { collectUsages, snapshotTrace, type TraceEntry } from "@/lib/trace.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createEntry(overrides?: Partial<TraceEntry>): TraceEntry {
+  return {
+    id: "entry-1",
+    type: "step",
+    startedAt: 1000,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// snapshotTrace
+// ---------------------------------------------------------------------------
+
+describe("snapshotTrace", () => {
+  it("returns a frozen array", () => {
+    const trace = [createEntry()];
+    const snapshot = snapshotTrace(trace);
+    expect(Object.isFrozen(snapshot)).toBe(true);
+  });
+
+  it("freezes each entry in the array", () => {
+    const trace = [createEntry(), createEntry({ id: "entry-2" })];
+    const snapshot = snapshotTrace(trace);
+    expect(Object.isFrozen(snapshot[0])).toBe(true);
+    expect(Object.isFrozen(snapshot[1])).toBe(true);
+  });
+
+  it("returns a structural clone, not the same references", () => {
+    const original = createEntry({ output: { value: 42 } });
+    const trace = [original];
+    const snapshot = snapshotTrace(trace);
+
+    const entry = snapshot[0] as TraceEntry;
+    expect(entry).not.toBe(original);
+    expect(entry.id).toBe(original.id);
+    expect(entry.output).toEqual({ value: 42 });
+  });
+
+  it("deep-freezes nested children", () => {
+    const child: TraceEntry = createEntry({ id: "child-1", type: "agent" });
+    const parent: TraceEntry = createEntry({
+      id: "parent-1",
+      type: "map",
+      children: [child],
+    });
+
+    const snapshot = snapshotTrace([parent]);
+
+    const snapped = snapshot[0] as TraceEntry;
+    const snappedChildren = snapped.children as readonly TraceEntry[];
+    expect(Object.isFrozen(snapped)).toBe(true);
+    expect(Object.isFrozen(snappedChildren)).toBe(true);
+    expect(Object.isFrozen(snappedChildren[0])).toBe(true);
+  });
+
+  it("handles deeply nested children (3 levels)", () => {
+    const grandchild = createEntry({ id: "grandchild", type: "step" });
+    const child = createEntry({ id: "child", type: "agent", children: [grandchild] });
+    const root = createEntry({ id: "root", type: "map", children: [child] });
+
+    const snapshot = snapshotTrace([root]);
+
+    const root0 = snapshot[0] as TraceEntry;
+    const root0Children = root0.children as readonly TraceEntry[];
+    const mid = root0Children[0] as TraceEntry;
+    const midChildren = mid.children as readonly TraceEntry[];
+    const deep = midChildren[0] as TraceEntry;
+    expect(Object.isFrozen(deep)).toBe(true);
+    expect(deep.id).toBe("grandchild");
+  });
+
+  it("handles an empty trace array", () => {
+    const snapshot = snapshotTrace([]);
+    expect(snapshot).toEqual([]);
+    expect(Object.isFrozen(snapshot)).toBe(true);
+  });
+
+  it("preserves all entry fields", () => {
+    const error = new Error("test failure");
+    const usage = {
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      reasoningTokens: 0,
+    };
+    const entry = createEntry({
+      id: "full-entry",
+      type: "reduce",
+      input: { items: [1, 2, 3] },
+      output: { total: 6 },
+      startedAt: 1000,
+      finishedAt: 2000,
+      error,
+      usage,
+    });
+
+    const snapshot = snapshotTrace([entry]);
+    const snapped = snapshot[0] as TraceEntry;
+
+    expect(snapped.id).toBe("full-entry");
+    expect(snapped.type).toBe("reduce");
+    expect(snapped.input).toEqual({ items: [1, 2, 3] });
+    expect(snapped.output).toEqual({ total: 6 });
+    expect(snapped.startedAt).toBe(1000);
+    expect(snapped.finishedAt).toBe(2000);
+    expect(snapped.error).toBe(error);
+    expect(snapped.usage).toEqual(usage);
+  });
+
+  it("does not modify the original trace", () => {
+    const trace = [createEntry({ id: "original" })];
+    snapshotTrace(trace);
+
+    // Original should remain unfrozen and mutable
+    const original = trace[0] as TraceEntry;
+    expect(Object.isFrozen(trace)).toBe(false);
+    expect(Object.isFrozen(original)).toBe(false);
+    original.id = "mutated";
+    expect(original.id).toBe("mutated");
+  });
+
+  it("handles entries without children property", () => {
+    const entry = createEntry({ id: "no-children" });
+    const snapshot = snapshotTrace([entry]);
+    const snapped = snapshot[0] as TraceEntry;
+    expect(snapped.children).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TraceEntry shape
+// ---------------------------------------------------------------------------
+
+describe("TraceEntry", () => {
+  it("supports all operation types", () => {
+    const types = ["step", "agent", "map", "each", "reduce", "while", "all", "race"] as const;
+    const entries: TraceEntry[] = types.map((type) => createEntry({ id: type, type }));
+
+    expect(entries).toHaveLength(8);
+    entries.forEach((entry, i) => {
+      // eslint-disable-next-line security/detect-object-injection -- Array index from forEach callback, not user input
+      expect(entry.type).toBe(types[i]);
+    });
+  });
+
+  it("allows optional fields to be undefined", () => {
+    const entry = createEntry();
+    expect(entry.input).toBeUndefined();
+    expect(entry.output).toBeUndefined();
+    expect(entry.finishedAt).toBeUndefined();
+    expect(entry.error).toBeUndefined();
+    expect(entry.usage).toBeUndefined();
+    expect(entry.children).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Helpers for collectUsages
+// ---------------------------------------------------------------------------
+
+const ZERO_USAGE: TokenUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+function createUsage(overrides?: Partial<TokenUsage>): TokenUsage {
+  return { ...ZERO_USAGE, ...overrides };
+}
+
+// ---------------------------------------------------------------------------
+// collectUsages()
+// ---------------------------------------------------------------------------
+
+describe("collectUsages()", () => {
+  it("returns empty array for an empty trace", () => {
+    const result = collectUsages([]);
+
+    expect(result).toEqual([]);
+  });
+
+  it("returns empty array when no entries have usage", () => {
+    const trace = [createEntry({ id: "step-1" }), createEntry({ id: "step-2" })];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([]);
+  });
+
+  it("collects usage from a single entry", () => {
+    const usage = createUsage({ inputTokens: 100, outputTokens: 50, totalTokens: 150 });
+    const trace = [createEntry({ id: "agent-1", type: "agent", usage })];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([usage]);
+  });
+
+  it("collects usage across multiple entries", () => {
+    const usageA = createUsage({ inputTokens: 100 });
+    const usageB = createUsage({ inputTokens: 200 });
+    const trace = [
+      createEntry({ id: "agent-1", type: "agent", usage: usageA }),
+      createEntry({ id: "agent-2", type: "agent", usage: usageB }),
+    ];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([usageA, usageB]);
+  });
+
+  it("skips entries without usage", () => {
+    const usage = createUsage({ inputTokens: 100 });
+    const trace = [
+      createEntry({ id: "step-1", type: "step" }),
+      createEntry({ id: "agent-1", type: "agent", usage }),
+      createEntry({ id: "step-2", type: "step" }),
+    ];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([usage]);
+  });
+
+  it("recursively collects usage from children", () => {
+    const childUsage = createUsage({ inputTokens: 50 });
+    const trace = [
+      createEntry({
+        id: "map-1",
+        type: "map",
+        children: [createEntry({ id: "agent-child", type: "agent", usage: childUsage })],
+      }),
+    ];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([childUsage]);
+  });
+
+  it("collects usage from parent and nested children", () => {
+    const parentUsage = createUsage({ inputTokens: 100 });
+    const childUsage = createUsage({ inputTokens: 200 });
+    const trace = [
+      createEntry({ id: "agent-top", type: "agent", usage: parentUsage }),
+      createEntry({
+        id: "map-1",
+        type: "map",
+        children: [createEntry({ id: "agent-nested", type: "agent", usage: childUsage })],
+      }),
+    ];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([parentUsage, childUsage]);
+  });
+
+  it("handles deeply nested children (3 levels)", () => {
+    const deepUsage = createUsage({ inputTokens: 42 });
+    const trace = [
+      createEntry({
+        id: "root",
+        type: "map",
+        children: [
+          createEntry({
+            id: "mid",
+            type: "step",
+            children: [createEntry({ id: "deep-agent", type: "agent", usage: deepUsage })],
+          }),
+        ],
+      }),
+    ];
+
+    const result = collectUsages(trace);
+
+    expect(result).toEqual([deepUsage]);
+  });
+});