@agent-native/core 0.7.10 → 0.7.12

package/docs/content/progress.md

@@ -0,0 +1,176 @@
+---
+title: "Progress"
+description: "Live progress signal for long-running agent tasks — start, update, complete"
+---
+
+# Progress
+
+Long agent tasks shouldn't hide behind a spinner. `progress_runs` gives the agent a way to announce _"I'm working on this, I'm 45% done, here's the current step"_ — which the UI renders as a floating runs tray with a percent bar.
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+Separate concern from [notifications](/docs/notifications): notifications fire once (_"X happened"_), progress is continuous state (_"X is 45% done"_). The two compose — `completeRun` followed by `notify(..., severity: "info")` tells the user when the work finishes even if they weren't watching the tray.
+
+## The lifecycle {#lifecycle}
+
+| Status      | Transition                  |
+| ----------- | --------------------------- |
+| `running`   | Initial — set by `startRun` |
+| `succeeded` | Happy-path terminal         |
+| `failed`    | Error terminal              |
+| `cancelled` | User interrupted            |
+
+Terminal statuses set `completed_at`. The UI tray shows only `running` rows; completed rows stay in the database for `list-runs` queries.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+Create a run. Returns the full `AgentRun` with a generated id.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+Emits `run.progress.started` on the event bus.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+Patch any field of a running run. Any omitted field stays unchanged.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+Emits `run.progress.updated` on the event bus. Returns the updated `AgentRun`, or `null` if the run doesn't exist or isn't owned by the caller.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+Transition to a terminal status. `succeeded` implicitly sets `percent=100`.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+Also emits `run.progress.updated` with the terminal status.
+
+### Listing {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+Mounted at `/_agent-native/runs/*` by the core-routes plugin. **Read-only over HTTP** — writes go through the agent tools since the agent is the canonical writer. All routes are owner-scoped.
+
+| Method   | Path                              |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+## UI component {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+Inline header widget — mount it next to the notifications bell. Shows a spinner icon + count badge when runs are active; click opens a dropdown with one live percent bar per run. Hides the trigger entirely when no active runs. Polls `/_agent-native/runs?active=true` every `pollMs` (default 3 s). Uses shadcn semantic tokens, adapts to light and dark themes.
+
+## Agent tools {#agent-tools}
+
+Four native tools are registered in every template:
+
+| Tool                  | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `start-run`           | Call at the top of a long task. Returns a runId.                |
+| `update-run-progress` | Call periodically during the task with `percent` and/or `step`. |
+| `complete-run`        | Terminal — one of `succeeded`, `failed`, `cancelled`.           |
+| `list-runs`           | Inspect recent runs (filter by `active=true`).                  |
+
+### When to start a run {#when-to-start}
+
+- Use for anything > ~5 seconds. A spinner with no context feels frozen.
+- Update at natural checkpoints, not every iteration. Every 5–10% is plenty.
+- **Always** call `complete-run`, including in error paths. An orphan `running` row is worse than no row.
+- Pair with `notify` on completion so the user sees the outcome when they're not actively watching the tray.
+
+## Event bus {#event-bus}
+
+Two events emit on the [event bus](/docs/automations#event-bus):
+
+| Event                  | Payload                            |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) can subscribe to these — for example, _"if a run takes longer than 5 minutes, notify me"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is running and (now - started) > 5 minutes"
+mode: agentic
+---
+Notify me that run {{runId}} has been running for a long time.
+```
+
+## How it works {#internals}
+
+- **Owner scoping** — every row has an `owner` column; every query filters on it. Users see only their own runs.
+- **Poll integration** — every mutation calls `recordChange()` so templates using [`useDbSync`](/docs/client) auto-invalidate without any extra wiring.
+- **Table name** — the framework also has an `agent_runs` table for internal agent-chat turn lifecycle tracking. The progress primitive uses `progress_runs` to keep the two concerns separate.
+- **Percent clamping** — values are clamped to `[0, 100]` and rounded to an integer on write.
+
+## What's next
+
+- [**Notifications**](/docs/notifications) — pair with `complete-run` to tell the user when work finishes
+- [**Automations**](/docs/automations) — watchdog slow runs via `run.progress.updated`
+- [**Client**](/docs/client) — `useDbSync` for real-time cache invalidation

package/docs/content/tracking.md

@@ -0,0 +1,168 @@
+---
+title: "Analytics Tracking"
+description: "Server-side analytics with pluggable providers — PostHog, Mixpanel, Amplitude, or custom webhook"
+---
+
+# Analytics Tracking
+
+One function, multiple destinations. Call `track()` from any server-side code — actions, plugins, server routes — and the event fans out to every registered analytics provider. No SDK dependencies, no client-side scripts, no blocking.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "order.completed",
+  { total: 49.99, items: 3 },
+  { userId: "steve@builder.io" },
+);
+```
+
+## Built-in providers {#built-in}
+
+Set an env var and the provider auto-registers at server startup. No code changes required.
+
+| Provider  | Env vars                                                                                        |
+| --------- | ----------------------------------------------------------------------------------------------- |
+| PostHog   | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`) |
+| Mixpanel  | `MIXPANEL_TOKEN`                                                                                |
+| Amplitude | `AMPLITUDE_API_KEY`                                                                             |
+| Webhook   | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional `Authorization` header)    |
+
+Multiple providers can be active simultaneously. Every event goes to all of them.
+
+## API {#api}
+
+### `track(name, properties?, meta?)` {#track}
+
+Fire an analytics event. Fans out to all registered providers.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track(
+  "meal.logged",
+  { mealName: "Salad", calories: 350 },
+  { userId: "steve@builder.io" },
+);
+```
+
+### `identify(userId, traits?)` {#identify}
+
+Identify a user with traits. Forwarded to providers that support it (PostHog, Mixpanel, Amplitude, webhook).
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("steve@builder.io", { plan: "pro", company: "Builder.io" });
+```
+
+### `registerTrackingProvider(provider)` {#register}
+
+Register a custom provider for any analytics backend.
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+    fetch("https://analytics.example.com/events", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(event),
+    }).catch(() => {});
+  },
+  identify(userId, traits) {
+    // Optional — link user identity to future events
+  },
+  flush() {
+    // Optional — called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()` {#flush}
+
+Flush all providers. Call before process exit to ensure pending events are sent.
+
+```ts
+import { flushTracking } from "@agent-native/core/tracking";
+
+await flushTracking();
+```
+
+### `unregisterTrackingProvider(name)` {#unregister}
+
+Remove a provider by name. Returns `true` if the provider was found and removed.
+
+### `listTrackingProviders()` {#list}
+
+Returns the names of all registered providers.
+
+## The TrackingProvider interface {#provider-interface}
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(
+    userId: string,
+    traits?: Record<string, unknown>,
+  ): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+Only `name` and `track` are required. `identify` and `flush` are optional — implement them if your backend supports user identity and batched delivery.
+
+## How it works {#internals}
+
+- **Batched HTTP** — built-in providers enqueue events and flush every 10 seconds or when 50 events accumulate, whichever comes first. This minimizes outbound requests without losing data.
+- **No SDK dependencies** — all built-in providers use raw `fetch()`. No PostHog SDK, no Mixpanel SDK, no Amplitude SDK. Keeps the framework lightweight.
+- **Best-effort delivery** — provider errors are caught and logged. A failing analytics integration never crashes the caller or blocks request handling.
+- **Global singleton** — the registry uses a `Symbol.for` key on `globalThis` so multiple ESM graph instances (dev-mode Vite + Nitro, symlinks) share one provider set.
+
+## Using track() in templates {#templates}
+
+Call `track()` from action handlers to record user or agent activity:
+
+```ts
+// actions/create-project.ts
+import { defineAction } from "@agent-native/core";
+import { track } from "@agent-native/core/tracking";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Create a new project.",
+  schema: z.object({
+    name: z.string(),
+    template: z.string().optional(),
+  }),
+  run: async ({ name, template }, ctx) => {
+    const project = await db
+      .insert(projects)
+      .values({ name, template })
+      .returning();
+
+    track("project.created", { name, template }, { userId: ctx.userEmail });
+
+    return { ok: true, projectId: project[0].id };
+  },
+});
+```
+
+Track calls are fire-and-forget — they return immediately and never block the action response.
+
+## What's next
+
+- [**Actions**](/docs/actions) — where most tracking calls originate
+- [**Server Plugins**](/docs/server) — `registerBuiltinProviders()` runs in the core-routes plugin at startup
+- [**Secrets**](/docs/security) — manage API keys for tracking providers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -9,6 +9,10 @@
     "url": "https://github.com/BuilderIO/agent-native",
     "directory": "packages/core"
   },
+  "bugs": {
+    "url": "https://github.com/BuilderIO/agent-native/issues"
+  },
+  "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bin": {
     "agent-native": "dist/cli/index.js"
   },
@@ -24,6 +28,7 @@
     "./server/request-context": "./dist/server/request-context.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",
+    "./db/drizzle-config": "./dist/db/drizzle-config.js",
     "./client": "./dist/client/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
     "./onboarding": "./dist/onboarding/index.js",
@@ -32,6 +37,8 @@
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
     "./credentials": "./dist/credentials/index.js",
+    "./event-bus": "./dist/event-bus/index.js",
+    "./fetch-tool": "./dist/tools/fetch-tool.js",
     "./file-upload": "./dist/file-upload/index.js",
     "./resources": "./dist/resources/index.js",
     "./resources/store": "./dist/resources/store.js",
@@ -52,10 +59,17 @@
     "./a2a": "./dist/a2a/index.js",
     "./mcp": "./dist/mcp/index.js",
     "./mcp-client": "./dist/mcp-client/index.js",
+    "./tracking": "./dist/tracking/index.js",
+    "./notifications": "./dist/notifications/index.js",
+    "./client/notifications": "./dist/client/notifications/index.js",
+    "./progress": "./dist/progress/index.js",
+    "./client/progress": "./dist/client/progress/index.js",
+    "./triggers": "./dist/triggers/index.js",
     "./terminal": "./dist/client/terminal/index.js",
     "./terminal/server": "./dist/terminal/index.js",
     "./tailwind": "./dist/tailwind.preset.js",
     "./styles/agent-native.css": "./dist/styles/agent-native.css",
+    "./agent/engine": "./dist/agent/engine/index.js",
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
   "files": [
@@ -65,7 +79,7 @@
     "src/templates"
   ],
   "scripts": {
-    "build": "tsc && rm -rf dist/templates && cp -r src/templates dist/templates && mkdir -p dist/styles && cp src/styles/*.css dist/styles/",
+    "build": "tsc && node scripts/finalize-build.mjs",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run",
@@ -74,7 +88,8 @@
     "release": "npm version patch && npm publish --access public"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.80.0",
+    "@anthropic-ai/sdk": "^0.90.0",
+    "@sentry/node": "^10.50.0",
     "@clack/prompts": "^1.2.0",
     "@libsql/client": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -104,45 +119,47 @@
     "isbot": "^5",
     "jose": "^6.2.2",
     "minimatch": "^10.0.0",
-    "nanoid": "^4.0.2",
-    "nitro": "3.0.260311-beta",
+    "nanoid": "^5.1.9",
+    "nitro": "3.0.260415-beta",
     "p-limit": "^7.3.0",
     "react-markdown": "^10.1.0",
     "react-router": "^7.13.1",
     "remark-gfm": "^4.0.1",
     "shiki": "^4.0.2",
-    "tailwind-merge": "^2.6.0",
+    "tailwind-merge": "^3.5.0",
     "tiptap-markdown": "^0.9.0",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30",
-    "zod": "^3.24.0"
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@ai-sdk/anthropic": ">=1",
-    "@ai-sdk/cohere": ">=1",
-    "@ai-sdk/google": ">=1",
-    "@ai-sdk/groq": ">=1",
-    "@ai-sdk/mistral": ">=1",
-    "@ai-sdk/openai": ">=1",
+    "@ai-sdk/anthropic": ">=3",
+    "@ai-sdk/cohere": ">=3",
+    "@ai-sdk/google": ">=3",
+    "@ai-sdk/groq": ">=3",
+    "@ai-sdk/mistral": ">=3",
+    "@ai-sdk/openai": ">=3",
     "@assistant-ui/react": ">=0.12",
     "@assistant-ui/react-markdown": ">=0.12",
+    "@openrouter/ai-sdk-provider": ">=2",
     "@supabase/supabase-js": ">=2",
     "@tabler/icons-react": ">=3",
+    "@tailwindcss/vite": ">=4",
     "@tanstack/react-query": ">=5",
     "@vitejs/plugin-react-swc": ">=4",
-    "@xterm/addon-fit": ">=0.10",
-    "@xterm/addon-web-links": ">=0.11",
-    "@xterm/xterm": ">=5",
-    "ai": ">=4",
+    "@xterm/addon-fit": ">=0.11",
+    "@xterm/addon-web-links": ">=0.12",
+    "@xterm/xterm": ">=6",
+    "ai": ">=6",
+    "ai-sdk-ollama": ">=3",
     "convex": ">=1",
+    "drizzle-kit": ">=0.31",
     "node-pty": ">=1",
-    "ollama-ai-provider": ">=1",
     "postgres": ">=3",
     "react": ">=18",
     "react-dom": ">=18",
     "react-router": ">=7",
     "tailwindcss": ">=4",
-    "@tailwindcss/vite": ">=4",
     "typescript": ">=5",
     "vite": ">=5",
     "ws": ">=8"
@@ -157,6 +174,9 @@
     "@ai-sdk/openai": {
       "optional": true
     },
+    "@openrouter/ai-sdk-provider": {
+      "optional": true
+    },
     "@ai-sdk/google": {
       "optional": true
     },
@@ -169,7 +189,7 @@
     "@ai-sdk/cohere": {
       "optional": true
     },
-    "ollama-ai-provider": {
+    "ai-sdk-ollama": {
       "optional": true
     },
     "@tabler/icons-react": {
@@ -199,6 +219,9 @@
     "convex": {
       "optional": true
     },
+    "drizzle-kit": {
+      "optional": true
+    },
     "@xterm/xterm": {
       "optional": true
     },
@@ -219,39 +242,40 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^1.2.12",
-    "@ai-sdk/google": "^1.2.22",
-    "@ai-sdk/groq": "^1.2.9",
-    "@ai-sdk/openai": "^1.3.24",
+    "@ai-sdk/anthropic": "^3.0.71",
+    "@ai-sdk/google": "^3.0.64",
+    "@ai-sdk/groq": "^3.0.35",
+    "@ai-sdk/openai": "^3.0.53",
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
     "@react-router/dev": "^7.13.1",
     "@react-router/fs-routes": "^7.13.1",
     "@supabase/supabase-js": "^2.49.0",
     "@tabler/icons-react": "^3.40.0",
-    "@tanstack/react-query": "^5.84.2",
+    "@tailwindcss/vite": "catalog:",
+    "@tanstack/react-query": "^5.99.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/diff-match-patch": "^1.0.36",
     "@types/express": "^5.0.6",
     "@types/node": "^24.2.1",
-    "@types/react": "^18.3.23",
+    "@types/react": "^19.2.14",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react-swc": "^4.0.0",
-    "@xterm/addon-fit": "^0.10.0",
-    "@xterm/addon-web-links": "^0.11.0",
-    "@xterm/xterm": "^5.5.0",
-    "ai": "^4.3.19",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/xterm": "^6.0.0",
+    "ai": "^6.0.168",
     "autoprefixer": "^10.4.21",
+    "drizzle-kit": "^0.31.10",
     "express": "^5.2.1",
     "firebase-admin": "^13.0.0",
     "node-pty": "^1.1.0",
-    "react": "^18.3.1",
+    "react": "^19.2.5",
     "react-router": "^7.13.1",
     "tailwindcss": "catalog:",
-    "@tailwindcss/vite": "catalog:",
-    "typescript": "^5.9.2",
-    "vite": "^8.0.0",
-    "vitest": "^3.2.4",
+    "typescript": "^6.0.3",
+    "vite": "catalog:",
+    "vitest": "^4.1.5",
     "ws": "^8.18.0"
   }
 }

package/src/templates/default/.agents/skills/agent-engines/SKILL.md

@@ -59,6 +59,7 @@ Returns `{ ok, latencyMs, response, capabilities }`. If `ok: false`, the error m
 | `anthropic` | Anthropic Claude SDK | `ANTHROPIC_API_KEY` |
 | `ai-sdk:anthropic` | Claude via Vercel AI SDK | `ANTHROPIC_API_KEY` |
 | `ai-sdk:openai` | OpenAI via Vercel AI SDK | `OPENAI_API_KEY` |
+| `ai-sdk:openrouter` | 300+ models (Anthropic, OpenAI, Google, Meta, …) routed through OpenRouter | `OPENROUTER_API_KEY` |
 | `ai-sdk:google` | Google Gemini via Vercel AI SDK | `GOOGLE_GENERATIVE_AI_API_KEY` |
 | `ai-sdk:groq` | Groq LPU via Vercel AI SDK | `GROQ_API_KEY` |
 | `ai-sdk:mistral` | Mistral via Vercel AI SDK | `MISTRAL_API_KEY` |
@@ -86,13 +87,41 @@ When using the `anthropic` engine (or `ai-sdk:anthropic`):
 
 These features are silently ignored when a non-Anthropic engine is active (capability-gated, no breakage).
 
+## Using OpenRouter
+
+`ai-sdk:openrouter` gives access to 300+ models from many providers through a single API. Model IDs use the `vendor/model` form:
+
+```
+set-agent-engine --engine "ai-sdk:openrouter" --model "anthropic/claude-sonnet-4.5"
+set-agent-engine --engine "ai-sdk:openrouter" --model "openai/gpt-4o"
+set-agent-engine --engine "ai-sdk:openrouter" --model "google/gemini-2.5-pro"
+```
+
+Any `vendor/model` string from [openrouter.ai/models](https://openrouter.ai/models) works — the `supportedModels` list in the registry is a UI hint, not an allow-list.
+
+**App attribution** (optional): pass `appName` / `appUrl` in the engine config to set the `X-OpenRouter-Title` / `HTTP-Referer` headers — useful to see your app on the OpenRouter dashboard and leaderboards:
+
+```ts
+createAISDKEngine("openrouter", {
+  apiKey: process.env.OPENROUTER_API_KEY,
+  appName: "My App",
+  appUrl: "https://myapp.example",
+});
+```
+
 ## Registering a Custom Engine
 
-Register custom engines in a server plugin at startup:
+Register custom engines in a server plugin at startup. Import from the
+`@agent-native/core/agent/engine` subpath:
 
 ```ts
 // server/plugins/my-engine.ts
-import { registerAgentEngine } from "@agent-native/core/server";
+import {
+  registerAgentEngine,
+  type AgentEngine,
+  type EngineEvent,
+  type EngineStreamOptions,
+} from "@agent-native/core/agent/engine";
 
 registerAgentEngine({
   name: "my-engine",
@@ -108,11 +137,37 @@ registerAgentEngine({
   defaultModel: "my-model-v1",
   supportedModels: ["my-model-v1", "my-model-v2"],
   requiredEnvVars: ["MY_ENGINE_API_KEY"],
-  create: (config) => new MyEngine(config),
+  create: (config): AgentEngine => ({
+    name: "my-engine",
+    label: "My Custom Engine",
+    defaultModel: "my-model-v1",
+    supportedModels: ["my-model-v1", "my-model-v2"],
+    capabilities: {
+      /* same shape as above */
+    } as any,
+    async *stream(opts: EngineStreamOptions): AsyncIterable<EngineEvent> {
+      // yield text-delta / thinking-delta / tool-call / usage events
+      // as they arrive, then:
+      yield { type: "assistant-content", parts: /* final content parts */ [] };
+      yield { type: "stop", reason: "end_turn" };
+    },
+  }),
 });
 ```
 
-After registering, the engine appears in `list-agent-engines` output and can be selected via `set-agent-engine`.
+### Engine stream contract
+
+Every engine's `stream(opts)` MUST emit, in order:
+
+1. Zero or more `text-delta`, `thinking-delta`, `tool-call`, and `usage`
+   events as they arrive from the model.
+2. Exactly one `{ type: "assistant-content", parts }` event with the
+   structured content for the turn. `runAgentLoop` reads this to
+   reconstruct the assistant message for the next turn.
+3. Exactly one terminal `{ type: "stop", reason }` event.
+
+After registering, the engine appears in `list-agent-engines` output and can
+be selected via `set-agent-engine`.
 
 ## Env Vars Reference
 
@@ -120,6 +175,7 @@ After registering, the engine appears in `list-agent-engines` output and can be
 |---|---|
 | `ANTHROPIC_API_KEY` | Required for `anthropic` and `ai-sdk:anthropic` engines |
 | `OPENAI_API_KEY` | Required for `ai-sdk:openai` |
+| `OPENROUTER_API_KEY` | Required for `ai-sdk:openrouter` |
 | `GOOGLE_GENERATIVE_AI_API_KEY` | Required for `ai-sdk:google` |
 | `GROQ_API_KEY` | Required for `ai-sdk:groq` |
 | `MISTRAL_API_KEY` | Required for `ai-sdk:mistral` |