eve 0.90.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -5,10 +5,8 @@ description: "Secure your agent's HTTP routes with an ordered auth walk, verifie
5
5
 
6
6
  eve has two independent auth systems:
7
7
 
8
- - **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer, gating the request before any model work runs.
9
- - **Tool and connection auth** (outbound) is how your agent signs in to an external service it calls, like an OAuth MCP server. It happens later, when a tool or connection actually reaches out.
10
-
11
- Start with route auth.
8
+ - **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer, before any model work.
9
+ - **Tool and connection auth** (outbound) signs your agent in to an external service that a tool or connection calls, like an OAuth MCP server.
12
10
 
13
11
  ## Route auth
14
12
 
@@ -19,9 +17,9 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
19
17
  - `POST /eve/v1/session/:sessionId/{cancel,compact,clear,end}`
20
18
  - `GET /eve/v1/session/:sessionId/stream`
21
19
 
22
- These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
20
+ eve fails closed: production traffic is rejected unless an authenticator accepts it, and anonymous access requires an explicit `none()`.
23
21
 
24
- The health route created by `eveChannel()` is public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials. Replacing `agent/channels/eve.ts` with a custom `defineChannel(...)` or disabling that slot also replaces or removes the health route.
22
+ The health route created by `eveChannel()` is public and skips the walk, so load balancers and uptime monitors can probe it without credentials. Replacing `agent/channels/eve.ts` with a custom `defineChannel(...)` or disabling that slot also replaces or removes the health route.
25
23
 
26
24
  ```ts title="agent/channels/eve.ts"
27
25
  import { eveChannel } from "eve/channels/eve";
@@ -32,17 +30,25 @@ export default eveChannel({
32
30
  });
33
31
  ```
34
32
 
35
- `vercelOidc()` is a convenience for Vercel-hosted agents and Vercel-to-Vercel callers, not a requirement. If your app already has users, sessions, API keys, or an identity provider, put that authenticator in the `auth` walk instead. Custom `AuthFn` entries are first-class and can fully replace Vercel OIDC.
33
+ `vercelOidc()` is a convenience for Vercel-hosted agents and Vercel-to-Vercel callers, not a requirement. If your app already has users, sessions, API keys, or an identity provider, put a custom `AuthFn` for it in the `auth` walk instead.
36
34
 
37
35
  ## The ordered auth walk
38
36
 
39
- `auth` takes a single `AuthFn` or an array that eve walks in order. Each entry has three possible outcomes:
37
+ `auth` takes a single `AuthFn` or an array that eve walks in order. Each entry has one of three outcomes:
38
+
39
+ | Entry | Result |
40
+ | ---------------------------- | -------------------------------------- |
41
+ | Returns `SessionAuthContext` | Accepts the request and stops the walk |
42
+ | Returns `null` / `undefined` | Skips to the next entry |
43
+ | Throws | Rejects with a specific status |
44
+
45
+ If every entry skips, the request gets a `401`. Its `WWW-Authenticate` header advertises the schemes the entries declare:
40
46
 
41
- - returns a `SessionAuthContext`: accept the request and stop the walk
42
- - returns `null` / `undefined`: skip to the next entry
43
- - **throws**: reject with a specific status
47
+ - `Basic` for `httpBasic()`.
48
+ - `Bearer` for `jwtHmac`, `jwtEcdsa`, `oidc`, and `vercelOidc`.
49
+ - `Bearer` for entries that declare none, such as a custom `AuthFn` or an empty array.
44
50
 
45
- If every entry skips, the request gets a `401` whose `WWW-Authenticate` header advertises the challenge scheme(s) the configured entries declare — `Basic` for `httpBasic()`, `Bearer` for the token-based helpers (`jwtHmac`, `jwtEcdsa`, `oidc`, `vercelOidc`), both when you mix them, and `Bearer` as a fallback for entries that don't declare a scheme (custom `AuthFn`s, or an empty array). See [`withAuthChallenges`](#custom-verifiers) to declare a scheme on a custom `AuthFn`.
51
+ See [`withAuthChallenges`](#custom-verifiers) to declare a scheme on a custom `AuthFn`.
46
52
 
47
53
  ```ts
48
54
  import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
@@ -67,7 +73,7 @@ export default eveChannel({
67
73
  });
68
74
  ```
69
75
 
70
- Put your own providers ahead of the catch-all helpers. `localDev()` is the final fallback: put `vercelOidc()` before it so a local Vercel OIDC bearer can resolve a user instead of being shadowed by the synthetic local principal. Any entry that doesn't recognize the caller returns `null`, and the walk moves on. On non-Vercel hosts, omit `vercelOidc()` unless you specifically want to accept Vercel-issued tokens.
76
+ Put your own providers ahead of the catch-all helpers, and `localDev()` last. A `vercelOidc()` before `localDev()` lets a local Vercel OIDC bearer resolve a real user instead of the stand-in `local-dev` caller. On non-Vercel hosts, omit `vercelOidc()` unless you want to accept Vercel-issued tokens.
71
77
 
72
78
  To reject with a precise status instead of skipping, throw:
73
79
 
@@ -85,7 +91,7 @@ Any other thrown error follows the normal channel failure path. When building a
85
91
 
86
92
  ## Verifier helpers
87
93
 
88
- `eve/channels/auth` ships these channel-auth helpers:
94
+ `eve/channels/auth` ships these helpers:
89
95
 
90
96
  | Helper | Use when |
91
97
  | ---------------- | -------------------------------------------------------------------------------------------------- |
@@ -97,31 +103,31 @@ Any other thrown error follows the normal channel failure path. When building a
97
103
  | `jwtEcdsa(...)` | You verify asymmetric JWTs minted by another system. |
98
104
  | `oidc(...)` | You want eve to verify OIDC-issued tokens from an arbitrary issuer. |
99
105
 
100
- `httpBasic(credentials, { realm })` accepts an optional `realm`, rendered on the `WWW-Authenticate: Basic` challenge (e.g. `Basic realm="agent", charset="UTF-8"`) so browsers label their native login prompt. It defaults to `"eve"`, ensuring every Basic challenge includes the required realm. Usernames and passwords are normalized to Unicode NFC before comparison, matching the advertised UTF-8 credential encoding.
106
+ `httpBasic(credentials, { realm })` renders `realm` on the `WWW-Authenticate: Basic` challenge (e.g. `Basic realm="agent", charset="UTF-8"`) so browsers label their login prompt. Omit `realm` to use `"eve"`. Usernames and passwords are normalized to Unicode NFC before comparison.
101
107
 
102
108
  Exercise caution for agents that process non-public, sensitive, regulated, or production data unless you have implemented other access controls.
103
109
 
104
110
  ### `localDev()`
105
111
 
106
- Authenticates a synthetic `local-dev` principal, but only while the process is a local development server: `eve dev` (which sets `EVE_DEV=1`) or `vercel dev` (detected by `VERCEL=1` and `VERCEL_ENV=development` together). This is a property of the deployment, not the request, so no request header can flip it. A production deployment (`eve start`, a Vercel deployment, or any container host) sets neither flag, so `localDev()` authenticates nothing there and every request falls through to the next entry.
112
+ Accepts the request as a stand-in `local-dev` caller, but only on a local development server: `eve dev` (which sets `EVE_DEV=1`) or `vercel dev` (`VERCEL=1` and `VERCEL_ENV=development` together). No request header can change this. A production deployment (`eve start`, a Vercel deployment, or any container host) sets neither flag, so every request falls through to the next entry.
107
113
 
108
- On a development server, `localDev()` also refuses requests that a browser sends for another website: the request host or its `Origin` is neither a loopback host nor one of this machine's own addresses. A web page that the developer opens cannot call the local agent, even through DNS rebinding. A frontend served from any loopback host and port, such as `http://localhost:3000` calling `http://127.0.0.1:2000`, still authenticates.
114
+ On a development server, `localDev()` refuses browser requests for another website. It refuses a request when its host or `Origin` is neither a loopback host nor one of this machine's addresses. A web page the developer opens can't call the local agent, even through DNS rebinding. A frontend on any loopback host and port, such as `http://localhost:3000` calling `http://127.0.0.1:2000`, still authenticates.
109
115
 
110
- On `eve dev`, `localDev()` also refuses callers whose connection comes from another machine. A server started with `eve dev --host 0.0.0.0` accepts LAN connections, but those callers do not get the `local-dev` principal. A tunnel or reverse proxy on the same machine, such as ngrok or a local nginx, connects from this machine, so the callers it forwards still get `local-dev`.
116
+ On `eve dev`, `localDev()` also refuses connections from another machine, so LAN callers of `eve dev --host 0.0.0.0` aren't accepted as `local-dev`. A tunnel or reverse proxy on the same machine, such as ngrok or a local nginx, connects locally, so its callers still get `local-dev`.
111
117
 
112
- Because it never opens a production deployment, `localDev()` is safe to leave in the walk. Still put a real authenticator ahead of it so production traffic has something to match.
118
+ `localDev()` is safe to leave in the walk. Still put a real authenticator ahead of it so production traffic has something to match.
113
119
 
114
120
  ### `vercelOidc()`
115
121
 
116
- Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted, which is why internal subagent and runtime callers authenticate with zero configuration. Tokens carrying an `external_sub` authenticate as user callers, but only when their `project_id` matches `VERCEL_PROJECT_ID` and their environment matches `VERCEL_TARGET_ENV` / `VERCEL_ENV`. In that case `external_sub` becomes the session subject, and the profile claims (`name`, `picture`, `email`) show up in `ctx.session.auth.current.attributes`. To admit tokens minted by other Vercel projects, pass `subjects: [...]` (AWS IAM-style `*` wildcards).
122
+ Verifies a bearer JWT against the [Vercel OIDC issuer](https://vercel.com/docs/oidc). Tokens minted for the current `VERCEL_PROJECT_ID` are always accepted, so internal subagent and runtime callers authenticate with no configuration. To admit tokens from other Vercel projects, pass `subjects: [...]` (AWS IAM-style `*` wildcards).
117
123
 
118
- Auth fails closed: routes reject unauthenticated traffic by default, and the OIDC user branch verifies `external_sub` against `VERCEL_PROJECT_ID` and the deployment environment, returning `false` when either is unset. An external-subject token cannot authenticate on a deployment that hasn't pinned its project.
124
+ Tokens carrying an `external_sub` authenticate as user callers. Their `project_id` must match `VERCEL_PROJECT_ID`, and their environment must match `VERCEL_TARGET_ENV` / `VERCEL_ENV`. If either variable is unset, these tokens fail. `external_sub` becomes the session subject, and the `name`, `picture`, and `email` claims appear in `ctx.session.auth.current.attributes`.
119
125
 
120
- To also permit [stubbed eval sessions](../evals/tool-stubs), use `eveVercelOidc` from `eve/channels/eve`. It takes the same options, and its subject entries can grant [tool replacement permission](#tool-replacement-permission).
126
+ `vercelOidc()` only authenticates. To also permit [stubbed eval sessions](../evals/tool-stubs), use `eveVercelOidc` from `eve/channels/eve` with the same options. Its subject entries can grant [tool replacement permission](#tool-replacement-permission): `{ subject: vercelSubject({ teamSlug: "acme", projectName: "eval-runner" }), allowToolStubs: true }`. Plain subject strings, and tokens accepted only because they come from the current project, grant ordinary access only.
121
127
 
122
128
  #### `subjects` patterns and `vercelSubject(...)`
123
129
 
124
- Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner:<team>:project:<name>:environment:<env>`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time, and defaults `environment` to `"production"` when you omit it, so an unspecified environment cannot silently accept preview or development tokens:
130
+ Each `subjects` entry is matched against the token's `sub` claim, shaped `owner:<team>:project:<name>:environment:<env>`. A hand-written typo silently rejects every caller, and an over-broad `*` silently admits unrelated ones, so build the pattern with `vercelSubject(...)`. It rejects malformed input at construction time. Omit `environment` to match only `"production"`:
125
131
 
126
132
  ```ts
127
133
  import { vercelOidc, vercelSubject } from "eve/channels/auth";
@@ -134,13 +140,13 @@ vercelOidc({
134
140
  });
135
141
  ```
136
142
 
137
- `teamSlug` and `projectName` are the human-readable slugs Vercel embeds in `sub` (not the stable `team_…` / `prj_…` IDs), so they can't contain `:` or `*`. `environment` is `"production" | "preview" | "development" | "*"`. Only hand-write the subject string yourself when you actually mean to match across teams with a wildcard.
143
+ `teamSlug` and `projectName` are the human-readable slugs in `sub`, not the `team_…` / `prj_…` IDs, and can't contain `:` or `*`. `environment` is `"production" | "preview" | "development" | "*"`. Hand-write the subject string only to match across teams with a wildcard.
138
144
 
139
145
  ### Custom verifiers
140
146
 
141
- When none of the shipped helpers fit, write your own `AuthFn` (the array example above) or call the low-level verifiers directly. Each verifier is the pure function sitting behind the matching strategy helper, and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
147
+ When no helper fits, write your own `AuthFn` (the array example above) or call the low-level verifiers directly.
142
148
 
143
- A custom `AuthFn` doesn't declare a `WWW-Authenticate` scheme by default, so `routeAuth` falls back to `Bearer` for it. Wrap it with `withAuthChallenges(fn, challenges)` to declare the scheme(s) it actually satisfies, so a mixed `auth` array produces an accurate 401:
149
+ A custom `AuthFn` declares no `WWW-Authenticate` scheme, so `routeAuth` falls back to `Bearer`. Wrap it with `withAuthChallenges(fn, challenges)` to declare the schemes it satisfies, so a mixed `auth` array produces an accurate 401:
144
150
 
145
151
  ```ts
146
152
  import { withAuthChallenges, type AuthFn } from "eve/channels/auth";
@@ -151,6 +157,8 @@ const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
151
157
  );
152
158
  ```
153
159
 
160
+ Each verifier is the pure function behind a helper and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
161
+
154
162
  | Verifier | Behind | Input |
155
163
  | -------------------------------------- | -------------- | -------------------------------- |
156
164
  | `verifyHttpBasic(header, credentials)` | `httpBasic()` | raw `Authorization` header value |
@@ -159,7 +167,7 @@ const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
159
167
  | `verifyOidc(token, config)` | `oidc()` | bearer token (OIDC, any issuer) |
160
168
  | `verifyVercelOidc(token, opts)` | `vercelOidc()` | bearer token (Vercel OIDC) |
161
169
 
162
- Pull the token with `extractBearerToken(request.headers.get("authorization"))` before you hand it to the JWT/OIDC verifiers. The configs (`VerifyJwtHmacConfig`, `VerifyJwtEcdsaConfig`, `VerifyOidcConfig`) take `issuer`, `audiences`, the signing material (`secret` / `publicKey` / `discoveryUrl`), and optional `subjects` / `claims` matchers.
170
+ Extract the token with `extractBearerToken(request.headers.get("authorization"))` before passing it to the JWT/OIDC verifiers. The configs (`VerifyJwtHmacConfig`, `VerifyJwtEcdsaConfig`, `VerifyOidcConfig`) take `issuer`, `audiences`, the signing material (`secret` / `publicKey` / `discoveryUrl`), and optional `subjects` / `claims` matchers.
163
171
 
164
172
  ```ts
165
173
  import { extractBearerToken, verifyJwtHmac, type AuthFn } from "eve/channels/auth";
@@ -180,7 +188,7 @@ function hmacAuth(): AuthFn<Request> {
180
188
 
181
189
  ### Failure responses in custom `defineChannel` routes
182
190
 
183
- If a `defineChannel` route handler runs its own checks instead of `routeAuth`, it can still emit a framework-shaped failure with `createUnauthorizedResponse(...)`. You get back a `Response` with `cache-control: no-store`, a `{ ok: false, code, error }` JSON body, and one `www-authenticate` header per challenge:
191
+ A `defineChannel` route that runs its own checks instead of `routeAuth` can return a framework-shaped failure from `createUnauthorizedResponse(...)`. The `Response` has `cache-control: no-store`, a `{ ok: false, code, error }` JSON body, and one `www-authenticate` header per challenge:
184
192
 
185
193
  ```ts title="agent/channels/intake.ts"
186
194
  import { defineChannel, POST } from "eve/channels";
@@ -202,11 +210,11 @@ export default defineChannel({
202
210
  });
203
211
  ```
204
212
 
205
- `UnauthenticatedError` and `ForbiddenError` wrap this builder (status `401` / `403`). Throw those from an `AuthFn` that `routeAuth` walks. Call `createUnauthorizedResponse` directly only when you're returning a `Response` from a hand-rolled route.
213
+ `UnauthenticatedError` (`401`) and `ForbiddenError` (`403`) wrap this builder; throw them from an `AuthFn` that `routeAuth` walks. Call `createUnauthorizedResponse` directly only when returning a `Response` from a hand-rolled route.
206
214
 
207
215
  ## Network policy
208
216
 
209
- `eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)` for cutting off requests before any model work starts. A request that fails the network policy is dropped ahead of both auth and runtime execution.
217
+ `eve/channels/auth` exports `createIpAllowList(...)` and `isIpAllowed(...)`. A request that fails the network policy is dropped before auth and runtime execution.
210
218
 
211
219
  ## Replace `placeholderAuth` before production
212
220
 
@@ -221,15 +229,15 @@ export default eveChannel({
221
229
  });
222
230
  ```
223
231
 
224
- In production, `placeholderAuth()` returns a structured `401` so a generated web chat app can say "auth isn't configured yet" instead of throwing an internal error. Replace it before a browser caller submits a production request: swap in your app's `AuthFn` or one of the shipped helpers. Delete the authored channel file entirely and eve selects the default channel source with `[vercelOidc(), localDev(), placeholderAuth()]`, which also rejects production traffic.
232
+ In production, `placeholderAuth()` returns a structured `401`, so a generated web chat app can report that auth isn't configured. Replace it with your app's `AuthFn` or a shipped helper before browser callers reach production. Without an authored channel file, eve uses the same `[vercelOidc(), localDev(), placeholderAuth()]` policy, which also rejects production traffic.
225
233
 
226
- You do not have to keep `vercelOidc()` in the final policy. For a self-hosted app, an app-embedded frontend, or any deployment that uses a non-Vercel identity system, use `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, generic `oidc()`, or a custom `AuthFn` that maps your verified user/session/API key into a `SessionAuthContext`.
234
+ You don't have to keep `vercelOidc()`. For a self-hosted app, an app-embedded frontend, or a non-Vercel identity system, use `httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, generic `oidc()`, or a custom `AuthFn`. A custom `AuthFn` maps your verified user, session, or API key to a `SessionAuthContext`.
227
235
 
228
- Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets never land in compiled artifacts. The runtime re-materializes them from the authored channel definition at boot.
236
+ Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets are never written into build output. eve reads them from your channel file when the server starts.
229
237
 
230
238
  ## Accepting forwarded identity from another deployment
231
239
 
232
- A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on create and continuation requests as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
240
+ A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) sends its end user's identity on create and follow-up requests as a `forwardedPrincipal` body field. eve rejects every forwarded identity with `403` until you name the forwarders you trust with `trustedForwarders` on `eveChannel`:
233
241
 
234
242
  ```ts title="agent/channels/eve.ts"
235
243
  import { eveChannel } from "eve/channels/eve";
@@ -243,11 +251,11 @@ export default eveChannel({
243
251
  });
244
252
  ```
245
253
 
246
- `trustedForwarders` authorizes the verified forwarder to supply eve delegation context: principal identity, parent session lineage, and, with principal forwarding, trace-content constraints. Match it precisely: `() => true` grants this authority to every caller that passes route auth, including preview deployments accepted by `vercelOidc()`. The framework default channel rejects forwarded principals and ignores the other context.
254
+ `trustedForwarders` lets the verified forwarder supply delegation context: the user's identity, the parent session chain, and, when it forwards an identity, trace-content limits. Match it precisely: `() => true` grants this authority to every caller that passes route auth, including preview deployments accepted by `vercelOidc()`. eve's default channel rejects forwarded identities and ignores the other context.
247
255
 
248
256
  ### Limiting what a forwarder may assert
249
257
 
250
- A forwarder accepted on its identity alone can assert any principal, including identities your tools trust directly, such as a Slack user or an app principal. When a forwarder should speak only for its own users, check what it asserts with the predicate's second argument:
258
+ A predicate that checks only the forwarder lets it claim any identity, such as a Slack user or app identity your tools trust. To limit a forwarder to its own users, check the claim in the predicate's second argument:
251
259
 
252
260
  ```ts title="agent/channels/eve.ts"
253
261
  import { eveChannel } from "eve/channels/eve";
@@ -275,41 +283,50 @@ export default eveChannel({
275
283
  });
276
284
  ```
277
285
 
278
- `assertion.principal` holds the `current` and `initiator` contexts the forwarder asserts, already stamped with `eve:forwarded-by`. `initiator` equals `current` when the sender omits it. `initiator` takes effect only on session creation; on continuation the predicate still sees the asserted `initiator`, but the session keeps its original initiator, so checking it does not constrain that pinned value. Attributes are asserted too, so check any attribute your tools trust. `assertion.principal` is absent when the predicate decides parent session lineage for a request that forwards no principal; a predicate that requires it accepts that forwarder's lineage only alongside a principal it accepts. The `ForwardedAssertion` and `TrustedForwarders` types are exported from `eve/channels/eve` for named predicates.
286
+ `assertion.principal` holds the `current` and `initiator` contexts the forwarder claims, already stamped with `eve:forwarded-by`. `initiator` equals `current` when the sender omits it. The forwarder supplies attributes too, so check any attribute your tools trust.
287
+
288
+ `initiator` takes effect only when the session is created. On a follow-up request, the predicate still sees the claimed `initiator`, but the session keeps its original initiator. Checking `initiator` on a follow-up doesn't change that original value.
279
289
 
280
- When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller.
290
+ `assertion.principal` is absent when a request forwards the parent session chain without an identity. A predicate that requires `assertion.principal` accepts that forwarder's session chain only alongside an identity it accepts. The `ForwardedAssertion` and `TrustedForwarders` types are exported from `eve/channels/eve` for named predicates.
281
291
 
282
- The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Forwarded identity rejections fail loud: a forwarded body without `trustedForwarders` configured, or with a forwarder or assertion the predicate refuses, is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
292
+ When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user as if they had called your deployment directly. On a follow-up request, only `auth.current` is replaced. User-scoped connections, local subagents, and further `forwardPrincipal` hops see the active turn's caller.
283
293
 
284
- Trusted parent session lineage populates `ctx.session.parent` and preserves the root session across the delegation chain. Untrusted lineage is ignored, and accepted lineage does not remove the normal root-session token cap.
294
+ The receiver always overwrites the `eve:forwarded-by` attribute on accepted contexts, so a forwarder can't falsify it. A forwarded body without `trustedForwarders`, or one the predicate refuses, gets `403`; a malformed payload gets `400`. Only identity metadata reaches the receiver, never tokens or credentials.
285
295
 
286
- For requests marked as remote delegations by a callback body and valid sampled `traceparent`, the same accepted `trustedForwarders` result may admit an origin audience and directional content ceiling from one W3C Baggage member. The assertion is not an authorization grant: the receiver's trace policy independently decides against the immutable origin audience, and the two decisions are intersected. Every later hop forwards only that narrowed result. Malformed, partial, unsampled, or mixed-version assertions become metadata-only. The callback and headers are caller-supplied; the verified transport principal and `trustedForwarders` are the trust boundary. See [Preserving trace content](./remote-agents#preserving-trace-content).
296
+ A trusted parent session chain fills `ctx.session.parent` and keeps the same root session across every hop. eve ignores an untrusted chain. The root session's normal token cap still applies to an accepted chain.
287
297
 
288
- W3C `traceparent`, `tracestate`, and the forwarded conversation ID are correlation metadata. They do not require `trustedForwarders`, establish session lineage, or grant session access.
298
+ A remote delegation request carries a callback body and a valid sampled `traceparent`. On such a request, an accepted `trustedForwarders` result can also admit an origin audience and input and output content limits from one W3C Baggage member. These values grant no authorization. The receiver's own trace policy also decides, using the origin audience. eve keeps only what both decisions allow, and later hops forward only that narrowed result. A malformed, partial, unsampled, or mixed-version value falls back to metadata-only tracing. The caller supplies the callback and headers, so trust rests only on the verified caller identity and `trustedForwarders`. See [Preserving trace content](./remote-agents#preserving-trace-content).
289
299
 
290
- > ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
300
+ W3C `traceparent`, `tracestate`, and the forwarded conversation ID are correlation metadata. They don't require `trustedForwarders`, link sessions, or grant session access.
291
301
 
292
- Subagent sessions are persistent by default, but they do not preserve caller authority between turns. Every accepted follow-up replaces `auth.current`, including replacing it with no authenticated caller on internal local delivery; per-user connection lookup is then keyed from that current principal. This prevents a later caller from resolving a prior caller's OAuth grant. It does not hide the persistent session's conversation history or artifacts from a caller who is otherwise allowed to continue that session; session ownership remains an application policy.
302
+ > ⚠️ Both deployments must support forwarding on follow-up requests before you resume persistent remote sessions. A receiver that supports forwarding only on create rejects a forwarded follow-up with HTTP 400. The sender doesn't fall back to sending as its own service. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity).
303
+
304
+ Subagent sessions persist by default but don't keep a caller's access between turns. Every accepted follow-up replaces `auth.current`, and clears it when an internal local message has no caller. Per-user connections use that caller, so a later caller can't use a prior caller's OAuth grant. A caller allowed to continue the session still sees its conversation history and artifacts. Your application decides who may use a session.
293
305
 
294
306
  ## What reaches `ctx.session.auth`
295
307
 
296
- Inside runtime code, `ctx.session.auth` carries the result of the channel's route auth (the walk above) forward as the caller snapshot:
308
+ Inside runtime code, `ctx.session.auth` carries the channel's route-auth result as a caller snapshot:
309
+
310
+ - `auth.current`: the caller on the active inbound turn. A follow-up from a different caller replaces it for that turn.
311
+ - `auth.initiator`: the caller that started the session. It never changes.
312
+
313
+ The caller stays the same for the whole turn; only its claims can change:
314
+
315
+ - A message from the turn's own caller joins the turn and updates `auth.current` with its claims. This includes a typed answer to a pending `ctx.ask()` or `ask_question`.
316
+ - A message from anyone else waits for the turn to end and runs as its own turn.
317
+ - Someone else can still answer a pending request with a button or structured response. The request then records them as its responder, and the turn keeps its `auth.current`.
297
318
 
298
- - `auth.current`: the caller on the active inbound turn.
299
- - `auth.initiator`: the caller that started the durable session.
300
- - A follow-up message updates `auth.current` but leaves `auth.initiator` alone. When a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
301
- - Within a turn the principal is fixed; only its claims may update. A message from the turn's own principal, including a typed answer to a pending `ctx.ask()` or `ask_question`, joins the turn and updates `auth.current` with its claims. A message from anyone else waits for the turn to end and runs as its own turn. Someone else can still answer a pending request with a button or structured response; that settles the request with them as its responder, and the turn keeps its `auth.current`.
302
- - `auth.current` is whatever the channel passed as `auth` when it dispatched the message. Route auth either accepts the request or returns `401`, but a route handler or channel hook can still dispatch with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`. On a continuation, `auth.current` is `null` while `auth.initiator` stays pinned to the session's original caller. Internal runtime paths, such as subagents, can also have no caller auth.
319
+ `auth.current` is whatever `auth` the channel sent the message with. A route handler or channel hook can send with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`; on a continuation, only `auth.current` is. Internal runtime paths, such as subagents, can also have no caller auth.
303
320
 
304
- Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth. Access is decided at the HTTP boundary, and the durable session carries the caller snapshot forward into your runtime code.
321
+ Use the caller on `auth.current` (or `auth.initiator`) to limit tools, choose [dynamic tools, skills, and other definitions](./dynamic-capabilities) per user, or enforce tenant boundaries.
305
322
 
306
- Route auth does not enforce session ownership. If multiple users or tenants can reach the same route, you must implement the per-user, per-tenant, or per-session authorization your application requires.
323
+ Route auth doesn't check who may use a session, and eve adds no per-session access list. If multiple users or tenants can reach the same route, implement the per-user, per-tenant, or per-session authorization your application requires.
307
324
 
308
325
  ## Tool replacement permission
309
326
 
310
- Creating a [stubbed eval session](../evals/tool-stubs) requires an explicit `allowToolStubs: true` in the verified route authentication result. The target's server configuration grants permission; request JSON cannot. With `eveVercelOidc`, put the grant on a `subjects` entry, as in the [tool stubs example](../evals/tool-stubs#permit-tool-replacement). Any matching entry with the grant permits replacement; other entries do not revoke it. Implicit current-project acceptance and user principals do not inherit project grants.
327
+ Creating a [stubbed eval session](../evals/tool-stubs) requires `allowToolStubs: true` in the verified route authentication result; request JSON can't grant it. With `eveVercelOidc`, put the grant on a `subjects` entry, as in the [tool stubs example](../evals/tool-stubs#permit-tool-replacement). Any matching entry with the grant permits replacement, and other entries don't revoke it. Tokens accepted only because they come from the current project, and user callers, don't inherit project grants.
311
328
 
312
- Custom authenticators return the same grant after verifying their caller; type standalone callbacks as `EveAuthFn` from `eve/channels/eve`. For example, this alternative channel permits stubs only in local development:
329
+ Custom authenticators return the same grant after verifying their caller. Type a standalone callback as `EveAuthFn` from `eve/channels/eve`. This channel permits stubs only in local development:
313
330
 
314
331
  ```ts
315
332
  import { localDev } from "eve/channels/auth";
@@ -324,9 +341,9 @@ export default eveChannel({
324
341
  });
325
342
  ```
326
343
 
327
- The channel checks the grant before forwarded-principal handling or `onMessage` projection. It removes the grant before using the identity for forwarding, audience classification, or session persistence. This is an authentication-result permission, not a session attribute.
344
+ eve removes the grant from the caller identity before it forwards or saves that identity, or uses it for audience classification.
328
345
 
329
- Later messages, approvals, controls, and result reads use normal channel authentication. There is no additional creator-only rule or replacement-permission recheck. Anyone your channel admits to an existing session can use its configured stubs; apply the same application-specific session-access policy you need for ordinary sessions.
346
+ Later messages, approvals, controls, and result reads use normal channel authentication without rechecking the grant. Anyone your channel admits to an existing session can use its configured stubs, so apply the same session-access policy as for ordinary sessions.
330
347
 
331
348
  ## Agent info access
332
349
 
@@ -343,9 +360,9 @@ const authenticateStaff: EveAuthFn = async (request) => {
343
360
 
344
361
  ## Tool and connection auth
345
362
 
346
- Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools should resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
363
+ Tool and connection auth signs your agent in to an external service that needs an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token. eve drives the sign-in, reuses the token within a step, and re-runs the call once the caller authorizes.
347
364
 
348
- The principal for user-scoped tool and connection auth comes from route auth. `connect("...")` from `@vercel/connect/eve` defaults to `principalType: "user"`, so the active session must have `ctx.session.auth.current.principalType === "user"` before the first token lookup can start OAuth. If the session is anonymous, local-dev-only, runtime-scoped, or service-scoped, eve fails fast with `reason: "principal_required"` because there is no end-user identity to bind the OAuth grant to.
365
+ The user for user-scoped auth comes from route auth. `connect("...")` from `@vercel/connect/eve` defaults to `principalType: "user"`, so OAuth can start only when `ctx.session.auth.current.principalType === "user"`. An anonymous, local-dev, runtime, or service session fails fast with `reason: "principal_required"`, because no end-user identity exists to bind the grant to.
349
366
 
350
367
  Use app-scoped auth when the external service should act as the agent itself:
351
368
 
@@ -359,7 +376,7 @@ Use user-scoped auth when the external service should act as the signed-in perso
359
376
  auth: connect("linear/myagent");
360
377
  ```
361
378
 
362
- For user-scoped auth in a browser app, the route-auth entry for the eve channel should verify your app session and return a user principal:
379
+ For user-scoped auth in a browser app, have the eve channel's route auth verify your app session and return a user identity:
363
380
 
364
381
  ```ts title="agent/channels/eve.ts"
365
382
  import { eveChannel } from "eve/channels/eve";
@@ -388,17 +405,17 @@ export default eveChannel({
388
405
  });
389
406
  ```
390
407
 
391
- Keep `principalId` stable for the same person, and include an `issuer` when the same app may accept users from multiple identity providers. The connection token cache keys user credentials by issuer and principal id so two providers cannot accidentally share a grant.
408
+ Keep `principalId` stable for the same person, and include an `issuer` when the app accepts users from multiple identity providers. eve keys user credentials by issuer and principal ID, so two identity providers can't share a grant.
392
409
 
393
- Built-in platform channels that identify a human sender, such as Slack, Discord, Teams, Telegram, Twilio, Linear, and GitHub, attach a user principal for that sender by default. A Slack mention, DM, or button click can therefore authorize a user-scoped connection for the Slack user who sent it without adding a separate browser-session auth function.
410
+ Built-in platform channels that identify a human sender attach a user identity for that sender by default. These include Slack, Discord, Teams, Telegram, Twilio, Linear, and GitHub. A Slack mention, DM, or button click can authorize a user-scoped connection for that Slack user without a browser-session auth function.
394
411
 
395
412
  ### On a connection
396
413
 
397
- Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval interaction, and self-hosted OAuth flow.
414
+ Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval prompt, and self-hosted OAuth flow.
398
415
 
399
416
  ### On a single tool
400
417
 
401
- When one tool calls a service behind OAuth, keep the auth provider at the call site and skip the separate connection. Providers take the same shapes as connection `auth`: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
418
+ When one tool calls a service behind OAuth, keep the auth provider at the call site instead of adding a connection. Providers take the same shapes as connection `auth`: `connect("...")` for Vercel Connect-backed OAuth, a custom interactive definition, or a plain `{ getToken }` for static credentials.
402
419
 
403
420
  ```ts title="agent/tools/list_okta_groups.ts"
404
421
  import { defineTool } from "eve/tools";
@@ -420,7 +437,7 @@ export default defineTool({
420
437
  });
421
438
  ```
422
439
 
423
- This same inline shape naturally handles tools that need more than one credential:
440
+ The same inline shape handles tools that need more than one credential:
424
441
 
425
442
  ```ts title="agent/tools/sync_ticket.ts"
426
443
  import { connect } from "@vercel/connect/eve";
@@ -447,7 +464,7 @@ export default defineTool({
447
464
  });
448
465
  ```
449
466
 
450
- Configure provider-specific OAuth targeting on the provider itself. For Vercel Connect, pass `tokenParams` to `connect(...)` when you need explicit OAuth scopes, resource indicators, or rich authorization requests:
467
+ Configure OAuth targeting on the provider. For Vercel Connect, pass `tokenParams` to `connect(...)` for explicit OAuth scopes, resource indicators, or rich authorization requests:
451
468
 
452
469
  ```ts
453
470
  const githubAuth = connect({
@@ -466,14 +483,14 @@ const githubAuth = connect({
466
483
 
467
484
  The tool's `ctx` exposes provider-scoped auth accessors:
468
485
 
469
- - `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in machinery as connection auth, scoped to that provider's tool-qualified auth key.
470
- - `ctx.requireAuth(provider, options?)` evicts the cached token for that inline provider and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token returned by `ctx.getToken(provider)`.
486
+ - `ctx.getToken(provider, options?)` resolves an inline provider such as `connect("github/myagent")`. It uses the same cache, callback, and sign-in flow as connection auth, keyed to this tool and that provider.
487
+ - `ctx.requireAuth(provider, options?)` evicts that provider's cached token and starts a fresh authorization challenge. Use it after a downstream `401` rejects a token from `ctx.getToken(provider)`.
471
488
 
472
- Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to trigger the consent flow for that provider. If a downstream request later rejects an already-resolved token, call `ctx.requireAuth(provider)` to evict and re-authorize it.
489
+ Throw `ConnectionAuthorizationRequiredError` from an inline provider's `getToken` to start that provider's consent flow.
473
490
 
474
- Vercel Connect providers usually supply their own display name in the authorization challenge. Set `displayName` in the inline options only when you need to override what users see, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`. It is presentation-only.
491
+ Vercel Connect providers usually supply their own display name for the authorization challenge. To override what users see, set `displayName`, for example `ctx.getToken(customAuth, { displayName: "Salesforce" })`.
475
492
 
476
- Inline providers derive a stable tool-qualified auth key from Vercel Connect metadata when available. If you pass multiple custom providers that do not carry provider metadata, give each one an explicit auth key, for example `ctx.getToken(auth, { authKey: "github" })`. This `authKey` controls eve's cache and callback keys; it is not an OAuth scope.
493
+ Inline providers derive a stable auth key from Vercel Connect metadata when available. Give each custom provider without that metadata an explicit key, for example `ctx.getToken(auth, { authKey: "github" })`. `authKey` sets eve's cache and callback keys; it is not an OAuth scope.
477
494
 
478
495
  ## What to read next
479
496
 
@@ -3,14 +3,13 @@ title: "Session State"
3
3
  description: "Persist and resume eve client sessions with durable session IDs and stream cursors."
4
4
  ---
5
5
 
6
- The TypeScript client uses one durable session ID for messages, controls, and
7
- streams. A `ClientSession` adds a local `streamIndex` cursor so reconnects do not
8
- replay events already consumed by that handle.
6
+ A `ClientSession` is a handle on one session ID, used for messages, controls,
7
+ and streams. It also keeps a local `streamIndex` cursor, so reconnects skip
8
+ events the handle already read.
9
9
 
10
10
  ## Read and persist state
11
11
 
12
- Create the session with its first turn, then persist `session.state` after
13
- consuming the delivery:
12
+ Save `session.state` after you read a response:
14
13
 
15
14
  ```ts
16
15
  const { session, delivery } = await client.sessions.create({
@@ -21,10 +20,11 @@ await delivery.result();
21
20
  await saveSessionState(session.state);
22
21
  ```
23
22
 
24
- The state is deliberately small:
23
+ The state holds the ID, the cursor, and an optional routing handle:
25
24
 
26
25
  ```ts
27
26
  interface ClientSessionState {
27
+ inbox?: string; // opaque; save and restore it unchanged
28
28
  sessionId: string;
29
29
  streamIndex: number;
30
30
  /** Opaque; persist it and pass it back unchanged. eve may extend it. */
@@ -32,8 +32,8 @@ interface ClientSessionState {
32
32
  }
33
33
  ```
34
34
 
35
- It is a remote stream cursor, not a transcript. Persist events separately when
36
- your application renders chat history.
35
+ It is a stream cursor, not a transcript. Save events separately when your
36
+ application renders chat history.
37
37
 
38
38
  ## Resume a saved session
39
39
 
@@ -46,31 +46,29 @@ const saved = (await loadSessionState()) as ClientSessionState;
46
46
  const session = client.sessions.attach(saved.sessionId, saved);
47
47
 
48
48
  const response = await session.send("Now shorten it.");
49
- console.log((await response.result()).message);
49
+ console.log((await response.result()).reply);
50
50
  ```
51
51
 
52
52
  Pass the whole saved state so its optional [`inbox`](./overview#faster-sends-with-inbox) value
53
53
  reaches later sends. `attach()` performs no request. Every later operation targets exactly
54
- `saved.sessionId`; it never follows or creates a replacement.
54
+ `saved.sessionId` and never creates a replacement.
55
55
 
56
- `send()` correlates its response with the message accepted by the server. If the
57
- saved cursor is behind, it skips earlier turns and advances past them before
58
- collecting the new result, including when another turn is active or queued. You
59
- do not need to drain the stream before sending. Upgrade the server alongside the
60
- client: a server that omits the accepted delivery identity causes `send()` to
61
- throw instead of returning an ambiguous result.
56
+ `send()` returns the response to the message the server accepted. If the saved
57
+ cursor is behind, the response skips earlier turns, even while another turn is
58
+ active or queued. You don't need to read the rest of the stream first. `send()`
59
+ throws when the server's reply has no delivery ID, so upgrade the server with
60
+ the client.
62
61
 
63
- If a configured reconnect limit ends the stream before the accepted turn reaches
64
- a boundary, collecting its response throws. A partial stream is not a completed
65
- result.
62
+ If a reconnect limit you set ends the stream before the turn finishes or pauses,
63
+ `result()` throws instead of returning a partial result.
66
64
 
67
65
  <a id="waiting-completed-and-reset-sessions" />
68
66
 
69
67
  ## Waiting, completed, and ended sessions
70
68
 
71
- A session that hasn't ended (`session.ended`) accepts another message through the
69
+ A session that hasn't ended (`session.ended`) accepts more messages through the
72
70
  same handle. An ended session does not. Start a fresh conversation
73
- explicitly with another `client.sessions.create(firstTurn)` call.
71
+ with another `client.sessions.create(firstTurn)` call.
74
72
 
75
73
  ```ts
76
74
  const ended = await session.end({ reason: "Start over" });
@@ -78,7 +76,7 @@ await ended.result();
78
76
  const { session: fresh, delivery } = await client.sessions.create({ message: "Begin again." });
79
77
  ```
80
78
 
81
- The old `session` remains pinned to its retired ID; `fresh` owns a different ID.
79
+ The old `session` keeps pointing at its retired ID; `fresh` has a different ID.
82
80
 
83
81
  ## Multiple sessions
84
82
 
@@ -97,13 +95,12 @@ await save("research", research.state);
97
95
  await save("support", support.state);
98
96
  ```
99
97
 
100
- The shared `Client` owns the base URL, auth, headers, and redirect policy. Each
101
- `ClientSession` owns its fixed ID and stream cursor.
98
+ The shared `Client` holds the base URL, auth, headers, and redirect policy. Each
99
+ `ClientSession` holds its fixed ID and stream cursor.
102
100
 
103
101
  ## Reconnect an existing stream
104
102
 
105
- `stream()` starts from the handle's saved cursor and advances it as events are
106
- read:
103
+ `stream()` starts from the handle's cursor and advances it as you read:
107
104
 
108
105
  ```ts
109
106
  const session = client.sessions.attach(saved.sessionId, saved);