@funkai/agents 0.1.0

package/docs/core/hooks.md

@@ -0,0 +1,95 @@
+# Hooks
+
+Hooks provide lifecycle callbacks for agents, workflows, and steps. All hooks are optional. Hook errors are swallowed (logged via `attemptEachAsync`, never thrown) so they never mask the original error or interrupt execution.
+
+## Agent Hooks
+
+Set on `AgentConfig`:
+
+| Hook           | Event fields                  | When                                                                         |
+| -------------- | ----------------------------- | ---------------------------------------------------------------------------- |
+| `onStart`      | `{ input }`                   | Before the model is called                                                   |
+| `onFinish`     | `{ input, result, duration }` | After successful generation                                                  |
+| `onError`      | `{ input, error }`            | On error, before Result is returned                                          |
+| `onStepFinish` | `{ stepId }`                  | After each tool-loop step (counter-based: `agentName:0`, `agentName:1`, ...) |
+
+## Workflow Hooks
+
+Set on `WorkflowConfig`:
+
+| Hook           | Event fields                           | When                                                  |
+| -------------- | -------------------------------------- | ----------------------------------------------------- |
+| `onStart`      | `{ input }`                            | After input validation, before handler runs           |
+| `onFinish`     | `{ input, output, duration }`          | After successful completion                           |
+| `onError`      | `{ input, error }`                     | On error, before Result is returned                   |
+| `onStepStart`  | `{ step: StepInfo }`                   | Before any `$` operation executes                     |
+| `onStepFinish` | `{ step: StepInfo, result, duration }` | After any `$` operation completes (success AND error) |
+
+`onStepFinish` fires on both success and error. On error, `result` is `undefined`.
+
+## Step-Level Hooks
+
+Each `$` config accepts its own hooks:
+
+| Hook       | Event fields               | When                       |
+| ---------- | -------------------------- | -------------------------- |
+| `onStart`  | `{ id }`                   | Before the step executes   |
+| `onFinish` | `{ id, result, duration }` | After successful execution |
+| `onError`  | `{ id, error }`            | On error                   |
+
+These are available on `$.step`, `$.agent`, `$.map`, `$.each`, `$.reduce`, `$.while`, `$.all`, and `$.race`.
+
+## Per-Call Hooks
+
+Agent per-call hooks are set on `AgentOverrides` (the second parameter to `.generate()` or `.stream()`). They have the same names as the base hooks but fire **after** the base hooks.
+
+```ts
+await myAgent.generate("hello", {
+  onStart: ({ input }) => console.log("call-level start"),
+  onFinish: ({ result, duration }) => console.log(`call done in ${duration}ms`),
+});
+```
+
+## Hook Merging
+
+Per-call hooks merge with base hooks -- base fires first, then call-level. Both are independently wrapped with `attemptEachAsync`, so an error in one hook does not prevent the other from running.
+
+For workflow engines created with `createWorkflowEngine()`, engine-level hooks fire first, then workflow-level hooks fire second.
+
+## Hook Execution Order
+
+For a `$.agent` call inside a workflow:
+
+```
+step.onStart -> workflow.onStepStart -> execute -> step.onFinish -> workflow.onStepFinish
+```
+
+On error, the sequence diverges:
+
+```
+step.onStart -> workflow.onStepStart -> execute (throws) -> step.onError -> workflow.onStepFinish
+```
+
+For an agent's tool-loop steps:
+
+```
+base.onStepFinish -> overrides.onStepFinish
+```
+
+The `stepId` for agent tool-loop steps is counter-based: `agentName:0`, `agentName:1`, etc.
+
+## Error Handling
+
+All hooks are executed via `attemptEachAsync`, which:
+
+1. Runs each hook sequentially.
+2. Catches and swallows any errors -- hook failures never propagate.
+3. Skips `undefined` hooks (no null checks needed at call sites).
+
+This means a failing hook will never mask the original error or prevent other hooks from running.
+
+## References
+
+- [Agent](agent.md)
+- [Workflow](workflow.md)
+- [Step Builder ($)](step.md)

package/docs/core/overview.md

@@ -0,0 +1,87 @@
+# Core Concepts
+
+The core module provides the fundamental building blocks: `agent()`, `workflow()`, `tool()`, and the `$` step builder. All public operations return `Result<T>` so callers never need try/catch.
+
+## Result Type
+
+```ts
+type Result<T> = (T & { ok: true }) | { ok: false; error: ResultError };
+```
+
+Success fields are **flat on the object** -- no `.value` wrapper. Callers pattern-match on `ok`:
+
+```ts
+const result = await myAgent.generate("hello");
+
+if (!result.ok) {
+  console.error(result.error.code, result.error.message);
+  return;
+}
+
+// Success -- all fields from T are directly on result
+console.log(result.output);
+console.log(result.messages);
+```
+
+`ResultError` has `code` (machine-readable), `message` (human-readable), and optional `cause` (original thrown error).
+
+Helper constructors and type guards are exported: `ok()`, `err()`, `isOk()`, `isErr()`.
+
+## Context
+
+The framework creates an internal `Context` for each workflow execution. Users never create or pass this directly.
+
+```ts
+interface ExecutionContext {
+  readonly signal: AbortSignal;
+  readonly log: Logger;
+}
+```
+
+`ExecutionContext` is the public subset exposed to custom step factories via `createWorkflowEngine()`. The internal `Context` extends it with a mutable `trace: TraceEntry[]` array for recording the execution graph.
+
+## Logger
+
+Pino-compatible leveled logger with `child()` support for scoped bindings.
+
+```ts
+interface Logger {
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+```
+
+Each level also supports pino's object-first overload: `log.info({ key: 'val' }, 'message')`.
+
+The framework calls `child()` at scope boundaries (workflow, step, agent) so log output automatically includes execution context (`workflowId`, `stepId`, `agentId`). When no logger is injected, `createDefaultLogger()` provides a console-based fallback.
+
+## TraceEntry
+
+Every tracked `$` operation produces a `TraceEntry`. Nested operations appear as `children`, forming a tree that represents the full execution graph.
+
+```ts
+interface TraceEntry {
+  id: string; // from the $ config's `id` field
+  type: OperationType; // 'step' | 'agent' | 'map' | 'each' | 'reduce' | 'while' | 'all' | 'race'
+  input?: unknown; // captured when the operation starts
+  output?: unknown; // captured on success
+  startedAt: number; // Unix ms
+  finishedAt?: number; // Unix ms (undefined while running)
+  error?: Error; // set on failure
+  usage?: TokenUsage; // token usage (populated for successful agent steps)
+  children?: TraceEntry[];
+}
+```
+
+The trace is exposed on `WorkflowResult.trace` as a frozen (immutable) snapshot after workflow completion.
+
+## References
+
+- [Agent](agent.md)
+- [Workflow](workflow.md)
+- [Step Builder ($)](step.md)
+- [Tools](tools.md)
+- [Hooks](hooks.md)

package/docs/core/step.md

@@ -0,0 +1,279 @@
+# $ StepBuilder
+
+The `$` object is passed into every workflow handler and step callback. It provides tracked operations that register data flow in the execution trace. Every call through `$` becomes a `TraceEntry`.
+
+`$` is passed into every callback, enabling composition and nesting. You can always skip `$` and use plain imperative code -- it just will not appear in the trace.
+
+## StepResult
+
+All `$` methods return `Promise<StepResult<T>>`:
+
+```ts
+type StepResult<T> =
+  | { ok: true; value: T; step: StepInfo; duration: number }
+  | { ok: false; error: StepError; step: StepInfo; duration: number };
+```
+
+`StepInfo` identifies the step:
+
+```ts
+interface StepInfo {
+  id: string; // from the $ config's `id` field
+  index: number; // auto-incrementing within the workflow
+  type: OperationType; // 'step' | 'agent' | 'map' | 'each' | 'reduce' | 'while' | 'all' | 'race'
+}
+```
+
+`StepError` extends `ResultError` with `stepId: string`.
+
+## $.step
+
+Single unit of work.
+
+```ts
+$.step<T>(config: StepConfig<T>): Promise<StepResult<T>>
+```
+
+| Field      | Required | Type                                                         | Description                  |
+| ---------- | -------- | ------------------------------------------------------------ | ---------------------------- |
+| `id`       | Yes      | `string`                                                     | Unique step identifier       |
+| `execute`  | Yes      | `(params: { $ }) => Promise<T>`                              | The step's logic             |
+| `onStart`  | No       | `(event: { id }) => void \| Promise<void>`                   | Hook: fires when step starts |
+| `onFinish` | No       | `(event: { id, result, duration }) => void \| Promise<void>` | Hook: fires on success       |
+| `onError`  | No       | `(event: { id, error }) => void \| Promise<void>`            | Hook: fires on error         |
+
+```ts
+const data = await $.step({
+  id: "fetch-data",
+  execute: async () => {
+    return await fetchData();
+  },
+});
+
+if (data.ok) {
+  console.log(data.value); // T
+}
+```
+
+## $.agent
+
+Agent call as a tracked operation. Calls `agent.generate()` internally and unwraps the result -- agent errors become `StepError`, agent success becomes `StepResult<GenerateResult>`.
+
+```ts
+$.agent<TInput>(config: AgentStepConfig<TInput>): Promise<StepResult<GenerateResult>>
+```
+
+| Field      | Required | Type               | Description                          |
+| ---------- | -------- | ------------------ | ------------------------------------ |
+| `id`       | Yes      | `string`           | Unique step identifier               |
+| `agent`    | Yes      | `Runnable<TInput>` | The agent (or workflow) to invoke    |
+| `input`    | Yes      | `TInput`           | Input to pass to the agent           |
+| `config`   | No       | `AgentOverrides`   | Inline overrides for this agent call |
+| `onStart`  | No       | hook               | Hook: fires when step starts         |
+| `onFinish` | No       | hook               | Hook: fires on success               |
+| `onError`  | No       | hook               | Hook: fires on error                 |
+
+The framework automatically passes the abort signal and a scoped logger to the agent.
+
+```ts
+const result = await $.agent({
+  id: "analyze",
+  agent: analyzerAgent,
+  input: { files: ["src/main.ts"] },
+});
+
+if (result.ok) {
+  console.log(result.value.output); // the agent's output
+  console.log(result.value.messages); // full message history
+}
+```
+
+## $.map
+
+Parallel map with optional concurrency limit. All items run concurrently (up to `concurrency` limit). Returns results in input order.
+
+```ts
+$.map<T, R>(config: MapConfig<T, R>): Promise<StepResult<R[]>>
+```
+
+| Field         | Required | Type                                         | Description                                 |
+| ------------- | -------- | -------------------------------------------- | ------------------------------------------- |
+| `id`          | Yes      | `string`                                     | Unique step identifier                      |
+| `input`       | Yes      | `T[]`                                        | Array of items to process                   |
+| `execute`     | Yes      | `(params: { item, index, $ }) => Promise<R>` | Process a single item                       |
+| `concurrency` | No       | `number`                                     | Max parallel executions (default: Infinity) |
+| `onStart`     | No       | hook                                         | Hook: fires when map starts                 |
+| `onFinish`    | No       | hook                                         | Hook: fires when all items complete         |
+| `onError`     | No       | hook                                         | Hook: fires on error                        |
+
+```ts
+const results = await $.map({
+  id: "process-files",
+  input: files,
+  concurrency: 5,
+  execute: async ({ item, index }) => {
+    return await processFile(item);
+  },
+});
+```
+
+## $.each
+
+Sequential side effects. Runs items one at a time in order. Returns `void`. Checks abort signal before each iteration.
+
+```ts
+$.each<T>(config: EachConfig<T>): Promise<StepResult<void>>
+```
+
+| Field      | Required | Type                                            | Description                   |
+| ---------- | -------- | ----------------------------------------------- | ----------------------------- |
+| `id`       | Yes      | `string`                                        | Unique step identifier        |
+| `input`    | Yes      | `T[]`                                           | Array of items to process     |
+| `execute`  | Yes      | `(params: { item, index, $ }) => Promise<void>` | Process a single item         |
+| `onStart`  | No       | hook                                            | Hook: fires when each starts  |
+| `onFinish` | No       | hook                                            | Hook: fires when all complete |
+| `onError`  | No       | hook                                            | Hook: fires on error          |
+
+```ts
+await $.each({
+  id: "notify-users",
+  input: users,
+  execute: async ({ item }) => {
+    await sendNotification(item.email);
+  },
+});
+```
+
+## $.reduce
+
+Sequential accumulation. Each step depends on the previous result. Checks abort signal before each iteration.
+
+```ts
+$.reduce<T, R>(config: ReduceConfig<T, R>): Promise<StepResult<R>>
+```
+
+| Field      | Required | Type                                                      | Description                    |
+| ---------- | -------- | --------------------------------------------------------- | ------------------------------ |
+| `id`       | Yes      | `string`                                                  | Unique step identifier         |
+| `input`    | Yes      | `T[]`                                                     | Array of items to reduce       |
+| `initial`  | Yes      | `R`                                                       | Initial accumulator value      |
+| `execute`  | Yes      | `(params: { item, accumulator, index, $ }) => Promise<R>` | Reduce function                |
+| `onStart`  | No       | hook                                                      | Hook: fires when reduce starts |
+| `onFinish` | No       | hook                                                      | Hook: fires when done          |
+| `onError`  | No       | hook                                                      | Hook: fires on error           |
+
+```ts
+const total = await $.reduce({
+  id: "sum-scores",
+  input: items,
+  initial: 0,
+  execute: async ({ item, accumulator }) => {
+    return accumulator + item.score;
+  },
+});
+```
+
+## $.while
+
+Conditional loop. Runs while a condition holds. Returns the last value, or `undefined` if the condition was false on first check. Checks abort signal before each iteration.
+
+```ts
+$.while<T>(config: WhileConfig<T>): Promise<StepResult<T | undefined>>
+```
+
+| Field       | Required | Type                                    | Description                                    |
+| ----------- | -------- | --------------------------------------- | ---------------------------------------------- |
+| `id`        | Yes      | `string`                                | Unique step identifier                         |
+| `condition` | Yes      | `(params: { value, index }) => boolean` | Loop condition (checked before each iteration) |
+| `execute`   | Yes      | `(params: { index, $ }) => Promise<T>`  | Execute one iteration                          |
+| `onStart`   | No       | hook                                    | Hook: fires when while starts                  |
+| `onFinish`  | No       | hook                                    | Hook: fires when loop ends                     |
+| `onError`   | No       | hook                                    | Hook: fires on error                           |
+
+The `condition` receives the last iteration's value (or `undefined` before the first iteration) and the current iteration index.
+
+```ts
+const result = await $.while({
+  id: "poll-status",
+  condition: ({ value, index }) => index < 10 && value !== "complete",
+  execute: async ({ index }) => {
+    await sleep(1000);
+    return await checkStatus();
+  },
+});
+```
+
+## $.all
+
+Concurrent heterogeneous operations -- like `Promise.all`. Entries are factory functions that receive an `AbortSignal` and return a promise. The framework creates an `AbortController`, links it to the parent signal, and starts all factories at the same time.
+
+```ts
+$.all(config: AllConfig): Promise<StepResult<unknown[]>>
+```
+
+| Field      | Required | Type             | Description                           |
+| ---------- | -------- | ---------------- | ------------------------------------- |
+| `id`       | Yes      | `string`         | Unique step identifier                |
+| `entries`  | Yes      | `EntryFactory[]` | Factory functions to run concurrently |
+| `onStart`  | No       | hook             | Hook: fires when all starts           |
+| `onFinish` | No       | hook             | Hook: fires when all complete         |
+| `onError`  | No       | hook             | Hook: fires on error                  |
+
+Where `EntryFactory = (signal: AbortSignal) => Promise<any>`.
+
+```ts
+const [users, repos] = await $.all({
+  id: "fetch-data",
+  entries: [(signal) => fetchUsers(signal), (signal) => fetchRepos(signal)],
+});
+```
+
+## $.race
+
+First-to-finish wins. Same `entries: EntryFactory[]` pattern as `$.all`. Losers are cancelled via abort signal when the winner resolves.
+
+```ts
+$.race(config: RaceConfig): Promise<StepResult<unknown>>
+```
+
+| Field      | Required | Type             | Description                      |
+| ---------- | -------- | ---------------- | -------------------------------- |
+| `id`       | Yes      | `string`         | Unique step identifier           |
+| `entries`  | Yes      | `EntryFactory[]` | Factory functions to race        |
+| `onStart`  | No       | hook             | Hook: fires when race starts     |
+| `onFinish` | No       | hook             | Hook: fires when winner resolves |
+| `onError`  | No       | hook             | Hook: fires on error             |
+
+```ts
+const result = await $.race({
+  id: "fastest-provider",
+  entries: [(signal) => fetchFromProviderA(signal), (signal) => fetchFromProviderB(signal)],
+});
+
+if (result.ok) {
+  const fastest = result.value;
+}
+```
+
+## Nesting
+
+`$` is passed into every callback so you can nest operations freely. Nested operations appear as `children` in the parent's trace entry.
+
+```ts
+const result = await $.step({
+  id: "outer",
+  execute: async ({ $ }) => {
+    const inner = await $.step({
+      id: "inner",
+      execute: async () => "nested value",
+    });
+    return inner.ok ? inner.value : "fallback";
+  },
+});
+```
+
+## References
+
+- [Workflow](workflow.md)
+- [Hooks](hooks.md)
+- [Core Overview](overview.md)

package/docs/core/tools.md

@@ -0,0 +1,98 @@
+# tool()
+
+`tool()` creates a tool for AI agent function calling. It wraps the AI SDK's `tool()` helper, converting Zod schemas to JSON Schema via `zodSchema()` for model I/O validation.
+
+## Signature
+
+```ts
+function tool<TInput, TOutput>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+```
+
+## ToolConfig
+
+| Field           | Required | Type                                  | Description                                |
+| --------------- | -------- | ------------------------------------- | ------------------------------------------ |
+| `description`   | Yes      | `string`                              | What the tool does (shown to the model)    |
+| `title`         | No       | `string`                              | Display title for UIs and logs             |
+| `inputSchema`   | Yes      | `ZodType<TInput>`                     | Zod schema for validating and typing input |
+| `outputSchema`  | No       | `ZodType<TOutput>`                    | Zod schema for validating output           |
+| `inputExamples` | No       | `Array<{ input: TInput }>`            | Example inputs to guide the model          |
+| `execute`       | Yes      | `(input: TInput) => Promise<TOutput>` | Execute the tool with validated input      |
+
+**Note:** There is no `name` field on `ToolConfig`. Tool names come from the object key when passed to an agent's `tools` record.
+
+## Tool Type
+
+The `Tool` type is the return type of the AI SDK's `tool()` function:
+
+```ts
+type Tool<TInput = unknown, TOutput = unknown> = ReturnType<typeof aiTool<TInput, TOutput>>;
+```
+
+## Example
+
+```ts
+import { tool, agent } from "@joggr/agent-sdk";
+import { z } from "zod";
+
+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(),
+    };
+  },
+});
+
+// Tool name ("fetchPage") comes from the object key:
+const assistant = agent({
+  name: "assistant",
+  model: "openai/gpt-4.1",
+  system: "You are a helpful assistant that can fetch web pages.",
+  tools: { fetchPage },
+});
+```
+
+### Output validation
+
+```ts
+const calculator = tool({
+  description: "Evaluate a math expression",
+  inputSchema: z.object({ expression: z.string() }),
+  outputSchema: z.object({ result: z.number() }),
+  execute: async ({ expression }) => {
+    return { result: evaluate(expression) };
+  },
+});
+```
+
+### Input examples
+
+```ts
+const searchTool = tool({
+  description: "Search the codebase for a pattern",
+  inputSchema: z.object({
+    query: z.string(),
+    fileType: z.string().optional(),
+  }),
+  inputExamples: [
+    { input: { query: "function handleError", fileType: "ts" } },
+    { input: { query: "TODO:" } },
+  ],
+  execute: async ({ query, fileType }) => {
+    return await searchCodebase(query, fileType);
+  },
+});
+```
+
+## References
+
+- [Agent](agent.md)
+- [Core Overview](overview.md)
+- [Guide: Create a Tool](../guides/create-tool.md)