eve 0.89.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 (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,11 +3,11 @@ title: "eve"
3
3
  description: "The default HTTP API for an agent, covering session routes, auth, and customization."
4
4
  ---
5
5
 
6
- The eve channel is the framework's default HTTP API. It's what the terminal UI, [`useEveAgent`](../guides/frontend/overview), `curl`, and any SDK client talk to when they start sessions, send messages, and stream events. The selected `channels/eve.ts` source owns the complete `/eve/v1` surface, including health, inspection, callbacks, task input, and session routes. eve supplies that source when `agent/channels/eve.ts` does not exist.
6
+ The eve channel is the framework's default HTTP API under `/eve/v1`. The terminal UI, [`useEveAgent`](../guides/frontend/overview), `curl`, and SDK clients use it to start sessions, send messages, and stream events. It also serves the health, agent info, callback, and task input routes.
7
7
 
8
- Every running eve app exposes its own API. `eve.dev` publishes framework documentation; it is not a shared API, authorization server, MCP server, or A2A server. Each deployment supplies its own host and authentication policy.
8
+ Each deployment serves its own API with its own host and authentication policy. `eve.dev` hosts framework documentation only; it is not a shared API, authorization server, MCP server, or A2A server.
9
9
 
10
- Reach for it when something needs HTTP access to your agent, including local tooling, a browser frontend, the terminal UI, or another API client. Most apps never write this file. Add `agent/channels/eve.ts` only to override the defaults, usually the route auth policy.
10
+ eve supplies the channel when `agent/channels/eve.ts` doesn't exist. Most apps never write this file. Add it only to change the defaults, usually who may call the routes:
11
11
 
12
12
  ```ts title="agent/channels/eve.ts"
13
13
  import { eveChannel } from "eve/channels/eve";
@@ -18,71 +18,9 @@ export default eveChannel({
18
18
  });
19
19
  ```
20
20
 
21
- ## Web Chat with Sign in with Vercel
22
-
23
- Run `eve add channel/web`, or select **Web Chat** from the terminal UI's channel
24
- picker. Choose **Next.js**, a hosting layout, then **Sign in with Vercel**. Sign
25
- in with Vercel is available only for the Next.js Web Chat app. Setup uses a
26
- linked Vercel project and creates a Vercel App that only members of that
27
- project's team can sign in to.
28
-
29
- For a new agent, initialize it first, then link a project and add Web Chat:
30
-
31
- ```bash
32
- eve init my-agent --non-interactive
33
- cd my-agent
34
- eve link
35
- eve add channel/web
36
- ```
37
-
38
- The generated Next.js app uses Better Auth sessions. The selected agent's HTTP
39
- channel verifies the same session, while retaining Vercel OIDC and local
40
- development access. In an agent workspace, setup configures only the selected
41
- agent. Other agents keep their own authentication policies.
42
-
43
- Setup registers `/api/auth/callback/vercel` as a project redirect URI, so Vercel
44
- validates callbacks against the project's deployment domains. The app uses the
45
- `authorization_code` grant, `client_secret_post` authentication, and the
46
- `openid`, `email`, and `profile` scopes. Setup writes `VERCEL_APP_CLIENT_ID`,
47
- `VERCEL_APP_CLIENT_SECRET`, and `BETTER_AUTH_SECRET` to production and preview;
48
- secret values are marked sensitive and are never printed or written to source.
49
- Run `eve deploy` after setup to publish the app. Local development continues
50
- without browser sign-in.
51
-
52
- For automation, supply the setup answers explicitly:
53
-
54
- ```bash
55
- eve add channel/web --non-interactive \
56
- --answer 'web-hosting="vercel"' \
57
- --answer 'web-authentication="vercel"'
58
- ```
59
-
60
- Use a linked project with permission to manage Vercel Apps and project
61
- environment variables. A team owner can complete setup if your role cannot
62
- create apps. The searchable team picker lists eligible teams first. Disabled
63
- teams show `needs permission` or `couldn't verify`, with shared recovery guidance
64
- below the list. If permissions cannot be verified, that team stays
65
- disabled until you sign in or retry. Linked projects are checked before
66
- interactive auth setup.
67
- If setup reports a missing prerequisite, complete it and resume with
68
- `eve add channel/web --skip-install`. Compatible existing apps
69
- and credentials are reused; conflicting app settings or credentials stop setup
70
- with an error. Authored channel or UI files are preserved unless you explicitly
71
- pass `--overwrite`.
72
-
73
- If the team has reached its Vercel App limit, remove an unused app in team
74
- settings and retry. If a generated app name or slug is taken by an incompatible
75
- app, rename the Vercel project in its settings and retry. Compatible apps from a
76
- concurrent setup are reused. A client-secret limit requires removing an unused
77
- secret from the app's settings; setup never removes an existing secret for you.
78
-
79
- Choose **Configure authentication myself** (`web-authentication=custom`) to
80
- keep the current channel policy. The default placeholder rejects production
81
- browser requests until you configure your own authentication.
82
-
83
21
  ## Routes
84
22
 
85
- The default eve channel inspects the agent, creates sessions, accepts callbacks and task input, controls sessions, and streams events. Its public routes include:
23
+ The default eve channel serves these routes:
86
24
 
87
25
  - `GET /eve/v1/health` (check whether the application is reachable)
88
26
  - `GET /eve/v1/info` (inspect the agent)
@@ -94,48 +32,30 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
94
32
  - `POST /eve/v1/session/:sessionId/end` (retire the session)
95
33
  - `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
96
34
 
97
- The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
35
+ Create a session, then put its returned ID in every follow-up, control, and stream path.
98
36
 
99
- `POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session using
100
- the channel's auth policy, without calling `onMessage` or creating a delivery. Non-empty bodies
101
- keep the message and answer behavior, including unknown-field validation; empty or invalid
102
- messages, an empty `answers` array, and payloads with neither input are rejected. Preparation
103
- returns `{ ok: true, status }`: `ready` when the owner already uses the serving
104
- deployment, `accepted` (HTTP 202) when a background preparation hint has been queued,
105
- `unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
106
- owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
107
- has completed. Idle preparation preserves the session ID, stream, history, and expiry;
108
- active work is not interrupted. See the [frontend guide](../guides/frontend/use-eve-agent#prewarming)
109
- for client usage and deployment routing.
37
+ `POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session to answer from the serving deployment. It checks the channel's auth policy, but calls no `onMessage` and sends no message. Preparation keeps the session ID, stream, history, and expiry, and doesn't interrupt running work. It returns `{ ok: true, status }`:
110
38
 
111
- `GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
39
+ | `status` | HTTP | Meaning |
40
+ | ------------------- | ---- | ------------------------------------------------------------------ |
41
+ | `ready` | 200 | The session already runs on the serving deployment. |
42
+ | `accepted` | 202 | A request to move the session is queued; the move may not be done. |
43
+ | `unsupported` | 200 | The World or the session can't move to the serving deployment. |
44
+ | `no_active_session` | 200 | No running session has this ID. |
112
45
 
113
- ### Request validation
46
+ A non-empty body is a message or answer, validated in full. eve rejects empty or invalid messages, an empty `answers` array, and payloads with neither input. See [Prewarming](../guides/frontend/use-eve-agent#prewarming) for client usage and deployment routing.
47
+
48
+ `GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` returns agent-info version 5. It checks the channel's auth policy, then serves only operator callers: `service` and `runtime` callers, and, when the channel's auth includes `localDev()`, callers it admits on a development server. Other callers, such as `user` or `anonymous` ones, get `403` with code `info_forbidden`, because the payload includes authored instructions, skill and schedule Markdown, and server paths. The TypeScript client throws `HealthResponseError` or `AgentInfoResponseError` on a malformed payload, and `ClientError` on a non-success response from either route.
114
49
 
115
- Session creation, follow-up message and input-response requests, and session controls reject
116
- unknown top-level JSON fields with `400 Bad Request`. The error names the unknown fields and
117
- lists the accepted fields for that route. Field names are case-sensitive: `outputschema` is
118
- not `outputSchema`. Invalid requests do not create sessions, dispatch messages, or apply controls.
50
+ ### Request validation
119
51
 
120
- Fields accepted on one route are not automatically valid on another. For example, `operationId`
121
- is accepted on session creation but rejected on follow-up messages.
52
+ Session creation, follow-up and input-response requests, and session controls reject unknown top-level JSON fields with `400 Bad Request`. The error names the unknown fields and lists the route's accepted fields. Field names are case-sensitive (`outputschema` is not `outputSchema`), and each route has its own set: `operationId` is accepted on session creation but rejected on follow-ups. A rejected request creates no session, sends no message, and applies no control. Correct the field or upgrade the server; don't strip behavior-changing options and retry.
122
53
 
123
- Follow-up message and input-response requests accept an `idempotencyKey` of 1 to 256 characters,
124
- for a retry that can't tell whether the first request was accepted. The key names the delivery:
125
- repeating the request with the same key returns the same `deliveryId`, and the input doesn't run
126
- again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
127
- new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
128
- last 1,024 keys, so use a new key for new input. The compact and clear routes
129
- accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; end accepts `reason`.
54
+ Request bodies can't contain eve's own attachment markers (`eve-url:`, `eve-sandbox:`, and `chat-sdk-file:`). A request that does returns `400 Bad Request`.
130
55
 
131
- Open payload objects such as `clientContext` keep their existing contracts. Delegated requests
132
- with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
133
- working. No other unknown fields are accepted. Authentication and existing value validation still
134
- apply, including permission checks for forwarded principals and tool stubs.
56
+ Compact and clear accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`, and end accepts `reason`. The unknown-field check applies to top-level fields, not to open payload objects such as `clientContext`. Delegated requests with a `callback` also accept and ignore an `activityObserver` field. Authentication and value validation still apply, including permission checks for forwarded caller identities and tool stubs.
135
57
 
136
- A newer client sending an unsupported field to an older server with strict validation fails
137
- rather than silently losing the requested behavior. Correct the field or upgrade the server;
138
- do not automatically remove behavior-changing options and retry.
58
+ Follow-up and input-response requests accept an `idempotencyKey` of 1 to 256 characters for retries that can't tell whether the first request was accepted. A repeat with the same key returns the original receipt and `deliveryId` without running the input again. A channel's [retried deliveries](./custom#retried-deliveries) differ: they get a new receipt whose result is `ignored`. The session remembers its last 1,024 keys, so use a new key for new input.
139
59
 
140
60
  ### Start and continue a session
141
61
 
@@ -146,12 +66,7 @@ curl -X POST https://<deployment>/eve/v1/session
146
66
  # {"ok":true,"sessionId":"wrun_A"}
147
67
  ```
148
68
 
149
- See [Start a session](../concepts/sessions-runs-and-streaming#start-a-session) for the
150
- initialization boundary, first-turn identity, readiness response, and retry behavior.
151
-
152
- The create request still requires route auth. Session audience and the timeout are selected
153
- at creation; they do not change when the first message arrives. Turn-scoped fields such as
154
- `clientContext` and `outputSchema` require a message on the create request.
69
+ The create request requires route auth and fixes the session's audience and timeout. Fields that apply to one turn, such as `clientContext` and `outputSchema` need a message on the create request. See [Start a session](../concepts/sessions-runs-and-streaming#start-a-session) for the initialization boundary, first-turn identity, readiness response, and retry behavior.
155
70
 
156
71
  Include an initial message to create the session and start its first turn in one request:
157
72
 
@@ -162,14 +77,7 @@ curl -X POST https://<deployment>/eve/v1/session \
162
77
  # {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
163
78
  ```
164
79
 
165
- Authenticated callers that may retry a create request can pass their own `operationId` for
166
- create-once semantics. Once the operation owner is active, the same operation under the same
167
- authenticated principal returns that session instead of dispatching the input again. The create
168
- route does not wait for a concurrently starting request to publish ownership: simultaneous
169
- requests can receive different accepted candidate IDs, while only the candidate that claims the
170
- operation runs its first turn. Retry the operation after startup when you need its canonical
171
- session ID. Anonymous callers cannot use `operationId`, and operation ownership expires when the
172
- session is no longer resumable.
80
+ An authenticated caller that may retry a create request can pass an `operationId` so the session is created once. Once that session is active, the same `operationId` from the same caller returns it without sending the input again. Simultaneous requests can receive different session IDs, but only one runs the first turn. Retry after startup to get the final session ID. Anonymous callers can't use `operationId`. An `operationId` is free again once its session can no longer resume.
173
81
 
174
82
  ```bash
175
83
  curl -X POST https://<deployment>/eve/v1/session \
@@ -179,8 +87,7 @@ curl -X POST https://<deployment>/eve/v1/session \
179
87
  # {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
180
88
  ```
181
89
 
182
- When the create request includes a message, a follow-up request accepts exactly one of
183
- `message` or `answers`; use the latter to answer a pending HITL request:
90
+ A follow-up request accepts exactly one of `message` or `answers`. Use `answers` to answer a pending approval or question:
184
91
 
185
92
  ```bash
186
93
  curl -X POST https://<deployment>/eve/v1/session/wrun_A \
@@ -188,15 +95,13 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
188
95
  -d '{"answers":[{"interactionId":"req_A","optionId":"approve"}]}'
189
96
  ```
190
97
 
191
- Follow-up messages use `turnPolicy: "steer"` by default. Before assistant answer output or local tool execution begins, steering interrupts pending model generation and applies the correction in the same turn. Executing tools finish and checkpoint their results first. After answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output; interrupted provider-managed search may run again. The turn ID stays the same.
192
-
193
- Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `answers` answer their addressed requests.
98
+ A follow-up message joins the running turn by default; see [Overlapping messages](./overview#overlapping-messages). Set `turnPolicy: "queue"` on `eveChannel(...)` to make follow-ups wait for running turns to finish. `answers` only answer the requests they name.
194
99
 
195
- Sending a message to an unknown or terminal session ID returns `409` with
196
- `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
197
- An existing workflow whose inbox is not yet available returns `409 session_not_ready` instead.
198
- A session that another eve version built returns `409 session_stranded` with the `eveVersion`
199
- that built it.
100
+ | Session state | Response |
101
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------ |
102
+ | Unknown or terminal | `409` with `{"code":"session_not_active","error":"The session is no longer active.","ok":false}` |
103
+ | Workflow exists but inbox isn't ready | `409 session_not_ready` |
104
+ | Built by another eve version | `409 session_stranded` with the `eveVersion` that built it |
200
105
 
201
106
  ### Send files
202
107
 
@@ -208,11 +113,9 @@ curl -X POST https://<deployment>/eve/v1/session/wrun_A \
208
113
  -d '{"message":[{"type":"text","text":"Summarize this report."},{"type":"file","mediaType":"application/pdf","filename":"report.pdf","data":"data:application/pdf;base64,JVBERi0xLjQK..."}]}'
209
114
  ```
210
115
 
211
- Framework-generated attachment markers (`eve-url:`, `eve-sandbox:`, and `chat-sdk-file:`) are not accepted in HTTP request bodies; they return `400 Bad Request`.
212
-
213
- `uploadPolicy` sets the size cap and allowed media types, 25 MB and every type by default. A request whose inline file breaks the policy returns `413` for size or `415` for type. Inline bytes also count toward the request body limit of the platform that serves the channel. On Vercel Functions that limit is 4.5 MB, so a base64 file stops at about 3.3 MB.
116
+ `uploadPolicy` sets the size cap and allowed media types; omit it for 25 MB and every type. An inline file that breaks the policy returns `413` for size or `415` for type. Inline bytes also count toward the hosting platform's request body limit: 4.5 MB on Vercel Functions, so about 3.3 MB of file before base64.
214
117
 
215
- For larger files, upload them from the browser to your own storage and send the URL in the file part. Add `fetchFile` to load the URLs you own inside the workflow step, so the bytes never pass through the request or the workflow start payload:
118
+ For larger files, upload from the browser to your own storage and send the URL in the file part. Add `fetchFile` to load your URLs after eve accepts the message, so the bytes never pass through the request:
216
119
 
217
120
  ```ts title="agent/channels/eve.ts"
218
121
  import { eveChannel } from "eve/channels/eve";
@@ -232,62 +135,105 @@ export default eveChannel({
232
135
  });
233
136
  ```
234
137
 
235
- `fetchFile` follows the [custom channel contract](./custom#file-uploads): return bytes to stage the file, or `null` for a URL that isn't yours. eve then downloads a public `https:` URL itself, and any other URL reaches the model as a note. `uploadPolicy` covers every file eve stages for the channel, including URLs that `fetchFile` loads and URLs eve downloads itself. eve checks the final bytes and the media type they prove, so a file over the cap, or one whose bytes are a disallowed type, reaches the model as a note instead of failing the request. See [Inbound attachments](../sandbox#inbound-attachments) for how eve stores files and shows them to the model.
138
+ `fetchFile` follows the [custom channel contract](./custom#file-uploads): return bytes to save the file to the sandbox, or `null` for a URL that isn't yours. eve downloads a public `https:` URL itself and passes any other URL to the model as a note. `uploadPolicy` also checks fetched and downloaded files by their actual bytes and detected media type. A violating file reaches the model as a note instead of failing the request. See [Inbound attachments](../sandbox#inbound-attachments) for how eve stores files and shows them to the model.
236
139
 
237
140
  ### Stream events
238
141
 
239
142
  Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
240
143
 
241
- Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before ending the session. End attempts to append its control delivery's `delivery.admitted` (`source: { control: "reset" }`) and `delivery.settled`, then `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }` naming that delivery, then close the stream. Existing readers finish when the stream ends.
144
+ Following a stranded session's stream returns `409 session_stranded`, and the TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead. The response ends at the last recorded event and carries the `x-eve-stream-tail-index` header. It doesn't change the session, so it works before you end the session.
242
145
 
243
- A session started by an eve version before v27 stores v26 events. Its stream route serves them as the v27 lines they record, so v27 clients render that history: messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions. Streamed text previews aren't translated, so a v26 session that is still running shows each part once it completes.
146
+ Ending a stranded session tries to append these events, then closes the stream so existing readers finish:
244
147
 
245
- Cursors still count stored lines. A stored event with nothing for a v27 reader to fold, such as a streamed delta, is sent as a `position` marker. The route reads these streams from their first line on every request, whatever the cursor. Once no running owner can add to the stream, a follow ends at the tail with `stream.ended`, so clients stop reconnecting.
148
+ 1. `delivery.admitted` with `source: { control: "reset" }`, then `delivery.settled`, for the end request.
149
+ 2. `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }`.
246
150
 
247
- After a session ends, the World keeps its stream only for its retention period. Reading a stream past that point returns `410 session_expired`. The history is gone, so the TypeScript client fails on the first response with a `ClientError` whose `code` is `"session_expired"`, without retrying.
151
+ A session started by an eve version before v27 stores v26 events, and the stream route serves them as v27 lines. Translation covers messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions.
152
+
153
+ - Streamed text previews aren't translated, so a running v26 session shows each part once it completes.
154
+ - Cursors count stored lines. A stored event with nothing to translate, such as a streamed delta, arrives as a `position` marker.
155
+ - When no running deployment can add to the stream, a follow ends at the last event with `stream.ended`, so clients stop reconnecting.
156
+
157
+ The World keeps an ended session's stream only for its retention period. After that, reading it returns `410 session_expired`, and the TypeScript client fails with a `ClientError` whose `code` is `"session_expired"`, without retrying.
248
158
 
249
159
  ### Cancel a turn
250
160
 
251
- Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.settled` with `outcome: "cancelled"`.
161
+ Post to `/eve/v1/session/:sessionId/cancel` to cancel the active turn. Include the observed `turnId` so a late request can't cancel a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.settled` with `outcome: "cancelled"`.
252
162
 
253
- See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for delivery receipts, HTTP status codes, subagent cancellation, and race behavior.
163
+ See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for receipts, HTTP status codes, subagent cancellation, and race behavior.
254
164
 
255
165
  ### Clear context
256
166
 
257
- Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `end` route instead. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
167
+ Post to `/eve/v1/session/:sessionId/clear` to cancel a running turn and every working task, then remove model-message history. The session ID, system prompt, tools, skills, state, limits, and sandbox stay. On a stranded session, clear returns `409 session_stranded` and changes nothing; use `end` instead. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
258
168
 
259
169
  ### Compact context
260
170
 
261
- Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
171
+ Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for a running turn to finish and reports its result on the stream. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
262
172
 
263
173
  <a id="reset-a-session" />
264
174
 
265
175
  ### End a session
266
176
 
267
- Post to `/eve/v1/session/:sessionId/end` to terminally retire that session. End never replaces the ID automatically; create a new session explicitly for a fresh conversation. End also works on a stranded session: eve cancels the stranded workflow run directly instead of delivering the command to it. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
177
+ Post to `/eve/v1/session/:sessionId/end` to end that session for good. Ending doesn't create a replacement; create a new session for a fresh conversation. On a stranded session, eve cancels the workflow run directly. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
268
178
 
269
- ## Replace or disable the defaults
179
+ ## Authentication
270
180
 
271
- An authored `agent/channels/eve.ts` replaces the complete default eve channel. An `eveChannel(...)` replacement keeps the standard route set with your options; a custom `defineChannel(...)` replacement exposes only the routes you declare. Health, inspection, and callbacks do not reappear through a hidden host fallback.
181
+ The `auth` option decides who can call `/eve/v1/info` and the session routes. The built-in helpers cover development and trusted infrastructure:
272
182
 
273
- Disable the complete surface by exporting `disableRoute()` at that slot:
183
+ - `localDev()` accepts requests during local development.
184
+ - `vercelOidc()` lets the local CLI and your team's other deployments call a deployed agent.
274
185
 
275
- ```ts title="agent/channels/eve.ts"
276
- import { disableRoute } from "eve/channels";
186
+ Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth: Clerk, Auth.js, OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`. Use Vercel OIDC only when Vercel-issued deployment tokens are part of your trust model.
277
187
 
278
- export default disableRoute();
188
+ `eve init` scaffolds `agent/channels/eve.ts` with `vercelOidc()`, `localDev()`, and `placeholderAuth()`, which returns a setup-focused 401 in production until you replace it with real auth. Without the file, eve uses the same `[vercelOidc(), localDev(), placeholderAuth()]` policy, which rejects production requests without a valid Vercel OIDC token.
189
+
190
+ `/eve/v1/info` also requires an operator caller. To let your own operator credential read it, return `principalType: "service"` from its `AuthFn`, as `jwtHmac()` and `jwtEcdsa()` do, or return `allowAgentInfo: true` from an `EveAuthFn`. See [Agent info access](../guides/auth-and-route-protection#agent-info-access). Keep end-user strategies returning `"user"` without the grant, so end users can't read it.
191
+
192
+ For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
193
+
194
+ ## Web Chat with Sign in with Vercel
195
+
196
+ To let your team sign in to a browser chat, run `eve add channel/web` or select **Web Chat** from the terminal UI's channel picker. Then choose **Next.js**, a hosting layout, and **Sign in with Vercel**. Sign in with Vercel is available only for the Next.js Web Chat app. Setup creates a Vercel App on the linked project that only members of the project's team can sign in to.
197
+
198
+ For a new agent, initialize it first, then link a project and add Web Chat:
199
+
200
+ ```bash
201
+ eve init my-agent --non-interactive
202
+ cd my-agent
203
+ eve link
204
+ eve add channel/web
279
205
  ```
280
206
 
281
- The default home page is a separate `channels/home.ts` source that serves `GET /` and `HEAD /`. Author `agent/channels/home.ts` to replace it or export `disableRoute()` there to remove it without affecting `/eve/v1`.
207
+ `eve init --channel-web-nextjs` scaffolds the app without authentication; sign-in setup runs only through `eve add channel/web` or the channel picker.
282
208
 
283
- ## CORS
209
+ The generated Next.js app signs users in with Better Auth. The agent's eve channel accepts the same sign-in, and still accepts Vercel OIDC and local development requests. In an agent workspace, setup configures only the selected agent.
284
210
 
285
- The eve channel leaves CORS untouched by default. Pass `cors: true` to enable
286
- permissive browser CORS with preflight handling, or pass an options object to
287
- narrow origins, methods, and headers. Route auth still runs on the actual
288
- session requests.
211
+ Setup registers `/api/auth/callback/vercel` as a project redirect URI, so Vercel validates callbacks against the project's deployment domains. The app uses the `authorization_code` grant, `client_secret_post` authentication, and the `openid`, `email`, and `profile` scopes. Setup writes `VERCEL_APP_CLIENT_ID`, `VERCEL_APP_CLIENT_SECRET`, and `BETTER_AUTH_SECRET` to production and preview as sensitive values, and never prints them or writes them to source. Run `eve deploy` after setup to publish the app. Local development runs without browser sign-in.
289
212
 
290
- Enable or narrow CORS only when browser clients call the channel directly:
213
+ For automation, supply the setup answers explicitly:
214
+
215
+ ```bash
216
+ eve add channel/web --non-interactive \
217
+ --answer 'web-hosting="vercel"' \
218
+ --answer 'web-authentication="vercel"'
219
+ ```
220
+
221
+ Setup needs a linked project and permission to manage Vercel Apps and project environment variables. If your role can't create apps, a team owner can complete setup. The team picker lists eligible teams first and disables teams marked `needs permission` or `couldn't verify` until you sign in or retry.
222
+
223
+ Setup reuses compatible existing apps and credentials, and stops with an error on conflicting app settings or credentials. It preserves authored channel and UI files unless you pass `--overwrite`.
224
+
225
+ | What you see | What to do |
226
+ | ----------------------------------------------- | ------------------------------------------------------------------------------- |
227
+ | Setup reports a missing prerequisite | Complete it, then resume with `eve add channel/web --skip-install`. |
228
+ | The team has reached its Vercel App limit | Remove an unused app in team settings and retry. |
229
+ | The generated app name or slug is already taken | Rename the Vercel project in its settings and retry. |
230
+ | The app has reached its client-secret limit | Remove an unused secret in the app's settings; setup never removes one for you. |
231
+
232
+ Choose **Configure authentication myself** (`web-authentication=custom`) to keep the current channel policy. The default placeholder rejects production browser requests until you configure your own authentication.
233
+
234
+ ## CORS
235
+
236
+ The eve channel sends no CORS headers by default. When browser clients call the channel directly, pass `cors: true` for permissive CORS with preflight handling, or an options object to narrow origins, methods, and headers. Route auth still runs on the session requests.
291
237
 
292
238
  ```ts title="agent/channels/eve.ts"
293
239
  import { eveChannel } from "eve/channels/eve";
@@ -303,34 +249,17 @@ export default eveChannel({
303
249
  });
304
250
  ```
305
251
 
306
- ## Authentication
307
-
308
- The `auth` option decides who can call `/eve/v1/info` and the session routes. The built-in helpers cover development and trusted infrastructure:
309
-
310
- - `localDev()` accepts requests during local development.
311
- - `vercelOidc()` lets the local CLI reach a deployed agent, and lets other internal deployments from your team call it.
312
-
313
- Neither admits browser users or external clients in production. For a public app, wire the channel to your own auth (Clerk, Auth.js, your own OIDC/JWT verification, an API-key verifier, or any custom `AuthFn`). Vercel OIDC is optional; use it only when Vercel-issued deployment tokens are part of your trust model.
314
-
315
- `eve init` scaffolds an `agent/channels/eve.ts` with a production placeholder so you replace it before going live. The generated channel checks Vercel OIDC before falling back to localhost access, and includes `placeholderAuth()`, which returns a setup-focused 401 in production until you swap it for real auth. Delete the file and eve selects its default channel source with `[vercelOidc(), localDev(), placeholderAuth()]`, which rejects all production traffic.
316
-
317
- For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
318
-
319
252
  ## Audience
320
253
 
321
- The eve channel assigns an observability audience when it creates a session. The
322
- audience controls whether instrumentation may capture session content:
323
-
324
- | Session creator | Default audience |
325
- | ----------------------------------------- | ---------------- |
326
- | Anonymous caller | `unknown` |
327
- | `user`, `service`, or `runtime` principal | `private` |
328
- | Any other principal type | `unknown` |
254
+ The eve channel sets each new session's audience from its caller. The audience controls whether traces may capture session content, not who may call the endpoint:
329
255
 
330
- Anonymous HTTP surfaces are `unknown` by default because reachability does not establish that their content is safe to record. Authenticated `user`, `service`, and `runtime` sessions are private because they belong to one identified party. Other authenticated principal types also remain `unknown`: trace consumers record metadata but omit content by default in preview and production. Set an explicit `audience: "public"` only for intentionally public traffic.
256
+ | Session creator | Default audience |
257
+ | -------------------------------------- | ---------------- |
258
+ | Anonymous caller | `unknown` |
259
+ | `user`, `service`, or `runtime` caller | `private` |
260
+ | Any other caller type | `unknown` |
331
261
 
332
- For a production endpoint whose conversations are all intentionally public,
333
- set a constant audience:
262
+ `user`, `service`, and `runtime` sessions are `private` because they belong to one identified party. For `unknown` sessions, traces record metadata but leave out content by default in preview and production. Set a constant `audience: "public"` only when every conversation on the endpoint is intentionally public:
334
263
 
335
264
  ```ts title="agent/channels/eve.ts"
336
265
  import { vercelOidc } from "eve/channels/auth";
@@ -342,22 +271,11 @@ export default eveChannel({
342
271
  });
343
272
  ```
344
273
 
345
- Audience also selects the default [run-data retention](../agent-config#run-data-retention).
346
- Outside development, private and unknown-audience sessions request deletion when
347
- they end. The Workflow World must support deletion to enforce it.
274
+ `audience` also accepts a function that receives `caller`, channel, and deployment environment. The audience is fixed when the session is created, so a later turn from a different caller doesn't change it. For an audience that depends on channel state or verified application data, use a [custom channel audience](./custom#conversation-audience).
348
275
 
349
- `audience` controls observability content capture; it does not change who may
350
- call the endpoint. `auth` still controls access. For a classification that
351
- depends on channel state or application-specific verified data, use a [custom
352
- channel audience](./custom#conversation-audience).
276
+ Audience also selects the default [run-data retention](../agent-config#run-data-retention). Outside development, private and unknown-audience sessions request deletion when they end, if the Workflow world supports deletion.
353
277
 
354
- You can also pass a function that receives `caller`, channel, and deployment
355
- environment. Classification is fixed at session creation, so a later
356
- turn from a different caller does not reclassify the session.
357
-
358
- For a remote agent, a trusted dispatch can forward the original audience and
359
- its trace-content ceiling. See [Preserving trace
360
- content](../guides/remote-agents#preserving-trace-content).
278
+ For a remote agent, a trusted caller can forward the original audience and its trace-content ceiling. See [Preserving trace content](../guides/remote-agents#preserving-trace-content).
361
279
 
362
280
  ## Customization
363
281
 
@@ -387,13 +305,13 @@ export default eveChannel({
387
305
  });
388
306
  ```
389
307
 
390
- `onMessage` must return an auth result. Return `title` alongside `auth` to set the title when the dispatch creates a session or sends the first message to a prewarmed session. A successful canonical eve HTTP message always dispatches and therefore always produces or continues a session.
308
+ `onMessage` must return an auth result, so every accepted message starts or continues a session. Return `title` alongside `auth` to set the session title. It applies when the message creates the session, or is the first message to one created without a message.
391
309
 
392
310
  ### Turn context
393
311
 
394
- `context` strings become user messages in durable session history. For context that applies to one turn only, return `clientContext` instead. It replaces the request's [`clientContext`](../guides/client/messages) for that turn: it reaches every model call in the turn and is not kept in session history.
312
+ `context` strings are saved as user messages in session history. For context that applies to one turn only, return `clientContext`. It replaces the request's [`clientContext`](../guides/client/messages) for every model call in the turn and isn't kept in session history.
395
313
 
396
- `ctx.eve.clientContext` holds the request's `clientContext` exactly as the client sent it, or `undefined` when it sent none. Use it to check or correct client-supplied state before the model sees it:
314
+ `ctx.eve.clientContext` holds the request's `clientContext` as sent, or `undefined`. Use it to check or correct client-supplied state before the model sees it:
397
315
 
398
316
  ```ts title="agent/channels/eve.ts"
399
317
  import { eveChannel, defaultEveAuth } from "eve/channels/eve";
@@ -412,15 +330,15 @@ export default eveChannel({
412
330
  ```
413
331
 
414
332
  - Omit `clientContext` to keep the request's context. Return `[]` to drop it.
415
- - The returned value takes the same shape as request `clientContext` (`ClientContextValue`, exported from `eve/channels/eve`): a string, an array of strings, or a JSON object. eve turns it into model messages the same way.
333
+ - The returned value has the request's `ClientContextValue` shape, exported from `eve/channels/eve`: a string, an array of strings, or a JSON object.
416
334
  - eve labels client-supplied entries `Client context:` for the model. Returned context is sent without the label.
417
- - `onMessage` runs only for requests with a message. An input response keeps the context its request sent.
335
+ - `onMessage` runs only for requests with a message. An answer keeps the context its request sent.
418
336
 
419
337
  ### Start from prior history
420
338
 
421
- Pass `history` to bring in conversation eve did not produce, such as a transcript your app stored, a conversation moving from another system, or a branch of an earlier exchange. The model sees each entry as a real user or assistant turn, not as a transcript inside one message.
339
+ Pass `history` to bring in conversation eve didn't produce, such as a stored transcript or a branch of an earlier exchange. The model sees each entry as a real user or assistant turn.
422
340
 
423
- Create a session that starts from stored history and waits for its first message with `create()` on a channel address. No turn runs until a message arrives:
341
+ Call `create()` on a channel address to create a session from stored history. No turn runs until a message arrives:
424
342
 
425
343
  ```ts title="agent/channels/app.ts"
426
344
  import { defineChannel, POST } from "eve/channels";
@@ -448,25 +366,39 @@ export default defineChannel({
448
366
  });
449
367
  ```
450
368
 
451
- The client then resumes that session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when a session already owned the address, or another `create()` or `send()` claimed it first. That session comes back unchanged and your `history` was not added, so check `created` before treating the session as seeded. Use a new address for each new conversation or branch.
452
-
453
- When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `end()` on the address, then `create()` again.
369
+ The client then resumes the session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when another session already owned the address or another `create()` or `send()` claimed it first. That session comes back unchanged, without your `history`. Use a new address for each new conversation or branch.
454
370
 
455
- `create()` returns once the new session claims its address, so a `send()` right after it reaches that session. It throws if no session claims the address within 15 seconds.
371
+ `create()` returns once the new session claims its address, so an immediate `send()` reaches it. It throws if no session claims the address within 15 seconds. On a [stranded](../guides/deployment/self-hosted-operations#recover-a-stranded-session) session, `create()` throws `SessionStrandedError` instead of replacing a conversation you may mean to import; call `end()` on the address, then `create()` again.
456
372
 
457
- `send()` accepts the same `history` option. The entries are added right before that message and its `context`, whether the send creates the session or continues it. The eve channel's `onMessage` can return `history` the same way. It applies to every message it is returned for, so return it only when the message should carry those turns.
373
+ `send()` accepts the same `history` option and adds the entries right before that message and its `context`, whether it creates or continues the session. The eve channel's `onMessage` can return `history` too, which applies to every message it's returned for.
458
374
 
459
- Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an optional `id` that is unique within the call. An entry with any other field is rejected, not dropped, so map your stored messages to these fields. Invalid history throws an `InvalidSessionHistoryError`, exported from `eve/channels`, that names the entry and the rule it broke. eve doesn't cap how many entries or how much text one call carries. Your route decides how much stored conversation to load, so trim long conversations there, for example to the newest messages. Tool calls, files, and reasoning are not supported.
375
+ Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an optional `id` unique within the call. eve rejects an entry with any other field, so map your stored messages to these fields. Invalid history throws an `InvalidSessionHistoryError`, exported from `eve/channels`, naming the entry and the broken rule. eve doesn't cap entries or text, so trim long conversations in your route. Tool calls, files, and reasoning are not supported.
460
376
 
461
377
  eve never accepts `history` from a client request body. Resolve it on the server and authorize the caller against the stored conversation.
462
378
 
463
- The stream records the entries on the `delivery.consumed` of the message that brought them, in `data.history`, with the same `role`, `text`, and `id` you passed. History from `create()` is recorded with the first message the channel accepts. When one turn takes in several messages at once, the model reads all of their history before what they sent. `transcriptOf()` from `eve/client` reads the entries in that order, so its `{ role, text }` messages can be passed straight back as `history` to branch a session. Frontend `messages` show them ahead of their message with `metadata.imported` set and your `id` in `metadata.historyId`, so you can rejoin your own annotations. Imported messages have no `metadata.turnId`, so a turn's reply never streams into one, and their message ids stay unique even when a later call reuses an `id`. After that, the entries are ordinary history: compaction, `clear()`, and handoffs treat them like any other turn.
379
+ The stream records the entries in `data.history` on the `delivery.consumed` of the message that brought them. History from `create()` is recorded with the first accepted message. When one turn takes in several messages, the model reads all their history first. `transcriptOf()` from `eve/client` returns entries in that order as `{ role, text }` messages you can pass back as `history` to branch a session.
380
+
381
+ Frontend `messages` show imported entries before their message, with `metadata.imported` set and your `id` in `metadata.historyId`. Imported messages have no `metadata.turnId`, so a turn's reply never streams into one. Their message ids stay unique even when a later call reuses an `id`. Compaction, `clear()`, and handoffs treat them like any other history.
382
+
383
+ ## Replace or disable the defaults
384
+
385
+ An authored `agent/channels/eve.ts` replaces the whole default eve channel. An `eveChannel(...)` replacement keeps the standard routes with your options. A `defineChannel(...)` replacement serves only the routes you declare, without the health, info, or callback routes.
386
+
387
+ Export `disableRoute()` to remove every `/eve/v1` route:
388
+
389
+ ```ts title="agent/channels/eve.ts"
390
+ import { disableRoute } from "eve/channels";
391
+
392
+ export default disableRoute();
393
+ ```
394
+
395
+ The default home page at `GET /` and `HEAD /` is a separate `home` channel. Author `agent/channels/home.ts` to replace it, or export `disableRoute()` there to remove it without affecting `/eve/v1`.
464
396
 
465
397
  ## Clients
466
398
 
467
399
  The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
468
400
 
469
- For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
401
+ For scripts, server-to-server calls, evals, tests, and custom clients, use the [Client SDK](../guides/client/overview), which wraps the session routes, stream cursor, and reconnect loop.
470
402
 
471
403
  ## What to read next
472
404