@funkai/agents 0.1.0

package/src/core/agents/base/utils.test.ts

@@ -0,0 +1,397 @@
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import type { Message } from "@/core/agents/base/types.js";
+import {
+  buildAITools,
+  buildPrompt,
+  resolveModel,
+  resolveSystem,
+  toTokenUsage,
+} from "@/core/agents/base/utils.js";
+import { RUNNABLE_META } from "@/lib/runnable.js";
+
+vi.mock("@/core/provider/provider.js", () => ({
+  openrouter: vi.fn((id: string) => ({ modelId: id })),
+}));
+
+// ---------------------------------------------------------------------------
+// resolveModel
+// ---------------------------------------------------------------------------
+
+describe("resolveModel", () => {
+  it("calls openrouter for a string model ID", () => {
+    const result = resolveModel("openai/gpt-4.1");
+    expect(result).toEqual({ modelId: "openai/gpt-4.1" });
+  });
+
+  it("returns a LanguageModel object as-is", () => {
+    const model = { modelId: "custom-model" } as never;
+    const result = resolveModel(model);
+    expect(result).toBe(model);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSystem
+// ---------------------------------------------------------------------------
+
+describe("resolveSystem", () => {
+  it("returns undefined when system is undefined", () => {
+    expect(resolveSystem(undefined, "input")).toBeUndefined();
+  });
+
+  it("returns undefined when system is null", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(resolveSystem(null as any, "input")).toBeUndefined();
+  });
+
+  it("returns a static string as-is", () => {
+    expect(resolveSystem("You are helpful", "input")).toBe("You are helpful");
+  });
+
+  it("calls function system with input and returns the result", () => {
+    // eslint-disable-next-line unicorn/consistent-function-scoping -- Test helper intentionally scoped within test case for locality
+    const system = ({ input }: { input: string }) => `System for ${input}`;
+    expect(resolveSystem(system, "topic")).toBe("System for topic");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildPrompt
+// ---------------------------------------------------------------------------
+
+describe("buildPrompt", () => {
+  it("returns { prompt } for a simple string input", () => {
+    const result = buildPrompt("hello", {});
+    expect(result).toEqual({ prompt: "hello" });
+  });
+
+  it("returns { messages } for a non-string input without typed config", () => {
+    const messages: Message[] = [{ role: "user", content: "hi" }];
+    const result = buildPrompt(messages, {});
+    expect(result).toEqual({ messages });
+  });
+
+  it("returns { prompt } for typed mode returning a string", () => {
+    const result = buildPrompt(
+      { topic: "AI" },
+      {
+        input: z.object({ topic: z.string() }),
+        prompt: ({ input }) => `Tell me about ${input.topic}`,
+      },
+    );
+    expect(result).toEqual({ prompt: "Tell me about AI" });
+  });
+
+  it("returns { messages } for typed mode returning messages array", () => {
+    const messages: Message[] = [{ role: "user", content: "hello" }];
+    const result = buildPrompt(
+      { topic: "AI" },
+      {
+        input: z.object({ topic: z.string() }),
+        prompt: () => messages,
+      },
+    );
+    expect(result).toEqual({ messages });
+  });
+
+  it("throws when input schema is provided without prompt function", () => {
+    expect(() => buildPrompt("test", { input: z.string() })).toThrow(
+      "Agent has `input` schema but no `prompt` function",
+    );
+  });
+
+  it("throws when prompt function is provided without input schema", () => {
+    expect(() => buildPrompt("test", { prompt: ({ input }) => `${input}` })).toThrow(
+      "Agent has `prompt` function but no `input` schema",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// toTokenUsage
+// ---------------------------------------------------------------------------
+
+describe("toTokenUsage", () => {
+  it("converts a fully populated LanguageModelUsage to TokenUsage", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: {
+        noCacheTokens: 85,
+        cacheReadTokens: 10,
+        cacheWriteTokens: 5,
+      },
+      outputTokenDetails: {
+        textTokens: 47,
+        reasoningTokens: 3,
+      },
+    });
+
+    expect(result).toEqual({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      cacheReadTokens: 10,
+      cacheWriteTokens: 5,
+      reasoningTokens: 3,
+    });
+  });
+
+  it("defaults undefined top-level fields to 0", () => {
+    const result = toTokenUsage({
+      inputTokens: undefined,
+      outputTokens: undefined,
+      totalTokens: undefined,
+      inputTokenDetails: {
+        noCacheTokens: undefined,
+        cacheReadTokens: undefined,
+        cacheWriteTokens: undefined,
+      },
+      outputTokenDetails: {
+        textTokens: undefined,
+        reasoningTokens: undefined,
+      },
+    });
+
+    expect(result.inputTokens).toBe(0);
+    expect(result.outputTokens).toBe(0);
+    expect(result.totalTokens).toBe(0);
+  });
+
+  it("defaults undefined detail fields to 0", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: {
+        noCacheTokens: undefined,
+        cacheReadTokens: undefined,
+        cacheWriteTokens: undefined,
+      },
+      outputTokenDetails: {
+        textTokens: undefined,
+        reasoningTokens: undefined,
+      },
+    });
+
+    expect(result.cacheReadTokens).toBe(0);
+    expect(result.cacheWriteTokens).toBe(0);
+    expect(result.reasoningTokens).toBe(0);
+  });
+
+  it("extracts cache tokens from inputTokenDetails", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: {
+        noCacheTokens: 90,
+        cacheReadTokens: 10,
+        cacheWriteTokens: undefined,
+      },
+      outputTokenDetails: {
+        textTokens: 50,
+        reasoningTokens: undefined,
+      },
+    });
+
+    expect(result.cacheReadTokens).toBe(10);
+    expect(result.cacheWriteTokens).toBe(0);
+  });
+
+  it("extracts reasoning tokens from outputTokenDetails", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: {
+        noCacheTokens: 100,
+        cacheReadTokens: undefined,
+        cacheWriteTokens: undefined,
+      },
+      outputTokenDetails: {
+        textTokens: 42,
+        reasoningTokens: 8,
+      },
+    });
+
+    expect(result.reasoningTokens).toBe(8);
+  });
+
+  it("defaults cache tokens to 0 when inputTokenDetails is undefined", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: undefined as never,
+      outputTokenDetails: {
+        textTokens: 50,
+        reasoningTokens: 0,
+      },
+    });
+
+    expect(result.cacheReadTokens).toBe(0);
+    expect(result.cacheWriteTokens).toBe(0);
+  });
+
+  it("defaults reasoning tokens to 0 when outputTokenDetails is undefined", () => {
+    const result = toTokenUsage({
+      inputTokens: 100,
+      outputTokens: 50,
+      totalTokens: 150,
+      inputTokenDetails: {
+        noCacheTokens: 100,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+      },
+      outputTokenDetails: undefined as never,
+    });
+
+    expect(result.reasoningTokens).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildAITools
+// ---------------------------------------------------------------------------
+
+describe("buildAITools", () => {
+  it("returns undefined when no tools or agents are provided", () => {
+    expect(buildAITools()).toBeUndefined();
+    expect(buildAITools(undefined, undefined)).toBeUndefined();
+  });
+
+  it("returns undefined for empty tool and agent records", () => {
+    expect(buildAITools({}, {})).toBeUndefined();
+  });
+
+  it("returns tools when only tools are provided", () => {
+    const tools = { myTool: { description: "test" } as never };
+    const result = buildAITools(tools);
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty("myTool");
+  });
+
+  it("wraps agents without inputSchema into prompt-based tools", () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "result" }),
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty("agent:sub");
+    const tools = result as Record<string, Record<string, unknown>>;
+    expect(tools["agent:sub"]).toHaveProperty("description");
+    expect(tools["agent:sub"]).toHaveProperty("execute");
+  });
+
+  it("wraps agents with inputSchema using the schema", () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "result" }),
+      [RUNNABLE_META]: {
+        name: "custom-name",
+        inputSchema: z.object({ query: z.string() }),
+      },
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty("agent:sub");
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    expect(tools["agent:sub"]).toHaveProperty("description");
+    // Description should use meta name
+    expect(tools["agent:sub"].description).toContain("custom-name");
+  });
+
+  it("uses fallback name when agent has no RUNNABLE_META name", () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "result" }),
+    };
+    const result = buildAITools(undefined, { fallbackKey: mockAgent as never });
+
+    expect(result).toBeDefined();
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    expect(tools["agent:fallbackKey"].description).toContain("fallbackKey");
+  });
+
+  it("merges tools and agents together", () => {
+    const tools = { myTool: { description: "test" } as never };
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "result" }),
+    };
+    const result = buildAITools(tools, { sub: mockAgent as never });
+
+    expect(result).toBeDefined();
+    expect(result).toHaveProperty("myTool");
+    expect(result).toHaveProperty("agent:sub");
+  });
+
+  it("execute calls generate on prompt-based agent and returns output", async () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "agent-output" }),
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+    expect(result).toBeDefined();
+
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    const output = await tools["agent:sub"].execute(
+      { prompt: "hello" },
+      { toolCallId: "tc-1", messages: [] },
+    );
+    expect(output).toBe("agent-output");
+    expect(mockAgent.generate).toHaveBeenCalledWith("hello", { signal: undefined });
+  });
+
+  it("execute throws when prompt-based agent returns error", async () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: false, error: { message: "agent failed" } }),
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+    expect(result).toBeDefined();
+
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    await expect(
+      tools["agent:sub"].execute({ prompt: "hello" }, { toolCallId: "tc-1", messages: [] }),
+    ).rejects.toThrow("agent failed");
+  });
+
+  it("execute calls generate on typed agent with inputSchema and returns output", async () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: true, output: "typed-output" }),
+      [RUNNABLE_META]: {
+        name: "typed-agent",
+        inputSchema: z.object({ query: z.string() }),
+      },
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+    expect(result).toBeDefined();
+
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    const output = await tools["agent:sub"].execute(
+      { query: "test" },
+      { toolCallId: "tc-1", messages: [] },
+    );
+    expect(output).toBe("typed-output");
+    expect(mockAgent.generate).toHaveBeenCalledWith({ query: "test" }, { signal: undefined });
+  });
+
+  it("execute throws when typed agent returns error", async () => {
+    const mockAgent = {
+      generate: vi.fn().mockResolvedValue({ ok: false, error: { message: "typed failed" } }),
+      [RUNNABLE_META]: {
+        name: "typed-agent",
+        inputSchema: z.object({ query: z.string() }),
+      },
+    };
+    const result = buildAITools(undefined, { sub: mockAgent as never });
+    expect(result).toBeDefined();
+
+    const tools = result as Record<string, { description: string; execute: Function }>;
+    await expect(
+      tools["agent:sub"].execute({ query: "test" }, { toolCallId: "tc-1", messages: [] }),
+    ).rejects.toThrow("typed failed");
+  });
+});

package/src/core/agents/base/utils.ts

@@ -0,0 +1,197 @@
+import type { LanguageModelUsage } from "ai";
+import { tool } from "ai";
+import { match, P } from "ts-pattern";
+import type { ZodType } from "zod";
+import { z } from "zod";
+
+import type { Agent, Message } from "@/core/agents/base/types.js";
+import { openrouter } from "@/core/provider/provider.js";
+import type { LanguageModel, TokenUsage } from "@/core/provider/types.js";
+import type { Tool } from "@/core/tool.js";
+import type { Model } from "@/core/types.js";
+import { RUNNABLE_META, type RunnableMeta } from "@/lib/runnable.js";
+
+/**
+ * Resolve a display name for a sub-agent tool from its runnable
+ * metadata, falling back to the provided name.
+ *
+ * @param meta - The runnable metadata, or undefined if not available.
+ * @param fallback - The fallback name to use if metadata is missing.
+ * @returns The resolved tool name.
+ *
+ * @private
+ */
+function resolveToolName(meta: RunnableMeta | undefined, fallback: string): string {
+  if (meta != null && meta.name != null) {
+    return meta.name;
+  }
+  return fallback;
+}
+
+/**
+ * Resolve a {@link Model} to an AI SDK `LanguageModel`.
+ */
+export function resolveModel(ref: Model): LanguageModel {
+  if (typeof ref === "string") {
+    return openrouter(ref);
+  }
+  return ref as LanguageModel;
+}
+
+/**
+ * Merge `Tool` records and wrap subagent `Runnable` objects into AI SDK
+ * tool format for `generateText` / `streamText`.
+ *
+ * Tools created via `tool()` are already AI SDK tools and are
+ * passed through directly. Only subagents need wrapping.
+ *
+ * Parent tools are automatically forwarded to sub-agents so they
+ * can access the same capabilities (e.g. sandbox filesystem tools)
+ * without explicit injection at each call site.
+ */
+export function buildAITools(
+  tools?: Record<string, Tool>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Agent generic params are contravariant; `unknown` breaks assignability
+  agents?: Record<string, Agent<any, any, any, any>>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ToolSet requires `any` values; `unknown` breaks assignability with AI SDK
+): Record<string, any> | undefined {
+  const hasTools = tools != null && Object.keys(tools).length > 0;
+  const hasAgents = agents != null && Object.keys(agents).length > 0;
+
+  if (!hasTools && !hasAgents) {
+    return undefined;
+  }
+
+  const agentTools = agents
+    ? Object.fromEntries(
+        Object.entries(agents).map(([name, runnable]) => {
+          // eslint-disable-next-line security/detect-object-injection -- Symbol-keyed property access; symbols cannot be user-controlled
+          const meta = (runnable as unknown as Record<symbol, unknown>)[RUNNABLE_META] as
+            | RunnableMeta
+            | undefined;
+          const toolName = resolveToolName(meta, name);
+          const agentToolName = `agent:${name}`;
+
+          const agentTool =
+            meta != null && meta.inputSchema != null
+              ? tool({
+                  description: `Delegate to ${toolName}`,
+                  inputSchema: meta.inputSchema,
+                  execute: async (input, { abortSignal }) => {
+                    const r = await runnable.generate(input, { signal: abortSignal, tools });
+                    if (!r.ok) {
+                      throw new Error(r.error.message);
+                    }
+                    return r.output;
+                  },
+                })
+              : tool({
+                  description: `Delegate to ${toolName}`,
+                  inputSchema: z.object({ prompt: z.string().describe("The prompt to send") }),
+                  execute: async (input: { prompt: string }, { abortSignal }) => {
+                    const r = await runnable.generate(input.prompt, { signal: abortSignal, tools });
+                    if (!r.ok) {
+                      throw new Error(r.error.message);
+                    }
+                    return r.output;
+                  },
+                });
+
+          return [agentToolName, agentTool];
+        }),
+      )
+    : {};
+
+  return { ...tools, ...agentTools };
+}
+
+/**
+ * Resolve the system prompt from config or override.
+ */
+export function resolveSystem<TInput>(
+  system: string | ((params: { input: TInput }) => string) | undefined,
+  input: TInput,
+): string | undefined {
+  if (system == null) {
+    return undefined;
+  }
+  if (typeof system === "function") {
+    return system({ input });
+  }
+  return system;
+}
+
+/**
+ * Build the prompt/messages from input based on mode (typed vs simple).
+ *
+ * Returns a discriminated object: either `{ prompt }` or `{ messages }`,
+ * never both — matching the AI SDK's `Prompt` union type.
+ */
+export function buildPrompt<TInput>(
+  input: TInput,
+  config: {
+    input?: ZodType<TInput>;
+    prompt?: (params: { input: TInput }) => string | Message[];
+  },
+): { prompt: string } | { messages: Message[] } {
+  const hasInput = Boolean(config.input);
+  const hasPrompt = Boolean(config.prompt);
+
+  return match({ hasInput, hasPrompt })
+    .with({ hasInput: true, hasPrompt: false }, () => {
+      throw new Error(
+        "Agent has `input` schema but no `prompt` function — both are required for typed mode",
+      );
+    })
+    .with({ hasInput: false, hasPrompt: true }, () => {
+      throw new Error(
+        "Agent has `prompt` function but no `input` schema — both are required for typed mode",
+      );
+    })
+    .with({ hasInput: true, hasPrompt: true }, () => {
+      // config.prompt is guaranteed non-null by the match
+      const promptFn = config.prompt as NonNullable<typeof config.prompt>;
+      const built = promptFn({ input });
+      return match(typeof built === "string")
+        .with(true, () => ({ prompt: built as string }))
+        .otherwise(() => ({ messages: built as Message[] }));
+    })
+    .otherwise(() =>
+      match(typeof input === "string")
+        .with(true, () => ({ prompt: input as string }))
+        .otherwise(() => ({ messages: input as Message[] })),
+    );
+}
+
+/**
+ * Convert AI SDK's `LanguageModelUsage` to our flat `TokenUsage`.
+ *
+ * Maps nested `inputTokenDetails` / `outputTokenDetails` to flat
+ * fields, resolving `undefined` → `0`.
+ *
+ * @param usage - The AI SDK usage object (from `totalUsage`).
+ * @returns A resolved {@link TokenUsage} with all fields as numbers.
+ */
+export function toTokenUsage(usage: LanguageModelUsage): TokenUsage {
+  const inputDetails = match(usage.inputTokenDetails)
+    .with(P.nonNullable, (d) => ({
+      cacheReadTokens: d.cacheReadTokens ?? 0,
+      cacheWriteTokens: d.cacheWriteTokens ?? 0,
+    }))
+    .otherwise(() => ({ cacheReadTokens: 0, cacheWriteTokens: 0 }));
+
+  const outputDetails = match(usage.outputTokenDetails)
+    .with(P.nonNullable, (d) => ({
+      reasoningTokens: d.reasoningTokens ?? 0,
+    }))
+    .otherwise(() => ({ reasoningTokens: 0 }));
+
+  return {
+    inputTokens: usage.inputTokens ?? 0,
+    outputTokens: usage.outputTokens ?? 0,
+    totalTokens: usage.totalTokens ?? 0,
+    cacheReadTokens: inputDetails.cacheReadTokens,
+    cacheWriteTokens: inputDetails.cacheWriteTokens,
+    reasoningTokens: outputDetails.reasoningTokens,
+  };
+}