eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/schedules.mdx

@@ -0,0 +1,104 @@
+---
+title: "Schedules"
+description: "Run an agent on a cron cadence: a fire-and-forget prompt, or a handler that hands work off to a channel."
+---
+
+A schedule is how the agent starts work on its own clock instead of waiting for an inbound message. Daily digests, data syncs, cleanup sweeps, heartbeats: anything that should fire on a cadence. Each one is a single file under `agent/schedules/` carrying a cron expression. Schedules are root-only, so declared subagents cannot have a `schedules/` directory.
+
+The name comes from the path under `schedules/` (`agent/schedules/billing/sweep.ts` → `"billing/sweep"`), and nested directories are fine.
+
+## `defineSchedule`
+
+Every schedule provides a `cron` and exactly one of `markdown` or `run`:
+
+```ts
+interface ScheduleDefinition {
+  cron: string;
+  markdown?: string; // fire-and-forget prompt (task mode)
+  run?: (args: ScheduleHandlerArgs) => Promise<void> | void; // handler
+}
+
+interface ScheduleHandlerArgs {
+  receive: CrossChannelReceiveFn; // hand the work off to a channel
+  waitUntil: (task: Promise<unknown>) => void; // keep the cron task alive past return
+  appAuth: SessionAuthContext; // pre-built app principal
+}
+```
+
+`defineSchedule` is just a pass-through for types. The compiler is what enforces the one-of rule.
+
+## Markdown form (fire-and-forget)
+
+This is the minimal schedule. Eve runs the agent on the prompt and throws away the output, though the agent can still call tools, write to backends, and log along the way. We call this task mode. A task-mode session runs to completion or fails; it cannot park to wait for a person or an OAuth sign-in.
+
+```ts title="agent/schedules/heartbeat.ts"
+import { defineSchedule } from "eve/schedules";
+
+export default defineSchedule({
+  cron: "*/5 * * * *",
+  markdown: "Pull open Linear issues and POST a summary to the metrics endpoint.",
+});
+```
+
+You can write the same thing as a plain `.md` file: its frontmatter takes `cron` and nothing else, and the body is the prompt.
+
+`agent/schedules/cleanup.md`:
+
+```md
+---
+cron: "0 0 * * 0"
+---
+
+Sweep stale workflow state.
+```
+
+## Handler form (`run`)
+
+Reach for a handler when the schedule needs to deliver to a channel, branch on conditions, or compute its arguments at fire time. The handler is in full control. It has no channel of its own, so it passes the work to one with `receive`.
+
+```ts title="agent/schedules/daily-digest.ts"
+import { defineSchedule } from "eve/schedules";
+
+import slack from "../channels/slack.js";
+
+export default defineSchedule({
+  cron: "0 9 * * 1-5",
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(slack, {
+        message: "Summarize yesterday's activity and post the digest.",
+        target: { channelId: "C0123ABC" },
+        auth: appAuth,
+      }),
+    );
+  },
+});
+```
+
+- `receive(channel, { message, target, auth })`: starts a session on another channel. Same contract as a route handler’s `args.receive`.
+- `waitUntil(promise)`: extends the cron task’s lifetime so the parked session and any in-flight fetches settle before the task ends. Wrap the `receive` call in it.
+- `appAuth`: the app principal (`{ authenticator: "app", principalId: "eve:app", principalType: "runtime" }`). Pass it as `receive(..., { auth: appAuth })` for work the agent does on its own behalf.
+
+A handler-form session runs on the same durable runtime engine as any other session, so it can park, for instance when the channel handoff is waiting for a Slack reply. Only markdown task mode is barred from waiting.
+
+## Trigger a schedule while iterating
+
+In production the cron cadence is the only thing that fires a schedule, but waiting for the next tick gets old fast while iterating in `eve dev`. So the dev server mounts a one-shot dispatch route: fire a schedule by name, out of band, exactly once.
+
+```sh
+curl -X POST http://localhost:3000/eve/v1/dev/schedules/heartbeat
+# -> { "scheduleId": "heartbeat", "sessionIds": ["..."] }
+```
+
+`:scheduleId` is the path-derived schedule name (`agent/schedules/heartbeat.ts` → `heartbeat`; URL-encode the `/` in nested names). It runs the exact dispatch path the production cron handler uses and returns the started session ids as JSON, so you can subscribe to each one’s [stream](./advanced/sessions-runs-and-streaming) at `GET /eve/v1/session/:sessionId/stream`. An unknown id comes back `404` with `availableScheduleIds`, listing the schedules the app actually defines.
+
+The route is dev-only. Production builds never mount it, and it needs no auth since the dev server is local-only.
+
+## On Vercel
+
+Hosted Vercel builds turn every `defineSchedule(...)` into a Vercel Cron Job, with each `cron` written as an entry in `.vercel/output/config.json`. Confirm discovery under Settings → Cron Jobs and watch execution history under Observability → Cron Jobs. Per-run logs land under Observability → Logs.
+
+## What to read next
+
+- Deliver schedule output to users → [Channels](./channels/overview)
+- Inspect a schedule run → [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming)

package/dist/docs/public/skills.mdx

@@ -0,0 +1,79 @@
+---
+title: "Skills"
+description: "Author load-on-demand procedures the model pulls into context with load_skill."
+---
+
+A skill is a model-loadable procedure that follows the `SKILL.md` convention: a markdown document (optionally a packaged directory with supporting files) that the model pulls into context on demand rather than carrying on every turn. Eve advertises each skill's description, and the model loads the full body only when a turn calls for it, the progressive-disclosure model the broader Agent Skills standard uses. A skill authored against that standard ports over as-is.
+
+## How loading works
+
+Eve scans the files under `agent/skills/` and exposes each one's description to the model alongside a framework-owned `load_skill` tool. When a request matches a skill's description (or you name the skill outright), the model calls `load_skill`, and Eve appends that skill's markdown to the active turn's context.
+
+The description is a routing hint, not a label. Write it as the task that should trigger activation:
+
+```md
+Use when the user needs a release checklist or changelog workflow.
+```
+
+Loading a skill adds instructions, never a new execution surface. Tools stay visible whether a skill is loaded or not. If you need typed runtime behavior, reach for a [tool](./tools) instead.
+
+## Markdown vs `defineSkill`
+
+The smallest skill is a flat markdown file. The content is the procedure, and the name comes from the path.
+
+```md title="agent/skills/forecast.md"
+Use the weather tool before answering forecast or temperature questions.
+```
+
+A packaged skill is a directory: a `SKILL.md` plus sibling files like `references/`, `assets/`, and `scripts/`. The packaged `SKILL.md` must carry `description` frontmatter. Flat markdown skills may skip it.
+
+`agent/skills/research/SKILL.md`:
+
+```md
+---
+description: Research unfamiliar topics before answering with confidence.
+---
+
+When the task is novel or ambiguous, gather evidence first, then answer with the
+key facts and the remaining uncertainty.
+```
+
+When markdown can't express what you need (typed values, generated content, or inline sibling files), author the skill in TypeScript with `defineSkill` from `eve/skills`:
+
+```ts title="agent/skills/research.ts"
+import { defineSkill } from "eve/skills";
+
+export default defineSkill({
+  description: "Research unfamiliar topics before answering with confidence.",
+  markdown:
+    "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",
+  files: {
+    "references/checklist.md": "# Checklist\n\n- Find primary sources.\n",
+  },
+});
+```
+
+Eve generates `SKILL.md` from `markdown`, and each `files` entry becomes a package-relative sibling. Start with plain markdown and move to `defineSkill` only when you hit its limits.
+
+Skills are scoped to the agent that declares them. A [subagent](./subagents)'s `skills/` are invisible to the root agent, and the reverse holds too. There's no shared-skill mechanism, so when you want to share executable helpers, put them in `lib/`.
+
+## Read skill files at runtime
+
+Loading a skill adds its `SKILL.md` to context. To reach a packaged skill's sibling files (references, assets, scripts) from inside a tool or hook, use `ctx.getSkill(id)`:
+
+```ts
+const research = ctx.getSkill("research");
+const checklist = await research.file("references/checklist.md").text();
+```
+
+The handle exposes the skill's `name` and `file(relativePath)`; file content is read lazily from the active sandbox.
+
+## Dynamic skills
+
+Want a different skill per principal, tenant, or channel, like the caller's own team playbook? Wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./advanced/dynamic-capabilities).
+
+## What to read next
+
+- [Connections](./connections): add tools from external MCP and OpenAPI servers
+- [Dynamic capabilities](./advanced/dynamic-capabilities): resolve skills per caller with `defineDynamic`
+- [Context control](./advanced/context-control): how skills fit the full context model

package/dist/docs/public/subagents.mdx

@@ -0,0 +1,76 @@
+---
+title: "Subagents"
+description: "Delegate work to child agents: a copy of the agent itself, or declared specialists with their own sandbox and skills."
+---
+
+A subagent is a child agent that one agent delegates a focused subtask to. Split work out into one when you want it to run in parallel, when the child should see a narrower set of tools, or when a specialist needs its own identity. There are two kinds.
+
+## The built-in `agent` tool
+
+Every agent gets an `agent` tool by default. The model calls it to delegate a subtask to a copy of itself:
+
+```ts
+{
+  message: string;       // everything the child needs; it does not see the parent's history
+  outputSchema?: object; // when set, the child runs in task mode and returns structured output
+}
+```
+
+The copy shares the parent's sandbox and tools. A child's file writes are immediately visible to the parent, which is what makes parallel calls natural: fan out a few copies to fix different files at once. The copy inherits auth and connections, but starts with fresh conversation history and fresh state. If a declared subagent calls `agent`, the child is a copy of _that_ subagent, not the root.
+
+An authored tool at `agent/tools/agent.ts` takes priority over the built-in.
+
+## Declared subagents
+
+A declared subagent lives under `agent/subagents/<id>/` and uses the same `defineAgent` helper as the root. Its location under `subagents/` is the only thing that marks it as a subagent. Declare one when the child needs a clearly different prompt, role, or tool surface.
+
+```ts title="agent/subagents/researcher/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  description: "Investigate ambiguous questions before the parent agent responds.",
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+`description` is required. The parent reads it to decide whether to delegate, so the compiler rejects any subagent whose `agent.ts` leaves it out.
+
+Minimum files:
+
+```text
+agent/subagents/researcher/
+├── agent.ts            # required (must export a description)
+├── instructions.md     # or instructions.ts, optional
+├── tools/              # optional, its own tools
+├── skills/             # optional, its own skills
+├── sandbox/            # optional, its own sandbox + workspace seed
+└── subagents/          # optional, nested subagents
+```
+
+`schedules/` is not supported inside a declared subagent: schedules are root-only.
+
+## The isolation boundary
+
+A declared subagent gets its own independent sandbox and its own `skills/` set. Neither crosses the parent boundary:
+
+- The child sees only skills authored under `agent/subagents/<id>/skills/`. Root `agent/skills/` stay out of reach during its turns. When two subagents need the same procedure, duplicate the markdown under each, or share typed helpers via `lib/`.
+- The child's sandbox does not inherit from the parent. It falls back to the framework default unless it authors `subagents/<id>/sandbox.ts`, or seeds files via `subagents/<id>/sandbox/workspace/`.
+
+The built-in `agent` tool is the exception: its children share the parent's sandbox and tools because they are copies of the same agent working on the same files.
+
+`defineState` is never shared, for either kind: each child starts with fresh durable state.
+
+## What the parent sees
+
+Eve lowers every subagent (built-in copy, declared, or [remote](./advanced/remote-agents)) into a model-visible tool with the same `{ message, outputSchema? }` shape. The parent packs `message` with everything the child needs, since the child never sees the parent's history. Set `outputSchema` and the child runs in task mode, returning structured output as the tool result.
+
+Each delegated subagent spins up its own child session and stream. The parent stream carries only the control-plane events `subagent.called` and `subagent.completed`. To follow the child's full progress, read `subagent.called.data.childSessionId` and subscribe at `GET /eve/v1/session/:childSessionId/stream`.
+
+## When to split
+
+Split out a subagent when the task needs a different prompt or specialist role, a narrower tool surface, or its own runtime context. Don't reach for one when a [skill](./skills) would do: if the agent can keep its identity and just needs an optional procedure, a skill is the lighter choice.
+
+## What to read next
+
+- Call another Eve deployment as a subagent → [Remote agents](./advanced/remote-agents)
+- Have the model orchestrate its subagents programmatically (fan-out, map-reduce) → [Dynamic workflows](./advanced/dynamic-workflows)

package/dist/docs/public/tools.mdx

@@ -0,0 +1,111 @@
+---
+title: "Tools"
+description: "Define typed actions the agent can call, and gate sensitive ones on human approval."
+---
+
+A tool is a typed action the agent can call: hit an API, run a query, write a file. The action stays in code you control. Tools run in your app runtime (full `process.env`), not the [sandbox](./sandbox).
+
+## Define a tool
+
+The filename is the tool name the model sees. A file at `agent/tools/get_weather.ts` is exposed as `get_weather`.
+
+```ts title="agent/tools/get_weather.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Get the current weather for a city.",
+  inputSchema: z.object({ city: z.string().min(1) }),
+  async execute({ city }, ctx) {
+    return { city, condition: "Sunny", temperatureF: 72 };
+  },
+});
+```
+
+A tool definition needs:
+
+- a filename slug under `agent/tools/`, the model-facing name.
+- a `description`: what the tool does, written for the model.
+- an `inputSchema`: a Zod schema (or any Standard Schema, or a plain JSON Schema object). Required. For no input, pass `z.object({})`. Zod and Standard Schema infer the `input` type in `execute`. Plain JSON Schema types it as `Record<string, unknown>`.
+- an `execute(input, ctx)`: the implementation. May be sync or async.
+
+When a tool returns structured data, add an optional `outputSchema`. With Zod or Standard Schema it also types the `execute` return.
+
+### The `ctx` parameter
+
+`execute` gets a `ctx` carrying the runtime accessors you'll reach for:
+
+- `ctx.session`: session metadata, turn, auth, parent lineage.
+- `ctx.getSandbox()`: the live [sandbox](./sandbox) handle.
+- `ctx.getSkill(id)`: read a packaged [skill](./skills)'s metadata and files.
+
+Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in Eve’s durable pause/resume model.
+
+Eve never runs authored tools during discovery: the model sees descriptors first, and only what it actually calls gets executed. Re-executing a step from the same input is idempotent, so tool side effects are not duplicated when a turn resumes after a crash.
+
+## Human-in-the-loop
+
+HITL is not a separate system. It is just a tool that pauses for a person before (or instead of) running. Gate one on approval with `needsApproval` and the helpers from `eve/tools/approval`:
+
+```ts
+import { defineTool } from "eve/tools";
+import { always } from "eve/tools/approval";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Refund a charge.",
+  inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
+  needsApproval: always(), // or once() / never() / a predicate
+  async execute(input) {
+    return refund(input);
+  },
+});
+```
+
+| Helper     | Behavior                                                                           |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `never()`  | Never require approval (the default when omitted).                                 |
+| `once()`   | Require approval only the first time the tool runs in a session; auto-allow after. |
+| `always()` | Require approval before every call.                                                |
+
+When the decision depends on the input, pass your own predicate instead of a helper. It receives `{ toolName, toolInput, approvedTools }` and returns a boolean. To require approval only when an amount crosses a threshold:
+
+```ts
+needsApproval: ({ toolInput }) => toolInput.amount > 1000,
+```
+
+### The pause and resume
+
+Approvals and questions share one protocol:
+
+1. The model requests input (an approval or an `ask_question`).
+2. Eve emits an `input.requested` stream event carrying the pending requests.
+3. The turn parks at `session.waiting`, durably, for as long as it takes.
+4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option label (case-insensitive) resolves automatically.
+
+The run picks back up exactly where it parked, and channels render the request for you. The Slack adapter, for example, turns approvals into buttons and questions into select menus.
+
+See [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming) for the event and resume contract.
+
+## Shape what the model sees with `toModelOutput`
+
+By default the model sees the full `execute` return. When a tool returns rich data a channel needs for rendering but the model only needs the gist, project it down with `toModelOutput`:
+
+```ts
+toModelOutput(output) {
+  return { type: "text", value: `Report for ${output.domain}: score ${output.score}.` };
+},
+```
+
+It receives the full, typed `execute` return and only affects the model. Channel event handlers and hooks still get the full output on `action.result`, so a channel can render rich platform output (Slack Block Kit, say) the model never sees. Return `{ type: "text", value }` for a summary, or `{ type: "json", value }` for a smaller object.
+
+## Survive compaction with `onCompact`
+
+When the harness [compacts history](./advanced/default-harness#compaction), it calls each tool's `onCompact(input, ctx)` in registration order and applies the merged result to the compacted session. Return nothing to leave things alone, `messages` to append to the compacted history, or a `sessionPatch` to shallow-merge into session state. It works on the projected output (what the model sees), and a throw fails the compaction step, so don't swallow errors.
+
+## What to read next
+
+- [Skills](./skills): on-demand procedures the model loads when relevant
+- [Default harness](./advanced/default-harness): the built-in tools and how to override or disable them
+- [Dynamic capabilities](./advanced/dynamic-capabilities): tools whose set is resolved per session with `defineDynamic`
+- [Auth & route protection](./advanced/auth-and-route-protection): authenticate a tool to an external service

package/dist/docs/public/tutorial/connect-a-warehouse.mdx

@@ -0,0 +1,47 @@
+---
+title: "Step 4: Connect a warehouse"
+description: "Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
+---
+
+The sample dataset got you running, but it's a stand-in. The next step is to point the agent at a real warehouse and let each user connect their own by signing in through their browser. That's what a connection is for: an MCP server the model reaches through tools, with auth that Eve drives for you.
+
+The filename sets the runtime name. Put the file at `agent/connections/warehouse.ts` and it registers as `"warehouse"`, with its tools surfaced as `connection__warehouse__<tool>`.
+
+## Declare the connection
+
+The warehouse exposes a generic SQL MCP behind OAuth. Pass `connect()` from `@vercel/connect/eve` as the auth, and Vercel Connect handles the OAuth flow, stores the tokens, and refreshes them for you:
+
+```ts title="agent/connections/warehouse.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.your-warehouse.example/sse",
+  description: "The team's data warehouse: run read-only SQL and list tables and columns.",
+  auth: connect("warehouse"),
+});
+```
+
+`"warehouse"` is the UID you chose when registering the Connect client. By default this OAuth is user-scoped. Each end-user authorizes in their own browser, and Eve resolves that user's token before every tool call.
+
+Connect is in private beta. Once enabled: `pnpm add @vercel/connect`, create the Connect client (`vercel connect create <type> --name warehouse`), link it to your project, then `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally. Full setup: [Connections](../connections).
+
+## What the user sees
+
+Ask a question that needs the warehouse:
+
+```text
+How many enterprise customers signed up last month?
+```
+
+The first time around, the model picks a warehouse tool but there's no token yet. So the turn parks and the channel shows a “Sign in” affordance. You authorize in the browser, and once the OAuth callback completes, the turn resumes from exactly that step (the durable parking from [Step 2](./how-it-runs)) and the query runs. Later calls in the session reuse the cached per-user token, so there's no prompt.
+
+## The token never reaches the model
+
+Right before each request to the MCP server, Eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model only ever sees tool names, descriptions, and results. The credential stays out of its reach.
+
+If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [Connections](../connections).
+
+→ Next: [Step 5: Run analysis](./run-analysis)
+
+Depth: [Connections](../connections) · [Auth & route protection](../advanced/auth-and-route-protection)

package/dist/docs/public/tutorial/first-agent.mdx

@@ -0,0 +1,61 @@
+---
+title: "Step 1: Your first agent"
+description: "Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
+---
+
+This tutorial builds one app end to end: a data analytics assistant. You ask in natural language, and over the next nine steps it learns to query a warehouse, run analysis in a sandbox, remember your team’s metric definitions, and refuse to torch your query budget without asking.
+
+Step 1 gets it talking. The scaffold bundles a small sample dataset, so your first question works with zero setup.
+
+## Scaffold
+
+```bash
+pnpm create eve@beta
+```
+
+The wizard prompts for a model and which channels to add (Web Chat or Slack). Skip both for this tutorial: every app ships the built-in HTTP API channel (`agent/channels/eve.ts`). The wizard then installs dependencies and writes a starter `agent/`.
+
+## Set the model
+
+`agent/agent.ts` holds the model and config. Use a capable model for analysis work:
+
+```ts
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-4.8",
+});
+```
+
+## Give it an analyst persona
+
+`agent/instructions.md` is the always-on system prompt. Replace the starter text with a standing identity for a data analyst:
+
+```md
+You are a senior data analyst. You answer questions about the team's data.
+
+- Prefer exact numbers to hand-waving. If you can compute it, compute it.
+- State the assumptions behind any number you report (date range, filters, grain).
+- Use the tools available to you rather than guessing. If you cannot answer from
+  the data, say so plainly.
+```
+
+Instructions are identity and standing rules. On-demand procedures belong in skills (Step 7), and actions belong in tools (Step 3). See [Instructions](../instructions).
+
+## Run it
+
+```bash
+eve dev
+```
+
+The local runtime boots and the dev TUI opens. Ask it something it can answer from general knowledge first:
+
+```text
+What's a good way to measure week-over-week retention?
+```
+
+You’ll get a reply that follows the analyst persona. It can’t see your data yet (that’s Step 3). First, a look at what just happened under the hood.
+
+→ Next: [Step 2: How it runs](./how-it-runs)
+
+Depth: [Getting Started](../getting-started) · [Instructions](../instructions)

package/dist/docs/public/tutorial/guard-the-spend.mdx

@@ -0,0 +1,59 @@
+---
+title: "Step 8: Guard the spend"
+description: "Gate expensive queries with cost-based approval: the agent pauses, asks, and resumes."
+---
+
+A single warehouse query can scan terabytes and bill you for the privilege. So before the agent fires off an expensive scan, make it stop and check with you: for a costly query, the agent pauses, asks you, and resumes with your answer. That's human-in-the-loop, and you wire it up with one field on the tool.
+
+`needsApproval` runs before `execute`. Return `true` and the turn parks on an approval request; you answer, and the run picks up from that exact step. The function gets the tool input, so you can make the decision cost-based.
+
+## Estimate, then gate
+
+Add a cheap estimator (a real warehouse exposes a dry-run byte estimate, so keep the helper illustrative) and gate `run_sql` on it:
+
+```ts title="agent/lib/cost.ts"
+// Illustrative: a real warehouse exposes a dry-run byte estimate.
+export function estimateScanGb(sql: string): number {
+  return /\bwhere\b/i.test(sql) ? 1 : 200; // unfiltered scans are the expensive ones
+}
+```
+
+```ts title="agent/tools/run_sql.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { runReadOnlySql } from "../lib/sample-db.js";
+import { estimateScanGb } from "../lib/cost.js";
+
+const THRESHOLD_GB = 50;
+
+export default defineTool({
+  description: "Run a read-only SQL query against the warehouse.",
+  inputSchema: z.object({ sql: z.string() }),
+  // Cost-based gate: only the expensive queries need a human yes.
+  needsApproval: ({ toolInput }) => estimateScanGb(toolInput?.sql ?? "") > THRESHOLD_GB,
+  async execute({ sql }) {
+    const { columns, rows } = await runReadOnlySql(sql);
+    return { columns, rows: rows.slice(0, 500), truncated: rows.length > 500 };
+  },
+});
+```
+
+Cheap queries run straight through. A query estimated above the threshold trips the gate.
+
+## Pause, ask, resume
+
+Ask for something that forces a large unfiltered scan:
+
+```text
+Total revenue across all customers, all time, broken out by day.
+```
+
+The model proposes the query, `needsApproval` returns `true`, and the turn parks. The stream emits `input.requested`, then `session.waiting`. How the prompt looks depends on the channel: buttons in the TUI, Block Kit in Slack, a UI control on the web. Approve it and the run resumes from exactly that step, then the query runs. Deny it and the tool is skipped, with the model told why.
+
+Each session has exactly one active continuation. Answer an approval against a stale handle and it's rejected, so there's no way to double-resume the same parked turn.
+
+The same machinery backs the built-in `ask_question` tool, where the model asks you mid-turn, and per-connection approval via `approval: once()`. See [Tools: human-in-the-loop](../tools).
+
+→ Next: [Step 9: Ship it](./ship-it)
+
+Depth: [Tools: human-in-the-loop](../tools)

package/dist/docs/public/tutorial/how-it-runs.mdx

@@ -0,0 +1,24 @@
+---
+title: "Step 2: How it runs"
+description: "Session, turn, and durable steps: what you just watched, and why it survives a crash."
+---
+
+You sent one message and got one answer. Here's the model behind that, in three words.
+
+**session** → your whole conversation (durable, can span days)
+**turn** → one message you send and the work it triggers
+**step** → a durable checkpoint within the turn
+
+Each turn runs as a durable workflow, and Eve saves progress at every step. Restart in the middle of a turn and it picks up from the last completed step, without re-running your tool calls. A turn that's waiting on you (an approval, a question) resumes whenever you answer, even if that's much later.
+
+That's why the features in the rest of this tutorial work the way they do:
+
+- The warehouse sign-in in Step 4 parks the turn until you authorize in the browser. A few minutes is fine.
+- The metric glossary in Step 6 survives across turns. State is checkpointed at step boundaries, so it sticks.
+- The spend approval in Step 8 pauses the turn on your yes/no, then picks up exactly where it left off.
+
+Your job is to author capabilities: tools, instructions, channels, skills. Eve drives the model↔tool loop and decides when a turn continues, waits, or ends. You never write that loop yourself.
+
+→ Next: [Step 3: Query sample data](./query-sample-data)
+
+Depth: [Execution model & durability](../advanced/execution-model-and-durability)

package/dist/docs/public/tutorial/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "Build an agent",
+  "pages": [
+    "first-agent",
+    "how-it-runs",
+    "query-sample-data",
+    "connect-a-warehouse",
+    "run-analysis",
+    "remember-definitions",
+    "team-playbooks",
+    "guard-the-spend",
+    "ship-it"
+  ]
+}

package/dist/docs/public/tutorial/query-sample-data.mdx

@@ -0,0 +1,81 @@
+---
+title: "Step 3: Query sample data"
+description: "Add a run_sql tool over the bundled sample dataset and watch the tool loop."
+---
+
+Right now the agent can hold a conversation but it can't see a single row of data. So give it a tool. A tool is the action primitive: typed input goes in, your code runs, structured output comes back. The name the model sees is just the filename, so `agent/tools/run_sql.ts` becomes the tool `run_sql`.
+
+## A tiny sample dataset
+
+To make the first query work without any setup, bundle a small in-memory dataset under `agent/lib/`. Keep it tiny. This is throwaway scaffolding, not the real warehouse (that comes in Step 4).
+
+```ts title="agent/lib/sample-db.ts"
+// A toy SQLite-in-memory stand-in. Swap for your real warehouse in Step 4.
+import initSqlJs from "sql.js";
+
+const SEED = `
+  CREATE TABLE orders (id INTEGER, customer_id INTEGER, amount_cents INTEGER, created_at TEXT);
+  INSERT INTO orders VALUES
+    (1, 10, 4200, '2026-05-01'), (2, 10, 1500, '2026-05-03'),
+    (3, 11, 9900, '2026-05-04'), (4, 12,  800, '2026-05-06');
+  CREATE TABLE customers (id INTEGER, name TEXT, plan TEXT);
+  INSERT INTO customers VALUES
+    (10, 'Acme', 'pro'), (11, 'Globex', 'enterprise'), (12, 'Initech', 'free');
+`;
+
+let dbPromise: Promise<import("sql.js").Database> | null = null;
+
+async function db() {
+  dbPromise ??= initSqlJs().then((SQL) => {
+    const database = new SQL.Database();
+    database.run(SEED);
+    return database;
+  });
+  return dbPromise;
+}
+
+export async function runReadOnlySql(sql: string) {
+  const database = await db();
+  const [result] = database.exec(sql);
+  if (!result) return { columns: [], rows: [] as unknown[][] };
+  return { columns: result.columns, rows: result.values };
+}
+```
+
+## The tool
+
+```ts title="agent/tools/run_sql.ts"
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { runReadOnlySql } from "../lib/sample-db.js";
+
+export default defineTool({
+  description:
+    "Run a read-only SQL query against the analytics tables (orders, customers) " +
+    "and return the columns and rows.",
+  inputSchema: z.object({
+    sql: z.string().describe("A single read-only SELECT statement."),
+  }),
+  async execute({ sql }) {
+    const { columns, rows } = await runReadOnlySql(sql);
+    // Bound the output so a wide query can't flood the model's context.
+    return { columns, rows: rows.slice(0, 500), truncated: rows.length > 500 };
+  },
+});
+```
+
+Tools run in your app runtime with full `process.env`, not in the sandbox. The `inputSchema` both validates the call and types the `input` you get inside `execute`. For output bounding, `toModelOutput`, and authorization, see [Tools](../tools).
+
+## Watch the tool loop
+
+Restart `eve dev` and ask:
+
+```text
+Which customer has spent the most, and how much?
+```
+
+Watch the loop play out in the TUI. The model emits a `run_sql` call, Eve runs your `execute`, and the rows come back as a tool result. The model reads them and answers with a real number. Eve drove the whole loop. All you supplied was the tool.
+
+→ Next: [Step 4: Connect a warehouse](./connect-a-warehouse)
+
+Depth: [Tools](../tools)