@funkai/agents 0.1.0

package/docs/provider/overview.md

@@ -0,0 +1,106 @@
+# Provider Overview
+
+The provider module integrates with OpenRouter for model access and provides a model catalog with pricing data.
+
+## OpenRouter
+
+All models are accessed via OpenRouter. The `openrouter()` function creates a language model from a model ID.
+
+```ts
+import { openrouter } from "@pkg/agent-sdk";
+
+const m = openrouter("openai/gpt-4.1");
+```
+
+The provider instance is cached at module scope and reused across calls. If `OPENROUTER_API_KEY` changes at runtime, the cache is invalidated and a new provider is created.
+
+## API Key
+
+Resolved from the `OPENROUTER_API_KEY` environment variable. Throws if not set.
+
+```ts
+// Override with a custom provider instance
+import { createOpenRouter } from "@pkg/agent-sdk";
+
+const provider = createOpenRouter({ apiKey: "sk-..." });
+const m = provider("openai/gpt-4.1");
+```
+
+## Model Catalog
+
+Models are defined in `models.config.json` and auto-generated into provider-specific files. Use the catalog functions to look up model definitions and pricing.
+
+```ts
+import { model, tryModel, models } from "@pkg/agent-sdk";
+
+// Look up a model (throws if not found)
+const gpt4 = model("openai/gpt-4.1");
+console.log(gpt4.pricing.prompt); // cost per input token
+
+// Safe lookup (returns undefined if not found)
+const maybe = tryModel("openai/gpt-4.1");
+
+// List all models, optionally filtered
+const allModels = models();
+const reasoningModels = models((m) => m.category === "reasoning");
+```
+
+## Token Usage
+
+Aggregate token counts across agent and workflow executions.
+
+```ts
+import { agentUsage, workflowUsage } from "@pkg/agent-sdk";
+
+// Single agent usage
+const usage = agentUsage("my-agent", tokenRecords);
+console.log(usage.inputTokens, usage.outputTokens, usage.totalTokens);
+
+// Workflow usage with per-agent breakdown
+const wfUsage = workflowUsage(allTokenRecords);
+for (const entry of wfUsage.usages) {
+  console.log(`${entry.agentId}: ${entry.totalTokens} tokens`);
+}
+```
+
+## Exports
+
+| Export                         | Description                                                       |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `openrouter(modelId)`          | Create a language model from OpenRouter (cached provider)         |
+| `createOpenRouter(options?)`   | Create a custom OpenRouter provider instance                      |
+| `model(id)`                    | Look up a model definition from the catalog (throws if not found) |
+| `tryModel(id)`                 | Look up a model definition (returns `undefined` if not found)     |
+| `models(filter?)`              | Get model definitions, optionally filtered by predicate           |
+| `agentUsage(agentId, records)` | Aggregate token counts for a single agent                         |
+| `workflowUsage(records)`       | Aggregate token counts for a workflow with per-agent breakdown    |
+
+## Model Reference
+
+String model IDs passed to `agent()` or `openrouter()` are resolved via OpenRouter at runtime. You can also pass an AI SDK `LanguageModel` instance directly.
+
+```ts
+import { agent } from "@pkg/agent-sdk";
+
+// String ID -- resolved via OpenRouter
+const a1 = agent({
+  name: "my-agent",
+  model: "openai/gpt-4.1",
+  system: "You are helpful.",
+});
+
+// AI SDK provider instance -- bypasses OpenRouter
+import { openai } from "@ai-sdk/openai";
+
+const a2 = agent({
+  name: "my-agent",
+  model: openai("gpt-4.1"),
+  system: "You are helpful.",
+});
+```
+
+## References
+
+- [Models](models.md)
+- [Create an Agent](../guides/create-agent.md)
+- [Troubleshooting](../troubleshooting.md)

package/docs/provider/usage.md

@@ -0,0 +1,100 @@
+# Token Usage
+
+Token tracking and aggregation for agent and workflow executions.
+
+## TokenUsageRecord
+
+Raw tracking record from a single model invocation. Fields are `number | undefined` because not all providers report every field.
+
+| Field              | Type                  | Description                              |
+| ------------------ | --------------------- | ---------------------------------------- |
+| `modelId`          | `string`              | OpenRouter model ID                      |
+| `inputTokens`      | `number \| undefined` | Input (prompt) tokens                    |
+| `outputTokens`     | `number \| undefined` | Output (completion) tokens               |
+| `totalTokens`      | `number \| undefined` | Input + output                           |
+| `cacheReadTokens`  | `number \| undefined` | Tokens served from provider prompt cache |
+| `cacheWriteTokens` | `number \| undefined` | Tokens written to prompt cache           |
+| `reasoningTokens`  | `number \| undefined` | Internal reasoning tokens (e.g. o3/o4)   |
+| `source`           | `object \| undefined` | Framework-populated source info          |
+
+The `source` field identifies which component produced the record:
+
+```ts
+source?: {
+  workflowId?: string
+  stepId?: string
+  agentId: string
+  scope: string[]
+}
+```
+
+## Agent Usage
+
+`agentUsage()` aggregates token counts from one or more raw records into a flat `AgentTokenUsage` object.
+
+```ts
+import { agentUsage } from "@pkg/agent-sdk";
+
+const usage = agentUsage("my-agent", records);
+console.log(usage.agentId); // 'my-agent'
+console.log(usage.inputTokens); // resolved number (0 if undefined)
+console.log(usage.outputTokens);
+console.log(usage.totalTokens);
+```
+
+## Workflow Usage
+
+`workflowUsage()` groups records by `source.agentId` and computes per-agent usage.
+
+```ts
+import { workflowUsage } from "@pkg/agent-sdk";
+
+const usage = workflowUsage(allRecords);
+for (const entry of usage.usages) {
+  console.log(`${entry.agentId}: ${entry.totalTokens} tokens`);
+}
+```
+
+## TokenUsage (resolved)
+
+The aggregated output type. All fields are resolved `number` (0 when the raw record was `undefined`).
+
+| Field              | Type     | Description               |
+| ------------------ | -------- | ------------------------- |
+| `inputTokens`      | `number` | Total input tokens        |
+| `outputTokens`     | `number` | Total output tokens       |
+| `totalTokens`      | `number` | Input + output            |
+| `cacheReadTokens`  | `number` | Cached input tokens       |
+| `cacheWriteTokens` | `number` | Cache write tokens        |
+| `reasoningTokens`  | `number` | Internal reasoning tokens |
+
+## Usage Utilities
+
+### `sumTokenUsage()`
+
+Sum multiple `TokenUsage` objects into a new one. Pure function, does not mutate inputs.
+
+```ts
+import { sumTokenUsage } from "@pkg/agent-sdk";
+
+const total = sumTokenUsage([usageA, usageB, usageC]);
+```
+
+### `collectUsages()`
+
+Walk a `TraceEntry[]` tree and collect all `usage` values into a flat array (recursively including children). Compose with `sumTokenUsage()` to aggregate usage across all `$.agent()` calls.
+
+```ts
+import { collectUsages, sumTokenUsage } from "@pkg/agent-sdk";
+
+const result = await myWorkflow.generate(input);
+if (result.ok) {
+  // result.usage is already computed, but you can also derive it from the trace:
+  const usage = sumTokenUsage(collectUsages(result.trace));
+}
+```
+
+## References
+
+- [Models](models.md)
+- [Provider Overview](overview.md)

package/docs/research/experimental-context.md

@@ -0,0 +1,167 @@
+# Research: `experimental_context` — Per-Call Context Store
+
+> **Date**: 2026-03-06
+> **AI SDK Version**: `^6.0.111`
+> **Status**: Gap identified — context is not wired through the SDK; tool execute signature drops it
+
+## Summary
+
+The Vercel AI SDK v6 provides `experimental_context` — a user-defined state object that flows through the entire `generateText`/`streamText` lifecycle. It is available in `prepareStep`, tool `execute` callbacks, and lifecycle hooks. Our SDK does not expose it at any layer, and our `tool()` helper actively drops the second argument that carries it.
+
+## How `experimental_context` Flows in the AI SDK
+
+```
+generateText({ experimental_context: initialState })
+        │
+        ▼
+   prepareStep({ experimental_context })
+        │  can return { experimental_context: modifiedState }
+        ▼
+   tool.execute(input, { experimental_context })
+        │  tools can read it (typed as unknown)
+        ▼
+   onStepFinish({ experimental_context })
+        │  callbacks can observe it
+        ▼
+   next step's prepareStep receives updated context
+        │
+        ▼
+   result.experimental_context  ←  final state after all steps
+```
+
+### Key Behaviors
+
+- **Mutable across steps**: `prepareStep` can return a new `experimental_context`, which propagates to all subsequent steps and tool calls
+- **Available in tool execute**: received as `execute(input, { experimental_context })`
+- **Typed as `unknown`**: consumers must cast/validate at runtime
+- **Experimental**: can break in patch releases (the `experimental_` prefix is the AI SDK's convention for unstable APIs)
+
+### AI SDK Code Example
+
+```typescript
+const result = await generateText({
+  model: openrouter("anthropic/claude-sonnet-4"),
+  tools: {
+    fetchData: tool({
+      description: "Fetch data from the API",
+      inputSchema: z.object({ endpoint: z.string() }),
+      execute: async (input, { experimental_context: ctx }) => {
+        const typed = ctx as { authToken: string };
+        const res = await fetch(input.endpoint, {
+          headers: { Authorization: `Bearer ${typed.authToken}` },
+        });
+        return res.json();
+      },
+    }),
+  },
+  experimental_context: { authToken: "sk-..." },
+  prepareStep: async ({ experimental_context, stepNumber }) => {
+    // Evolve context between steps
+    const ctx = experimental_context as { authToken: string; stepCount: number };
+    return {
+      experimental_context: { ...ctx, stepCount: stepNumber },
+    };
+  },
+});
+```
+
+## Current SDK State
+
+### `tool.ts` — Execute signature drops context
+
+Our `tool()` helper wraps execute as:
+
+```typescript
+// tool.ts:111
+execute: async (data: TInput) => config.execute(data),
+```
+
+The AI SDK passes a second `options` argument to `execute` containing `{ experimental_context, abortSignal, messages, ... }`. Our wrapper discards this entirely. Tools created with our `tool()` can never access context.
+
+### `ToolConfig` — No context in the type
+
+```typescript
+// tool.ts:65
+execute: (input: TInput) => Promise<TOutput>;
+```
+
+The execute signature only accepts `input`. There is no options parameter.
+
+### `AgentConfig` / `AgentOverrides` — No context field
+
+Neither type includes `experimental_context` or any equivalent. The `generateText` call in `agent.ts` does not pass it.
+
+### Comparison: Our `ExecutionContext` vs AI SDK `experimental_context`
+
+| Aspect                         | AI SDK `experimental_context`      | Our `ExecutionContext`                              |
+| ------------------------------ | ---------------------------------- | --------------------------------------------------- |
+| **Layer**                      | Per-`generateText` call, per-step  | Per-workflow, per-`$` operation                     |
+| **Available in tools**         | Yes, via execute's second arg      | No                                                  |
+| **Mutable between steps**      | Yes, via `prepareStep`             | No (readonly signal + logger)                       |
+| **Available in `prepareStep`** | Yes                                | N/A (no `prepareStep` exposed)                      |
+| **User-defined shape**         | Yes (typed as `unknown`)           | No (fixed: signal + logger + trace)                 |
+| **Purpose**                    | Ambient state for the agentic loop | Framework plumbing (cancellation, logging, tracing) |
+
+These are complementary, not competing. `ExecutionContext` is framework infrastructure; `experimental_context` is user-space state.
+
+## Implementation Path
+
+### 1. Extend `ToolConfig.execute` to accept context
+
+```typescript
+interface ToolConfig<TInput, TOutput> {
+  execute: (input: TInput, options?: { context?: unknown }) => Promise<TOutput>;
+}
+```
+
+And forward the AI SDK's second arg:
+
+```typescript
+// tool.ts — updated wrapper
+execute: async (data: TInput, options) => config.execute(data, {
+  context: options?.experimental_context,
+}),
+```
+
+### 2. Add context to `AgentConfig` and `AgentOverrides`
+
+```typescript
+interface AgentConfig<TInput, TOutput, TTools, TSubAgents> {
+  // ...existing fields
+  context?: unknown;
+}
+
+interface AgentOverrides<TTools, TSubAgents> {
+  // ...existing fields
+  context?: unknown;
+}
+```
+
+### 3. Forward to `generateText`
+
+```typescript
+const aiResult = await generateText({
+  // ...existing params
+  experimental_context: overrideContext ?? config.context,
+});
+```
+
+### 4. Combine with `prepareStep`
+
+Once both `prepareStep` and `experimental_context` are wired, the context becomes fully mutable across the agentic loop — enabling patterns like:
+
+- Accumulating discovered information across steps
+- Passing auth tokens or session state to tools
+- Tracking which tools have been called and their results
+- Sharing state between parent agent and sub-agents-as-tools
+
+## Open Issues
+
+- [GitHub #10482](https://github.com/vercel/ai/issues/10482) — Requests tighter `experimental_context` integration in `prepareStep` (may already be resolved in latest v6)
+- The `experimental_` prefix means this API could change. Consider wrapping it behind a stable SDK-level abstraction so consumers are insulated from upstream changes.
+
+## References
+
+- [AI SDK Tool Calling docs](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling)
+- [generateText API Reference](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)
+- [GitHub Issue #10482](https://github.com/vercel/ai/issues/10482)

package/docs/research/gap-analysis.md

@@ -0,0 +1,86 @@
+# Research: Agent SDK Gap Analysis
+
+> **Date**: 2026-03-06
+> **AI SDK Version**: `^6.0.111`
+
+## Overview
+
+This document consolidates all identified gaps between our agent SDK wrapper and the underlying Vercel AI SDK v6 capabilities, specifically for supporting agentic loop control, context management, and sub-agent orchestration.
+
+For detailed analysis of each area, see:
+
+- [prepareStep and activeTools](./prepare-step-and-active-tools.md)
+- [experimental_context](./experimental-context.md)
+- [Sub-Agent Model](./sub-agent-model.md)
+
+## Gap Summary
+
+| #   | Gap                                    | Severity   | Current State                                                                                            | AI SDK Capability                                                                                        |
+| --- | -------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| 1   | No `prepareStep` support               | **High**   | `AgentConfig`/`AgentOverrides` have no field; `agent.ts` does not pass it to `generateText`/`streamText` | `prepareStep` callback fires before each step; can modify model, messages, tools, system prompt, context |
+| 2   | No `activeTools` support               | **High**   | Not exposed at any layer                                                                                 | Top-level and per-step tool restriction via string array of tool names                                   |
+| 3   | No `experimental_context` support      | **High**   | Not exposed; `tool()` drops the second execute arg that carries it                                       | User-defined state flows through `prepareStep`, tool `execute`, and lifecycle hooks                      |
+| 4   | `tool()` drops AI SDK execute options  | **High**   | `tool.ts:111` wraps as `(data) => config.execute(data)`, discarding options                              | Second arg provides `{ experimental_context, abortSignal, messages, toolCallId }`                        |
+| 5   | No context forwarding to sub-agents    | **Medium** | Sub-agents start fresh with only their `input`                                                           | `experimental_context` could carry parent state to child tools                                           |
+| 6   | No dynamic sub-agent spawning          | **Medium** | `agents` config is static at creation time                                                               | `prepareStep` + `activeTools` can dynamically add/remove tools per step                                  |
+| 7   | No shared state between sibling agents | **Medium** | Sub-agents are fully isolated                                                                            | `experimental_context` accumulation via `prepareStep`                                                    |
+| 8   | No per-delegation step budget          | **Low**    | Child agents use their own `maxSteps` (default 20)                                                       | `AgentOverrides.maxSteps` exists but isn't used in sub-agent wrapper                                     |
+| 9   | No result-to-context feedback          | **Medium** | Sub-agent output is only a tool result string                                                            | `prepareStep` can accumulate tool results into context between steps                                     |
+
+## Impact on Use Cases
+
+### Agentic Loop Control
+
+Without `prepareStep`, the agentic loop is fully model-driven with no programmatic intervention between steps. Cannot:
+
+- Compress context when it grows too large (token budget management)
+- Restrict tools to specific phases of execution
+- Switch models based on task complexity
+- Adapt system prompts based on progress
+
+### Sub-Agent Orchestration
+
+Without context forwarding and `prepareStep`, sub-agents operate in isolation. Cannot:
+
+- Pass parent conversation context to child agents
+- Accumulate findings across multiple delegations
+- Dynamically decide which sub-agents to make available
+- Coordinate sibling agents through shared state
+
+### Tool Context Access
+
+Without forwarding the execute options, tools are blind to ambient state. Cannot:
+
+- Access auth tokens or session info from context
+- Read accumulated state from prior steps
+- Use the `abortSignal` provided by the AI SDK (note: our tools do not receive it, though sub-agent wrappers do)
+
+## Recommended Implementation Order
+
+```
+Phase 1: Foundation (P0)
+├── Wire prepareStep through AgentConfig + AgentOverrides + agent.ts
+├── Wire activeTools through AgentConfig + AgentOverrides + agent.ts
+├── Wire experimental_context through AgentConfig + AgentOverrides + agent.ts
+└── Fix tool() execute to forward AI SDK options (context + abortSignal)
+
+Phase 2: Sub-Agent Enhancement (P1)
+├── Context-aware sub-agent wrapper in buildAITools
+├── Per-delegation maxSteps support
+└── Result accumulation via prepareStep example/utility
+
+Phase 3: Advanced Patterns (P2)
+├── Dynamic agent spawning via prepareStep
+├── Shared state store tool
+└── Message compression/summarization utilities
+```
+
+## Files That Need Changes
+
+| File                      | Changes                                                                           |
+| ------------------------- | --------------------------------------------------------------------------------- |
+| `src/core/agent/types.ts` | Add `prepareStep`, `activeTools`, `context` to `AgentConfig` and `AgentOverrides` |
+| `src/core/agent/agent.ts` | Forward new fields to `generateText`/`streamText` calls                           |
+| `src/core/tool.ts`        | Extend `ToolConfig.execute` signature; forward AI SDK options in wrapper          |
+| `src/core/agent/utils.ts` | Update `buildAITools` sub-agent wrapper to forward context                        |
+| `src/index.ts`            | Export new types                                                                  |

package/docs/research/prepare-step-and-active-tools.md

@@ -0,0 +1,138 @@
+# Research: `prepareStep` and `activeTools` Support
+
+> **Date**: 2026-03-06
+> **AI SDK Version**: `^6.0.111`
+> **Status**: Gap identified — neither `prepareStep` nor `activeTools` are wired through the SDK
+
+## Summary
+
+The Vercel AI SDK v6 provides two key parameters for controlling the agentic tool-calling loop: `prepareStep` (a callback that fires **before** each step) and `activeTools` (restricts which tools are available). Our agent SDK does not expose or forward either of these to `generateText`/`streamText`.
+
+## What the AI SDK v6 Provides
+
+### `prepareStep`
+
+An async callback passed to `generateText`/`streamText` that fires before each step in the tool-calling loop.
+
+**Input (`PrepareStepOptions`):**
+
+| Field                  | Type                  | Description                                                              |
+| ---------------------- | --------------------- | ------------------------------------------------------------------------ |
+| `steps`                | `StepResult<TOOLS>[]` | All previously executed steps with results, tool calls, and usage        |
+| `stepNumber`           | `number`              | Current step index (0-based)                                             |
+| `model`                | `LanguageModel`       | The current model                                                        |
+| `messages`             | `ModelMessage[]`      | Messages about to be sent to the model                                   |
+| `experimental_context` | `unknown`             | User-defined context (see [context research](./experimental-context.md)) |
+
+**Output (`PrepareStepResult<TOOLS>`):**
+
+| Field                  | Type                        | Description                            |
+| ---------------------- | --------------------------- | -------------------------------------- |
+| `model`                | `LanguageModel` (optional)  | Override model for this step           |
+| `messages`             | `ModelMessage[]` (optional) | Override/transform messages            |
+| `activeTools`          | `string[]` (optional)       | Restrict available tools for this step |
+| `toolChoice`           | `ToolChoice` (optional)     | Force a specific tool or `"required"`  |
+| `system`               | `string` (optional)         | Override system prompt                 |
+| `experimental_context` | `unknown` (optional)        | Modify context for subsequent steps    |
+| `providerOptions`      | `Record` (optional)         | Provider-specific settings             |
+
+### `activeTools`
+
+An array of tool name strings that restricts which tools the model can invoke. Available both at the top-level `generateText` call (static restriction) and inside `prepareStep` (dynamic per-step restriction). Does not change the tool call/result types — only limits availability.
+
+## Current SDK State
+
+### `agent.ts` — `generateText` call (lines 237-263)
+
+```typescript
+const aiResult = await generateText({
+  model,
+  system,
+  ...promptParams,
+  tools: aiTools,
+  output,
+  stopWhen: stepCountIs(maxSteps),
+  abortSignal: overrideSignal,
+  onStepFinish: async (step) => {
+    /* observability only */
+  },
+});
+```
+
+No `prepareStep` or `activeTools` parameters are passed.
+
+### `AgentConfig` — missing fields
+
+The `AgentConfig` interface (`types.ts`) defines hooks for `onStart`, `onFinish`, `onError`, and `onStepFinish`. None of these run **before** a step or can modify the next step's configuration.
+
+### `AgentOverrides` — missing fields
+
+The `AgentOverrides` interface has per-call overrides for `model`, `system`, `tools`, `agents`, `maxSteps`, `output`, and hooks. No `prepareStep` or `activeTools`.
+
+## Capabilities Unlocked by Wiring These Through
+
+### Context Window Management
+
+```typescript
+prepareStep: async ({ messages, stepNumber }) => {
+  // Keep only last N messages when context grows too large
+  if (messages.length > 50) {
+    return {
+      messages: [messages[0], ...messages.slice(-20)],
+    };
+  }
+  return {};
+};
+```
+
+### Dynamic Tool Activation
+
+```typescript
+prepareStep: async ({ stepNumber }) => {
+  // Phase 1: research only
+  if (stepNumber < 3) {
+    return { activeTools: ["search", "readFile"] };
+  }
+  // Phase 2: editing
+  return { activeTools: ["editFile", "writeFile"] };
+};
+```
+
+### Model Switching
+
+```typescript
+prepareStep: async ({ steps }) => {
+  const lastStep = steps.at(-1);
+  // Switch to a more capable model if the task is complex
+  if (lastStep?.toolCalls.length > 3) {
+    return { model: openrouter("anthropic/claude-sonnet-4") };
+  }
+  return {};
+};
+```
+
+### System Prompt Adaptation
+
+```typescript
+prepareStep: async ({ steps }) => {
+  const completedTools = steps.flatMap((s) => s.toolCalls.map((tc) => tc.toolName));
+  if (completedTools.includes("analyzeCode")) {
+    return { system: "You have analyzed the code. Now focus on generating the fix." };
+  }
+  return {};
+};
+```
+
+## Implementation Path
+
+1. Add `prepareStep` and `activeTools` fields to `AgentConfig<TInput, TOutput, TTools, TSubAgents>`
+2. Add the same fields to `AgentOverrides<TTools, TSubAgents>`
+3. Forward them to the `generateText`/`streamText` calls in `agent.ts`
+4. For `prepareStep`, merge base config + per-call override (call-level wraps base-level, or provide a composition utility)
+
+## References
+
+- [AI SDK 6 Blog Post](https://vercel.com/blog/ai-sdk-6)
+- [Agents: Loop Control Docs](https://ai-sdk.dev/docs/agents/loop-control)
+- [generateText API Reference](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)
+- [streamText API Reference](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text)