eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,20 +3,18 @@ title: "Connect a Warehouse (Optional)"
3
3
  description: "Optional follow-up to the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
4
4
  ---
5
5
 
6
- 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.
6
+ A connection is an MCP server the model reaches through tools, with auth that eve drives for you. When you have a warehouse with an MCP server, connect it to the analytics assistant and let each user sign in through their browser. Complete [the tutorial with sample data](./first-agent) first.
7
7
 
8
- [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.
8
+ [Vercel Connect](https://vercel.com/changelog/vercel-connect-secure-access-to-external-services-for-your-agents) is needed only for the OAuth integration on this page; the rest of the tutorial uses the [sample dataset](./query-sample-data).
9
9
 
10
10
  ## Before you start
11
11
 
12
- This integration needs:
13
-
14
12
  - 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.
15
13
  - Permission to authorize that server, with read-only access to the data you want the agent to query.
16
14
  - A Vercel account and a linked project for Connect.
17
15
  - 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.
18
16
 
19
- 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.
17
+ On a first pass through the tutorial, keep `run_sql` and [continue to Run analysis](./run-analysis).
20
18
 
21
19
  ## Register the connector
22
20
 
@@ -28,14 +26,14 @@ npx vercel@latest link
28
26
  npx vercel@latest connect create "https://your-warehouse.example/mcp" --name warehouse
29
27
  ```
30
28
 
31
- 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:
29
+ Follow the provider-specific registration prompts. Copy the **connector UID returned by the CLI**, not the display name `warehouse`. Attach the returned connector to this project, then pull the local environment:
32
30
 
33
31
  ```bash
34
32
  npx vercel@latest connect attach "<returned-connector-uid>" --yes
35
33
  npx vercel@latest env pull
36
34
  ```
37
35
 
38
- `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.
36
+ `vercel env pull` provides `VERCEL_OIDC_TOKEN` for local requests to Connect. That token identifies your Vercel project, not an end user, so 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.
39
37
 
40
38
  ## Declare the connection
41
39
 
@@ -52,9 +50,9 @@ export default defineMcpClientConnection({
52
50
  });
53
51
  ```
54
52
 
55
- 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.
53
+ The filename registers the eve connection as `"warehouse"`, independent of the connector UID, with tools named `warehouse__<tool>`. The remote server determines which tools exist; check its tool inventory and read-only permissions before using it.
56
54
 
57
- `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).
55
+ By default, `connect("...")` uses a separate token for each user. Each user authorizes in their own browser, and eve gets that user's token before a tool call. The eve channel's route auth must map the signed-in app user to `principalType: "user"`. Sessions from `localDev()`, a runtime token, or a placeholder guard fail with `reason: "principal_required"` before OAuth starts. For a shared app credential, see [app vs. user auth](../connections#choose-app-vs-user-auth).
58
56
 
59
57
  ## Deploy and try it
60
58
 
@@ -64,15 +62,15 @@ Deploy the updated app so the authenticated web app includes the new connection:
64
62
  npx vercel@latest deploy
65
63
  ```
66
64
 
67
- 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.
65
+ 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 local dev server uses `localDev()`, which doesn't provide the user identity this connection requires.
68
66
 
69
- 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.
67
+ Ask the agent to inspect the warehouse's available tables, then query a table you have access to. Rely on the server's schema, not the tutorial's `orders` and `customers` tables.
70
68
 
71
- 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.
69
+ If the user has not authorized the connector, the turn pauses and the channel shows a sign-in link. After the browser callback succeeds, the turn resumes and retries the tool call. Later calls reuse the grant while it remains valid. See [MCP connection troubleshooting](../connections/mcp#troubleshooting) if registration succeeds but the tool cannot connect.
72
70
 
73
71
  ## The token never reaches the model
74
72
 
75
- Right before each request to the MCP server, eve resolves the user's bearer and, once the user has authorized, sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The credential stays in the app runtime.
73
+ Before each request to the MCP server, eve gets the user's token and sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The token stays in your app's server code.
76
74
 
77
75
  Gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`) when needed. See [MCP connections](../connections/mcp).
78
76
 
@@ -3,22 +3,22 @@ title: "Your First Agent"
3
3
  description: "Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
4
4
  ---
5
5
 
6
- For a bespoke learning experience, start with the [eve template gallery](https://vercel.com/templates/eve) or ask your coding agent to build your use case. For example:
6
+ To start from your own use case, use the [eve template gallery](https://vercel.com/templates/eve) or ask your coding agent to build your use case. For example:
7
7
 
8
8
  - “Build an eve Slack agent that answers questions from our team’s documentation.”
9
9
  - “Build an eve incident-response agent that investigates alerts using our observability tools.”
10
10
  - “Build an eve GitHub maintainer that triages issues and summarizes pull requests.”
11
11
 
12
- 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.
12
+ For a step-by-step walkthrough, continue with this tutorial. Over eight steps you build a data analytics assistant. It answers natural-language questions, queries sample data, and runs analysis in a sandbox. It also remembers your team's metric definitions and asks before exceeding your query budget.
13
13
 
14
- 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.
14
+ Step 1 gets it talking. Step 3 creates a small local dataset that you use throughout, so you need no warehouse or Vercel Connect account. [Connect a warehouse](./connect-a-warehouse) is an optional follow-up once your agent works.
15
15
 
16
16
  ## Prerequisites
17
17
 
18
18
  - Node 24 or newer and npm.
19
- - A working model credential, configured through [Getting Started](../getting-started). Keep the model and credential you already tested there.
19
+ - A working model credential, configured through [Getting Started](../getting-started).
20
20
 
21
- 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
+ Without a credential, "Run the agent" below fails when eve tries to reach the model. The dev TUI's `/model` flow walks you through pasting a key or linking a project.
22
22
 
23
23
  ## Scaffold the agent
24
24
 
@@ -27,19 +27,17 @@ npx eve@latest init analytics-assistant
27
27
  cd analytics-assistant
28
28
  ```
29
29
 
30
- The command writes the starter agent and built-in HTTP API channel
31
- (`agent/channels/eve.ts`), installs dependencies, initializes Git, and offers
32
- to start the development server. Stop the server if you started it before
33
- continuing with the edits below. It does not create a Vercel project or deploy. `init` creates the
34
- `analytics-assistant/` directory, so `cd` into it before running further
35
- commands.
30
+ `init` creates the `analytics-assistant/` directory with the starter agent and
31
+ built-in HTTP API channel (`agent/channels/eve.ts`). It also installs
32
+ dependencies, initializes Git, and offers to start the development server. If
33
+ you started the server, stop it before you continue with the edits below. `init`
34
+ does not create a Vercel project or deploy.
36
35
 
37
36
  ## Keep your configured model
38
37
 
39
38
  `agent/agent.ts` holds the model and config. Use the same model and credentials
40
- that worked in Getting Started. The tutorial does not require switching providers.
41
- If you need to configure this new project, use `/model` in the dev TUI before
42
- sending your first question.
39
+ that worked in Getting Started; the tutorial works with any provider. To configure
40
+ this new project, use `/model` in the dev TUI before sending your first question.
43
41
 
44
42
  ## Give it an analyst persona
45
43
 
@@ -62,13 +60,13 @@ Instructions are identity and standing rules. On-demand procedures belong in ski
62
60
  npm run dev
63
61
  ```
64
62
 
65
- The `init` scaffold writes a `dev` script that runs the `eve dev` binary from the project's `node_modules`. The local runtime boots and the dev TUI opens. Ask it something it can answer from general knowledge first:
63
+ The `dev` script runs `eve dev` from the project's `node_modules`. The agent starts locally and the dev TUI opens. Ask it something it can answer from general knowledge first:
66
64
 
67
65
  ```text
68
66
  What's a good way to measure week-over-week retention?
69
67
  ```
70
68
 
71
- You get a reply that follows the analyst persona. It can't see your data yet (that comes in Step 3). First, a look at what happened under the hood.
69
+ You get a reply that follows the analyst persona. It can't see your data yet (that comes in Step 3). First, look at what happened when you sent the question.
72
70
 
73
71
  → Next: [How it runs](./how-it-runs)
74
72
 
@@ -3,15 +3,13 @@ title: "Guard the Spend"
3
3
  description: "Part 7 of the Build an Agent tutorial. Gate expensive queries with cost-based approval. The agent pauses, asks, and resumes."
4
4
  ---
5
5
 
6
- 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.
6
+ Make the analytics assistant check with you before a query exceeds a cost 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. The example assigns each query a simulated scan cost, so it incurs no warehouse charges.
7
7
 
8
- `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.
8
+ `approval` runs before `execute` and receives the tool input, so the decision can be cost-based. Return `"user-approval"` and the turn pauses on an approval request. When you answer, the turn continues from that exact step.
9
9
 
10
10
  ## Estimate, then gate
11
11
 
12
- 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.
13
-
14
- Add a cheap estimator and gate `run_sql` on it:
12
+ Add a cheap estimator and gate `run_sql` on it. If you later [connect a warehouse](./connect-a-warehouse), use the provider's dry-run estimate instead:
15
13
 
16
14
  ```ts title="agent/lib/cost.ts"
17
15
  // Illustrative: a real warehouse exposes a dry-run byte estimate.
@@ -51,11 +49,11 @@ Ask for something that forces a large unfiltered scan:
51
49
  Total revenue across all customers, all time, broken out by day.
52
50
  ```
53
51
 
54
- The model proposes the query, `approval` returns `"user-approval"`, and the turn parks. The stream emits `interaction.opened`, then `turn.paused` awaiting it, and the turn stays open until someone answers. How the prompt looks depends on the channel, whether buttons in the TUI, Block Kit in Slack, or 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.
52
+ The model proposes the query, `approval` returns `"user-approval"`, and the turn pauses. The stream emits `interaction.opened`, then `turn.paused`, and the turn stays open until someone answers. The channel renders the prompt: buttons in the TUI, Block Kit in Slack, or a UI control on the web. Approve it and the turn continues from that step and runs the query. Deny it and the tool is skipped, with the model told why.
55
53
 
56
- 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.
54
+ An answer approves the call only while its request is waiting. An answer to an already-answered or cancelled request never approves the earlier call, so a paused turn can't resume twice. See [Send a follow-up message](../concepts/sessions-runs-and-streaming#send-a-follow-up-message).
57
55
 
58
- The same machinery backs the opt-in `ask_question` tool, where the model asks you mid-turn, and per-connection approval via `approval: once()`. See [Tools and human-in-the-loop](../tools).
56
+ The same pause and resume also powers the opt-in `ask_question` tool, where the model asks you mid-turn, and per-connection approval via `approval: once()`. See [Tools and human-in-the-loop](../tools).
59
57
 
60
58
  → Next: [Ship it](./ship-it)
61
59
 
@@ -5,20 +5,20 @@ description: "Part 2 of the Build an Agent tutorial. Session, turn, and durable
5
5
 
6
6
  The analytics assistant sent one message and got one answer. Three terms describe the model behind that.
7
7
 
8
- | Term | Meaning |
9
- | ----------- | ------------------------------------------------- |
10
- | **session** | Your whole conversation (durable, can span days). |
11
- | **turn** | One message you send and the work it triggers. |
12
- | **step** | A durable checkpoint within the turn. |
8
+ | Term | Meaning |
9
+ | ----------- | ---------------------------------------------- |
10
+ | **session** | Your whole conversation. It can span days. |
11
+ | **turn** | One message you send and the work it triggers. |
12
+ | **step** | A saved checkpoint within the turn. |
13
13
 
14
- The session runs as one durable workflow, and eve saves each turn's progress at every step. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval. A turn that's waiting on you (an approval, a question) resumes whenever you answer, even if that's much later.
14
+ A session survives restarts and redeploys, because eve saves each turn's progress at every step. A completed step never runs again; eve reuses its saved result. A step that is interrupted runs again from its start. Make side effects such as charges or emails idempotent, or gate them with approval. A turn that's waiting on you (an approval, a question) resumes whenever you answer, even if that's much later.
15
15
 
16
16
  That's why the features in the rest of this tutorial work the way they do:
17
17
 
18
- - The metric glossary in Step 5 survives across turns. State is checkpointed at step boundaries, so it sticks.
18
+ - The metric glossary in Step 5 survives across turns, because eve saves state at each step.
19
19
  - The spend approval in Step 7 pauses the turn on your yes/no, then picks up exactly where it left off.
20
20
 
21
- 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.
21
+ You write the tools, instructions, channels, and skills. eve drives the model-to-tool loop and decides when a turn continues, waits, or ends.
22
22
 
23
23
  → Next: [Step 3: Query sample data](./query-sample-data)
24
24
 
@@ -3,7 +3,7 @@ title: "Query Sample Data"
3
3
  description: "Part 3 of the Build an Agent tutorial. Add a run_sql tool over a local sample dataset and watch the tool loop."
4
4
  ---
5
5
 
6
- 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`.
6
+ The analytics assistant can hold a conversation, but it can't see a single row of data. Give it a tool: typed input goes in, your code runs, and structured output comes back. The name the model sees is the filename, so `agent/tools/run_sql.ts` becomes the tool `run_sql`.
7
7
 
8
8
  ## Install the sample database
9
9
 
@@ -14,7 +14,7 @@ npm install sql.js
14
14
  npm install --save-dev @types/sql.js
15
15
  ```
16
16
 
17
- `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:
17
+ `sql.js` loads its WebAssembly binary from the installed package at runtime, so keep the package external. Add this `build` property inside your existing `defineAgent({ ... })` in `agent/agent.ts`, keeping your configured `model` and its imports:
18
18
 
19
19
  ```ts
20
20
  build: {
@@ -22,11 +22,11 @@ build: {
22
22
  },
23
23
  ```
24
24
 
25
- Restart the dev server after changing `externalDependencies`. eve reads this setting when the server starts.
25
+ eve reads `externalDependencies` when the server starts, so restart the dev server after changing it.
26
26
 
27
27
  ## A tiny sample dataset
28
28
 
29
- 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.
29
+ Create `agent/lib/sample-db.ts` with the dataset below. These four orders and three customers supply the data for every remaining tutorial step, with no database server or account. The dataset is recreated when the app restarts.
30
30
 
31
31
  ```ts title="agent/lib/sample-db.ts"
32
32
  import initSqlJs from "sql.js";
@@ -71,9 +71,9 @@ export async function runReadOnlySql(sql: string) {
71
71
  }
72
72
  ```
73
73
 
74
- 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.
74
+ The outer `SELECT` accepts queries, including `WITH` queries, and rejects writes and configuration statements. The helper reads at most 501 rows; the extra row lets the tool report that its 500-row output was truncated.
75
75
 
76
- 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.
76
+ A row limit does not bound the work needed to compute a query. When adapting the tool to a production database, use database-enforced read-only permissions and query timeouts.
77
77
 
78
78
  ## Define the run_sql tool
79
79
 
@@ -97,7 +97,7 @@ export default defineTool({
97
97
  });
98
98
  ```
99
99
 
100
- 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).
100
+ Tools run in your app's server code 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).
101
101
 
102
102
  ## Watch the tool loop
103
103
 
@@ -107,7 +107,7 @@ Restart the dev server with `npm run dev` and ask:
107
107
  Which customer has spent the most, and how much?
108
108
  ```
109
109
 
110
- 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.
110
+ 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 answers Globex with 9,900 cents ($99.00); amounts are stored in cents. eve ran the whole loop; you wrote the tool.
111
111
 
112
112
  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.
113
113
 
@@ -3,9 +3,9 @@ title: "Remember Definitions"
3
3
  description: "Part 5 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
4
4
  ---
5
5
 
6
- 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.
6
+ Every team has house definitions: "active" means a purchase in the last 30 days, revenue is net of refunds, a "week" starts Monday. State gives the analytics assistant a place to keep them so you don't re-explain them every turn.
7
7
 
8
- `defineState(name, initial)` creates a typed, named slot that survives across step and turn boundaries within a session. You read it with `get()` and change it with `update()`.
8
+ `defineState(name, initial)` creates a typed, named value that lasts across steps and turns within a session. You read it with `get()` and change it with `update()`.
9
9
 
10
10
  ## Define the glossary slot
11
11
 
@@ -63,9 +63,9 @@ export default defineTool({
63
63
  → recalls the definition, writes the matching SQL, answers
64
64
  ```
65
65
 
66
- 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.
66
+ The sample data has two high-value customers: Acme ($57) and Globex ($99). The second turn is a separate turn in the same session, and the definition is still there. eve saves state at each step, as described in [Step 2](./how-it-runs).
67
67
 
68
- 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 clear the glossary each turn? Call `glossary.update(() => ({ terms: {} }))` in a lifecycle hook. More in [State](../concepts/state).
68
+ State belongs to one session and one agent, so a subagent starts with empty state and never sees the parent's. To clear the glossary each turn, call `glossary.update(() => ({ terms: {} }))` in a [hook](../guides/hooks). More in [State](../concepts/state).
69
69
 
70
70
  → Next: [Team playbooks](./team-playbooks)
71
71
 
@@ -3,13 +3,11 @@ title: "Run Analysis"
3
3
  description: "Part 4 of the Build an Agent tutorial. Seed the sample database schema into the sandbox workspace, then compute and chart beyond SQL."
4
4
  ---
5
5
 
6
- 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.
7
-
8
- This takes two pieces. First seed reference files the model can read, then compute against them.
6
+ 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: an isolated bash environment with a `/workspace` filesystem. Every agent gets exactly one. First seed reference files the model can read, then compute against them.
9
7
 
10
8
  ## Seed the schema into the workspace
11
9
 
12
- 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.
10
+ Seed the sample database schema into the sandbox so the model isn't guessing at table shapes. eve copies everything under `agent/sandbox/workspace/` into the sandbox's `/workspace` directory when the session starts.
13
11
 
14
12
  ```text
15
13
  agent/sandbox/
@@ -25,13 +23,13 @@ CREATE TABLE orders (id INTEGER, customer_id INTEGER, amount_cents INTEGER,
25
23
  CREATE TABLE customers (id INTEGER, name TEXT, plan TEXT);
26
24
  ```
27
25
 
28
- 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.
26
+ eve lists the top-level `/workspace` entries for the model, so it knows `schema.sql` is there to read. A `workspace/` folder needs no sandbox definition; you add one next to install the chart dependencies.
29
27
 
30
28
  ## Install the chart dependencies
31
29
 
32
- 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`. 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 yet.
30
+ 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`. The `just-bash` fallback cannot run Python or install packages, and Python on your laptop isn't visible to the sandbox. To skip local containers for now, [continue to the next chapter](./remember-definitions).
33
31
 
34
- The default eve images for Docker 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:
32
+ The default eve images for Docker and Vercel Sandbox include Python, but not matplotlib. Add this definition alongside `workspace/` to install matplotlib in a virtual environment without changing the system Python:
35
33
 
36
34
  ```ts title="agent/sandbox/sandbox.ts"
37
35
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -58,7 +56,7 @@ export const environment = DefaultSandbox.environment({
58
56
  export default defineSandbox(() => environment.open());
59
57
  ```
60
58
 
61
- Preparation 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 preparation. The same definition uses Vercel Sandbox after deployment to Vercel.
59
+ Preparation runs when eve builds the sandbox template, and sessions inherit the installed environment. The first build downloads from Ubuntu package repositories and PyPI, so keep the default network policy. A custom `deny-all` or allow-list policy must permit these downloads. After deployment to Vercel, the same definition runs on Vercel Sandbox.
62
60
 
63
61
  Restart `npm run dev` after adding the definition. Before asking for a chart, send this message in the TUI:
64
62
 
@@ -66,11 +64,11 @@ Restart `npm run dev` after adding the definition. Before asking for a chart, se
66
64
  Run /workspace/.venv/bin/python -c "import matplotlib; print(matplotlib.__version__)" in the sandbox.
67
65
  ```
68
66
 
69
- 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.
67
+ The command should print `3.10.8`. If setup fails, find the failing command in the dev server's sandbox logs and resolve it before continuing.
70
68
 
71
69
  ## Compute and chart in the sandbox
72
70
 
73
- 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()`:
71
+ The built-in `bash`, `read_file`, and `write_file` tools already target the sandbox. When you write your own analysis tools, get the sandbox with `ctx.getSandbox()`:
74
72
 
75
73
  ```ts title="agent/tools/chart_series.ts"
76
74
  import { randomUUID } from "node:crypto";
@@ -135,9 +133,9 @@ export default defineTool({
135
133
  });
136
134
  ```
137
135
 
138
- The tool uses the Python environment installed in bootstrap. `matplotlib.use('Agg')` selects a renderer that writes PNGs without a desktop display.
136
+ `matplotlib.use('Agg')` selects a renderer that writes PNGs without a desktop display.
139
137
 
140
- `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.
138
+ `sandbox.run()` returns an exit code instead of throwing when the command fails, so check `exitCode` before returning a chart path. Throwing gives the model the failed command's output, so it reports the failure instead of claiming a chart exists.
141
139
 
142
140
  Ask for a chart using the sample data from Step 3:
143
141
 
@@ -145,13 +143,13 @@ Ask for a chart using the sample data from Step 3:
145
143
  Plot daily order revenue in dollars for May 2026.
146
144
  ```
147
145
 
148
- 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.
146
+ 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.
149
147
 
150
148
  ## Save the chart to your computer
151
149
 
152
- 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.
150
+ A sandbox path is not a download URL or a file on your laptop. `readBinaryFile` copies the 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 base64 data stays out of its context. The TUI shows tool results as text and does not save or preview the PNG.
153
151
 
154
- 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:
152
+ Create this script in your project root. It asks for a chart through the same local HTTP API as the TUI, then saves the tool result as `chart.png` in the current directory:
155
153
 
156
154
  ```ts title="save-chart.ts"
157
155
  import { writeFile } from "node:fs/promises";
@@ -204,25 +202,25 @@ if (!saved) {
204
202
  console.log(`Saved ${resolve("chart.png")}`);
205
203
  ```
206
204
 
207
- Keep `npm run dev` running. In a second terminal, run the script with the actual URL printed by the dev server; for example:
205
+ Keep `npm run dev` running. In a second terminal, run the script with the URL the dev server printed:
208
206
 
209
207
  ```bash
210
208
  node save-chart.ts http://localhost:2000
211
209
  ```
212
210
 
213
- 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.
211
+ Open the saved `chart.png` in your image viewer. The script runs in a separate session from your TUI conversation, overwrites an existing `chart.png`, and fails if the turn returns no chart.
214
212
 
215
- 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.
213
+ 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.
216
214
 
217
- 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 `call.settled` output to build an image preview or download control. Returning bytes from a tool does not add that UI automatically.
215
+ To save a chart from a hosted agent, pass the deployment URL and configure [client authentication](../guides/client/overview#authentication). In a web UI, build an image preview or download control from the same `call.settled` output. Returning bytes from a tool adds no UI by itself.
218
216
 
219
- 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.
217
+ This example limits charts to 1 MiB because eve saves tool outputs in the session's history. For larger files, copy the bytes to your application's file storage and return an authorized download URL. Sandbox files are not permanent artifact storage.
220
218
 
221
219
  ## Secrets stay out of the sandbox
222
220
 
223
- The sandbox doesn't inherit your app's `process.env`. Secrets you pass explicitly through an environment or per-call `env` option are available inside the sandbox. 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.
221
+ The sandbox doesn't inherit your app's `process.env`; only secrets you pass explicitly through an environment or per-call `env` option reach it. `run_sql` and the sample database run in your app, and only query results reach the chart tool, so the sandbox needs no database credentials.
224
222
 
225
- 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).
223
+ The sandbox runs on your laptop during `eve dev` and on Vercel Sandbox when deployed. Backends, when sandboxes start and stop, and network policy are in [Sandbox](../sandbox).
226
224
 
227
225
  → Next: [Remember definitions](./remember-definitions)
228
226
 
@@ -3,17 +3,17 @@ title: "Ship It"
3
3
  description: "Part 8 of the Build an Agent tutorial. Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
4
4
  ---
5
5
 
6
- The analytics assistant runs in the TUI. Now add a web dashboard and deploy a private, single-user version on Vercel. This example protects the sample app with a username and password. It does not require another authentication service.
6
+ The analytics assistant runs in the TUI. Next, add a web dashboard and deploy a private, single-user version on Vercel, protected by a username and password with no separate authentication service.
7
7
 
8
8
  ## Add the Web Chat app
9
9
 
10
- Step 1 scaffolded the agent without a web frontend. Add one now with `eve add channel/web`, run from the `analytics-assistant/` directory, and choose **Next.js** when it asks which framework to use:
10
+ Step 1 scaffolded the agent without a web frontend. From the `analytics-assistant/` directory, run `eve add channel/web` and choose **Next.js** when it asks which framework to use:
11
11
 
12
12
  ```bash
13
13
  npx eve add channel/web
14
14
  ```
15
15
 
16
- This adds a Next.js app (`next.config.ts`, `app/page.tsx`, `app/_components/`) wired to the existing eve channel, plus the chat UI components and their dependencies. Run `npm install` afterward to install the added packages. The generated `next.config.ts` wraps your config with `withEve`, which wires the eve routes automatically:
16
+ This adds a Next.js app (`next.config.ts`, `app/page.tsx`, `app/_components/`) wired to the existing eve channel, plus the chat UI components and their dependencies. Run `npm install` afterward. The generated `next.config.ts` wraps your config with `withEve`, which wires the eve routes:
17
17
 
18
18
  ```ts title="next.config.ts"
19
19
  import type { NextConfig } from "next";
@@ -28,15 +28,15 @@ export default withEve(nextConfig);
28
28
 
29
29
  Keep the generated `app/_components/agent-chat.tsx` and `agent-message.tsx` components. `app/page.tsx` already renders the chat, and `useEveAgent` handles session creation and streaming.
30
30
 
31
- The generated UI displays tool results and errors, authorization links, approval buttons, and question forms. The spend approval from [Guard the spend](./guard-the-spend) needs those controls to resume a waiting turn. A component that renders only text messages leaves those interactions unavailable.
31
+ The generated UI displays tool results and errors, authorization links, approval buttons, and question forms. The spend approval from [Guard the spend](./guard-the-spend) needs those controls to resume a waiting turn, so a component that renders only text leaves it stuck.
32
32
 
33
- Run `npm run dev`, open the local web URL printed by the server, and ask for an unfiltered revenue query. Confirm that the approval appears and that approving it lets the query finish. You can customize the UI after this flow works; see [Frontend](../guides/frontend/overview).
33
+ Run `npm run dev`, open the local web URL the server prints, and ask for an unfiltered revenue query. Confirm that the approval appears and that approving it lets the query finish. To customize the UI afterward, see [Frontend](../guides/frontend/overview).
34
34
 
35
35
  ## Replace `placeholderAuth`
36
36
 
37
- The scaffold's channel ships with `placeholderAuth()`, which rejects unauthenticated production requests. Replace it with a verifier that checks credentials on every request. Never return a fixed user without checking the request.
37
+ The scaffold's channel ships with `placeholderAuth()`, which rejects unauthenticated production requests. Replace it with a verifier that checks credentials on every request; never return a fixed user without checking the request.
38
38
 
39
- Create `agent/lib/auth.ts`. This uses eve's HTTP Basic verifier, which compares passwords in constant time. Missing environment variables, missing credentials, and wrong credentials all fail closed:
39
+ Create `agent/lib/auth.ts`. eve's HTTP Basic verifier compares passwords in constant time, and missing environment variables, missing credentials, and wrong credentials all fail closed:
40
40
 
41
41
  ```ts title="agent/lib/auth.ts"
42
42
  import { verifyHttpBasic, withAuthChallenges } from "eve/channels/auth";
@@ -63,7 +63,7 @@ export const appAuth = withAuthChallenges(
63
63
  );
64
64
  ```
65
65
 
66
- Replace `agent/channels/eve.ts`, removing the earlier `devTeam` entry. The eve channel checks `appAuth` for session creation, messages, controls, and streams. The remaining helpers preserve authenticated Vercel CLI access and local development:
66
+ Replace `agent/channels/eve.ts`, dropping the `devTeam` entry from Step 6. The eve channel checks `appAuth` for session creation, messages, controls, and streams; the other helpers keep authenticated Vercel CLI access and local development:
67
67
 
68
68
  ```ts title="agent/channels/eve.ts"
69
69
  import { eveChannel } from "eve/channels/eve";
@@ -75,9 +75,9 @@ export default eveChannel({
75
75
  });
76
76
  ```
77
77
 
78
- The verified username becomes the user principal. The `growth` team selects the sample playbook from [Team playbooks](./team-playbooks). Keep these credentials private to one person. A shared password does not give each person a separate identity or isolated sessions. For a multi-user app, use a real session provider and enforce [session ownership](../guides/auth-and-route-protection#what-reaches-ctxsessionauth).
78
+ The verified username becomes the signed-in user. The `growth` team selects the sample playbook from [Team playbooks](./team-playbooks). Keep these credentials private to one person, because a shared password gives no one a separate identity or isolated sessions. For a multi-user app, use a real session provider and check [which user each session belongs to](../guides/auth-and-route-protection#what-reaches-ctxsessionauth).
79
79
 
80
- Add `proxy.ts` at the project root so opening the dashboard triggers the browser's native username/password prompt. It protects the generated UI routes; eve API routes keep their channel auth, so an OIDC-authenticated CLI request does not encounter a browser-only gate:
80
+ Add `proxy.ts` at the project root so opening the dashboard triggers the browser's username/password prompt. It protects only the generated UI routes; eve API routes keep their channel auth, so OIDC-authenticated CLI requests still work:
81
81
 
82
82
  ```ts title="proxy.ts"
83
83
  import { routeAuth } from "eve/channels/auth";
@@ -93,7 +93,7 @@ export async function proxy(request: Request) {
93
93
  export const config = { matcher: ["/", "/s/:path*"] };
94
94
  ```
95
95
 
96
- After login, the browser sends the credentials on same-origin requests from the generated chat. When a browser sends an `Origin` header, the Basic verifier also requires [`Sec-Fetch-Site: same-origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site). Keep the auth module server-side: never put the password in a React component, a `NEXT_PUBLIC_` variable, or a client-side `useEveAgent` option. Use HTTPS for deployed HTTP Basic authentication.
96
+ After login, the browser sends the credentials on same-origin requests from the generated chat. When a browser sends an `Origin` header, `appAuth` also requires [`Sec-Fetch-Site: same-origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site). Keep the auth module server-side: never put the password in a React component, a `NEXT_PUBLIC_` variable, or a client-side `useEveAgent` option. Use HTTPS for deployed HTTP Basic authentication.
97
97
 
98
98
  ## Deploy to Vercel
99
99
 
@@ -105,15 +105,15 @@ npx vercel@latest env add ANALYTICS_USERNAME preview
105
105
  npx vercel@latest env add ANALYTICS_PASSWORD preview
106
106
  ```
107
107
 
108
- Before deploying, configure the model credential your agent uses in the project's Preview environment; local `.env` values are not uploaded by deployment. If you used a local ChatGPT subscription, switch `agent/agent.ts` to an AI Gateway model and configure `AI_GATEWAY_API_KEY` for that model. Subscription credentials stay on your laptop. See [Deployment](../guides/deployment/overview) for model and runtime configuration.
108
+ Before deploying, configure your model credential in the project's Preview environment, because deployment doesn't upload local `.env` values. If you used a local ChatGPT subscription, which stays on your laptop, switch `agent/agent.ts` to an AI Gateway model and configure `AI_GATEWAY_API_KEY`. See [Deployment](../guides/deployment/overview) for model and runtime configuration.
109
109
 
110
110
  ```bash
111
111
  npx vercel@latest deploy
112
112
  ```
113
113
 
114
- Open the HTTPS preview URL and enter the configured username and password. Create a session and ask a sample-data question. In a private browser window, cancel the login prompt and verify the dashboard is denied. A `POST /eve/v1/session` request without credentials must also return `401`.
114
+ Open the HTTPS preview URL, enter the username and password, and ask a sample-data question. In a private browser window, cancel the login prompt and verify the dashboard is denied. A `POST /eve/v1/session` request without credentials must also return `401`.
115
115
 
116
- The authenticated web app and eve runtime share the same origin, and the sandbox runs on Vercel Sandbox. You can also smoke-test the deployment through the authenticated CLI:
116
+ The web app and the agent share one origin, and the sandbox runs on Vercel Sandbox. You can also smoke-test the deployment through the authenticated CLI:
117
117
 
118
118
  ```bash
119
119
  npx eve remote connect --url https://your-analytics-app.vercel.app
@@ -121,25 +121,25 @@ npx eve remote connect --url https://your-analytics-app.vercel.app
121
121
 
122
122
  For a production deployment, add the username, password, and model credential to the Production environment too, then run `npx vercel@latest deploy --prod`. Missing Basic credentials keep browser access closed.
123
123
 
124
- The private assistant queries the sample data, runs analysis in a sandbox, charts the results, remembers definitions, loads the Growth playbook, and asks before an expensive query.
124
+ The private assistant queries the sample data, runs analysis in a sandbox, and charts the results. It also remembers definitions, loads the Growth playbook, and asks before an expensive query.
125
125
 
126
126
  ## What you learned
127
127
 
128
- Across the eight steps you built and shipped one agent, and along the way you used:
128
+ Across the eight steps you built and shipped one agent using:
129
129
 
130
130
  - **Tools** to give the model typed actions (`run_sql`, `chart_series`, `define_metric`).
131
131
  - **The sandbox** to compute and chart beyond SQL in an isolated `/workspace`.
132
132
  - **State** (`defineState`) to remember the team's glossary across turns.
133
133
  - **Dynamic skills** (`defineDynamic`) to load the right team playbook per caller.
134
134
  - **Human-in-the-loop** approval (`approval`) to gate expensive queries.
135
- - **Channel auth** to turn a request into an authenticated principal.
136
- - **Deployment** to Vercel, with the runtime behind your web app.
135
+ - **Channel auth** to turn a request into a signed-in user.
136
+ - **Deployment** to Vercel, with the agent behind your web app.
137
137
 
138
138
  ## Next steps
139
139
 
140
140
  - [Connect a warehouse](./connect-a-warehouse) when you have a data service to use in place of the sample dataset.
141
141
  - [MCP connections](../connections/mcp) for tool allowlists and per-connection approval.
142
- - [Sandbox](../sandbox) for backends, lifecycle, and network policy.
142
+ - [Sandbox](../sandbox) for backends, when sandboxes start and stop, and network policy.
143
143
  - [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.
144
144
  - [Authentication](../guides/auth-and-route-protection) for production auth patterns.
145
145