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.
- package/CHANGELOG.md +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/frame.js +1 -1
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -194
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +205 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +17 -18
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +100 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +47 -41
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/prepare-for-1-0.md +23 -1
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- 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
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
|
|
15
|
+
```ts title="agent/connections/linear.ts"
|
|
16
|
+
import { defineMcpClientConnection } from "eve/connections";
|
|
20
17
|
|
|
21
|
-
|
|
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
|
-
|
|
29
|
+
The filename is the connection name, so this file registers as `"linear"`.
|
|
24
30
|
|
|
25
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
38
|
+
## Options
|
|
30
39
|
|
|
31
|
-
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
57
|
+
Read [MCP connections](/docs/connections/mcp) for `defineMcpClientConnection`, transport requirements, and MCP tool filters.
|
|
85
58
|
|
|
86
|
-
|
|
59
|
+
## OpenAPI connections
|
|
87
60
|
|
|
88
|
-
|
|
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
|
-
|
|
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
|
-
|
|
65
|
+
## Choose app vs. user auth
|
|
102
66
|
|
|
103
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
//
|
|
294
|
-
// throw `
|
|
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
|
-
//
|
|
301
|
-
//
|
|
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
|
|
310
|
-
//
|
|
311
|
-
//
|
|
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
|
-
|
|
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` |
|
|
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
|
-
|
|
312
|
+
Omit `resume` when the provider keeps flow state on its server.
|
|
332
313
|
|
|
333
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
320
|
+
Throw these error classes from `eve/connections` in `getToken` or `completeAuthorization`:
|
|
346
321
|
|
|
347
|
-
- `ConnectionAuthorizationRequiredError(connectionName)`: the user must
|
|
348
|
-
- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`:
|
|
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`,
|
|
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
|
|
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
|
|
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
|
|
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.
|