@funkai/agents 0.1.0

package/docs/guides/create-workflow.md

@@ -0,0 +1,374 @@
+# Create a Workflow
+
+## Prerequisites
+
+- `@pkg/agent-sdk` installed
+- `OPENROUTER_API_KEY` environment variable set
+- Familiarity with Zod schemas
+
+## Steps
+
+### 1. Define a basic workflow
+
+A workflow has typed `input` and `output` Zod schemas and a handler function. The handler receives validated input and a `$` step builder for tracked operations.
+
+```ts
+import { workflow } from "@pkg/agent-sdk";
+import { z } from "zod";
+
+const myWorkflow = workflow(
+  {
+    name: "data-processor",
+    input: z.object({ url: z.url() }),
+    output: z.object({ title: z.string(), wordCount: z.number() }),
+  },
+  async ({ input, $ }) => {
+    const page = await $.step({
+      id: "fetch-page",
+      execute: async () => {
+        const res = await fetch(input.url);
+        return await res.text();
+      },
+    });
+
+    if (!page.ok) throw new Error(page.error.message);
+
+    return {
+      title: input.url,
+      wordCount: page.value.split(/\s+/).length,
+    };
+  },
+);
+```
+
+### 2. Use `$.step` for tracked operations
+
+Every `$.step` call is registered in the execution trace. The `execute` callback receives a nested `$` for further composition.
+
+```ts
+const result = await $.step({
+  id: "process-data",
+  execute: async ({ $ }) => {
+    // Nest further tracked operations
+    const sub = await $.step({
+      id: "sub-task",
+      execute: async () => computeResult(),
+    });
+    return sub.ok ? sub.value : fallback;
+  },
+});
+```
+
+All `$` methods return `StepResult<T>`. Check `.ok` and access `.value` on success.
+
+```ts
+if (result.ok) {
+  console.log(result.value); // the step's return value
+  console.log(result.duration); // wall-clock time in ms
+} else {
+  console.error(result.error.message);
+  console.error(result.error.stepId);
+}
+```
+
+### 3. Use `$.agent` for agent calls
+
+Run an agent as a tracked workflow step. The framework records the agent name, input, and output in the trace.
+
+```ts
+import { agent } from "@pkg/agent-sdk";
+
+const analyzer = agent({
+  name: "analyzer",
+  model: "openai/gpt-4.1",
+  input: z.object({ text: z.string() }),
+  prompt: ({ input }) => `Analyze this text:\n\n${input.text}`,
+});
+
+const wf = workflow(
+  {
+    name: "analysis-pipeline",
+    input: z.object({ content: z.string() }),
+    output: z.object({ analysis: z.string() }),
+  },
+  async ({ input, $ }) => {
+    const result = await $.agent({
+      id: "analyze-content",
+      agent: analyzer,
+      input: { text: input.content },
+    });
+
+    if (!result.ok) throw new Error(result.error.message);
+
+    return { analysis: result.value.output };
+  },
+);
+```
+
+### 4. Use `$.map` for parallel processing
+
+Process an array of items concurrently. Results are returned in input order. Use `concurrency` to limit parallelism.
+
+```ts
+const pages = await $.map({
+  id: "fetch-pages",
+  input: urls,
+  concurrency: 3,
+  execute: async ({ item: url, index, $ }) => {
+    const res = await fetch(url);
+    return { url, status: res.status, body: await res.text() };
+  },
+});
+
+if (pages.ok) {
+  console.log(pages.value); // array of results in input order
+}
+```
+
+### 5. Use `$.all` for heterogeneous concurrent operations
+
+`$.all` runs multiple independent operations concurrently, like `Promise.all`. Entries are **factory functions** that receive an `AbortSignal` and return a promise.
+
+```ts
+const results = await $.all({
+  id: "parallel-tasks",
+  entries: [
+    (signal) => fetchMetadata(signal),
+    (signal) => fetchContent(signal),
+    (signal) =>
+      $.step({
+        id: "compute",
+        execute: async () => heavyComputation(),
+      }),
+  ],
+});
+
+if (results.ok) {
+  const [metadata, content, computed] = results.value;
+}
+```
+
+Entries must be factory functions, not pre-started promises. This ensures the framework controls when work starts and can cancel entries via the signal.
+
+### 6. Use `$.race` for first-to-finish
+
+`$.race` runs multiple operations concurrently and returns the first to resolve. Losers are cancelled via abort signal. Entries follow the same factory function pattern as `$.all`.
+
+```ts
+const fastest = await $.race({
+  id: "fastest-source",
+  entries: [(signal) => fetchFromCDN(signal), (signal) => fetchFromOrigin(signal)],
+});
+
+if (fastest.ok) {
+  console.log(fastest.value); // result from whichever finished first
+}
+```
+
+### 7. Use other step types
+
+| Method     | Description                                                         |
+| ---------- | ------------------------------------------------------------------- |
+| `$.each`   | Sequential side effects. Returns `void`.                            |
+| `$.reduce` | Sequential accumulation. Each step depends on the previous result.  |
+| `$.while`  | Conditional loop. Runs while a condition holds. Returns last value. |
+
+```ts
+// $.each - sequential side effects
+await $.each({
+  id: "notify-users",
+  input: users,
+  execute: async ({ item: user }) => {
+    await sendNotification(user.email, message);
+  },
+});
+
+// $.reduce - sequential accumulation
+const total = await $.reduce({
+  id: "aggregate-scores",
+  input: items,
+  initial: 0,
+  execute: async ({ item, accumulator }) => {
+    return accumulator + item.score;
+  },
+});
+
+// $.while - conditional loop
+const converged = await $.while({
+  id: "iterate-until-stable",
+  condition: ({ value, index }) => index < 10 && (value === undefined || value.delta > 0.01),
+  execute: async ({ index }) => {
+    return await computeIteration(index);
+  },
+});
+```
+
+### 8. Stream step progress events
+
+Use `.stream()` to receive `StepEvent` objects as the workflow executes.
+
+```ts
+const result = await myWorkflow.stream({ url: "https://example.com" });
+
+if (result.ok) {
+  const reader = result.stream.getReader();
+  while (true) {
+    const { done, value: event } = await reader.read();
+    if (done) break;
+
+    switch (event.type) {
+      case "step:start":
+        console.log(`Step started: ${event.step.id}`);
+        break;
+      case "step:finish":
+        console.log(`Step finished: ${event.step.id} (${event.duration}ms)`);
+        break;
+      case "step:error":
+        console.error(`Step failed: ${event.step.id}`, event.error);
+        break;
+      case "workflow:finish":
+        console.log(`Workflow complete (${event.duration}ms)`);
+        break;
+    }
+  }
+
+  // Final output, trace, and duration are on the result
+  console.log(result.output);
+  console.log(result.trace);
+}
+```
+
+### 9. Export as a plain function
+
+Use `.fn()` for clean single-function exports.
+
+```ts
+export const processData = myWorkflow.fn();
+
+// Callers use it like a regular async function
+const result = await processData({ url: "https://example.com" });
+```
+
+### 10. Add hooks for observability
+
+```ts
+const wf = workflow(
+  {
+    name: "observed-workflow",
+    input: InputSchema,
+    output: OutputSchema,
+    onStart: ({ input }) => console.log("Workflow started"),
+    onFinish: ({ input, output, duration }) => console.log(`Done in ${duration}ms`),
+    onError: ({ input, error }) => console.error("Failed:", error.message),
+    onStepStart: ({ step }) => console.log(`Step ${step.id} started`),
+    onStepFinish: ({ step, result, duration }) =>
+      console.log(`Step ${step.id} done in ${duration}ms`),
+  },
+  handler,
+);
+```
+
+## Full example
+
+```ts
+import { agent, workflow, tool } from "@pkg/agent-sdk";
+import { z } from "zod";
+
+// Define tools
+const fetchPage = tool({
+  description: "Fetch a web page",
+  inputSchema: z.object({ url: z.url() }),
+  execute: async ({ url }) => {
+    const res = await fetch(url);
+    return { url, body: await res.text() };
+  },
+});
+
+// Define agents
+const summarizer = agent({
+  name: "summarizer",
+  model: "openai/gpt-4.1",
+  input: z.object({ text: z.string() }),
+  prompt: ({ input }) => `Summarize:\n\n${input.text}`,
+});
+
+// Define workflow
+const pipeline = workflow(
+  {
+    name: "summarize-pages",
+    input: z.object({ urls: z.array(z.url()) }),
+    output: z.object({
+      summaries: z.array(z.object({ url: z.string(), summary: z.string() })),
+    }),
+  },
+  async ({ input, $ }) => {
+    // Fetch all pages in parallel
+    const pages = await $.map({
+      id: "fetch-pages",
+      input: input.urls,
+      concurrency: 5,
+      execute: async ({ item: url }) => {
+        const res = await fetch(url);
+        return { url, body: await res.text() };
+      },
+    });
+
+    if (!pages.ok) throw new Error("Failed to fetch pages");
+
+    // Summarize each page with the agent
+    const summaries = await $.map({
+      id: "summarize-pages",
+      input: pages.value,
+      concurrency: 3,
+      execute: async ({ item: page, $ }) => {
+        const result = await $.agent({
+          id: `summarize-${page.url}`,
+          agent: summarizer,
+          input: { text: page.body },
+        });
+        if (!result.ok) throw new Error(`Failed to summarize ${page.url}`);
+        return { url: page.url, summary: result.value.output };
+      },
+    });
+
+    if (!summaries.ok) throw new Error("Failed to summarize");
+
+    return { summaries: summaries.value };
+  },
+);
+
+export const summarizePages = pipeline.fn();
+```
+
+## Verification
+
+- `result.ok` is `true` on success
+- `result.output` contains the validated workflow output
+- `result.trace` contains the frozen execution trace
+- `result.usage` contains aggregated token usage from all `$.agent()` calls
+- `result.duration` contains total wall-clock time in milliseconds
+
+## Troubleshooting
+
+### Input validation failed
+
+**Fix:** Check that the input matches the `input` Zod schema. Ensure all required fields are present and types are correct.
+
+### Output validation failed
+
+**Fix:** Ensure the handler returns an object matching the `output` Zod schema.
+
+### Step result not checked
+
+**Fix:** All `$` methods return `StepResult` -- check `.ok` before accessing `.value`.
+
+### `$.all`/`$.race` type error
+
+**Fix:** Entries must be factory functions `(signal) => Promise`, not pre-started promises.
+
+## References
+
+- [Create an Agent](create-agent.md)
+- [Create a Tool](create-tool.md)
+- [Provider Overview](../provider/overview.md)
+- [Troubleshooting](../troubleshooting.md)

package/docs/overview.md

@@ -0,0 +1,244 @@
+# Agent SDK
+
+`@pkg/agent-sdk` is a lightweight agent orchestration framework built on the [Vercel AI SDK](https://ai-sdk.dev). It provides typed primitives for creating AI agents, tools, and multi-step workflows with observable execution traces.
+
+## Design Principles
+
+| Principle                      | Description                                                                                |
+| ------------------------------ | ------------------------------------------------------------------------------------------ |
+| Functions all the way down     | `agent()`, `tool()`, `workflow()` return plain objects, no classes                         |
+| Composition over configuration | Combine small functions instead of large option bags                                       |
+| Closures are state             | Workflow state is just variables in your handler                                           |
+| Result, never throw            | Every public method returns `Result<T>`, callers pattern-match                             |
+| Zero hidden state              | No singletons, no module-level registries                                                  |
+| `$` is optional sugar          | The `$` helpers register data flow for observability; you can always use plain `for` loops |
+| Context is internal            | The framework tracks execution state automatically                                         |
+
+## Architecture
+
+```mermaid
+%%{init: {
+  'theme': 'base',
+  'themeVariables': {
+    'primaryColor': '#313244',
+    'primaryTextColor': '#cdd6f4',
+    'primaryBorderColor': '#6c7086',
+    'lineColor': '#89b4fa',
+    'secondaryColor': '#45475a',
+    'tertiaryColor': '#1e1e2e',
+    'background': '#1e1e2e',
+    'mainBkg': '#313244',
+    'clusterBkg': '#1e1e2e',
+    'clusterBorder': '#45475a'
+  },
+  'flowchart': { 'curve': 'basis', 'padding': 15 }
+}}%%
+
+flowchart LR
+  Input:::external
+
+  subgraph core [" "]
+    tool["tool()"]:::coreNode
+    agent["agent()"]:::coreNode
+    workflow["workflow()"]:::coreNode
+    engine["createWorkflowEngine()"]:::coreNode
+  end
+
+  subgraph steps [" "]
+    direction TB
+    dollar["$ (StepBuilder)"]:::step
+    stepOp["$.step"]:::step
+    agentOp["$.agent"]:::step
+    mapOp["$.map / $.each"]:::step
+    reduceOp["$.reduce / $.while"]:::step
+    concOp["$.all / $.race"]:::step
+  end
+
+  subgraph provider [" "]
+    direction LR
+    OpenRouter:::gateway
+    Model:::gateway
+  end
+
+  Input --> agent
+  Input --> workflow
+  agent -- ".generate() / .stream()" --> Result:::coreNode
+  workflow -- ".generate() / .stream()" --> Result
+  engine --> workflow
+  workflow --> dollar
+  dollar --> stepOp & agentOp & mapOp & reduceOp & concOp
+  agentOp --> agent
+  tool --> agent
+  agent --> OpenRouter --> Model
+
+  classDef external fill:#313244,stroke:#f5c2e7,stroke-width:2px,color:#cdd6f4
+  classDef coreNode fill:#313244,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+  classDef step fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+  classDef gateway fill:#313244,stroke:#fab387,stroke-width:2px,color:#cdd6f4
+
+  style core fill:#181825,stroke:#89b4fa,stroke-width:2px
+  style steps fill:#181825,stroke:#a6e3a1,stroke-width:2px
+  style provider fill:none,stroke:#fab387,stroke-width:2px,stroke-dasharray:5 5
+```
+
+## Core Concepts
+
+### `tool()`
+
+Create tools for AI agent function calling. Wraps the AI SDK's `tool()` with `zodSchema()` conversion.
+
+```ts
+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() };
+  },
+});
+```
+
+### `agent()`
+
+Create an agent with typed input, prompt template, tools, subagents, hooks, and `Result` return. Two modes:
+
+| Config                 | `.generate()` first param | How the prompt is built        |
+| ---------------------- | ------------------------- | ------------------------------ |
+| `input` + `prompt` set | Typed `TInput`            | `prompt({ input })` renders it |
+| Both omitted           | `string \| Message[]`     | Passed directly to the model   |
+
+```ts
+const summarizer = agent({
+  name: "summarizer",
+  model: "openai/gpt-4.1",
+  input: z.object({ text: z.string() }),
+  prompt: ({ input }) => `Summarize:\n\n${input.text}`,
+});
+
+const result = await summarizer.generate({ text: "..." });
+if (result.ok) {
+  console.log(result.output);
+}
+```
+
+Every agent exposes `.generate()`, `.stream()`, and `.fn()`.
+
+### `workflow()`
+
+Create a workflow with typed I/O, `$` step builder, hooks, and execution trace. The handler IS the workflow -- state is just variables.
+
+```ts
+const wf = workflow(
+  {
+    name: "analyze",
+    input: InputSchema,
+    output: OutputSchema,
+  },
+  async ({ input, $ }) => {
+    const data = await $.step({
+      id: "fetch-data",
+      execute: async () => fetchData(input.id),
+    });
+
+    const result = await $.agent({
+      id: "analyze",
+      agent: myAgent,
+      input: { data: data.value },
+    });
+
+    return { data: data.value, analysis: result.ok ? result.output : null };
+  },
+);
+```
+
+The `$` step builder provides tracked operations:
+
+| Method     | Description                                                   |
+| ---------- | ------------------------------------------------------------- |
+| `$.step`   | Execute a single unit of work                                 |
+| `$.agent`  | Execute an agent call as a tracked operation                  |
+| `$.map`    | Parallel map over items (with optional concurrency limit)     |
+| `$.each`   | Sequential side effects, returns void                         |
+| `$.reduce` | Sequential accumulation, each step depends on previous result |
+| `$.while`  | Conditional loop, runs while a condition holds                |
+| `$.all`    | Heterogeneous concurrent operations (like `Promise.all`)      |
+| `$.race`   | Concurrent operations, first to finish wins                   |
+
+### `createWorkflowEngine()`
+
+Create a custom workflow factory that adds additional step types to `$` and/or sets default hooks.
+
+```ts
+const engine = createWorkflowEngine({
+  $: {
+    retry: async ({ ctx, config }) => {
+      // custom step implementation with access to ExecutionContext
+    },
+  },
+  onStart: ({ input }) => telemetry.trackStart(input),
+});
+```
+
+## Key Types
+
+### Result
+
+Every public method returns `Result<T>` instead of throwing:
+
+```ts
+type Result<T> = (T & { ok: true }) | { ok: false; error: ResultError };
+```
+
+Error codes: `VALIDATION_ERROR`, `AGENT_ERROR`, `WORKFLOW_ERROR`, `ABORT_ERROR`. Helpers: `ok()`, `err()`, `isOk()`, `isErr()`.
+
+### Runnable
+
+Both `Agent` and `Workflow` satisfy the `Runnable` interface, enabling composition. Subagents passed to `agent({ agents })` are automatically wrapped as callable tools.
+
+### Context
+
+Internal -- never exposed to users. The framework creates it automatically. Custom step factories (via `createWorkflowEngine`) receive `ExecutionContext` with `signal` and `log`.
+
+### Logger
+
+Pino-compatible interface with `child()` support. The framework creates scoped child loggers at each boundary (workflow, step, agent).
+
+## Provider
+
+OpenRouter integration for model resolution. The `Model` type accepted by `agent()` is `string | LanguageModel` -- string IDs are resolved via OpenRouter at runtime, or pass any AI SDK provider instance directly.
+
+| Export                       | Description                                                      |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `openrouter(modelId)`        | Returns a `LanguageModel` (cached provider, reused across calls) |
+| `createOpenRouter(options?)` | Create a new OpenRouter provider instance                        |
+| `model(id)`                  | Look up a `ModelDefinition` by ID (throws if not found)          |
+| `tryModel(id)`               | Look up a `ModelDefinition` by ID (returns `undefined`)          |
+| `models(filter?)`            | Return all model definitions, optionally filtered                |
+
+## Execution Trace
+
+Workflows produce a frozen `TraceEntry[]` tree representing every tracked `$` operation:
+
+| Field        | Type            | Description                                                         |
+| ------------ | --------------- | ------------------------------------------------------------------- |
+| `id`         | `string`        | Step ID from the `$` config                                         |
+| `type`       | `OperationType` | `step`, `agent`, `map`, `each`, `reduce`, `while`, `all`, or `race` |
+| `startedAt`  | `number`        | Unix milliseconds                                                   |
+| `finishedAt` | `number?`       | Unix milliseconds (undefined while running)                         |
+| `error`      | `Error?`        | Present on failure                                                  |
+| `usage`      | `TokenUsage?`   | Token usage (populated for successful agent steps)                  |
+| `children`   | `TraceEntry[]?` | Nested operations (iterations, sub-steps)                           |
+
+## References
+
+- [Agent](core/agent.md)
+- [Workflow](core/workflow.md)
+- [Step Builder ($)](core/step.md)
+- [Tools](core/tools.md)
+- [Hooks](core/hooks.md)
+- [Provider](provider/overview.md)
+- [Models](provider/models.md)
+- [Token Usage](provider/usage.md)
+- [Create an Agent](guides/create-agent.md)
+- [Create a Workflow](guides/create-workflow.md)
+- [Create a Tool](guides/create-tool.md)

package/docs/provider/models.md

@@ -0,0 +1,55 @@
+# Models
+
+The SDK includes a model catalog with metadata and pricing for supported OpenRouter models. Used for cost calculation and model selection.
+
+Model data is auto-generated from the OpenRouter API. Run `pnpm --filter=@pkg/agent-sdk generate:models` to refresh.
+
+## Model Definition
+
+Each model entry has:
+
+| Field      | Type            | Description                                   |
+| ---------- | --------------- | --------------------------------------------- |
+| `id`       | `string`        | OpenRouter model ID (e.g. `'openai/gpt-4.1'`) |
+| `category` | `ModelCategory` | `'chat'`, `'coding'`, or `'reasoning'`        |
+| `pricing`  | `ModelPricing`  | Per-token rates (OpenRouter convention)       |
+
+## Pricing
+
+| Field               | Type     | Description                           |
+| ------------------- | -------- | ------------------------------------- |
+| `prompt`            | `number` | USD per input token                   |
+| `completion`        | `number` | USD per output token                  |
+| `inputCacheRead`    | `number` | USD per cached input token (optional) |
+| `inputCacheWrite`   | `number` | USD per cached input write (optional) |
+| `webSearch`         | `number` | USD per web search request (optional) |
+| `internalReasoning` | `number` | USD per reasoning token (optional)    |
+| `image`             | `number` | USD per image input token (optional)  |
+
+## Lookup
+
+Three functions:
+
+- `model(id)` -- Returns a single `ModelDefinition` or throws if the ID is not in the catalog.
+- `tryModel(id)` -- Returns a single `ModelDefinition` or `undefined` if the ID is not in the catalog.
+- `models(filter?)` -- Returns model definitions, optionally filtered by a predicate.
+
+```ts
+import { model, tryModel, models } from "@pkg/agent-sdk";
+
+const m = model("openai/gpt-4.1");
+console.log(m.pricing.prompt); // cost per input token
+console.log(m.category); // 'chat'
+
+const all = models();
+const reasoning = models((m) => m.category === "reasoning");
+```
+
+## Adding a Model
+
+Add an entry to `models.config.json` at the package root with the OpenRouter model ID and category, then run `pnpm --filter=@pkg/agent-sdk generate:models` to fetch pricing from the API.
+
+## References
+
+- [Provider Overview](overview.md)
+- [Token Usage](usage.md)