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
@@ -4,123 +4,87 @@ description: "Expose external MCP and OpenAPI servers to the model, with connect
4
4
  url: /connections
5
5
  ---
6
6
 
7
- A connection wires an agent into an external server you don't author, either an MCP server (Linear, GitHub, a warehouse) or any HTTP API with an OpenAPI document. eve handles the parts you'd otherwise hand-roll, discovering the remote tools, surfacing them to the model, and brokering auth. To instead let eve communicate with users through an external service, use a [channel](/docs/channels/overview).
7
+ A connection gives your agent the tools of an external server you don't author: an MCP server, or an HTTP API with an OpenAPI document. Each connection is one file under `agent/connections/`. Use one when the model should call another service, such as Linear or GitHub, with credentials the model never sees.
8
8
 
9
- Connections live under `agent/connections/`. A static connection's runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. A dynamic connection file can instead resolve a caller-specific connection set at session or turn boundaries. The model never sees a connection's URL or credentials. It finds tools with the built-in [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill), where a query such as `linear__` searches one connection's tools, and calls them with `eve__tool`. Stream events, approval policies, and hooks name each call by its qualified name, `<connection>__<tool>` (e.g. `linear__list_issues`).
10
-
11
- A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve, except that a dynamic connection with exactly a static connection's name replaces that static connection; see [Naming and conflicts](/docs/guides/dynamic-capabilities#naming-and-conflicts). Both errors name the two sides of the conflict; rename either one.
12
-
13
- Static and dynamic connection definitions must use `defineMcpClientConnection`
14
- or `defineOpenAPIConnection` from `eve/connections`. Plain object exports are
15
- rejected because they do not identify a protocol.
16
-
17
- ## MCP connections
9
+ ```text
10
+ agent/
11
+ └── connections/
12
+ └── linear.ts # registers the "linear" connection
13
+ ```
18
14
 
19
- Use an MCP connection when the external service already exposes an MCP server. The server publishes its tools and schemas, and eve makes the matched tools callable by the model. Each tool's JSON Schema reaches the model as published, minus any arguments you supply with `toolCall.providedArguments`, and eve checks the model's arguments against it before it calls the server.
15
+ ```ts title="agent/connections/linear.ts"
16
+ import { defineMcpClientConnection } from "eve/connections";
20
17
 
21
- Read [MCP connections](/docs/connections/mcp) for `defineMcpClientConnection`, transport requirements, and MCP tool filters.
18
+ export default defineMcpClientConnection({
19
+ url: "https://mcp.linear.app/mcp", // required: the MCP server's endpoint
20
+ description: "Linear workspace.", // required: the model reads this to pick a connection
21
+ // optional: omit for servers that need no token
22
+ auth: {
23
+ principalType: "app", // the default: one shared credential for every session
24
+ getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
25
+ },
26
+ });
27
+ ```
22
28
 
23
- ## OpenAPI connections
29
+ The filename is the connection name, so this file registers as `"linear"`.
24
30
 
25
- Use an OpenAPI connection when the service exposes an OpenAPI 3.x document. eve turns operations in the document into connection tools, one per operation.
31
+ Define every connection with `defineMcpClientConnection` or `defineOpenAPIConnection` from `eve/connections`. eve rejects a plain object export because it does not name a protocol.
26
32
 
27
- Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnection`, `baseUrl`, and operation filters.
33
+ - The model finds tools with the built-in [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and calls them with `eve__tool`. A query such as `linear__` searches one connection's tools.
34
+ - Stream events, approval policies, and hooks name each call `<connection>__<tool>`, such as `linear__list_issues`.
35
+ - The model never sees a connection's URL or credentials, and tokens never enter the conversation history.
36
+ - A connection reserves its name and every name that starts with `<name>__`. No tool, subagent, or other connection can use them.
28
37
 
29
- ## Dynamic connections
38
+ ## Options
30
39
 
31
- Use `defineDynamic` when the connection set depends on the authenticated user,
32
- tenant, or another runtime lookup. Import it with the connection factories from
33
- `eve/connections`. The function returns one connection definition, a map, or `null`.
34
- Use `ctx.memo` for JSON observations that should stay fixed for a key.
40
+ `defineMcpClientConnection` and `defineOpenAPIConnection` share most fields:
35
41
 
36
- ```ts title="agent/connections/accounts.ts"
37
- import { defineDynamic, defineMcpClientConnection } from "eve/connections";
38
- import { accountAuth, listAccounts } from "../lib/accounts";
42
+ | Field | Default | What it does |
43
+ | --------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
44
+ | `url` (MCP) or `spec` (OpenAPI) | Required | The MCP server's endpoint, or the OpenAPI document. |
45
+ | `description` | Required | The model reads it to choose which connection to search. |
46
+ | `auth` | No token | Sends a token as `Authorization: Bearer <token>`. See the auth sections below. |
47
+ | `headers` | None | Extra HTTP headers. The map or each value can be a function of the session. |
48
+ | `approval` | Calls run without approval | `never()`, `once()`, `always()`, `auto()`, or your own policy. |
49
+ | `instanceKey` | None | A stable, non-secret account or tenant ID. Required on authenticated [dynamic connections](#dynamic-connections). |
50
+ | `toolCall.providedArguments` | None | Arguments your app supplies. eve removes them from the model's input schema. |
51
+ | `tools` (MCP) or `operations` (OpenAPI) | Every tool or operation | A filter with exactly one of `allow` or `block`. |
39
52
 
40
- export default defineDynamic(async (ctx) => {
41
- const userId = ctx.session.auth.current?.principalId;
42
- if (!userId) return null;
43
- const accounts = await ctx.memo(userId, async () =>
44
- (await listAccounts(userId)).map(({ description, id, mcpUrl, slug }) => ({
45
- description,
46
- id,
47
- mcpUrl,
48
- slug,
49
- })),
50
- );
51
- return Object.fromEntries(
52
- accounts.map((account) => [
53
- account.slug,
54
- defineMcpClientConnection({
55
- url: account.mcpUrl,
56
- description: account.description,
57
- instanceKey: account.id,
58
- auth: accountAuth(account.id),
59
- }),
60
- ]),
61
- );
62
- });
63
- ```
53
+ ## MCP connections
64
54
 
65
- For a single returned definition, the filename supplies the connection name.
66
- For a map, each bare map key becomes a connection name. Every entry must use
67
- `defineMcpClientConnection` or `defineOpenAPIConnection`. Authenticated entries
68
- must also set `instanceKey` to a stable, non-secret account or tenant identifier.
69
- Build connections and auth callbacks outside memos; memos keep only JSON observations.
70
- See [Dynamic capabilities](/docs/guides/dynamic-capabilities#dynamic-connections)
71
- for when eve evaluates connections, naming, conflicts, and failure behavior.
72
-
73
- Tools from a dynamic connection can require approval, including an
74
- `approval.response` policy. When an approval resumes, even in a fresh process,
75
- eve rebuilds the connection from its definition with saved memo results and checks the response
76
- policy. Before the approved call runs, eve
77
- checks that the connection's identity has not changed since the call requested
78
- approval. A changed connection fails the call rather than sending it to a
79
- replacement destination.
80
- Request a new tool call and approval after correcting the connection. Identity
81
- includes the endpoint and `instanceKey`; use a distinct `instanceKey` for each
82
- account or tenant even when they share an endpoint.
55
+ Use an MCP connection when the service exposes an MCP server. Each tool's JSON Schema reaches the model as the server publishes it, minus any arguments you supply with `toolCall.providedArguments`. eve validates the model's arguments against that schema before it calls the server.
83
56
 
84
- ## Static-token auth
57
+ Read [MCP connections](/docs/connections/mcp) for `defineMcpClientConnection`, transport requirements, and MCP tool filters.
85
58
 
86
- `getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange:
59
+ ## OpenAPI connections
87
60
 
88
- ```ts title="agent/connections/linear.ts"
89
- import { defineMcpClientConnection } from "eve/connections";
61
+ Use an OpenAPI connection when the service publishes an OpenAPI 3.x or Swagger 2.0 document. eve turns each operation into a connection tool.
90
62
 
91
- export default defineMcpClientConnection({
92
- url: "https://mcp.linear.app/mcp",
93
- description: "Linear workspace.",
94
- auth: {
95
- principalType: "app",
96
- getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
97
- },
98
- });
99
- ```
63
+ Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnection`, `baseUrl`, and operation filters.
100
64
 
101
- If the token has a known TTL, set `expiresAt` (milliseconds since epoch). Once it expires, eve calls `getToken` again before the next request, including requests on an existing MCP client.
65
+ ## Choose app vs. user auth
102
66
 
103
- When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Set `principalType: "user"` when each end-user carries their own token.
67
+ A connection credential belongs to the agent or to the person using it. Per-user credentials depend on route auth: eve gets a user's token only when `ctx.session.auth.current?.principalType === "user"`.
104
68
 
105
- eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
69
+ | Whose credential | Use when | Auth shape |
70
+ | ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
71
+ | App | The agent uses one shared service, bot, or app credential. | `auth: { getToken }` (the default `principalType: "app"`), or `connect({ connector, principalType: "app" })`. |
72
+ | User | Each end-user signs in with their own third-party account. | `connect("linear/myagent")`, or `auth: { principalType: "user", getToken }`. |
73
+ | User from a job | Background work uses the grant of the user who started it. | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |
106
74
 
107
- ## Choose app vs. user auth
75
+ `principalType: "user"` uses the token of the user already signed in on the session. It doesn't mean "ask a human later."
108
76
 
109
- A connection credential can belong to the agent or to the person using it. This choice is separate from route auth, but user-scoped connection auth depends on route auth: eve can only resolve a user token when the active session has `ctx.session.auth.current?.principalType === "user"`.
77
+ On a connection, `principalType` says whose credential it is, for both `getToken` auth and `connect()` from `@vercel/connect/eve`. In route auth, `principalType` describes the caller.
110
78
 
111
- | Credential owner | Use when | Auth shape |
112
- | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
113
- | App | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect. |
114
- | User | Each end-user should authorize and use their own third-party account. | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`. |
115
- | User from a job | Background work should use the same user's OAuth grant that started the work. | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |
79
+ ## Static-token auth
116
80
 
117
- `principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
81
+ `getToken` returns a `TokenResult` (`{ token, expiresAt? }`), as in the example at the top of this page. eve calls it on each connection attempt, so it can read the token from an env var, a secrets manager, or your own OAuth exchange.
118
82
 
119
- `principalType` selects credential ownership for both raw `getToken` auth and `connect()` from `@vercel/connect/eve`. The retired `credentialOwner` field is rejected. This ownership setting is separate from a route-auth session identity, where `principalType` describes the caller.
83
+ Set `expiresAt` (milliseconds since epoch) when the token has a known TTL. After that time, eve calls `getToken` again before the next request, including on an MCP client that is already open.
120
84
 
121
85
  ## No auth
122
86
 
123
- Drop `auth` entirely for servers that need no token, such as a localhost server during development or a public one:
87
+ Omit `auth` for servers that need no token, such as a public server or a localhost server during development:
124
88
 
125
89
  ```ts title="agent/connections/local.ts"
126
90
  import { defineMcpClientConnection } from "eve/connections";
@@ -131,11 +95,11 @@ export default defineMcpClientConnection({
131
95
  });
132
96
  ```
133
97
 
134
- Use no-auth connections only for services that are intentionally public, local-only, or otherwise protected outside eve. Do not use no-auth connections for sensitive third-party services.
98
+ Use no auth only for public, local-only, or externally protected services, never for sensitive third-party services.
135
99
 
136
100
  ## Headers
137
101
 
138
- Use `headers` when the server wants a non-Bearer scheme (an API-key header) or extra configuration. Headers stack on top of `auth` and work for both MCP and OpenAPI connections:
102
+ Use `headers` for a scheme other than Bearer, such as an API-key header, or for extra configuration. Headers add to `auth` and work on MCP and OpenAPI connections:
139
103
 
140
104
  ```ts title="agent/connections/example.ts"
141
105
  import { defineMcpClientConnection } from "eve/connections";
@@ -149,14 +113,16 @@ export default defineMcpClientConnection({
149
113
 
150
114
  ## Per-caller auth and headers
151
115
 
152
- When credentials or routing depend on the caller, make `auth` or `headers` a function. eve calls it inside the active turn and passes the same session context exposed to tools and hooks:
116
+ When credentials or routing depend on the caller, make `auth` or `headers` a function. eve calls it during the turn with the same session context that tools and hooks get:
153
117
 
154
118
  ```ts title="agent/connections/warehouse.ts"
155
119
  import { defineOpenAPIConnection } from "eve/connections";
156
120
 
157
121
  export default defineOpenAPIConnection({
158
122
  spec: "https://warehouse.example.com/openapi.json",
159
- description: "The caller's tenant-scoped warehouse.",
123
+ description: "The caller's tenant warehouse.",
124
+ // sync or async; returns the same object that static `auth` accepts,
125
+ // including a `connect(...)` provider
160
126
  auth: (ctx) => ({
161
127
  principalType: "user",
162
128
  getToken: async () => ({
@@ -169,7 +135,7 @@ export default defineOpenAPIConnection({
169
135
  });
170
136
  ```
171
137
 
172
- An `auth` resolver returns the same provider object accepted by static `auth`, including a `connect(...)` provider for interactive OAuth. The resolver itself can be async. Header callbacks can return the whole map, as above, or resolve individual values:
138
+ A header function can return the whole map, as above, or you can make each value a function:
173
139
 
174
140
  ```ts
175
141
  headers: {
@@ -177,11 +143,11 @@ headers: {
177
143
  }
178
144
  ```
179
145
 
180
- Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
146
+ Use `principalType: "user"` for per-user tokens, so eve rejects callers who aren't signed in and keeps each user's token separate. The `auth` function doesn't authenticate the inbound request; route auth does.
181
147
 
182
148
  ## Per-connection approval
183
149
 
184
- To put every tool a connection serves behind a human, use the helpers from `eve/tools/approval`:
150
+ To make a human approve every tool call on a connection, use the helpers from `eve/tools/approval`:
185
151
 
186
152
  ```ts title="agent/connections/linear.ts"
187
153
  import { defineMcpClientConnection } from "eve/connections";
@@ -190,14 +156,20 @@ import { once } from "eve/tools/approval";
190
156
  export default defineMcpClientConnection({
191
157
  url: "https://mcp.linear.app/mcp",
192
158
  description: "Linear workspace.",
193
- auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
194
159
  approval: once(),
195
160
  });
196
161
  ```
197
162
 
198
- `never()` lets every call through, `once()` asks for approval the first time in a session, `always()` asks every time, and `auto()` uses a decision model to allow routine calls and ask about dangerous or unclear effects. The pause and resume is the same human-in-the-loop flow covered in [Tools](/docs/tools).
163
+ | Helper | Behavior |
164
+ | ---------- | -------------------------------------------------------------------------- |
165
+ | `never()` | Lets every call through |
166
+ | `once()` | Asks the first time in a session |
167
+ | `always()` | Asks every time |
168
+ | `auto()` | A decision model allows routine calls and asks about risky or unclear ones |
199
169
 
200
- To decide per call, pass your own policy. It receives the same context as a tool's approval policy, with `toolName` set to the connection tool's full name, `<connection>__<tool>`, and `toolInput` set to the input the model sent:
170
+ [Tools](/docs/tools) covers how the turn pauses for the approval and continues after it.
171
+
172
+ To decide per call, pass your own policy. It gets the same context as a tool approval policy, with `toolName` set to `<connection>__<tool>` and `toolInput` set to the model's input:
201
173
 
202
174
  ```ts title="agent/connections/linear.ts"
203
175
  import { defineMcpClientConnection } from "eve/connections";
@@ -205,19 +177,48 @@ import { defineMcpClientConnection } from "eve/connections";
205
177
  export default defineMcpClientConnection({
206
178
  url: "https://mcp.linear.app/mcp",
207
179
  description: "Linear workspace.",
208
- auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
209
180
  approval: ({ toolName }) =>
210
181
  toolName === "linear__delete_comment" ? "user-approval" : "not-applicable",
211
182
  });
212
183
  ```
213
184
 
214
- For connection tools that can create, modify, delete, transmit, purchase, message, or access sensitive data, use approval, allow-lists, or other safeguards appropriate to the action.
185
+ Some connection tools create, modify, delete, transmit, purchase, message, or access sensitive data. Protect them with approval, allow-lists, or other safeguards that fit the action.
186
+
187
+ ### Send the approver to the server
188
+
189
+ [Approval is consent only](/docs/human-in-the-loop): it never changes who the turn runs as. An approved connection call keeps the requester's identity, so `ctx.session.auth.current` and the connection's `auth` token stay the requester's, and later calls in the turn are unaffected. While an approved call runs, its `headers` and `toolCall.providedArguments` callbacks also receive `ctx.approval.responder`, the person who approved it, with access to their credentials. That's a separate identity your code explicitly sends to the server, not a replacement for the requester:
190
+
191
+ ```ts title="agent/connections/gateway.ts"
192
+ import { defineMcpClientConnection } from "eve/connections";
193
+ import { always } from "eve/tools/approval";
194
+
195
+ export default defineMcpClientConnection({
196
+ url: "https://gateway.example.com/mcp",
197
+ description: "Internal systems through the MCP gateway.",
198
+ approval: {
199
+ request: always(),
200
+ response: ({ response }) =>
201
+ admins.includes(response.principal.principalId)
202
+ ? { status: "allowed" }
203
+ : { status: "rejected", reason: "Only admins can approve gateway calls." },
204
+ },
205
+ auth: gatewayAuth,
206
+ headers: async (ctx) => {
207
+ const approver = await ctx.approval?.responder.getToken(gatewayApproverAuth);
208
+ return approver === undefined ? {} : { "X-Approver-Token": approver.token };
209
+ },
210
+ });
211
+ ```
212
+
213
+ `ctx.approval.responder.getToken(provider)` resolves the approver's token as it does in a [`defineTool` tool](/docs/human-in-the-loop): it never starts a sign-in, and throws a `ConnectionAuthorizationFailedError` with `reason: "approver_authorization_required"` when the approver has no token. `headers` can't set `Authorization` when the connection also sets `auth`, so send the approver's token in another header, or omit `auth` and set `Authorization` yourself.
214
+
215
+ `ctx.approval` is absent for calls that needed no approval, and while eve connects to the server and lists its tools. The approver's identity reaches only the requests of the call they approved. Pair it with an `approval.response` policy so only people whose access the call may use can approve it.
215
216
 
216
217
  ## Interactive OAuth via Vercel Connect
217
218
 
218
- When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into eve's authorization flow.
219
+ [Vercel Connect](https://vercel.com/docs/connect) lets each end-user sign in to an OAuth server in their own browser. The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh through eve's sign-in flow.
219
220
 
220
- Create and attach the connector from the Vercel project or agent app that will use it:
221
+ Create and attach the connector from the Vercel project that will use it:
221
222
 
222
223
  ```bash
223
224
  npm install @vercel/connect
@@ -227,7 +228,7 @@ vercel connect attach <connector-uid> --yes
227
228
  vercel env pull
228
229
  ```
229
230
 
230
- Use the connector UID returned by the CLI in `connect("<connector-uid>")`. The service identifier accepted by `vercel connect create` depends on the provider; it is not necessarily the same as an MCP runtime URL or OpenAPI base URL.
231
+ Pass the connector UID that `vercel connect create` returns to `connect("<connector-uid>")`. The `--name` display name isn't the UID. The service identifier for `vercel connect create` depends on the provider, and can differ from the MCP URL or OpenAPI base URL.
231
232
 
232
233
  ```ts title="agent/connections/linear.ts"
233
234
  import { connect } from "@vercel/connect/eve";
@@ -236,48 +237,27 @@ import { defineMcpClientConnection } from "eve/connections";
236
237
  export default defineMcpClientConnection({
237
238
  url: "https://mcp.linear.app/mcp",
238
239
  description: "Linear workspace: issues, projects, cycles, and comments.",
239
- auth: connect("linear/myagent"),
240
+ auth: connect("linear/myagent"), // per-user by default
241
+ // for one shared credential, use:
242
+ // auth: connect({ connector: "linear/myagent", principalType: "app" }),
240
243
  });
241
244
  ```
242
245
 
243
- Use the connector UID returned by `vercel connect create`; the display name passed to `--name` is not the UID. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, opens a sign-in (`interaction.opened` with `request.kind: "sign-in"`) when that user has not authorized yet, and resumes the parked turn after the callback completes.
244
-
245
- Discovering tools never posts a sign-in prompt for a service the answer does not need: `eve__search` never asks for sign-in. Before the user signs in, eve connects to an MCP server without a token, so a server that lists its tools anonymously is searched like any other connection, and sign-in starts only when one of its tools asks for it (see [When eve asks for sign-in](/docs/connections/mcp#when-eve-asks-for-sign-in)). Most OAuth MCP servers reject even tool listing without the user's token, so `search` lists such a connection as one result named after the connection, such as `linear`. The model asks for sign-in explicitly, one connection at a time, by calling that name with `eve__tool({ name: "linear" })`; once the user signs in, `eve__search({ query: "linear__" })` returns the connection's tools. Calling a tool with `eve__tool` on such a connection also asks for sign-in.
246
-
247
- A sign-in holds the turn open until the user connects, the turn is cancelled, or the user sends another message. That message steers the turn: eve withdraws the sign-in, its interaction settles `withdrawn`, and the model reads the message next. Messages from other people in a shared thread wait until the turn ends, and the completed sign-in resumes the turn as the person who started it.
248
-
249
- When a local subagent needs interactive authorization, eve surfaces the authorization lifecycle on the root session's channel, including through nested subagent chains. The challenge still points to the child session's callback, so completing it resumes the child directly while the parent continues waiting for its result. The parent's turn stays open: the relayed sign-in is the parent's own `interaction.opened`, and the turn resumes under the same `turnId` once the subagent returns.
246
+ eve gets the current user's token before each tool call. If that user hasn't signed in yet, eve sends an `interaction.opened` event with `request.kind: "sign-in"`. The turn continues after the OAuth callback completes.
250
247
 
251
- That means the channel that creates or continues the session must authenticate a real user. For a web app, configure `agent/channels/eve.ts` so your app session maps to `principalType: "user"`; for platform channels, use the built-in channel auth that maps the sender to a user principal. If no authenticated user is attached to the session, the first user-scoped connection call fails with `reason: "principal_required"`.
252
-
253
- If the remote service should act as the agent itself instead of the end-user, make the Connect connection app-scoped:
254
-
255
- ```ts title="agent/connections/linear.ts"
256
- import { connect } from "@vercel/connect/eve";
257
- import { defineMcpClientConnection } from "eve/connections";
248
+ `eve__search` never asks for sign-in. When a server refuses to list tools without a token, search shows the connection as one result named after it, such as `linear`. Calling that name or any of its tools asks for sign-in. See [When eve asks for sign-in](/docs/connections/mcp#when-eve-asks-for-sign-in).
258
249
 
259
- export default defineMcpClientConnection({
260
- url: "https://mcp.linear.app/mcp",
261
- description: "Linear workspace: issues, projects, cycles, and comments.",
262
- auth: connect({ connector: "linear/myagent", principalType: "app" }),
263
- });
264
- ```
250
+ A sign-in keeps the turn open until the user connects, the turn is cancelled, or the user sends another message. That message steers the turn: the sign-in ends as `withdrawn`, and the model reads the message next. Messages from other people in a shared thread wait until the turn ends. A completed sign-in continues the turn as the person who started it.
265
251
 
266
- App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. See [Authentication](/docs/guides/auth-and-route-protection) when a user-scoped connection needs your HTTP channel to establish the caller's identity.
252
+ When a local subagent at any depth needs sign-in, the root session's channel gets it as the parent's own `interaction.opened`. Completing it continues the child, and the parent's turn continues under the same `turnId` after the subagent returns.
267
253
 
268
- ### Troubleshooting Vercel Connect auth
254
+ The channel that creates or continues the session must authenticate a real user. For a web app, configure `agent/channels/eve.ts` to map your app session to `principalType: "user"`. Platform channels' built-in auth maps the sender to a user.
269
255
 
270
- | Symptom | What it means | Fix |
271
- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
272
- | `reason: "principal_required"` | A user-scoped connection ran without an authenticated user on the active session. | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |
273
- | A sign-in `interaction.opened` but no UI | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge. | Render the challenge from the stream event and continue the same session after the callback. |
274
- | OAuth works locally but fails after deploy | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |
275
- | A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal. | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work. |
276
- | Sign-in ends on a Vercel login or protection page | The deployment is behind Deployment Protection, and sign-in callback URLs never carry the automation bypass secret. | Have the user sign in to Vercel with access to the project, or add a Deployment Protection Exception for the domain. |
256
+ With `principalType: "app"`, the service acts as the agent, and nobody is asked to sign in. If the connector isn't installed or can't issue an app token, the tool call fails and doesn't retry, so an operator can fix the connector. See [Authentication](/docs/guides/auth-and-route-protection) to identify the caller in your HTTP channel.
277
257
 
278
258
  ## Self-hosted interactive OAuth
279
259
 
280
- To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; the factory pins that value for you.
260
+ To run your own OAuth without Vercel Connect, use `defineInteractiveAuthorization` from `eve/connections`. eve creates a callback URL and pauses the turn until the token comes back, even across restarts and redeploys. The factory always sets `principalType: "user"`.
281
261
 
282
262
  ```ts title="agent/connections/linear.ts"
283
263
  import {
@@ -290,15 +270,15 @@ export default defineMcpClientConnection({
290
270
  url: "https://mcp.linear.app/mcp",
291
271
  description: "Linear workspace.",
292
272
  auth: defineInteractiveAuthorization<{ verifier: string }>({
293
- // Probed before every tool call. Return a token to run the tool;
294
- // throw `Required` to start the consent flow.
273
+ // Runs before every tool call. Return a token to run the tool;
274
+ // throw `ConnectionAuthorizationRequiredError` to ask the user to sign in.
295
275
  getToken: async ({ principal }) => {
296
276
  const token = await loadStoredToken(principal);
297
277
  if (!token) throw new ConnectionAuthorizationRequiredError("linear");
298
278
  return { token };
299
279
  },
300
- // Runs in a durable step. Return the user-facing `challenge` and
301
- // an optional `resume` value the runtime journals across the park.
280
+ // Return the `challenge` the user sees and an optional `resume` value.
281
+ // eve saves `resume` until the callback arrives.
302
282
  startAuthorization: async ({ callbackUrl }) => {
303
283
  const verifier = makePkceVerifier();
304
284
  return {
@@ -306,10 +286,9 @@ export default defineMcpClientConnection({
306
286
  resume: { verifier },
307
287
  };
308
288
  },
309
- // Runs when the provider redirects to the callback URL. `resume` is
310
- // typed as `{ verifier: string } | undefined`; `callback.params`
311
- // holds the IdP's returned query/body params.
312
- // Persist the token here so `getToken` finds it on later tool calls.
289
+ // Runs on the provider's redirect. `resume` is `{ verifier } | undefined`;
290
+ // `callback.params` holds the provider's query or body params.
291
+ // Save the token so `getToken` finds it on later calls.
313
292
  completeAuthorization: async ({ principal, resume, callback }) => {
314
293
  const token = await exchangeCode(resume!.verifier, callback.params.code!);
315
294
  await saveStoredToken(principal, token);
@@ -319,33 +298,31 @@ export default defineMcpClientConnection({
319
298
  });
320
299
  ```
321
300
 
322
- `getToken` runs before every tool call. eve does not store tokens for you: the token returned from `completeAuthorization` is reused only within the current workflow step, so it never lands in durable session state. Save it in `completeAuthorization` (or let your OAuth provider keep it) and read it back in `getToken`. If `getToken` cannot find the token on a later call, eve asks the user to sign in again. `startAuthorization` and `completeAuthorization` are both-or-neither: provide one without the other and you get a definition error. The `challenge`'s public fields appear on the sign-in's `interaction.opened`, in `request.signIn`. Its fields:
301
+ eve doesn't store tokens for you, including the token `completeAuthorization` returns. Save it there, or let your OAuth provider keep it, and read it in `getToken`. If `getToken` can't find it on a later call, eve asks the user to sign in again.
302
+
303
+ Provide both `startAuthorization` and `completeAuthorization`, or neither. One alone is a definition error. The `challenge` fields appear in `request.signIn` on the sign-in's `interaction.opened` event:
323
304
 
324
- | Field | Purpose |
325
- | -------------- | ----------------------------------------------------------------------------------------- |
326
- | `url` | The authorize URL for redirect or device flows. |
327
- | `userCode` | The device code, for device flows. |
328
- | `instructions` | The call to action when there's no URL. |
329
- | `displayName` | Human-readable provider name channels show on the sign-in affordance (e.g. "Salesforce"). |
305
+ | Field | Purpose |
306
+ | -------------- | ------------------------------------------------------------------------------ |
307
+ | `url` | The authorize URL for redirect or device flows. |
308
+ | `userCode` | The device code, for device flows. |
309
+ | `instructions` | The call to action when there's no URL. |
310
+ | `displayName` | The provider name channels show on the sign-in prompt, such as `"Salesforce"`. |
330
311
 
331
- Drop `resume` when the provider keeps flow state server-side, so nothing has to cross the step boundary.
312
+ Omit `resume` when the provider keeps flow state on its server.
332
313
 
333
- The callback URL never carries `VERCEL_AUTOMATION_BYPASS_SECRET`, because the user's browser and the provider both see it. On a deployment behind [Deployment Protection](https://vercel.com/docs/deployment-protection), the person signing in must pass protection on their own, for example through Vercel Authentication or a [Deployment Protection Exception](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/deployment-protection-exceptions).
314
+ `displayName` set on the `auth` definition, such as `auth: { ...connect("salesforce/myagent"), displayName: "Salesforce" }`, wins over the challenge's value. When neither is set, channels title-case the connection name.
334
315
 
335
- `displayName` is presentation-only. The connection's resolved name still keys
336
- the callback URL, while eve scopes token caching and authorization completion
337
- to the opaque resolved instance identity. You can also set `displayName` on the
338
- `auth` definition itself (e.g.
339
- `auth: { ...connect("salesforce/myagent"), displayName: "Salesforce" }`); that
340
- definition-level value wins over one the strategy stamps on the challenge, and
341
- channels fall back to title-casing the connection name when neither is set.
316
+ The callback URL never carries `VERCEL_AUTOMATION_BYPASS_SECRET`, because the user's browser and the provider both see it. Behind [Deployment Protection](https://vercel.com/docs/deployment-protection), the person signing in must pass Vercel Authentication or a [Deployment Protection Exception](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/deployment-protection-exceptions).
342
317
 
343
318
  ### Signaling authorization state
344
319
 
345
- Two error classes drive the consent flow. Throw them from `getToken` or `completeAuthorization`; both are exported from `eve/connections`.
320
+ Throw these error classes from `eve/connections` in `getToken` or `completeAuthorization`:
346
321
 
347
- - `ConnectionAuthorizationRequiredError(connectionName)`: the user must authorize. Throw it from `getToken` to open a sign-in (`interaction.opened` with `request.kind: "sign-in"`) and kick off the flow.
348
- - `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up as the sign-in's `interaction.settled` reason and on the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial. The sign-in's `interaction.settled` then carries `response.retryable: false`, and a later tool call in the same turn that needs the same grant for the same principal fails with that failure instead of asking the user to sign in again. The next turn asks again.
322
+ - `ConnectionAuthorizationRequiredError(connectionName)`: the user must sign in. Throw it from `getToken` to send an `interaction.opened` event with `request.kind: "sign-in"`.
323
+ - `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: sign-in failed. `reason` is a stable code, such as `"access_denied"`. It appears as the reason on the sign-in's `interaction.settled` event and on the failed tool result.
324
+
325
+ Omit `retryable` to allow retries. Set it to `false` when retrying can't help, such as when the user denies access. `interaction.settled` then carries `response.retryable: false`. Later calls in the same turn that need the same grant for the same user fail without asking again. The next turn asks again.
349
326
 
350
327
  ```ts
351
328
  import { ConnectionAuthorizationFailedError } from "eve/connections";
@@ -356,11 +333,11 @@ throw new ConnectionAuthorizationFailedError("linear", {
356
333
  });
357
334
  ```
358
335
 
359
- To narrow a caught error, use `isConnectionAuthorizationRequiredError(err)` and `isConnectionAuthorizationFailedError(err)`. They match on `err.name`, which is why they survive the class-identity split `instanceof` can hit after bundling.
336
+ To narrow a caught error, use `isConnectionAuthorizationRequiredError(err)` and `isConnectionAuthorizationFailedError(err)`. They match on `err.name`, so they work after bundling, where `instanceof` can fail.
360
337
 
361
338
  ### Handling a revoked token mid-call
362
339
 
363
- `getToken` only runs _before_ a tool call, so a grant revoked while a tool is mid-flight first surfaces as a downstream `401` inside your `execute`. A plain throw there is only a tool error, so the model sees a failure and the cached bearer sticks around. Instead, map a provider `401` to `ctx.requireAuth(provider)`. eve then evicts the rejected token from its per-step cache and re-runs the consent flow with a fresh one, exactly as it does for a connection whose server rejects the bearer.
340
+ `getToken` runs only before a tool call, so a grant revoked during the call shows up as a `401` inside your `execute`. A plain throw keeps the cached token. Call `ctx.requireAuth(provider)` instead, so eve drops the token and asks the user to sign in again.
364
341
 
365
342
  ```ts title="agent/tools/list_issues.ts"
366
343
  import { connect } from "@vercel/connect/eve";
@@ -377,8 +354,8 @@ export default defineTool({
377
354
  const res = await fetch("https://api.linear.app/graphql", {
378
355
  headers: { authorization: `Bearer ${token}` },
379
356
  });
380
- // The grant was revoked since getToken ran: re-challenge instead of
381
- // returning a dead-token error to the model.
357
+ // The grant was revoked after getToken ran: ask the user to sign in
358
+ // again instead of returning a dead-token error to the model.
382
359
  if (res.status === 401) ctx.requireAuth(linearAuth);
383
360
  return await res.json();
384
361
  },
@@ -387,12 +364,70 @@ export default defineTool({
387
364
 
388
365
  ### Authorization and approval together
389
366
 
390
- A tool can require both sign-in (`auth`) and a human approval. The model's approval gate runs before the tool's `execute`, so the order the user sees is **approve, then sign in**. eve records the approval on session state the moment it's granted, and that record survives the sign-in park, so when the turn resumes after authorization the tool is not put through approval again. You get one approval and one sign-in, never a double prompt.
367
+ A tool can require both sign-in (`auth`) and human approval. Approval runs before `execute`, so the user sees **approve, then sign in**. eve keeps a granted approval, so the turn doesn't ask for approval again after sign-in.
368
+
369
+ ## Dynamic connections
370
+
371
+ Use `defineDynamic` from `eve/connections` when the set of connections depends on the signed-in user, the tenant, or another runtime lookup. The function returns one connection definition, a map of them, or `null`. Wrap lookups in `ctx.memo` so their JSON results stay fixed for a key.
372
+
373
+ ```ts title="agent/connections/accounts.ts"
374
+ import { defineDynamic, defineMcpClientConnection } from "eve/connections";
375
+ import { accountAuth, listAccounts } from "../lib/accounts";
376
+
377
+ export default defineDynamic(async (ctx) => {
378
+ const userId = ctx.session.auth.current?.principalId;
379
+ if (!userId) return null; // no connections for callers who aren't signed in
380
+ const accounts = await ctx.memo(userId, async () =>
381
+ (await listAccounts(userId)).map(({ description, id, mcpUrl, slug }) => ({
382
+ description,
383
+ id,
384
+ mcpUrl,
385
+ slug,
386
+ })),
387
+ );
388
+ return Object.fromEntries(
389
+ accounts.map((account) => [
390
+ account.slug,
391
+ defineMcpClientConnection({
392
+ url: account.mcpUrl,
393
+ description: account.description,
394
+ instanceKey: account.id, // required when the connection has auth
395
+ auth: accountAuth(account.id),
396
+ }),
397
+ ]),
398
+ );
399
+ });
400
+ ```
401
+
402
+ - A single returned definition takes the filename as its name. In a map, each key is a connection name.
403
+ - Every entry must use `defineMcpClientConnection` or `defineOpenAPIConnection`.
404
+ - An entry with `auth` must set `instanceKey` to a stable, non-secret account or tenant ID. Use a different `instanceKey` for each account or tenant, even when they share an endpoint.
405
+ - Build connections and auth callbacks outside `ctx.memo`, because memos keep only JSON.
406
+
407
+ See [Dynamic capabilities](/docs/guides/dynamic-capabilities#dynamic-connections) for when eve runs the function, naming, conflicts, and what happens when it fails.
408
+
409
+ Tools from a dynamic connection can require approval, including an `approval.response` policy. When the user answers, even in a new process, eve rebuilds the connection from the saved `ctx.memo` results. If its endpoint or `instanceKey` changed after the approval request, the call fails instead of reaching a different server. Fix the connection, then make a new call.
410
+
411
+ ## Troubleshooting
412
+
413
+ | What you see | What to do |
414
+ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
415
+ | The build fails with a connection name conflict | Rename one side; the error names both. Dynamic tools, subagents, and connections follow the same rule, but a dynamic connection with exactly a static connection's name replaces it. See [Naming and conflicts](/docs/guides/dynamic-capabilities#conflicts). |
416
+
417
+ ### Troubleshooting Vercel Connect auth
418
+
419
+ | What you see | What to do |
420
+ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
421
+ | `reason: "principal_required"` | A per-user connection ran with no signed-in user, such as in a schedule, a same-project runtime token, or `localDev()` run. Return `principalType: "user"` from the channel's route auth, or use app auth. |
422
+ | A sign-in `interaction.opened` event, but no UI | Render the sign-in from the stream event, and continue the same session after the callback. |
423
+ | OAuth works locally but fails after deploy | Run Connect setup from the project that uses it, deploy again, and check the connector UID, because the project may lack the link or OIDC scope. |
424
+ | Sign-in ends on a Vercel login or protection page | Have the user sign in to Vercel with project access, or add a Deployment Protection Exception for the domain. |
391
425
 
392
426
  ## What to read next
393
427
 
428
+ - [Channels](/docs/channels/overview): use a channel instead when users should reach your agent through an external service.
429
+ - [Tools](/docs/tools): author your own tools next to connection tools. The same approval helpers apply.
394
430
  - [MCP connections](/docs/connections/mcp): connect to remote MCP servers.
395
431
  - [OpenAPI connections](/docs/connections/openapi): generate tools from OpenAPI operations.
396
432
  - [Integrations](/integrations): browse every connection eve ships using the Connections filter.
397
- - [Tools](/docs/tools): authored tools live alongside connection-provided tools; the same approval helpers apply.
398
433
  - [Security model](/docs/concepts/security-model): how connection credentials stay out of the model's reach.