@funkai/agents 0.1.0

package/docs/core/workflow.md

@@ -0,0 +1,235 @@
+# workflow()
+
+`workflow()` creates a `Workflow` from a configuration object and an imperative handler function. The handler IS the workflow -- no step arrays, no definition objects. State is just variables. `$` is passed in for tracked operations.
+
+## Signature
+
+```ts
+function workflow<TInput, TOutput>(
+  config: WorkflowConfig<TInput, TOutput>,
+  handler: WorkflowHandler<TInput, TOutput>,
+): Workflow<TInput, TOutput>;
+```
+
+## WorkflowConfig
+
+| Field          | Required | Type                                                            | Description                                 |
+| -------------- | -------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `name`         | Yes      | `string`                                                        | Unique workflow name (used in logs, traces) |
+| `input`        | Yes      | `ZodType<TInput>`                                               | Zod schema for validating input             |
+| `output`       | Yes      | `ZodType<TOutput>`                                              | Zod schema for validating output            |
+| `logger`       | No       | `Logger`                                                        | Pino-compatible logger                      |
+| `onStart`      | No       | `(event: { input }) => void \| Promise<void>`                   | Hook: fires when the workflow starts        |
+| `onFinish`     | No       | `(event: { input, output, duration }) => void \| Promise<void>` | Hook: fires on success                      |
+| `onError`      | No       | `(event: { input, error }) => void \| Promise<void>`            | Hook: fires on error                        |
+| `onStepStart`  | No       | `(event: { step: StepInfo }) => void \| Promise<void>`          | Hook: fires when any `$` step starts        |
+| `onStepFinish` | No       | `(event: { step, result, duration }) => void \| Promise<void>`  | Hook: fires when any `$` step finishes      |
+
+## WorkflowHandler
+
+```ts
+type WorkflowHandler<TInput, TOutput> = (params: WorkflowParams<TInput>) => Promise<TOutput>;
+```
+
+The handler receives `{ input, $ }`:
+
+- `input` -- the validated input after Zod parsing.
+- `$` -- the `StepBuilder` for tracked operations (`$.step`, `$.agent`, `$.map`, etc.).
+
+The handler returns `TOutput`, which is validated against the `output` Zod schema before being returned to the caller.
+
+## Workflow Interface
+
+```ts
+interface Workflow<TInput, TOutput> {
+  generate(input: TInput, config?: WorkflowOverrides): Promise<Result<WorkflowResult<TOutput>>>;
+  stream(input: TInput, config?: WorkflowOverrides): Promise<Result<WorkflowStreamResult<TOutput>>>;
+  fn(): (input: TInput, config?: WorkflowOverrides) => Promise<Result<WorkflowResult<TOutput>>>;
+}
+```
+
+### generate()
+
+Runs the workflow to completion. Returns `Result<WorkflowResult<TOutput>>`.
+
+```ts
+interface WorkflowResult<TOutput> {
+  output: TOutput; // validated output
+  trace: readonly TraceEntry[]; // frozen execution trace tree
+  usage: TokenUsage; // aggregated token usage from all $.agent() calls
+  duration: number; // wall-clock time in ms
+}
+```
+
+On success, `result.ok` is `true` and `output`, `trace`, `duration` are flat on the result object.
+
+### stream()
+
+Runs the workflow with streaming step progress. Returns `Result<WorkflowStreamResult<TOutput>>`.
+
+```ts
+interface WorkflowStreamResult<TOutput> {
+  output: TOutput; // available after stream completes
+  trace: readonly TraceEntry[]; // available after stream completes
+  usage: TokenUsage; // aggregated token usage (available after stream completes)
+  duration: number; // available after stream completes
+  stream: ReadableStream<StepEvent>;
+}
+```
+
+Subscribe to `stream` for real-time step progress events.
+
+### StepEvent
+
+Events emitted on the workflow stream:
+
+| Type              | Fields                       | Description               |
+| ----------------- | ---------------------------- | ------------------------- |
+| `step:start`      | `step: StepInfo`             | A `$` operation started   |
+| `step:finish`     | `step`, `result`, `duration` | A `$` operation completed |
+| `step:error`      | `step`, `error`              | A `$` operation failed    |
+| `workflow:finish` | `output`, `duration`         | The workflow completed    |
+
+### fn()
+
+Returns a plain function with the same signature as `.generate()`. Use for clean single-function exports.
+
+## WorkflowOverrides
+
+Per-call overrides passed as the optional second parameter to `.generate()` or `.stream()`.
+
+| Field    | Type          | Description                   |
+| -------- | ------------- | ----------------------------- |
+| `signal` | `AbortSignal` | Abort signal for cancellation |
+
+When the signal fires, all in-flight `$` operations check `signal.aborted` and abort. The signal propagates through the entire execution tree.
+
+## createWorkflowEngine()
+
+For custom step types, use `createWorkflowEngine()`. It returns a `workflow()`-like factory with custom methods added to `$`.
+
+```ts
+function createWorkflowEngine<TCustomSteps>(
+  config: EngineConfig<TCustomSteps>,
+): WorkflowFactory<TCustomSteps>;
+```
+
+### EngineConfig
+
+| Field          | Type                    | Description                     |
+| -------------- | ----------------------- | ------------------------------- |
+| `$`            | `CustomStepDefinitions` | Custom step types to add to `$` |
+| `onStart`      | hook                    | Default hook for all workflows  |
+| `onFinish`     | hook                    | Default hook for all workflows  |
+| `onError`      | hook                    | Default hook for all workflows  |
+| `onStepStart`  | hook                    | Default hook for all workflows  |
+| `onStepFinish` | hook                    | Default hook for all workflows  |
+
+Engine-level hooks fire first, then workflow-level hooks fire second.
+
+Each custom step factory receives `{ ctx: ExecutionContext, config }` where `ExecutionContext` provides the abort signal and scoped logger:
+
+```ts
+type CustomStepFactory<TConfig, TResult> = (params: {
+  ctx: ExecutionContext;
+  config: TConfig;
+}) => Promise<TResult>;
+```
+
+### Example
+
+```ts
+const engine = createWorkflowEngine({
+  $: {
+    retry: async ({ ctx, config }) => {
+      let lastError: Error | undefined;
+      for (let attempt = 0; attempt < config.attempts; attempt++) {
+        if (ctx.signal.aborted) throw new Error("Aborted");
+        try {
+          return await config.execute({ attempt });
+        } catch (err) {
+          lastError = err as Error;
+          await sleep(config.backoff * (attempt + 1));
+        }
+      }
+      throw lastError;
+    },
+  },
+  onStart: ({ input }) => telemetry.trackStart(input),
+  onFinish: ({ output, duration }) => telemetry.trackFinish(output, duration),
+});
+
+const myWorkflow = engine(
+  {
+    name: "my-workflow",
+    input: MyInput,
+    output: MyOutput,
+  },
+  async ({ input, $ }) => {
+    // $.retry is fully typed from the engine config
+    const data = await $.retry({
+      attempts: 3,
+      backoff: 1000,
+      execute: async () => fetch("https://api.example.com/data"),
+    });
+    return data;
+  },
+);
+```
+
+## Full Example
+
+```ts
+import { workflow, agent, tool } from "@joggr/agent-sdk";
+import { z } from "zod";
+
+const analyzeAgent = agent({
+  name: "analyzer",
+  model: "openai/gpt-4.1",
+  input: z.object({ files: z.array(z.string()) }),
+  prompt: ({ input }) => `Analyze these files:\n${input.files.join("\n")}`,
+});
+
+const InputSchema = z.object({ repo: z.string() });
+const OutputSchema = z.object({ report: z.string(), fileCount: z.number() });
+
+const reporter = workflow(
+  {
+    name: "reporter",
+    input: InputSchema,
+    output: OutputSchema,
+  },
+  async ({ input, $ }) => {
+    // $.step for a tracked unit of work
+    const files = await $.step({
+      id: "list-files",
+      execute: async () => listFiles(input.repo),
+    });
+
+    if (!files.ok) {
+      return { report: "Failed to list files", fileCount: 0 };
+    }
+
+    // $.agent for a tracked agent call
+    const analysis = await $.agent({
+      id: "analyze",
+      agent: analyzeAgent,
+      input: { files: files.value },
+    });
+
+    return {
+      report: analysis.ok ? analysis.value.output : "Analysis failed",
+      fileCount: files.value.length,
+    };
+  },
+);
+
+const result = await reporter.generate({ repo: "my-org/my-repo" });
+```
+
+## References
+
+- [Core Overview](overview.md)
+- [Step Builder ($)](step.md)
+- [Hooks](hooks.md)
+- [Guide: Create a Workflow](../guides/create-workflow.md)

package/docs/guides/create-agent.md

@@ -0,0 +1,224 @@
+# Create an Agent
+
+## Prerequisites
+
+- `@pkg/agent-sdk` installed
+- `OPENROUTER_API_KEY` environment variable set
+- Familiarity with Zod schemas (for typed agents)
+
+## Steps
+
+### 1. Create a simple agent
+
+Pass a `name`, `model`, and optional `system` prompt. In simple mode, `.generate()` accepts a raw `string` or `Message[]`.
+
+```ts
+import { agent } from "@pkg/agent-sdk";
+
+const helper = agent({
+  name: "helper",
+  model: "openai/gpt-4.1",
+  system: "You are a helpful assistant.",
+});
+
+const result = await helper.generate("What is TypeScript?");
+if (result.ok) {
+  console.log(result.output); // string
+}
+```
+
+### 2. Create a typed agent
+
+Add an `input` Zod schema and a `prompt` function. Both are required together. `.generate()` now accepts the typed input.
+
+```ts
+import { agent } from "@pkg/agent-sdk";
+import { z } from "zod";
+
+const summarizer = agent({
+  name: "summarizer",
+  model: "openai/gpt-4.1",
+  input: z.object({
+    text: z.string(),
+    maxLength: z.number().optional(),
+  }),
+  prompt: ({ input }) =>
+    `Summarize the following text${input.maxLength ? ` in under ${input.maxLength} words` : ""}:\n\n${input.text}`,
+  system: "You produce concise summaries.",
+});
+
+const result = await summarizer.generate({
+  text: "A very long article...",
+  maxLength: 100,
+});
+```
+
+### 3. Add tools
+
+Pass a `tools` record. Tool names come from the object keys. See [Create a Tool](create-tool.md).
+
+```ts
+import { agent, tool } from "@pkg/agent-sdk";
+import { z } from "zod";
+
+const fetchPage = tool({
+  description: "Fetch a web page by URL",
+  inputSchema: z.object({ url: z.url() }),
+  execute: async ({ url }) => {
+    const res = await fetch(url);
+    return { status: res.status, body: await res.text() };
+  },
+});
+
+const researcher = agent({
+  name: "researcher",
+  model: "openai/gpt-4.1",
+  system: "You research topics by fetching web pages.",
+  tools: { fetchPage },
+});
+```
+
+### 4. Add subagents
+
+Pass an `agents` record. Each subagent is auto-wrapped as a delegatable tool. Abort signals propagate from parent to child.
+
+```ts
+const writer = agent({
+  name: "writer",
+  model: "openai/gpt-4.1",
+  input: z.object({ topic: z.string() }),
+  prompt: ({ input }) => `Write an article about ${input.topic}`,
+});
+
+const editor = agent({
+  name: "editor",
+  model: "openai/gpt-4.1",
+  system: "You review and improve articles. Delegate writing to the writer agent.",
+  agents: { writer },
+});
+```
+
+### 5. Use structured output
+
+Pass an `output` config to get typed structured output instead of a string. Accepts AI SDK `Output` strategies or raw Zod schemas.
+
+```ts
+import { Output } from "ai";
+
+// Zod schema auto-wrapped as Output.object()
+const classifier = agent({
+  name: "classifier",
+  model: "openai/gpt-4.1",
+  output: z.object({
+    category: z.enum(["bug", "feature", "question"]),
+    confidence: z.number(),
+  }),
+  input: z.object({ title: z.string(), body: z.string() }),
+  prompt: ({ input }) => `Classify this issue:\n\nTitle: ${input.title}\nBody: ${input.body}`,
+});
+
+// Or use Output directly
+const tagger = agent({
+  name: "tagger",
+  model: "openai/gpt-4.1",
+  output: Output.array({ element: z.object({ tag: z.string(), score: z.number() }) }),
+  system: "Extract tags from the text.",
+});
+```
+
+### 6. Stream output
+
+Use `.stream()` for incremental text delivery. The result contains a `ReadableStream<string>` for live chunks, plus `output` and `messages` as promises that resolve after the stream completes.
+
+```ts
+const result = await helper.stream("Explain async/await in detail");
+
+if (result.ok) {
+  // Consume text chunks as they arrive
+  const reader = result.stream.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    process.stdout.write(value);
+  }
+
+  // Await final output and messages after stream completes
+  const finalOutput = await result.output;
+  const messages = await result.messages;
+}
+```
+
+### 7. Export as a plain function
+
+Use `.fn()` for clean single-function exports.
+
+```ts
+export const summarize = summarizer.fn();
+
+// Callers use it like a regular async function
+const result = await summarize({ text: "...", maxLength: 50 });
+```
+
+### 8. Handle cancellation
+
+Pass an `AbortController` signal via per-call overrides.
+
+```ts
+const controller = new AbortController();
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10_000);
+
+const result = await helper.generate("Explain quantum computing", {
+  signal: controller.signal,
+});
+
+if (!result.ok) {
+  console.error(result.error.code); // 'AGENT_ERROR'
+}
+```
+
+### 9. Use per-call overrides
+
+Override model, system prompt, tools, output, and hooks for a single call without changing the agent definition.
+
+```ts
+const result = await helper.generate("Explain monads", {
+  model: "anthropic/claude-sonnet-4-20250514",
+  system: "You explain concepts using simple analogies.",
+  maxSteps: 5,
+  onStart: ({ input }) => console.log("Starting with:", input),
+  onFinish: ({ result, duration }) => console.log(`Done in ${duration}ms`),
+});
+```
+
+## Verification
+
+- `result.ok` is `true` on success
+- `result.output` contains the agent's response (string or typed object)
+- `result.messages` contains the full message history including tool calls
+
+## Troubleshooting
+
+### OPENROUTER_API_KEY not set
+
+**Fix:** Set the `OPENROUTER_API_KEY` environment variable in your `.env` file or shell environment.
+
+### Agent has `input` schema but no `prompt` function
+
+**Fix:** Provide both `input` and `prompt`, or omit both for simple mode.
+
+### Agent has `prompt` function but no `input` schema
+
+**Fix:** Provide both `input` and `prompt`, or omit both for simple mode.
+
+### Input validation failed
+
+**Fix:** Check that the input matches the Zod schema. Ensure all required fields are present and types are correct.
+
+## References
+
+- [Create a Tool](create-tool.md)
+- [Create a Workflow](create-workflow.md)
+- [Provider Overview](../provider/overview.md)
+- [Troubleshooting](../troubleshooting.md)

package/docs/guides/create-tool.md

@@ -0,0 +1,137 @@
+# Create a Tool
+
+## Prerequisites
+
+- `@pkg/agent-sdk` installed
+- Familiarity with Zod schemas
+
+## Steps
+
+### 1. Define a tool with `tool()`
+
+A tool wraps a function for AI agent function calling. Provide a `description`, an `inputSchema`, and an `execute` function.
+
+```ts
+import { tool } from "@pkg/agent-sdk";
+import { z } from "zod";
+
+const fetchPage = tool({
+  description: "Fetch a web page by URL",
+  inputSchema: z.object({ url: z.url() }),
+  execute: async (input) => {
+    const res = await fetch(input.url);
+    return { url: input.url, status: res.status, body: await res.text() };
+  },
+});
+```
+
+The `execute` function receives the validated input directly -- not wrapped in an object.
+
+### 2. Register the tool on an agent
+
+Pass tools as a record on the agent config. The tool's name comes from the object key, not from the tool definition itself.
+
+```ts
+import { agent } from "@pkg/agent-sdk";
+
+const researcher = agent({
+  name: "researcher",
+  model: "openai/gpt-4.1",
+  system: "You research topics by fetching web pages.",
+  tools: { fetchPage },
+});
+```
+
+The model sees the tool as `fetchPage` and uses the `description` to decide when to call it.
+
+### 3. Add optional configuration
+
+| Field           | Type                    | Description                                                       |
+| --------------- | ----------------------- | ----------------------------------------------------------------- |
+| `description`   | `string`                | **Required.** What the tool does. Shown to the model.             |
+| `inputSchema`   | `ZodType`               | **Required.** Validates and types the input from the model.       |
+| `execute`       | `(input) => Promise<T>` | **Required.** Runs when the model calls the tool.                 |
+| `outputSchema`  | `ZodType`               | Optional. Validates the return value before sending to the model. |
+| `title`         | `string`                | Optional. Human-readable display title for UIs and logs.          |
+| `inputExamples` | `Array<{ input: T }>`   | Optional. Example inputs to guide the model.                      |
+
+### 4. Add output validation
+
+Use `outputSchema` to validate the tool's return value before it is sent back to the model.
+
+```ts
+const calculator = tool({
+  description: "Evaluate a math expression",
+  inputSchema: z.object({ expression: z.string() }),
+  outputSchema: z.object({ result: z.number() }),
+  execute: async ({ expression }) => {
+    const result = eval(expression); // simplified example
+    return { result };
+  },
+});
+```
+
+### 5. Add input examples
+
+Use `inputExamples` to help the model understand expected input structure. Natively supported by Anthropic; for other providers, examples can be injected into the description via middleware.
+
+```ts
+const searchTool = tool({
+  description: "Search the codebase",
+  inputSchema: z.object({
+    query: z.string().describe("Search query"),
+    maxResults: z.number().default(10),
+  }),
+  inputExamples: [
+    { input: { query: "authentication middleware", maxResults: 5 } },
+    { input: { query: "database connection pool", maxResults: 10 } },
+  ],
+  execute: async ({ query, maxResults }) => {
+    return await codeSearch(query, maxResults);
+  },
+});
+```
+
+### 6. Destructure input for cleaner code
+
+Since `execute` receives the validated input directly, you can destructure it in the function signature.
+
+```ts
+const createFile = tool({
+  description: "Create a file with the given content",
+  inputSchema: z.object({
+    path: z.string(),
+    content: z.string(),
+  }),
+  execute: async ({ path, content }) => {
+    await fs.writeFile(path, content);
+    return { created: path };
+  },
+});
+```
+
+## Verification
+
+- The agent calls the tool during `.generate()` when the model decides to use it
+- Check that `result.messages` contains tool call and tool result entries
+- Tool return values appear in the model's context for subsequent reasoning
+
+## Troubleshooting
+
+### Tool not being called
+
+**Fix:** Improve the `description` so the model understands when to use it.
+
+### Input validation errors
+
+**Fix:** Ensure the `inputSchema` matches what the model is likely to produce.
+
+### Tool name mismatch
+
+**Fix:** Tool names come from the object key in `tools: { myName: myTool }`, not from the tool definition.
+
+## References
+
+- [Create an Agent](create-agent.md)
+- [Create a Workflow](create-workflow.md)
+- [Troubleshooting](../troubleshooting.md)