@funkai/agents 0.1.0

package/src/core/provider/usage.ts

@@ -0,0 +1,97 @@
+import { groupBy, sumBy } from "es-toolkit";
+import { match, P } from "ts-pattern";
+
+import type {
+  TokenUsage,
+  TokenUsageRecord,
+  AgentTokenUsage,
+  FlowAgentTokenUsage,
+} from "@/core/provider/types.js";
+
+/**
+ * Aggregate token counts across multiple raw tracking records.
+ *
+ * Sums each field, treating `undefined` as `0`.
+ */
+function aggregateTokens(usages: TokenUsageRecord[]): TokenUsage {
+  return {
+    inputTokens: sumBy(usages, (u) => u.inputTokens ?? 0),
+    outputTokens: sumBy(usages, (u) => u.outputTokens ?? 0),
+    totalTokens: sumBy(usages, (u) => u.totalTokens ?? 0),
+    cacheReadTokens: sumBy(usages, (u) => u.cacheReadTokens ?? 0),
+    cacheWriteTokens: sumBy(usages, (u) => u.cacheWriteTokens ?? 0),
+    reasoningTokens: sumBy(usages, (u) => u.reasoningTokens ?? 0),
+  };
+}
+
+/**
+ * Compute final usage for a single agent call.
+ *
+ * Aggregates token counts from one or more raw tracking records.
+ * Returns a flat object with tokens + agentId.
+ *
+ * @param agentId - The agent that produced these records.
+ * @param records - Raw tracking records from the agent's execution.
+ * @returns Flat {@link AgentTokenUsage} with resolved token counts.
+ */
+export function agentUsage(
+  agentId: string,
+  records: TokenUsageRecord | TokenUsageRecord[],
+): AgentTokenUsage {
+  const arr = match(records)
+    .when(Array.isArray, (r) => r)
+    .otherwise((r) => [r]);
+  const tokens = aggregateTokens(arr);
+
+  return {
+    agentId,
+    ...tokens,
+  };
+}
+
+/**
+ * Compute final usage for a flow agent with multiple agent calls.
+ *
+ * Groups raw tracking records by `source.agentId`, computes per-agent
+ * usage via {@link agentUsage}.
+ *
+ * @param records - Raw tracking records from all agents in the flow.
+ * @returns {@link FlowAgentTokenUsage} with per-agent breakdown.
+ */
+export function flowAgentUsage(records: TokenUsageRecord[]): FlowAgentTokenUsage {
+  const grouped = groupBy(records, (r) =>
+    match(r.source)
+      .with(P.nonNullable, (s) =>
+        match(s.agentId)
+          .with(P.string, (id) => id)
+          .otherwise(() => "unknown"),
+      )
+      .otherwise(() => "unknown"),
+  );
+
+  const usages = Object.entries(grouped).map(([id, group]) => agentUsage(id, group));
+
+  return {
+    usages,
+  };
+}
+
+/**
+ * Sum multiple {@link TokenUsage} objects field-by-field.
+ *
+ * Pure function — returns a new object without mutating any input.
+ * Returns zero-valued usage when given an empty array.
+ *
+ * @param usages - Array of usage objects to sum.
+ * @returns A new `TokenUsage` with each field summed.
+ */
+export function sumTokenUsage(usages: TokenUsage[]): TokenUsage {
+  return {
+    inputTokens: sumBy(usages, (u) => u.inputTokens),
+    outputTokens: sumBy(usages, (u) => u.outputTokens),
+    totalTokens: sumBy(usages, (u) => u.totalTokens),
+    cacheReadTokens: sumBy(usages, (u) => u.cacheReadTokens),
+    cacheWriteTokens: sumBy(usages, (u) => u.cacheWriteTokens),
+    reasoningTokens: sumBy(usages, (u) => u.reasoningTokens),
+  };
+}

package/src/core/tool.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { tool } from "@/core/tool.js";
+
+const greetTool = tool({
+  description: "Greet a person by name",
+  inputSchema: z.object({ name: z.string() }),
+  execute: async ({ name }) => ({
+    message: `Hello, ${name}!`,
+  }),
+});
+
+describe("tool", () => {
+  it("returns an object with description, inputSchema, and execute", () => {
+    expect(greetTool).toHaveProperty("description", "Greet a person by name");
+    expect(greetTool).toHaveProperty("inputSchema");
+    expect(greetTool).toHaveProperty("execute");
+  });
+
+  it("executes and returns the expected output", async () => {
+    if (greetTool.execute == null) {
+      throw new Error("Expected greetTool.execute to be defined");
+    }
+    const result = await greetTool.execute({ name: "Ada" }, { toolCallId: "test", messages: [] });
+    expect(result).toEqual({ message: "Hello, Ada!" });
+  });
+
+  it("wraps inputSchema as an AI SDK schema with jsonSchema", () => {
+    expect(greetTool.inputSchema).toHaveProperty("jsonSchema");
+  });
+
+  it("wraps outputSchema when provided", () => {
+    const t = tool({
+      description: "Tool with output schema",
+      inputSchema: z.object({ x: z.number() }),
+      outputSchema: z.object({ result: z.number() }),
+      execute: async ({ x }) => ({ result: x * 2 }),
+    });
+
+    expect(t).toHaveProperty("outputSchema");
+  });
+
+  it("sets title when provided", () => {
+    const t = tool({
+      description: "Tool with title",
+      title: "My Tool",
+      inputSchema: z.object({ x: z.number() }),
+      execute: async ({ x }) => x,
+    });
+
+    expect(t).toHaveProperty("title", "My Tool");
+  });
+
+  it("sets inputExamples when provided", () => {
+    const t = tool({
+      description: "Tool with examples",
+      inputSchema: z.object({ x: z.number() }),
+      inputExamples: [{ input: { x: 42 } }],
+      execute: async ({ x }) => x,
+    });
+
+    expect(t).toHaveProperty("inputExamples");
+  });
+});

package/src/core/tool.ts

@@ -0,0 +1,164 @@
+import { tool as aiTool, zodSchema } from "ai";
+import { isFunction, isNil } from "es-toolkit";
+import { has, isObject } from "es-toolkit/compat";
+import { P, match } from "ts-pattern";
+import type { ZodType } from "zod";
+
+/**
+ * Configuration for creating a tool.
+ *
+ * @typeParam TInput - Input type, inferred from the `inputSchema` Zod schema.
+ * @typeParam TOutput - Output type, inferred from the `execute` return.
+ */
+export interface ToolConfig<TInput, TOutput> {
+  /**
+   * Human-readable description of what the tool does.
+   *
+   * Shown to the model alongside the tool name. A good description
+   * helps the model decide when and how to call the tool.
+   */
+  description: string;
+
+  /**
+   * Display title for the tool.
+   *
+   * Optional human-readable title shown in UIs and logs.
+   */
+  title?: string;
+
+  /**
+   * Zod schema for validating and typing tool input.
+   *
+   * The schema is serialized to JSON Schema and sent to the model.
+   * Input from the model is validated against it before `execute`
+   * is called.
+   */
+  inputSchema: ZodType<TInput>;
+
+  /**
+   * Zod schema for validating tool output.
+   *
+   * When provided, the return value of `execute` is validated
+   * against this schema before being sent back to the model.
+   */
+  outputSchema?: ZodType<TOutput>;
+
+  /**
+   * Example inputs to guide the model.
+   *
+   * Helps the model understand expected input structure. Natively
+   * supported by Anthropic; for other providers, use
+   * `addToolInputExamplesMiddleware` to inject examples into the
+   * tool description.
+   */
+  inputExamples?: Array<{ input: TInput }>;
+
+  /**
+   * Execute the tool with validated input.
+   *
+   * Called by the framework after the model requests a tool call and
+   * the input passes schema validation.
+   *
+   * @param input - The validated tool input.
+   * @returns The tool output returned to the model.
+   */
+  execute: (input: TInput) => Promise<TOutput>;
+}
+
+/**
+ * A tool instance — the return type of `tool()` / `ai.tool()`.
+ *
+ * Defaults use `any` so `Record<string, Tool>` accepts concrete
+ * typed tools without contravariance issues (same pattern as
+ * {@link SubAgents}).
+ *
+ * @typeParam TInput - Tool input type.
+ * @typeParam TOutput - Tool output type.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Tool<TInput = any, TOutput = any> = ReturnType<typeof aiTool<TInput, TOutput>>;
+
+/**
+ * Create a tool for AI agent function calling.
+ *
+ * Wraps the AI SDK's `tool()` helper. The `inputSchema` (and optional
+ * `outputSchema`) are wrapped via `zodSchema()` so the AI SDK can
+ * convert them to JSON Schema and validate model I/O at runtime.
+ *
+ * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/tool
+ *
+ * @example
+ * ```typescript
+ * const fetchPage = tool({
+ *   description: 'Fetch the contents of a web page by URL',
+ *   inputSchema: z.object({
+ *     url: z.url(),
+ *   }),
+ *   execute: async ({ url }) => {
+ *     const res = await fetch(url)
+ *     return {
+ *       url,
+ *       status: res.status,
+ *       body: await res.text(),
+ *     }
+ *   },
+ * })
+ * ```
+ */
+export function tool<TInput, TOutput>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput> {
+  const resolvedOutputSchema = resolveOutputSchema(config.outputSchema);
+  const result = {
+    description: config.description,
+    title: config.title,
+    inputSchema: zodSchema(config.inputSchema),
+    outputSchema: resolvedOutputSchema,
+    inputExamples: config.inputExamples,
+    execute: async (data: TInput) => config.execute(data),
+  };
+  assertTool<TInput, TOutput>(result);
+  return aiTool(result);
+}
+
+/**
+ * Resolve an optional Zod output schema into a zodSchema-wrapped value.
+ *
+ * @private
+ */
+function resolveOutputSchema<TOutput>(
+  schema: ZodType<TOutput> | undefined,
+): ReturnType<typeof zodSchema> | undefined {
+  return match(schema)
+    .with(P.nullish, () => undefined)
+    .otherwise((value) => zodSchema(value));
+}
+
+/**
+ * Runtime assertion that narrows `value` to `Tool<TInput, TOutput>`.
+ *
+ * Validates structural shape at runtime — `inputSchema` is present and
+ * `execute` is a function. Generic type parameters (`TInput`, `TOutput`)
+ * are erased at runtime, so only the structural shape can be verified.
+ *
+ * This assertion exists because TypeScript cannot evaluate the AI SDK's
+ * `NeverOptional<TOutput>` conditional type when `TOutput` is an
+ * unresolved generic — a known limitation with higher-order conditional
+ * types. Using `asserts` is TypeScript's endorsed narrowing mechanism
+ * and provides a runtime safety net if the AI SDK's tool shape changes.
+ *
+ * @private
+ */
+/* v8 ignore start -- defensive guard; tool() always constructs a valid object */
+function assertTool<TInput, TOutput>(value: unknown): asserts value is Tool<TInput, TOutput> {
+  if (isNil(value) || !isObject(value)) {
+    throw new TypeError("Expected tool to be an object");
+  }
+
+  if (!has(value, "inputSchema")) {
+    throw new TypeError("Tool is missing required property: inputSchema");
+  }
+
+  if (!has(value, "execute") || !isFunction(value.execute)) {
+    throw new TypeError("Tool is missing required property: execute");
+  }
+}
+/* v8 ignore stop */

package/src/core/types.ts

@@ -0,0 +1,66 @@
+import type { AsyncIterableStream, LanguageModel } from "ai";
+
+import type { StreamPart } from "@/core/agents/base/types.js";
+import type { Result } from "@/utils/result.js";
+
+/**
+ * A model reference.
+ *
+ * Accepts either:
+ * - A **string model ID** (e.g. `'openai/gpt-4.1'`) resolved via
+ *   OpenRouter at runtime.
+ * - An **AI SDK `LanguageModel` instance** — including models wrapped
+ *   with middleware via `wrapLanguageModel()`.
+ *
+ * @example
+ * ```typescript
+ * // String ID — resolved via OpenRouter
+ * const agent1 = agent({
+ *   name: 'my-agent',
+ *   model: 'openai/gpt-4.1',
+ *   system: 'You are helpful.',
+ * })
+ *
+ * // AI SDK provider instance
+ * import { openai } from '@ai-sdk/openai'
+ * const agent2 = agent({
+ *   name: 'my-agent',
+ *   model: openai('gpt-4.1'),
+ *   system: 'You are helpful.',
+ * })
+ *
+ * // Middleware-wrapped model
+ * import { wrapLanguageModel, extractReasoningMiddleware } from 'ai'
+ * import { anthropic } from '@ai-sdk/anthropic'
+ * const agent3 = agent({
+ *   name: 'reasoner',
+ *   model: wrapLanguageModel({
+ *     model: anthropic('claude-sonnet-4-5-20250929'),
+ *     middleware: extractReasoningMiddleware({ tagName: 'think' }),
+ *   }),
+ *   system: 'Think step by step.',
+ * })
+ * ```
+ */
+export type Model = string | LanguageModel;
+
+/** @deprecated Use `Model` instead. */
+export type ModelRef = Model;
+
+/**
+ * A value that can be generated against — the shared contract
+ * between Agent and Workflow.
+ *
+ * Both `Agent` and `Workflow` satisfy this interface. Any API that
+ * accepts a `Runnable` works with either.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any -- Runnable config accepts implementation-specific options that cannot be narrowed at the interface level */
+export interface Runnable<TInput = unknown, TOutput = unknown> {
+  generate(input: TInput, config?: any): Promise<Result<{ output: TOutput }>>;
+  stream(
+    input: TInput,
+    config?: any,
+  ): Promise<Result<{ output: Promise<TOutput>; fullStream: AsyncIterableStream<StreamPart> }>>;
+  fn(): (input: TInput, config?: any) => Promise<Result<{ output: TOutput }>>;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */

package/src/index.ts

@@ -0,0 +1,95 @@
+export { tool } from "@/core/tool.js";
+export { agent } from "@/core/agents/base/agent.js";
+export { resolveOutput } from "@/core/agents/base/output.js";
+export { flowAgent } from "@/core/agents/flow/flow-agent.js";
+export { createFlowEngine } from "@/core/agents/flow/engine.js";
+export { createDefaultLogger } from "@/core/logger.js";
+export { model, tryModel, models } from "@/core/models/index.js";
+export { createOpenRouter, openrouter } from "@/core/provider/provider.js";
+export { agentUsage, flowAgentUsage, sumTokenUsage } from "@/core/provider/usage.js";
+export { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+
+export type { Runnable, Model, ModelRef } from "@/core/types.js";
+export type { TextStreamPart, AsyncIterableStream, ToolSet } from "ai";
+export { toError, safeStringify, safeStringifyJSON } from "@/utils/error.js";
+export { ok, err, isOk, isErr } from "@/utils/result.js";
+export type { Result, ResultError } from "@/utils/result.js";
+export type { Logger } from "@/core/logger.js";
+export type { Tool, ToolConfig } from "@/core/tool.js";
+
+export type { OutputSpec, OutputParam } from "@/core/agents/base/output.js";
+
+export type {
+  SubAgents,
+  Message,
+  Agent,
+  AgentConfig,
+  AgentOverrides,
+  GenerateResult,
+  StreamResult,
+  StreamPart,
+} from "@/core/agents/base/types.js";
+
+export type {
+  FlowAgent,
+  FlowAgentConfig,
+  FlowAgentConfigBase,
+  FlowAgentConfigWithOutput,
+  FlowAgentConfigWithoutOutput,
+  FlowAgentOverrides,
+  FlowAgentHandler,
+  FlowAgentParams,
+  FlowAgentGenerateResult,
+  StepInfo,
+} from "@/core/agents/flow/types.js";
+
+export type {
+  FlowFactory,
+  FlowEngineConfig,
+  CustomStepDefinitions as FlowCustomStepDefinitions,
+  CustomStepFactory as FlowCustomStepFactory,
+  TypedCustomSteps as FlowTypedCustomSteps,
+} from "@/core/agents/flow/engine.js";
+
+export type { StepBuilderOptions } from "@/core/agents/flow/steps/factory.js";
+export type { StepResult, StepError } from "@/core/agents/flow/steps/result.js";
+export type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+export type { StepConfig } from "@/core/agents/flow/steps/step.js";
+export type { AgentStepConfig } from "@/core/agents/flow/steps/agent.js";
+export type { MapConfig } from "@/core/agents/flow/steps/map.js";
+export type { EachConfig } from "@/core/agents/flow/steps/each.js";
+export type { ReduceConfig } from "@/core/agents/flow/steps/reduce.js";
+export type { WhileConfig } from "@/core/agents/flow/steps/while.js";
+export type { AllConfig, EntryFactory } from "@/core/agents/flow/steps/all.js";
+export type { RaceConfig } from "@/core/agents/flow/steps/race.js";
+
+export type {
+  OpenRouterLanguageModelId,
+  ModelId,
+  ModelCategory,
+  ModelPricing,
+  ModelDefinition,
+} from "@/core/models/index.js";
+
+export type {
+  LanguageModel,
+  TokenUsage,
+  TokenUsageRecord,
+  AgentTokenUsage,
+  FlowAgentTokenUsage,
+} from "@/core/provider/types.js";
+
+export type { Output } from "ai";
+
+export type { ExecutionContext } from "@/lib/context.js";
+
+/** @deprecated Use `ExecutionContext` instead. */
+export type { Context } from "@/lib/context.js";
+
+export { collectUsages } from "@/lib/trace.js";
+export type { OperationType, TraceEntry } from "@/lib/trace.js";
+
+/** @deprecated Use `OperationType` instead. */
+export type { TraceType } from "@/lib/trace.js";
+
+export type { ResolveParam } from "@/utils/resolve.js";

package/src/lib/context.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import type { TraceEntry } from "@/lib/trace.js";
+import { createMockCtx, createMockExecutionCtx, createMockLogger } from "@/testing/index.js";
+
+// ---------------------------------------------------------------------------
+// ExecutionContext via createMockExecutionCtx
+// ---------------------------------------------------------------------------
+
+describe("ExecutionContext", () => {
+  it("provides a non-aborted signal by default", () => {
+    const ctx = createMockExecutionCtx();
+    expect(ctx.signal.aborted).toBe(false);
+  });
+
+  it("provides a mock logger", () => {
+    const ctx = createMockExecutionCtx();
+    expect(ctx.log).toBeDefined();
+    expect(ctx.log.info).toBeDefined();
+    expect(ctx.log.debug).toBeDefined();
+    expect(ctx.log.warn).toBeDefined();
+    expect(ctx.log.error).toBeDefined();
+    expect(ctx.log.child).toBeDefined();
+  });
+
+  it("accepts signal override", () => {
+    const controller = new AbortController();
+    controller.abort();
+    const ctx = createMockExecutionCtx({ signal: controller.signal });
+    expect(ctx.signal.aborted).toBe(true);
+  });
+
+  it("accepts logger override", () => {
+    const log = createMockLogger();
+    const ctx = createMockExecutionCtx({ log });
+    expect(ctx.log).toBe(log);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Context via createMockCtx
+// ---------------------------------------------------------------------------
+
+describe("Context", () => {
+  it("provides an empty trace by default", () => {
+    const ctx = createMockCtx();
+    expect(ctx.trace).toEqual([]);
+  });
+
+  it("provides a non-aborted signal by default", () => {
+    const ctx = createMockCtx();
+    expect(ctx.signal.aborted).toBe(false);
+  });
+
+  it("provides a mock logger", () => {
+    const ctx = createMockCtx();
+    expect(ctx.log).toBeDefined();
+  });
+
+  it("accepts trace override", () => {
+    const trace = [{ id: "step-1", type: "step" as const, startedAt: Date.now() }];
+    const ctx = createMockCtx({ trace });
+    expect(ctx.trace).toBe(trace);
+    expect(ctx.trace).toHaveLength(1);
+  });
+
+  it("accepts all overrides simultaneously", () => {
+    const controller = new AbortController();
+    const log = createMockLogger();
+    const trace = [{ id: "op-1", type: "agent" as const, startedAt: 1000 }];
+
+    const ctx = createMockCtx({ signal: controller.signal, log, trace });
+
+    expect(ctx.signal).toBe(controller.signal);
+    expect(ctx.log).toBe(log);
+    expect(ctx.trace).toBe(trace);
+  });
+
+  it("allows pushing entries to the mutable trace array", () => {
+    const ctx = createMockCtx();
+    ctx.trace.push({ id: "new-entry", type: "step", startedAt: Date.now() });
+    expect(ctx.trace).toHaveLength(1);
+    const entry = ctx.trace[0] as TraceEntry;
+    expect(entry.id).toBe("new-entry");
+  });
+});

package/src/lib/context.ts

@@ -0,0 +1,49 @@
+import type { Message } from "@/core/agents/base/types.js";
+import type { Logger } from "@/core/logger.js";
+import type { TraceEntry } from "@/lib/trace.js";
+
+/**
+ * Public execution context for custom step factories.
+ *
+ * Provides the abort signal and scoped logger — the minimal surface
+ * needed to integrate with framework cancellation and logging.
+ * The mutable trace is internal-only.
+ */
+export interface ExecutionContext {
+  readonly signal: AbortSignal;
+  readonly log: Logger;
+}
+
+/**
+ * Internal execution context.
+ *
+ * Created by the framework when a workflow or flow agent starts.
+ * Threaded through every `$` call automatically. Users never create,
+ * pass, or interact with this directly.
+ *
+ * @internal
+ *   Only accessible to framework internals. Custom step factories
+ *   receive {@link ExecutionContext} instead.
+ */
+export interface Context extends ExecutionContext {
+  /**
+   * Execution trace — every tracked operation is recorded here.
+   *
+   * The framework appends entries as `$` operations start and complete.
+   * Read this after workflow/flow agent completion to inspect the full
+   * execution graph.
+   */
+  readonly trace: TraceEntry[];
+
+  /**
+   * Synthetic messages produced by `$` steps.
+   *
+   * Each tracked operation pushes a tool-call (assistant) message when
+   * it starts and a tool-result (tool) message when it finishes.
+   * The array is flat — nested steps push to the same array so messages
+   * appear in execution order.
+   *
+   * Used by `flowAgent` to populate `GenerateResult.messages`.
+   */
+  readonly messages: Message[];
+}