eve 0.52.1 → 0.52.3

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

@@ -1,58 +1,81 @@
 ---
-title: "Connect a Warehouse"
-description: "Part 4 of the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
+title: "Connect a Warehouse (Optional)"
+description: "Optional follow-up to the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
 ---
 
-The sample dataset got the analytics assistant running, but it's a stand-in. Now 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. It's an MCP server the model reaches through tools, with auth that eve drives for you.
+Complete [the tutorial with sample data](./first-agent) first. When you have a warehouse with an MCP server, you can connect it to the analytics assistant and let each user sign in through their browser. That's what a connection is for. It's an MCP server the model reaches through tools, with auth that eve drives for you.
 
-This step depends on Vercel Connect, which is in private beta. No Connect access? Keep the Step 3 sample dataset and read this step for the connection model. Steps 5 through 9 work against the sample dataset, so you can complete the tutorial without a warehouse.
+[Vercel Connect is generally available](https://vercel.com/changelog/vercel-connect-secure-access-to-external-services-for-your-agents). You can complete the tutorial with the [sample dataset](./query-sample-data); Connect is only needed for the OAuth integration shown on this page.
 
-The filename sets the runtime name. Put the file at `agent/connections/warehouse.ts` and it registers as `"warehouse"`, with its tools surfaced as `warehouse__<tool>`.
+## Before you start
+
+This integration needs:
+
+- A warehouse account and a working MCP server for that warehouse, with its full endpoint URL. Connect manages credentials; it does not create a warehouse or turn a SQL database into an MCP server.
+- Permission to authorize that server, with read-only access to the data you want the agent to query.
+- A Vercel account and a linked project for Connect.
+- An authenticated user on the eve session. Complete the route-auth setup in [Ship it](./ship-it#replace-placeholderauth) before trying per-user OAuth from a web app.
+
+If you are working through the tutorial for the first time, keep `run_sql` and [continue to Run analysis](./run-analysis). You can add this integration later.
+
+## Register the connector
+
+Run these commands from `analytics-assistant/`. Replace the example URL with your MCP server's actual endpoint, including its path:
+
+```bash
+npm install @vercel/connect
+npx vercel@latest link
+npx vercel@latest connect create "https://your-warehouse.example/mcp" --name warehouse
+```
+
+Follow the provider-specific registration prompts. Copy the **connector UID returned by the CLI**. The display name `warehouse` is not the connector UID. Attach the returned connector to this project, then pull the local environment:
+
+```bash
+npx vercel@latest connect attach "<returned-connector-uid>" --yes
+npx vercel@latest env pull
+```
+
+`vercel env pull` provides `VERCEL_OIDC_TOKEN` for local requests to Connect. That token identifies your Vercel project; it does not sign an end user into the app. The steps below use the authenticated deployment from [Ship it](./ship-it#replace-placeholderauth). The [Connect reference](https://vercel.com/docs/connect) covers service-specific setup and project attachments.
 
 ## 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:
+Create `agent/connections/warehouse.ts`. Replace both the endpoint URL and connector UID below with the values you just configured:
 
 ```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",
+  url: "https://your-warehouse.example/mcp",
   description: "The team's data warehouse: run read-only SQL and list tables and columns.",
-  auth: connect("warehouse"),
+  auth: connect("<returned-connector-uid>"),
 });
 ```
 
-`"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.
+The filename registers the eve connection as `"warehouse"`, with tools named `warehouse__<tool>`. This eve name is independent of the Connect connector UID. The remote server determines which tools exist; check its tool inventory and read-only permissions before using it.
 
-Before testing the warehouse from a web app, make sure the eve channel route auth maps your signed-in app user to `principalType: "user"`. A Connect-backed connection can only start per-user OAuth when the active session already has an authenticated user principal. If route auth still only accepts `localDev()`, a runtime token, or a placeholder guard, the first warehouse tool call fails with `reason: "principal_required"` instead of showing the sign-in challenge.
+`connect("...")` is user-scoped by default. Each end-user authorizes in their own browser, and eve resolves that user's token before a tool call. The eve channel's route auth must map the signed-in app user to `principalType: "user"`. `localDev()`, a runtime token, or a placeholder guard cannot supply that identity; those sessions fail with `reason: "principal_required"` before OAuth starts. For a shared app credential, see [app vs. user auth](../connections#choose-app-vs-user-auth).
 
-Once Connect is enabled on your account, wire it up:
+## Deploy and try it
 
-1. Install the package: `npm install @vercel/connect`.
-2. Create the Connect client: `vercel connect create <type> --name warehouse`.
-3. Link the client to your project.
-4. Run `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally.
+Deploy the updated app so the authenticated web app includes the new connection:
 
-For the full reference, see [MCP connections](../connections/mcp).
-
-## What the user sees
+```bash
+npx vercel@latest deploy
+```
 
-Ask a question that needs the warehouse:
+Open the new HTTPS preview URL, sign in with the credentials configured in [Ship it](./ship-it#replace-placeholderauth), and create a new session. The tutorial's development server bypasses the browser login and uses `localDev()`; restarting `npm run dev` alone does not provide the user identity this connection requires.
 
-```text
-How many enterprise customers signed up last month?
-```
+From your authenticated web app, ask the agent to inspect the warehouse's available tables and then query a table you have access to. Use the server's schema rather than assuming it has the tutorial's `orders` and `customers` tables.
 
-The first time, 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.
+If the user has not authorized the connector, the turn parks and the channel shows a sign-in link. Complete authorization in the browser; after the callback succeeds, the turn resumes and retries the tool call. Later calls use the existing grant while it remains valid. See [MCP connection troubleshooting](../connections/mcp#troubleshooting) if registration succeeds but the tool cannot connect.
 
 ## 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.
+Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The credential stays in the app runtime.
 
-If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [MCP connections](../connections/mcp).
+Gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`) when needed. See [MCP connections](../connections/mcp).
 
-→ Next: [Run analysis](./run-analysis)
+→ Return to the tutorial: [Run analysis](./run-analysis)
 
 Learn more: [MCP connections](../connections/mcp) · [Authentication](../guides/auth-and-route-protection)

package/docs/tutorial/first-agent.mdx

@@ -1,16 +1,22 @@
 ---
 title: "Your First Agent"
-description: "Part 1 of the Build an Agent tutorial. Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
+description: "Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
 ---
 
-The Build an Agent tutorial constructs 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 exceed your query budget without asking.
+For a bespoke learning experience, start with the [eve template gallery](https://eve.dev/templates) or ask your coding agent to build your use case. For example:
 
-Step 1 gets it talking. The scaffold bundles a small sample dataset, so your first question works with zero setup.
+- “Build an eve Slack agent that answers questions from our team’s documentation.”
+- “Build an eve incident-response agent that investigates alerts using our observability tools.”
+- “Build an eve GitHub maintainer that triages issues and summarizes pull requests.”
+
+If you prefer a step-by-step walkthrough, continue with this tutorial. It constructs one app end to end: a data analytics assistant. You ask in natural language, and over eight steps it learns to query sample data, run analysis in a sandbox, remember your team's metric definitions, and refuse to exceed your query budget without asking.
+
+Step 1 gets it talking. In Step 3 you create a small local dataset that you use throughout the tutorial. You can complete the tutorial without a warehouse or Vercel Connect account. [Connect a warehouse](./connect-a-warehouse) is an optional follow-up once your agent works.
 
 ## Prerequisites
 
 - Node 24 or newer and npm.
-- A model credential. The scaffold's default model goes through the [Vercel AI Gateway](../getting-started), so you need `AI_GATEWAY_API_KEY` (or `VERCEL_OIDC_TOKEN` pulled via `vercel link`). A direct provider model like `anthropic("claude-opus-4-8")` instead needs that provider's AI SDK package and key, here `@ai-sdk/anthropic` and `ANTHROPIC_API_KEY`.
+- A working model credential, configured through [Getting Started](../getting-started). Keep the model and credential you already tested there.
 
 If you have not run eve before, complete [Getting Started](../getting-started) first. Without a credential, "Run the agent" below fails when the runtime tries to reach the model; the dev TUI's `/model` flow walks you through pasting a key or linking a project.
 
@@ -21,24 +27,19 @@ npx eve@latest init analytics-assistant
 cd analytics-assistant
 ```
 
-The command writes the starter agent with eve's default model and built-in HTTP API
-channel (`agent/channels/eve.ts`), installs dependencies, initializes Git, and
-starts the development server. Stop the server before continuing with the edits
-below. It does not create a Vercel project or deploy. `init` creates the
+The command writes the starter agent and built-in HTTP API channel
+(`agent/channels/eve.ts`), installs dependencies, initializes Git, and offers
+to start the development server. Stop the server if you started it before
+continuing with the edits below. It does not create a Vercel project or deploy. `init` creates the
 `analytics-assistant/` directory, so `cd` into it before running further
 commands.
 
-## Set the model
-
-`agent/agent.ts` holds the model and config. Use a capable model for analysis work:
+## Keep your configured model
 
-```ts
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-});
-```
+`agent/agent.ts` holds the model and config. Use the same model and credentials
+that worked in Getting Started. The tutorial does not require switching providers.
+If you need to configure this new project, use `/model` in the dev TUI before
+sending your first question.
 
 ## Give it an analyst persona
 
@@ -53,7 +54,7 @@ You are a senior data analyst. You answer questions about the team's data.
   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).
+Instructions are identity and standing rules. On-demand procedures belong in skills (Step 6), and actions belong in tools (Step 3). See [Instructions](../instructions).
 
 ## Run the agent
 

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

@@ -1,15 +1,15 @@
 ---
 title: "Guard the Spend"
-description: "Part 8 of the Build an Agent tutorial. Gate expensive queries with cost-based approval. The agent pauses, asks, and resumes."
+description: "Part 7 of the Build an Agent tutorial. Gate expensive queries with cost-based approval. The agent pauses, asks, and resumes."
 ---
 
-A single warehouse query can scan terabytes and run up the bill. So before the analytics assistant fires off an expensive scan, make it stop and check with you. 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.
+Use the sample dataset to practice an approval before a tool runs. The example assigns a simulated scan cost to each query; it does not incur warehouse charges. Make the analytics assistant stop and check with you before a query exceeds that threshold. 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.
 
 `approval` runs before `execute`. Return `"user-approval"` 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
 
-This step keeps `run_sql` on the Step 3 sample dataset so you can demo the gate locally. With a real warehouse you'd gate the warehouse connection tool from Step 4 the same way, on a dry-run byte estimate instead of the toy heuristic below.
+This step keeps `run_sql` on the Step 3 sample dataset so you can demo the gate locally. If you later [connect a warehouse](./connect-a-warehouse), use the provider's dry-run estimate to decide when approval is needed.
 
 Add a cheap estimator and gate `run_sql` on it:
 
@@ -30,7 +30,7 @@ const THRESHOLD_GB = 50;
 
 export default defineTool({
   description: "Run a read-only SQL query against the analytics tables.",
-  inputSchema: z.object({ sql: z.string() }),
+  inputSchema: z.object({ sql: z.string().max(10_000) }),
   // Cost-based gate: only the expensive queries need a human yes.
   approval: ({ toolInput }) =>
     estimateScanGb(toolInput?.sql ?? "") > THRESHOLD_GB ? "user-approval" : "not-applicable",

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

@@ -15,9 +15,8 @@ Each turn runs as a durable workflow, and eve saves progress at every step. Comp
 
 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.
+- The metric glossary in Step 5 survives across turns. State is checkpointed at step boundaries, so it sticks.
+- The spend approval in Step 7 pauses the turn on your yes/no, then picks up exactly where it left off.
 
 You author capabilities, including tools, instructions, channels, and skills. eve drives the model-to-tool loop and decides when a turn continues, waits, or ends. You never write that loop yourself.
 

package/docs/tutorial/meta.json

@@ -5,11 +5,11 @@
     "first-agent",
     "how-it-runs",
     "query-sample-data",
-    "connect-a-warehouse",
     "run-analysis",
     "remember-definitions",
     "team-playbooks",
     "guard-the-spend",
-    "ship-it"
+    "ship-it",
+    "connect-a-warehouse"
   ]
 }

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

@@ -1,6 +1,6 @@
 ---
 title: "Query Sample Data"
-description: "Part 3 of the Build an Agent tutorial. Add a run_sql tool over the bundled sample dataset and watch the tool loop."
+description: "Part 3 of the Build an Agent tutorial. Add a run_sql tool over a local sample dataset and watch the tool loop."
 ---
 
 The analytics assistant can hold a conversation, but it can't see a single row of data. 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 the filename, so `agent/tools/run_sql.ts` becomes the tool `run_sql`.
@@ -14,27 +14,21 @@ npm install sql.js
 npm install --save-dev @types/sql.js
 ```
 
-`sql.js` loads its WebAssembly binary from the installed package at runtime. Keep the package external so the binary remains next to its JavaScript:
+`sql.js` loads its WebAssembly binary from the installed package at runtime. Keep the package external so the binary remains next to its JavaScript. Add this `build` property inside your existing `defineAgent({ ... })` in `agent/agent.ts`, keeping your configured `model` and its imports:
 
-```ts title="agent/agent.ts" {5-7}
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-  build: {
-    externalDependencies: ["sql.js"],
-  },
-});
+```ts
+build: {
+  externalDependencies: ["sql.js"],
+},
 ```
 
 Restart the dev server after changing `externalDependencies`. eve reads this setting when the server starts.
 
 ## A tiny sample dataset
 
-Store a small in-memory dataset under `agent/lib/`. Keep it tiny. This is throwaway scaffolding, not the real warehouse (that comes in Step 4).
+Create `agent/lib/sample-db.ts` with the dataset below. These four orders and three customers supply the data for every remaining tutorial step. No database server, account, or connection string is needed. The dataset is recreated when the app restarts.
 
 ```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 = `
@@ -60,12 +54,27 @@ async function db() {
 
 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 };
+  const query = `SELECT * FROM (\n${sql.trim().replace(/;$/, "")}\n) LIMIT 501`;
+  const statement = database.prepare(query);
+  try {
+    // prepare() accepts the first statement; reject any unparsed trailing SQL.
+    if (statement.getSQL() !== query) {
+      throw new Error("Provide a single SELECT query.");
+    }
+    const columns = statement.getColumnNames();
+    const rows: unknown[][] = [];
+    while (rows.length < 501 && statement.step()) rows.push(statement.get());
+    return { columns, rows };
+  } finally {
+    statement.free();
+  }
 }
 ```
 
+The outer `SELECT` lets SQLite accept queries, including `WITH` queries, while rejecting writes and configuration statements. The helper prepares one statement, rejects trailing SQL, and reads at most 501 rows. The extra row lets the tool report that its 500-row output was truncated. It frees the statement even when a query fails.
+
+This is an in-memory tutorial database. A row limit does not bound the work needed to compute a query; use database-enforced read-only permissions and query timeouts when adapting the tool to a production database.
+
 ## Define the run_sql tool
 
 ```ts title="agent/tools/run_sql.ts"
@@ -78,7 +87,7 @@ export default defineTool({
     "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."),
+    sql: z.string().max(10_000).describe("A single read-only SELECT statement."),
   }),
   async execute({ sql }) {
     const { columns, rows } = await runReadOnlySql(sql);
@@ -98,8 +107,10 @@ Restart the dev server with `npm run dev` and ask:
 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.
+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. The result is Globex with 9,900 cents ($99.00). The amounts are stored in cents, so divide by 100 when reporting dollars. eve drove the whole loop; you supplied the tool.
+
+Keep `run_sql` and the sample database for the rest of the tutorial. When you have your own data service, [Connect a warehouse](./connect-a-warehouse) explains the optional integration.
 
-→ Next: [Connect a warehouse](./connect-a-warehouse)
+→ Next: [Run analysis](./run-analysis)
 
 Learn more: [Tools](../tools)

package/docs/tutorial/remember-definitions.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Remember Definitions"
-description: "Part 6 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
+description: "Part 5 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
 ---
 
 Every team has house definitions for the analytics assistant. "Active" means a purchase in the last 30 days, revenue is net of refunds, a "week" starts Monday. Re-explaining all of that on every turn is a waste. State gives the agent a place to keep them.
@@ -55,15 +55,15 @@ export default defineTool({
 ## See it persist
 
 ```text
-> For us, an active customer is one with a purchase in the last 30 days.
+> For this dataset, a high-value customer has at least $50 in total orders.
   Remember that.
-  → calls define_metric("active customer", "purchase in the last 30 days")
+  → calls define_metric("high-value customer", "at least $50 in total orders")
 
-> How many active customers do we have?
+> How many high-value customers do we have?
   → recalls the definition, writes the matching SQL, answers
 ```
 
-The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
+The sample data has two high-value customers: Acme ($57) and Globex ($99). This definition works with the same fixed dataset whenever you run the tutorial. The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
 
 State is scoped to a session and isolated per agent, so a subagent starts with fresh state and never sees the parent's. Need to reset something each turn? Call `update(() => fresh)` in a lifecycle hook. More in [State](../concepts/state).
 

package/docs/tutorial/run-analysis.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Run Analysis"
-description: "Part 5 of the Build an Agent tutorial. Seed the warehouse schema into the sandbox workspace, then compute and chart beyond SQL."
+description: "Part 4 of the Build an Agent tutorial. Seed the sample database schema into the sandbox workspace, then compute and chart beyond SQL."
 ---
 
 SQL tells the analytics assistant the numbers, but a cohort curve, a forecast, or a chart needs real computation. That's what the sandbox is for. It's an isolated bash environment with a `/workspace` filesystem, and every agent gets exactly one.
@@ -9,7 +9,7 @@ This takes two pieces. First seed reference files the model can read, then compu
 
 ## Seed the schema into the workspace
 
-Mount the warehouse schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout, where anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
+Mount the sample database schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout, where anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
 
 ```text
 agent/sandbox/
@@ -21,65 +21,202 @@ agent/sandbox/
 ```sql
 -- agent/sandbox/workspace/schema.sql
 -- Reference only: table shapes the analyst can read before writing queries.
-CREATE TABLE orders     (id INT, customer_id INT, amount_cents INT, created_at DATE);
-CREATE TABLE customers  (id INT, name TEXT, plan TEXT, signed_up_at DATE);
+CREATE TABLE orders     (id INTEGER, customer_id INTEGER, amount_cents INTEGER, created_at TEXT);
+CREATE TABLE customers  (id INTEGER, name TEXT, plan TEXT);
 ```
 
-Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. No `agent/sandbox/sandbox.ts` required. A `workspace/` folder keeps the default sandbox and seeds your files into it.
+Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. A `workspace/` folder seeds your files without requiring a sandbox definition. Add one next to install the chart dependencies.
+
+## Install the chart dependencies
+
+Python needs a sandbox that runs real binaries. For local development, start a Docker-compatible daemon and run `docker info` to verify it is reachable before restarting `npm run dev`. eve also supports [microsandbox](../sandbox#microsandbox) on compatible hosts. The `just-bash` fallback cannot run Python or install packages; installing Python on your laptop does not add it to the sandbox. You can [continue to the next chapter](./remember-definitions) if you do not want to set up a local container or VM yet.
+
+The default eve images for Docker, microsandbox, and Vercel Sandbox include Python, but not matplotlib. Add this definition alongside `workspace/` to install matplotlib in a virtual environment. It uses the same environment for installation and chart execution, without changing the system Python:
+
+```ts title="agent/sandbox/sandbox.ts"
+import { defineSandbox } from "eve/sandbox";
+
+export default defineSandbox({
+  async bootstrap({ use }) {
+    const sandbox = await use();
+    const commands = [
+      "sudo apt-get update && sudo apt-get install -y python3 python3-venv",
+      "python3 -m venv /workspace/.venv",
+      "/workspace/.venv/bin/python -m pip install matplotlib==3.10.8",
+      "/workspace/.venv/bin/python -c \"import matplotlib.pyplot; print('Chart dependencies ready')\"",
+    ];
+    for (const command of commands) {
+      const result = await sandbox.run({ command });
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `Chart setup failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+        );
+      }
+    }
+  },
+});
+```
+
+Bootstrap runs when eve builds the sandbox template, and sessions inherit the installed environment. The first build needs network access to Ubuntu package repositories and PyPI. Keep the default network policy while following this example; a custom `deny-all` or allow-list policy must permit these downloads during bootstrap. The same definition uses Vercel Sandbox after deployment to Vercel.
+
+Restart `npm run dev` after adding the definition. Before asking for a chart, send this message in the TUI:
+
+```text
+Run /workspace/.venv/bin/python -c "import matplotlib; print(matplotlib.__version__)" in the sandbox.
+```
+
+The command should print `3.10.8`. If setup fails, check the dev server's sandbox logs for the failing command. Resolve the package download or backend error before continuing.
 
 ## Compute and chart in the sandbox
 
 The built-in `bash`, `read_file`, and `write_file` tools already target the sandbox. When you write your own analysis steps, grab a live handle with `ctx.getSandbox()`:
 
 ```ts title="agent/tools/chart_series.ts"
+import { randomUUID } from "node:crypto";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 
 export default defineTool({
   description:
     "Plot a time series to a PNG in the workspace. Pass {date, value} points; " +
-    "returns the chart path.",
+    "returns the chart path and PNG data for the client to save.",
   inputSchema: z.object({
-    title: z.string(),
-    points: z.array(z.object({ date: z.string(), value: z.number() })),
+    title: z.string().min(1).max(120),
+    points: z
+      .array(z.object({ date: z.string().max(40), value: z.number() }))
+      .min(1)
+      .max(366),
   }),
   async execute({ title, points }, ctx) {
     const sandbox = await ctx.getSandbox();
+    const directory = `analysis/${randomUUID()}`;
     await sandbox.writeTextFile({
-      path: "analysis/series.json",
+      path: `${directory}/series.json`,
       content: JSON.stringify({ title, points }),
     });
     await sandbox.writeTextFile({
-      path: "analysis/plot.py",
+      path: `${directory}/plot.py`,
       content: [
         "import json, matplotlib",
         "matplotlib.use('Agg')",
         "import matplotlib.pyplot as plt",
         "d = json.load(open('series.json'))",
+        "plt.figure(figsize=(8, 4), dpi=100)",
         "plt.plot([p['date'] for p in d['points']], [p['value'] for p in d['points']])",
         "plt.title(d['title']); plt.savefig('chart.png')",
       ].join("\n"),
     });
-    const root = sandbox.resolvePath("analysis");
-    await sandbox.run({ command: `cd ${JSON.stringify(root)} && python plot.py` });
-    return { chart: `${root}/chart.png` };
+    const root = sandbox.resolvePath(directory);
+    const result = await sandbox.run({
+      command: `cd ${JSON.stringify(root)} && /workspace/.venv/bin/python plot.py`,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Chart generation failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+      );
+    }
+    const chart = `${root}/chart.png`;
+    const png = await sandbox.readBinaryFile({ path: chart });
+    if (!png || png.byteLength === 0) {
+      throw new Error("The chart command did not produce a PNG.");
+    }
+    if (png.byteLength > 1024 * 1024) {
+      throw new Error("The chart exceeds the 1 MiB download limit. Plot fewer points.");
+    }
+    return { chart, pngBase64: Buffer.from(png).toString("base64") };
+  },
+  toModelOutput({ chart }) {
+    return {
+      type: "text",
+      value: `Created ${chart}. The PNG is available in the tool result for the client to save.`,
+    };
   },
 });
 ```
 
-This tool shells out to `python` with matplotlib, which the sandbox base image does not preinstall. Install the runtime in sandbox bootstrap (or bake it into a custom image) so `python plot.py` resolves. See [Sandbox](../sandbox) for where bootstrap runs.
+The tool uses the Python environment installed in bootstrap. `matplotlib.use('Agg')` selects a renderer that writes PNGs without a desktop display.
 
-Now ask for something past plain SQL. If you skipped Step 4, this still works against the Step 3 sample dataset:
+`sandbox.run()` returns an exit code even when the command fails. Check `exitCode` before returning a chart path. Throwing an error gives the model the failed command's output, including a missing Python executable or matplotlib import, so it can report the failure instead of claiming a chart exists.
+
+Ask for a chart using the sample data from Step 3:
 
 ```text
-Plot total order revenue per customer.
+Plot daily order revenue in dollars for May 2026.
+```
+
+The model queries `run_sql` for daily totals, divides `amount_cents` by 100, and passes date/value points to `chart_series`. The sample data has four dates with revenue of $42, $15, $99, and $8. The chart uses the same data you queried in Step 3.
+
+## Save the chart to your computer
+
+A sandbox path is not a download URL or a file on your laptop. `readBinaryFile` copies the generated PNG out of the sandbox into the tool result, where your client can use it. `toModelOutput` sends the model only a short description, so the image's base64 data does not fill its context. The TUI shows tool results as text; it does not save or preview this PNG automatically.
+
+Create this script in your project root. It asks for a chart through the same local HTTP API as the TUI, then saves the successful tool result as `chart.png` in the directory where you run the script:
+
+```ts title="save-chart.ts"
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Client } from "eve/client";
+import { z } from "zod";
+
+const host = process.argv[2];
+if (!host) throw new Error("Usage: node save-chart.ts <dev-server-url>");
+
+const client = new Client({ host });
+const { response } = await client.sessions.create({
+  message: "Use run_sql and chart_series to plot daily order revenue in May 2026.",
+});
+const turn = await response.result();
+if (turn.status === "failed") throw new Error("The agent turn failed. Check the dev server logs.");
+if (turn.inputRequests.length > 0) {
+  const prompts = turn.inputRequests.map((request) => request.prompt).join("\n");
+  throw new Error(
+    `Session ${turn.sessionId} needs your input before it can create the chart:\n${prompts}`,
+  );
+}
+
+const chartOutput = z.object({ pngBase64: z.string().min(1).max(1_398_104) });
+let saved = false;
+for (const event of turn.events) {
+  if (event.type !== "action.result") continue;
+  const result = event.data.result;
+  if (result.kind !== "tool-result" || result.toolName !== "chart_series" || result.isError)
+    continue;
+
+  const { pngBase64 } = chartOutput.parse(result.output);
+  const png = Buffer.from(pngBase64, "base64");
+  if (
+    png.byteLength > 1024 * 1024 ||
+    !png.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+  ) {
+    throw new Error("The tool result is not a PNG within the 1 MiB download limit.");
+  }
+  await writeFile("chart.png", png);
+  saved = true;
+}
+if (!saved) {
+  console.error(turn.message ?? "The agent returned no explanation.");
+  throw new Error("No chart was returned. Check the agent's response above and sandbox setup.");
+}
+console.log(`Saved ${resolve("chart.png")}`);
+```
+
+Keep `npm run dev` running. In a second terminal, run the script with the actual URL printed by the dev server; for example:
+
+```bash
+node save-chart.ts http://localhost:2000
 ```
 
-The model queries for the numbers (the warehouse from Step 4, or the sample dataset if you skipped it), checks `schema.sql` to get the grain right, then calls `chart_series` to render the PNG in `/workspace`.
+Open the saved `chart.png` in your image viewer. This creates a separate session from your TUI conversation and overwrites an existing `chart.png`. A failed tool call or a turn without a chart fails the script instead of claiming a file was saved.
+
+This step does not require approvals. If you return after adding the approval gate in [Guard the spend](./guard-the-spend), the script reports any pending request with its session ID. [Respond through the client](../guides/client/messages#answer-human-input-requests) before collecting that session's chart result.
+
+The same client can save a chart from a hosted agent: pass the deployment URL and configure [client authentication](../guides/client/overview#authentication) for that deployment. The file is saved on the computer running the script. In a web UI, consume the same `action.result` output to build an image preview or download control. Returning bytes from a tool does not add that UI automatically.
+
+This example caps charts at 1 MiB because tool outputs are persisted with session events. For larger files, copy the bytes to your application's file storage and return an authorized download URL instead. Sandbox files themselves are not permanent artifact storage.
 
 ## Secrets stay out of the sandbox
 
-The sandbox has no `process.env` and no access to your app's secrets. Your warehouse token lives in the app runtime, and firewall brokering is the only path it takes to the warehouse host. It never enters the sandbox process.
+The sandbox has no `process.env` and no access to your app's secrets. The `run_sql` tool and sample database run in your app. You pass only the query results to the chart tool; the sandbox does not need database credentials.
 
 The local backend runs the sandbox on your laptop during `eve dev`; on Vercel it runs on Vercel Sandbox. Lifecycle, backends, and network policy are in [Sandbox](../sandbox).