eve 0.85.0 → 0.86.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 (56) hide show
  1. package/README.md +7 -4
  2. package/dist/CHANGELOG.md +38 -0
  3. package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
  4. package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
  5. package/dist/src/cli/dev/tui/runner.d.ts +1 -1
  6. package/dist/src/cli/dev/tui/runner.js +1 -1
  7. package/dist/src/cli/run.js +1 -1
  8. package/dist/src/compiled/.vendor-stamp.json +4 -4
  9. package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
  10. package/dist/src/compiled/@vercel/schedules/index.js +2 -2
  11. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  12. package/dist/src/execution/proxied-deliver-step.js +1 -1
  13. package/dist/src/execution/session/active-turn.js +1 -1
  14. package/dist/src/execution/session/answer-caller.d.ts +9 -5
  15. package/dist/src/execution/session/answer-caller.js +1 -1
  16. package/dist/src/execution/session/principal.d.ts +8 -0
  17. package/dist/src/execution/session/principal.js +1 -1
  18. package/dist/src/execution/session/program.js +1 -1
  19. package/dist/src/execution/session/turn-step.js +1 -1
  20. package/dist/src/execution/session/turn.js +1 -1
  21. package/dist/src/execution/session-callback-request.js +1 -1
  22. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  23. package/dist/src/harness/attachment-staging.d.ts +2 -2
  24. package/dist/src/harness/attachment-staging.js +1 -1
  25. package/dist/src/internal/application/stamped-package-version.js +1 -1
  26. package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
  27. package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
  28. package/dist/src/public/schedules/providers/vercel.js +1 -1
  29. package/dist/src/runtime/subagents/workflow.js +1 -1
  30. package/dist/src/setup/scaffold/create/project.js +1 -1
  31. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  32. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  33. package/docs/channels/eve.mdx +1 -5
  34. package/docs/concepts/project-structure.mdx +1 -1
  35. package/docs/concepts/security-model.md +4 -0
  36. package/docs/concepts/upgrade-to-v27-events.md +68 -0
  37. package/docs/getting-started.mdx +2 -0
  38. package/docs/guides/auth-and-route-protection.md +1 -0
  39. package/docs/guides/client/streaming.mdx +1 -1
  40. package/docs/guides/deployment/self-hosting.md +1 -1
  41. package/docs/guides/frontend/meta.json +1 -0
  42. package/docs/guides/frontend/nextjs.mdx +329 -121
  43. package/docs/guides/frontend/overview.mdx +115 -335
  44. package/docs/guides/frontend/tanstack.mdx +1 -1
  45. package/docs/guides/frontend/use-eve-agent-svelte.mdx +5 -5
  46. package/docs/guides/frontend/use-eve-agent-vue.mdx +5 -5
  47. package/docs/guides/frontend/use-eve-agent.mdx +385 -0
  48. package/docs/guides/hooks.md +1 -1
  49. package/docs/guides/remote-agents.md +4 -2
  50. package/docs/guides/self-modification.md +6 -0
  51. package/docs/reference/cli.md +1 -2
  52. package/docs/sandbox/index.mdx +1 -1
  53. package/package.json +13 -21
  54. package/CHANGELOG.md +0 -3106
  55. package/dist/src/self-modification/agent.d.ts +0 -12
  56. package/dist/src/self-modification/agent.js +0 -1
@@ -1,46 +1,97 @@
1
1
  ---
2
2
  title: "Next.js"
3
- description: "Run an eve agent and a Next.js app as one project with withEve."
3
+ description: "Add an eve chat to a Next.js app, from setup and authentication to saved conversations and deployment."
4
4
  ---
5
5
 
6
- `eve/next` connects a Next.js app to one or more eve agents. Wrap your Next.js config with `withEve(nextConfig)` to run the app and agents with one development command and deploy them as one Vercel project. Browser requests use same-origin routes; the agent runtimes remain separate services.
6
+ Your Next.js app and your eve agent run side by side on the same domain. Pages go to Next.js, and requests to `/eve/v1/*` go to the agent. The agent runs as its own service, never inside the Next.js server. Your React code is the same whichever setup you pick below.
7
7
 
8
- Use this integration when Next.js owns the application's development and deployment lifecycle. If the frontend is a peer of an agent workspace, compose the services with [`eve/vercel`](../deployment/vercel#compose-agents-with-other-vercel-services) on Vercel or your [self-hosted process manager and proxy](../deployment/self-hosting#run-workspace-members). A peer frontend can use `eve/react` without `eve/next`. See [Project Structure](/docs/concepts/project-structure#configure-a-web-deployment) for the choice.
8
+ ## Choose a setup
9
9
 
10
- ## Prerequisites
10
+ There are two ways to connect the app and the agent. Both deploy as one Vercel project.
11
11
 
12
- - The `eve` package installed in your project (`npm install eve@latest`).
13
- - An existing eve agent directory. If you don't have one, start from [Getting Started](../../getting-started).
14
- - A Next.js app, or an eve project where you want to generate one below.
12
+ | | Vercel services (recommended) | Next.js hosts the agent |
13
+ | ------------ | ------------------------------ | ----------------------------- |
14
+ | What you add | A root `vercel.ts` | A wrapper in `next.config.ts` |
15
+ | Run locally | `vercel dev --local` | `next dev` |
16
+ | Self-host | Run the app and agent yourself | `next start` runs both |
15
17
 
16
- ## Add the generated Web Chat app
18
+ Start with **Vercel services**. Choose Next.js hosting when Next.js should run everything, for example when you add an agent to an existing Next.js app that deploys from the project root.
17
19
 
18
- Install the generated Web Chat app from a standalone agent project, and choose **Next.js** when the installer asks which framework to use:
20
+ ## Create a chat app
21
+
22
+ From your agent project, run the Web Chat installer:
19
23
 
20
24
  ```bash
21
25
  eve add channel/web
22
26
  ```
23
27
 
24
- For an agent workspace, select the member the chat should call:
28
+ It asks three questions:
25
29
 
26
- ```bash
27
- eve add channel/web --agent support
30
+ 1. **Framework:** choose **Next.js**.
31
+ 2. **Hosting:** choose **Vercel services**, or **Next.js** to have Next.js host the agent.
32
+ 3. **Authentication:** choose **Sign in with Vercel**, or set it up yourself. See [Authenticate users](#authenticate-users).
33
+
34
+ In a project with several agents, add `--agent <name>` to pick the one the chat talks to.
35
+
36
+ The installer creates a Next.js app in `apps/web/`:
37
+
38
+ ```text
39
+ project/
40
+ ├── agent/
41
+ │ └── channels/eve.ts # who can call the agent from a browser
42
+ ├── apps/web/
43
+ │ ├── app/
44
+ │ │ ├── _components/ # the chat UI
45
+ │ │ ├── page.tsx # landing page
46
+ │ │ └── s/ # conversation pages
47
+ │ └── next.config.ts
48
+ ├── package.json # dependencies and scripts
49
+ └── vercel.ts # Vercel services only
28
50
  ```
29
51
 
30
- The installer configures the chat for the selected agent. By default, it adds a shared Next.js
31
- application under `apps/web`; if a root Web Chat app already exists, it configures that app instead.
32
- For Next.js hosting, the installer wraps `next.config.ts` with `withEve()`. When setting up a new
33
- app, choose **Next.js** to host the integration. The generated chat uses same-origin `/eve/v1/*`
34
- routes for a standalone agent or `/eve/<name>/v1/*` routes for a workspace member. Running the
35
- installer from a workspace root without selecting a member is not supported.
52
+ Start it with the command the installer prints:
53
+
54
+ | Command | Starts |
55
+ | ----------------- | ------------------------------------------------------ |
56
+ | `npm run dev:all` | The app and the agent together (Vercel services) |
57
+ | `npm run dev:web` | The app. With Next.js hosting, it starts the agent too |
58
+ | `npm run dev` | The agent alone, in the eve terminal UI |
59
+
60
+ `dev:all` needs Vercel CLI 59.16.0 or newer, but not a linked project.
61
+
62
+ Before you deploy, replace the placeholder auth the installer generates. Until then, production browser requests get `401`. See [Authenticate users](#authenticate-users).
36
63
 
37
- Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
64
+ ## Add eve to an existing app
38
65
 
39
- To integrate an existing Next.js application without generating a chat UI, follow the steps below.
40
- To deploy the frontend and agents as separate Vercel services, choose **Vercel services** during
41
- setup instead; see the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment).
66
+ ### With Vercel services
67
+
68
+ Leave `next.config.ts` alone. Add a `vercel.ts` at the project root that tells Vercel where your app lives:
69
+
70
+ ```ts title="vercel.ts"
71
+ import { withEve } from "eve/vercel";
72
+
73
+ export default await withEve({
74
+ services: {
75
+ web: {
76
+ framework: "nextjs",
77
+ root: "apps/web",
78
+ buildCommand: "node ../../node_modules/next/dist/bin/next build",
79
+ },
80
+ },
81
+ routes: [{ src: "^(.*)$", destination: { type: "service", service: "web" } }],
82
+ });
83
+ ```
42
84
 
43
- ## Wrap the Next.js config
85
+ `withEve` adds your agents and their routes for you: `/eve/v1/*` for one agent, or `/eve/<name>/v1/*` for each agent in a workspace.
86
+
87
+ - Install `eve` in the root `package.json`.
88
+ - Remove any `vercel.json`.
89
+
90
+ See [Compose agents with other Vercel services](../deployment/vercel#compose-agents-with-other-vercel-services) for more options.
91
+
92
+ ### With Next.js hosting
93
+
94
+ Wrap your Next.js config:
44
95
 
45
96
  ```ts title="next.config.ts"
46
97
  import type { NextConfig } from "next";
@@ -51,162 +102,319 @@ const nextConfig: NextConfig = {};
51
102
  export default withEve(nextConfig);
52
103
  ```
53
104
 
54
- By default `withEve(nextConfig)` looks for an `agent/` folder inside your Next.js project root and mounts its API at `/eve/v1/*`. When the project root is an eve workspace with `agents/<name>/` members, it discovers every member and mounts each at `/eve/<name>/v1/*` instead. You do not need an explicit `agents` map for this layout.
105
+ `withEve` looks for your agent next to `next.config.ts`. If the agent lives somewhere else, point to it:
55
106
 
56
- If one agent lives somewhere else, point at it with `eveRoot`:
107
+ ```ts title="apps/web/next.config.ts"
108
+ export default withEve(nextConfig, { eveRoot: "../.." });
109
+ ```
57
110
 
58
- ```ts
59
- export default withEve(nextConfig, {
60
- eveRoot: "../my-agent",
61
- });
111
+ This setup needs Next.js 16 and React 19. See [`withEve` options](#witheve-options) for the rest.
112
+
113
+ ## Build the chat UI
114
+
115
+ Call `useEveAgent` from a Client Component:
116
+
117
+ ```tsx title="apps/web/app/_components/chat.tsx"
118
+ "use client";
119
+
120
+ import { useEveAgent } from "eve/react";
121
+
122
+ export function Chat() {
123
+ const agent = useEveAgent();
124
+ const isResuming = agent.status === "resuming";
125
+
126
+ return (
127
+ <form
128
+ onSubmit={(event) => {
129
+ event.preventDefault();
130
+ const message = String(new FormData(event.currentTarget).get("message") ?? "").trim();
131
+ if (message.length > 0 && !isResuming) {
132
+ void agent.send(message);
133
+ }
134
+ }}
135
+ >
136
+ {agent.messages.map((message) => (
137
+ <article key={message.id}>
138
+ <header>{message.role}</header>
139
+ {message.parts.map((part, index) =>
140
+ part.type === "text" ? <p key={part.id ?? index}>{part.text}</p> : null,
141
+ )}
142
+ </article>
143
+ ))}
144
+ <input disabled={isResuming} name="message" />
145
+ <button disabled={isResuming} type="submit">
146
+ Send
147
+ </button>
148
+ </form>
149
+ );
150
+ }
62
151
  ```
63
152
 
64
- ## Mount agents outside a workspace
153
+ A real chat also needs to show tool calls, approvals, questions, and sign-ins. Without them, a turn that waits on the user can't continue. The generated chat handles all of these. To build your own, see [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) and [Sign-ins](./overview#sign-ins-and-other-interactions).
65
154
 
66
- To mount agents that are not members of the project-level `agents/` workspace, use `agents`. String values are agent roots; object values can override the build command or private production service prefix for that agent:
155
+ ## Give each conversation a URL
67
156
 
68
- ```ts
69
- export default withEve(nextConfig, {
70
- agents: {
71
- support: "./apps/support-agent",
72
- billing: {
73
- root: "./apps/billing-agent",
74
- buildCommand: "pnpm build:billing-agent",
75
- servicePrefix: "/_eve_internal/billing",
76
- },
77
- },
78
- });
157
+ The generated chat gives every conversation its own address:
158
+
159
+ | URL | Shows |
160
+ | ---------------- | ----------------------------------------------------------- |
161
+ | `/` | The landing page |
162
+ | `/s` | A new, empty conversation |
163
+ | `/s/[sessionId]` | A saved conversation, including any reply still in progress |
164
+
165
+ The conversation page passes its session ID to the hook:
166
+
167
+ ```tsx title="apps/web/app/s/[sessionId]/page.tsx"
168
+ import { SessionChat } from "@/app/_components/session-chat";
169
+
170
+ export default async function SessionPage({
171
+ params,
172
+ }: {
173
+ readonly params: Promise<{ readonly sessionId: string }>;
174
+ }) {
175
+ const { sessionId } = await params;
176
+ return <SessionChat key={sessionId} sessionId={sessionId} />;
177
+ }
79
178
  ```
80
179
 
81
- Named agents mount under `/eve/<name>/v1/*`. Call the matching agent from React with `agent`:
180
+ ```tsx title="apps/web/app/_components/session-chat.tsx"
181
+ "use client";
82
182
 
83
- ```tsx
84
- const support = useEveAgent({ agent: "support" });
85
- const billing = useEveAgent({ agent: "billing" });
183
+ import { useEveAgent } from "eve/react";
184
+
185
+ export function SessionChat({ sessionId }: { readonly sessionId: string }) {
186
+ const agent = useEveAgent({
187
+ initialSession: { sessionId, streamIndex: 0 },
188
+ resume: true,
189
+ });
190
+ // Render agent.messages as in the basic chat.
191
+ }
86
192
  ```
87
193
 
88
- Use either `eveRoot` or `agents`, not both. `eveRoot` remains the shorthand for a single unnamed agent mounted at `/eve/v1/*`.
194
+ Three things to get right:
89
195
 
90
- Generated agent services build with `EVE_PUBLIC_ROUTE_PREFIX` set to the agent's public mount (for example `/eve/support`) so framework-minted callback URLs — OAuth connection callbacks and remote-subagent session callbacks — resolve to the public per-agent path. If you configure eve services manually in `vercel.json` instead, export that variable in each named agent's build command.
196
+ - **Change the URL without the router.** Once `/s` creates a session, switch the address to `/s/{sessionId}` with the browser's own `replaceState`. Next.js patches `window.history`, and going through its router would remount the page and cut off the reply:
91
197
 
92
- ### `withEve` options
198
+ ```ts
199
+ History.prototype.replaceState.call(
200
+ window.history,
201
+ window.history.state,
202
+ "",
203
+ `/s/${encodeURIComponent(sessionId)}`,
204
+ );
205
+ ```
93
206
 
94
- All fields are optional.
207
+ - **Use a `key` to switch conversations.** Keying the chat on the session ID gives each conversation a fresh hook.
208
+ - **Disable input while loading.** While `status` is `"resuming"`, show the messages but don't accept new ones.
95
209
 
96
- | Option | Type | Default | Purpose |
97
- | -------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
- | `eveRoot` | `string` | Next.js app root | Eve project root, relative to the Next.js app root unless absolute. It may contain either one `agent/` or an `agents/` workspace. Do not combine with `agents`. |
99
- | `agents` | `Record<string, ...>` | inferred for a workspace | Named eve agents to mount under `/eve/<name>/v1/*`. `withEve()` discovers project-level `agents/<name>/` members when `agents` and `eveRoot` are unset; otherwise each value is a root string or `{ root, buildCommand?, servicePrefix? }`. |
100
- | `eveBuildCommand` | `string` | generated | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`. |
101
- | `servicePrefix` | `string` | `"/_eve_internal/eve"` | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix. |
102
- | `devServerTimeoutMs` | `number` | `180000` | Maximum time to wait for each eve development server to become available. |
210
+ ## Authenticate users
103
211
 
104
- When the Next.js app is a peer of an eve project, select its root without repeating every agent path. The root may contain either one `agent/` or an `agents/` workspace:
212
+ The browser calls the agent on your own domain, so it sends your app's cookies along. The agent checks them in `agent/channels/eve.ts`.
105
213
 
106
- ```ts title="apps/web/next.config.ts"
107
- import type { NextConfig } from "next";
108
- import { withEve } from "eve/next";
214
+ Replace the generated `placeholderAuth()` with a function that reads your app's session:
109
215
 
110
- const nextConfig: NextConfig = {};
216
+ ```ts title="agent/channels/eve.ts"
217
+ import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
218
+ import { eveChannel } from "eve/channels/eve";
219
+ import { getSession } from "@/lib/auth";
111
220
 
112
- export default withEve(nextConfig, {
113
- eveRoot: "../..",
221
+ const appSession: AuthFn<Request> = async (request) => {
222
+ const session = await getSession(request);
223
+ if (!session) return null;
224
+ return {
225
+ authenticator: "app",
226
+ principalId: session.userId,
227
+ principalType: "user",
228
+ attributes: {},
229
+ };
230
+ };
231
+
232
+ export default eveChannel({
233
+ auth: [appSession, vercelOidc(), localDev()],
114
234
  });
115
235
  ```
116
236
 
117
- For slow cold starts, increase the development timeout:
237
+ eve tries each entry in order:
118
238
 
119
- ```ts
120
- export default withEve(nextConfig, {
121
- devServerTimeoutMs: 300_000,
239
+ - `appSession` accepts your signed-in users.
240
+ - `vercelOidc()` accepts your own server code and the eve terminal UI.
241
+ - `localDev()` accepts requests during local development only.
242
+
243
+ For a public demo, `none()` from `eve/channels/auth` lets anyone in. Don't use it for private data. See [Authentication](../auth-and-route-protection) for more.
244
+
245
+ If your app uses tokens instead of cookies, pass them to the hook:
246
+
247
+ ```tsx
248
+ const agent = useEveAgent({
249
+ auth: { bearer: async () => await getAccessToken() },
122
250
  });
123
251
  ```
124
252
 
125
- ## Call the hook
253
+ ### Sign in with Vercel
126
254
 
127
- For a single unnamed agent, call [`useEveAgent`](./overview) without `agent` or `baseUrl`. For named agents, whether discovered from a workspace or configured explicitly, pass the name:
255
+ Choose **Sign in with Vercel** in the installer to let members of your Vercel team sign in, with nothing to build. It needs a linked Vercel project. Local development skips sign-in. See [Web Chat with Sign in with Vercel](../../channels/eve#web-chat-with-sign-in-with-vercel) for details.
128
256
 
129
- ```tsx
130
- "use client";
257
+ ## Save conversations
131
258
 
132
- import { useEveAgent } from "eve/react";
259
+ eve already keeps every conversation, so a URL with a session ID is enough to reopen one. Add your own database when you want a chat list, titles, or faster page loads.
260
+
261
+ Keep your chat record separate from the eve session. Your record holds the title and owner; eve holds the messages. Store the session and its events alongside your record:
133
262
 
134
- export function SupportStatus() {
135
- const support = useEveAgent({ agent: "support" });
136
- return <p>{support.status}</p>;
263
+ ```ts
264
+ type SavedChat = {
265
+ id: string;
266
+ ownerId: string;
267
+ session: ClientSessionState | null; // from onSessionChange
268
+ events: SessionStreamEvent[]; // from onEvent
269
+ };
270
+ ```
271
+
272
+ Then:
273
+
274
+ 1. **Create the chat record before the first message.** If the user reloads mid-reply, the page can still find the conversation.
275
+ 2. **Save as things happen.** Save `session` in `onSessionChange` and each event in `onEvent`. Don't wait for the reply to finish: a turn waiting on the user hasn't finished.
276
+ 3. **Load on the server.** Read the saved chat in a Server Component, and pass `events` and `session` to the Client Component as `initialEvents` and `initialSession`, with `resume: true`. Saved messages show at once, and the live reply picks up from there.
277
+ 4. **Store `session` as eve gives it to you.** Don't compute the cursor from the number of events.
278
+
279
+ See [Resume a saved session](./use-eve-agent#resume-a-saved-session) for exactly how saved events and catch-up fit together. Upgrading saved chats from eve v26? See [Upgrade to v27 events](../../concepts/upgrade-to-v27-events).
280
+
281
+ ## Call the agent from server code
282
+
283
+ Route Handlers, Server Actions, and cron jobs can call the agent with `Client` from `eve/client`. Point it at your own domain, and sign requests with your project's Vercel OIDC token:
284
+
285
+ ```ts title="apps/web/app/api/summarize/route.ts"
286
+ import { getVercelOidcToken } from "@vercel/oidc";
287
+ import { Client } from "eve/client";
288
+ import { getSession } from "@/lib/auth";
289
+
290
+ export async function POST(request: Request) {
291
+ const session = await getSession(request);
292
+ if (!session) return new Response("Unauthorized", { status: 401 });
293
+
294
+ const client = new Client({
295
+ baseUrl: new URL(request.url).origin,
296
+ auth: { vercelOidc: { token: async () => await getVercelOidcToken() } },
297
+ redirect: "manual",
298
+ });
299
+
300
+ const { delivery } = await client.sessions.create({ message: "Summarize today's tickets." });
301
+ const result = await delivery.result();
302
+ return Response.json({ status: result.status });
137
303
  }
138
304
  ```
139
305
 
140
- See [Basic chat](./overview#basic-chat-react) for rendering messages and sending turns.
306
+ - Check who's calling before you call the agent, as above. The OIDC token gives your code the app's own access, so an unchecked route would let anyone use it.
307
+ - Install `@vercel/oidc`, and run `eve link` once so the token works locally.
308
+ - The token identifies your app, not a user. To act as the signed-in user, forward their cookie in `headers` instead.
309
+ - Without an incoming request, as in a cron job, use `https://${process.env.VERCEL_URL}` as the domain.
310
+
311
+ See [Client SDK](../client/overview) for more.
141
312
 
142
- Bind each chat route to its agent, and include the agent identity in durable-session URLs so the UI does not restore a session through the wrong agent route. Remount the chat component when switching agents: the hook reads `agent` when it creates its store.
313
+ ## Use multiple agents
143
314
 
144
- Requests are same-origin, so the browser sends application cookies to the agent. Each agent must verify those credentials through its own channel authentication policy. For non-cookie schemes, attach the credentials yourself:
315
+ With several agents, each one gets its own path, such as `/eve/support/v1/*`. Pick one in the hook:
145
316
 
146
317
  ```tsx
147
- const agent = useEveAgent({
148
- headers: async () => ({
149
- authorization: `Bearer ${await getAccessToken()}`,
150
- }),
318
+ const support = useEveAgent({ agent: "support" });
319
+ ```
320
+
321
+ - Give each chat page one agent, and include the agent name in its URLs.
322
+ - Remount the chat when switching agents.
323
+ - Set up authentication for each agent.
324
+
325
+ Both setups find the agents in your project automatically. With Next.js hosting, you can also list agents that live elsewhere:
326
+
327
+ ```ts title="next.config.ts"
328
+ export default withEve(nextConfig, {
329
+ agents: {
330
+ support: "./apps/support-agent",
331
+ billing: { root: "./apps/billing-agent", buildCommand: "pnpm build:billing-agent" },
332
+ },
151
333
  });
152
334
  ```
153
335
 
154
- Configure authorization for every exposed agent before accepting production browser traffic. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
336
+ Use either `eveRoot` or `agents`, not both.
155
337
 
156
- ## Use the generated Web Chat routes
338
+ ## Run, build, and deploy
157
339
 
158
- `eve init --channel-web-nextjs` and `eve add channel/web` generate a chat UI with URL-addressed durable sessions:
340
+ ### Run locally
159
341
 
160
- - `/` is the initial landing page.
161
- - `/s` opens the conversation layout without creating an eve session. The first message creates the session.
162
- - `/s/[sessionId]` attaches to that durable session, replays its transcript, and follows an in-flight turn.
342
+ - **Vercel services:** `npm run dev:all`.
343
+ - **Next.js hosting:** `npm run dev:web`. Next.js starts the agent for you. To use an agent you already started, set `EVE_BASE_URL` to its address.
163
344
 
164
- After the first message is accepted, Web Chat replaces the browser URL with `/s/{sessionId}` without remounting the active stream. Reloading that URL passes the session to `useEveAgent` with `resume: true`, so completed history is replayed and an unfinished response continues streaming. **New chat** navigates to the sessionless `/s` route; it does not reset or delete the prior session, which remains available at its URL.
345
+ ### Deploy to Vercel
165
346
 
166
- The generated UI keeps transcript scroll position in browser `sessionStorage`. This is presentation state only and is not written to the eve session.
347
+ From the project root:
167
348
 
168
- For a custom Next.js chat route, pass the route session ID explicitly:
349
+ ```bash
350
+ eve link
351
+ eve deploy
352
+ ```
169
353
 
170
- ```tsx
171
- const agent = useEveAgent({
172
- initialSession: { sessionId, streamIndex: 0 },
173
- resume: true,
174
- });
354
+ The app and each agent deploy together as one Vercel project. See [Deploy to Vercel](../deployment/vercel) for credentials and sandboxes.
355
+
356
+ <Callout type="warning" title="Next.js hosting from apps/web">
357
+ When the installer puts a Next.js-hosted app in `apps/web/`, Vercel doesn't build it by default.
358
+ In your Vercel project settings, set the Build Command to `npm run build:web` and the Output
359
+ Directory to `apps/web/.next`.
360
+ </Callout>
361
+
362
+ ### Run a production build locally
363
+
364
+ With Next.js hosting, `next start` runs the built agent too. Build both first:
365
+
366
+ ```bash
367
+ eve build
368
+ npm run build:web
369
+ next start apps/web
175
370
  ```
176
371
 
177
- See [Resumable sessions](./overview#resumable-sessions) for persistence and replay semantics.
372
+ The agent listens on port `4274`. Set `EVE_NEXT_PRODUCTION_PORT` to change it.
178
373
 
179
- ## Dev vs deploy topology
374
+ With several agents, a root `eve build` doesn't build them for `next start`. Run `eve build` in each `agents/<name>/` directory instead.
180
375
 
181
- - **Local dev.** `npm run dev` boots the eve dev server next to `next dev` and rewrites the eve routes over to it. The browser only ever talks to the Next.js origin.
182
- - **Vercel.** The web app and the eve runtime deploy as a single project. `withEve()` writes Build Output `services` for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Next.js app itself remains the default app. Vercel assembles authored [schedules](../../schedules) into the project config as Vercel Cron Jobs, including correctly prefixed jobs for named agents, while cron entries owned by the Next.js app are preserved. By default, generated services run the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
376
+ ### Self-host
183
377
 
184
- ```ts
185
- export default withEve(nextConfig, {
186
- eveBuildCommand: "npm run build:eve",
187
- });
188
- ```
378
+ - **Vercel services:** run the app and each agent with your own process manager and proxy. See [Self-host eve](../deployment/self-hosting#run-workspace-members).
379
+ - **Next.js hosting:** `next start` runs the agent for you. To run the agent yourself instead, put it behind a proxy that serves it under the private path `/_eve_internal/eve` (the `servicePrefix` option), then set `EVE_NEXT_PRODUCTION_ORIGIN` to that proxy's address when you build and start Next.js.
189
380
 
190
- - **Local production build.** `next build && next start` serves the eve runtime from its built `.output/server/index.mjs` on a stable local port (`4274`) and proxies the eve routes to it. Run `eve build` first so that output exists. In an `agents/` workspace, build every member from its `agents/<name>/` directory before starting Next.js. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
381
+ ## Troubleshooting
191
382
 
192
- ```bash
193
- export EVE_NEXT_PRODUCTION_PORT=5000
194
- npm run build && npm start
195
- ```
383
+ | You see | Fix |
384
+ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
385
+ | `401` "Production auth is not configured" | Replace `placeholderAuth()`. See [Authenticate users](#authenticate-users) |
386
+ | "The Next.js output directory `.next` was not found" on deploy | Set the Build Command and Output Directory. See [Deploy to Vercel](#deploy-to-vercel) |
387
+ | The reply stops after the first message | Change the URL with `History.prototype.replaceState`. See [Give each conversation a URL](#give-each-conversation-a-url) |
388
+ | Messages repeat or vanish after a reload | Save `session` from `onSessionChange` as is |
389
+ | `next dev` times out waiting for the agent | Raise `devServerTimeoutMs` |
390
+ | A custom channel route returns `404` with Vercel services | Route it to the agent in `vercel.ts`. See [Compose agents](../deployment/vercel#compose-agents-with-other-vercel-services) |
196
391
 
197
- - **Non-Vercel hosts.** `withEve()` provides both agent process startup and Next.js proxy rewrites; self-hosters using this path do not need to recreate the browser-facing routing. The Vercel service output is a separate integration, not a self-hosting requirement. By default, `next start` runs each built eve service on its derived loopback port. If your host supervises eve services itself, run each service separately and set `EVE_NEXT_PRODUCTION_ORIGIN` to the origin that serves its private route prefix:
392
+ ## Reference
198
393
 
199
- ```bash
200
- export EVE_NEXT_PRODUCTION_ORIGIN=https://agent.example.com
201
- npm run build && npm start
202
- ```
394
+ ### `withEve` options
395
+
396
+ Options for `withEve` from `eve/next`. All are optional.
397
+
398
+ | Option | Default | Purpose |
399
+ | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
400
+ | `eveRoot` | The Next.js app root | Where your agent project lives |
401
+ | `agents` | Found automatically | Agents to mount at `/eve/<name>/v1/*`. Each is a path or `{ root, buildCommand?, servicePrefix? }` |
402
+ | `eveBuildCommand` | Runs the installed `eve` | Command that builds each agent |
403
+ | `devServerTimeoutMs` | `180000` | How long `next dev` waits for each agent to start |
404
+ | `servicePrefix` | `"/_eve_internal/eve"` | Private route path for self-hosted proxying and hand-written Vercel services |
203
405
 
204
- This setting disables automatic production agent startup. The destination includes `servicePrefix`: for named agents, the default is `/_eve_internal/eve/<name>/eve/v1/*`. Configure that routing on the destination host, and use the same origin setting when building and starting Next.js.
406
+ ### Environment variables
205
407
 
206
- If the public routing layer mounts an agent below a path, set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments so callback URLs use the public path. Process restarts, persistent workflow storage, sandbox configuration, and workflow callback routing remain hosting responsibilities; see [Self-host eve](../deployment/self-hosting).
408
+ | Variable | Purpose |
409
+ | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
410
+ | `EVE_BASE_URL` | Next.js hosting, development: use an agent you already started |
411
+ | `EVE_NEXT_PRODUCTION_PORT` | Next.js hosting: first port for agents that `next start` runs. Defaults to `4274` |
412
+ | `EVE_NEXT_PRODUCTION_ORIGIN` | Next.js hosting: address of a proxy serving your agents under `servicePrefix`. Turns off automatic startup |
413
+ | `EVE_PUBLIC_ROUTE_PREFIX` | Self-hosting: an agent's public path, such as `/eve/support`, so callback links work |
207
414
 
208
415
  ## What to read next
209
416
 
210
- - [Frontend overview](./overview): the `useEveAgent` API
211
- - [Auth & route protection](../auth-and-route-protection)
212
- - [Deployment](../deployment/overview)
417
+ - [Frontend overview](./overview): everything the chat hook can do
418
+ - [Authentication](../auth-and-route-protection): checking who's calling
419
+ - [Deploy to Vercel](../deployment/vercel): services, credentials, and sandboxes
420
+ - [Client SDK](../client/overview): calling the agent from server code