eve 0.90.0 → 0.91.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +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/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/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/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/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/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/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.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/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- 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 -198
- 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 +175 -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 +16 -19
- 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 +87 -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 +45 -43
- 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/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
|
@@ -3,22 +3,17 @@ title: "Multi-Tenant Approvals"
|
|
|
3
3
|
description: "Resolve tenant policy asynchronously for authored tools, OpenAPI operations, and MCP tools."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
eve's `approval` field
|
|
6
|
+
Multi-tenant approvals let your application decide, per tenant, whether a tool call is allowed, denied, or needs human confirmation. eve's `approval` field takes an async function that receives the session, the full tool name, and the tool input. One adapter turns those into a request to your policy store. Tools, OpenAPI connections, and MCP connections all use the same adapter.
|
|
7
7
|
|
|
8
8
|
Use this with [multi-tenant outbound auth](./multi-tenant-auth) when your own
|
|
9
|
-
API key, JWT, or app session establishes the tenant
|
|
10
|
-
credential
|
|
9
|
+
API key, JWT, or app session establishes the tenant. In that pattern, your
|
|
10
|
+
credential store supplies the connection credential instead of OAuth.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
1. one adapter translates eve's approval context into an application policy request;
|
|
15
|
-
2. tools, OpenAPI connections, and MCP connections reuse that adapter.
|
|
16
|
-
|
|
17
|
-
Tenant policy storage remains yours. It might be a few columns in PostgreSQL, a policy service, an authorization engine, or configuration in a durable KV store.
|
|
12
|
+
You store tenant policy. It can be a few columns in PostgreSQL, a policy service, an authorization engine, or configuration in a KV store.
|
|
18
13
|
|
|
19
14
|
## Adapt tenant policy to eve approval
|
|
20
15
|
|
|
21
|
-
|
|
16
|
+
This adapter checks that the current caller and the caller who started the session belong to the same tenant. Then it asks your policy store:
|
|
22
17
|
|
|
23
18
|
```ts title="agent/lib/tenant-approval.ts"
|
|
24
19
|
import type { ApprovalContext, ApprovalStatus } from "eve/tools/approval";
|
|
@@ -66,13 +61,13 @@ export async function decideTenantApproval(
|
|
|
66
61
|
}
|
|
67
62
|
```
|
|
68
63
|
|
|
69
|
-
For authored tools, `ctx.toolName` is the path-derived name such as `transfer_funds`. For connection tools, it
|
|
64
|
+
For authored tools, `ctx.toolName` is the path-derived name such as `transfer_funds`. For connection tools, it includes the connection name, such as `billing__updateSubscription` or `support__add_internal_note`. Your policy service can match exact names, patterns for a whole connection, roles, amounts, environments, or any other rule the tenant sets.
|
|
70
65
|
|
|
71
|
-
The
|
|
66
|
+
The function runs for every call, so `"user-approval"` asks for a separate decision on each action. [`once()`](/docs/human-in-the-loop#remember-approval-for-a-tool) remembers approval for the tool across all inputs in the session. It does not create grants for a tenant.
|
|
72
67
|
|
|
73
68
|
## Apply it to an authored tool
|
|
74
69
|
|
|
75
|
-
Approval runs before `execute`.
|
|
70
|
+
Approval runs before `execute`. `execute` must still read and enforce the tenant, because approval is a gate, not authorization:
|
|
76
71
|
|
|
77
72
|
```ts title="agent/tools/transfer_funds.ts"
|
|
78
73
|
import { defineTool } from "eve/tools";
|
|
@@ -103,11 +98,11 @@ export default defineTool({
|
|
|
103
98
|
});
|
|
104
99
|
```
|
|
105
100
|
|
|
106
|
-
Use an
|
|
101
|
+
Use an idempotency key from your application for side effects, because approval doesn't make a repeated step safe.
|
|
107
102
|
|
|
108
103
|
## Apply it to an OpenAPI connection
|
|
109
104
|
|
|
110
|
-
The same
|
|
105
|
+
The same function gates every generated operation. The full operation name lets tenant policy tell reads from writes:
|
|
111
106
|
|
|
112
107
|
```ts title="agent/connections/billing.ts"
|
|
113
108
|
import { defineOpenAPIConnection } from "eve/connections";
|
|
@@ -129,7 +124,7 @@ export default defineOpenAPIConnection({
|
|
|
129
124
|
});
|
|
130
125
|
```
|
|
131
126
|
|
|
132
|
-
The allow-list limits
|
|
127
|
+
The allow-list limits which operations the model can find. Approval decides whether a found operation may run.
|
|
133
128
|
|
|
134
129
|
## Apply it to an MCP connection
|
|
135
130
|
|
|
@@ -157,7 +152,7 @@ The policy receives `connection:support__search_tickets` or `connection:support_
|
|
|
157
152
|
|
|
158
153
|
## Supply the policy adapter
|
|
159
154
|
|
|
160
|
-
The
|
|
155
|
+
The adapter needs only this interface:
|
|
161
156
|
|
|
162
157
|
```ts title="agent/lib/approval-policies.ts"
|
|
163
158
|
export interface ApprovalPolicyRequest {
|
|
@@ -179,17 +174,17 @@ export interface ApprovalPolicyProvider {
|
|
|
179
174
|
export { approvalPolicies } from "../../lib/approval-policies";
|
|
180
175
|
```
|
|
181
176
|
|
|
182
|
-
Your provider decides the policy model. A common implementation checks
|
|
177
|
+
Your provider decides the policy model. A common implementation checks tenant membership and looks for an exact resource rule, then a rule for the whole connection. It checks role and input thresholds, and it denies by default.
|
|
183
178
|
|
|
184
|
-
|
|
179
|
+
When a policy lookup fails, throw or deny. Never allow silently. Check authorization again inside `execute` for tools with side effects, because membership or policy can change while the session waits for approval.
|
|
185
180
|
|
|
186
181
|
## Protect the approval response
|
|
187
182
|
|
|
188
|
-
An approval
|
|
183
|
+
An approval pauses the session, and the pause survives restarts and redeploys. A later request resumes the session. Your HTTP boundary must stop a caller from continuing or streaming another tenant's session. Save which tenant and user each session belongs to, and check it before you forward these requests:
|
|
189
184
|
|
|
190
185
|
- `POST /eve/v1/session/:sessionId`, including `answers`;
|
|
191
186
|
- `GET /eve/v1/session/:sessionId/stream`.
|
|
192
187
|
|
|
193
|
-
|
|
188
|
+
By default, only the caller whose turn requested the call can approve or cancel it. To change who may respond, add an [approval response policy](/docs/human-in-the-loop#authorizing-approval-responses). The policy receives the responder as `response.principal` and the requester as `request.principal`. It runs for both Approve and Cancel.
|
|
194
189
|
|
|
195
|
-
|
|
190
|
+
For a four-eyes workflow, where a different person or role must approve, branch on `response.decision`. Allow `deny` so the requester can still cancel the call. For `approve`, reject a `response.principal` that matches `request.principal`, and check the responder's role.
|
|
@@ -3,17 +3,17 @@ title: "Multi-Tenant Outbound Auth"
|
|
|
3
3
|
description: "Select tenant-scoped credentials inside authored tools, OpenAPI connections, and MCP connections from the active turn context."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Multi-tenant outbound auth picks the current tenant's credentials from the signed-in caller that eve passes into every turn:
|
|
7
7
|
|
|
8
|
-
- tool
|
|
9
|
-
- OpenAPI and MCP `auth`
|
|
10
|
-
-
|
|
8
|
+
- A tool's `execute` receives `ctx` directly.
|
|
9
|
+
- OpenAPI and MCP `auth` can be an async function of `ctx`.
|
|
10
|
+
- Connection `headers` can be an async function that returns a map, or a map of async values.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Your application stores tenant membership and credentials. The model never sees or chooses those credentials.
|
|
13
13
|
|
|
14
14
|
## Establish the tenant scope
|
|
15
15
|
|
|
16
|
-
Configure route auth so the accepted
|
|
16
|
+
Configure route auth so the accepted caller has a string `tenantId` attribute. Then put the check in one helper:
|
|
17
17
|
|
|
18
18
|
```ts title="agent/lib/tenant.ts"
|
|
19
19
|
import type { SessionContext } from "eve/context";
|
|
@@ -39,7 +39,7 @@ The tenant comes from verified route auth, never a prompt, tool argument, or rem
|
|
|
39
39
|
|
|
40
40
|
For production apps with many customer orgs, the inbound credential is often
|
|
41
41
|
your own API key, session cookie, or JWT. Use that credential to authenticate
|
|
42
|
-
the caller before eve starts a run, then
|
|
42
|
+
the caller before eve starts a run, then add the tenant to the session:
|
|
43
43
|
|
|
44
44
|
```ts title="agent/channels/eve.ts"
|
|
45
45
|
import { eveChannel } from "eve/channels/eve";
|
|
@@ -70,25 +70,28 @@ export default eveChannel({
|
|
|
70
70
|
});
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
`verifyAgentCaller` is application code
|
|
74
|
-
JWT, or
|
|
75
|
-
to the tenant they
|
|
76
|
-
|
|
77
|
-
|
|
73
|
+
`verifyAgentCaller` is application code that validates an API key, verifies a
|
|
74
|
+
JWT, or reads an app session. It must return only after confirming that the user
|
|
75
|
+
belongs to the tenant they claim.
|
|
76
|
+
|
|
77
|
+
- Keep `principalId` stable for the same user.
|
|
78
|
+
- Include an `issuer` when ids can come from more than one identity system.
|
|
79
|
+
- Put routing values such as `tenantId` in `attributes`.
|
|
78
80
|
|
|
79
81
|
If one user can switch between orgs, authenticate the selected org on every
|
|
80
|
-
|
|
81
|
-
current turn.
|
|
82
|
+
request that creates or continues a session. Set the selected `tenantId` on
|
|
83
|
+
the current turn.
|
|
82
84
|
|
|
83
|
-
This is not connection OAuth. The user is already
|
|
84
|
-
eve uses that
|
|
85
|
+
This is not connection OAuth. The user is already signed in to your app, and
|
|
86
|
+
eve uses that user to pick the outbound credential.
|
|
85
87
|
|
|
86
88
|
## Build tenant connection auth
|
|
87
89
|
|
|
88
|
-
For Bearer tokens or tenant
|
|
89
|
-
|
|
90
|
-
eve
|
|
91
|
-
|
|
90
|
+
For Bearer tokens or JWTs for one tenant, write one auth helper that never
|
|
91
|
+
prompts the user to sign in. Use it for OpenAPI and MCP connections. With
|
|
92
|
+
`principalType: "user"`, eve requires a signed-in user from route auth and
|
|
93
|
+
passes that user to `getToken` as `principal`. eve never reuses a token
|
|
94
|
+
fetched for one user for another user:
|
|
92
95
|
|
|
93
96
|
```ts title="agent/lib/tenant-connection-auth.ts"
|
|
94
97
|
import type { AuthorizationDefinition, ConnectionPrincipal } from "eve/connections";
|
|
@@ -124,14 +127,14 @@ export function tenantBearerAuth(service: TenantService): AuthorizationDefinitio
|
|
|
124
127
|
```
|
|
125
128
|
|
|
126
129
|
The model never supplies `tenantId` or sees the returned token. If the remote
|
|
127
|
-
service uses
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
130
|
+
service uses one credential for all users in a tenant, look it up by
|
|
131
|
+
`tenantId` in your provider. Connection auth with `principalType: "user"` still
|
|
132
|
+
rejects sessions without a signed-in user, and it never gives one caller's
|
|
133
|
+
token to another caller.
|
|
131
134
|
|
|
132
135
|
## Authenticate an authored tool call
|
|
133
136
|
|
|
134
|
-
|
|
137
|
+
Read the tenant inside `execute`, get its credential from your provider, and build the outbound request:
|
|
135
138
|
|
|
136
139
|
```ts title="agent/tools/list_invoices.ts"
|
|
137
140
|
import { defineTool } from "eve/tools";
|
|
@@ -158,12 +161,12 @@ export default defineTool({
|
|
|
158
161
|
});
|
|
159
162
|
```
|
|
160
163
|
|
|
161
|
-
The model controls only `limit`. Even if a prompt asks for another tenant,
|
|
164
|
+
The model controls only `limit`. Even if a prompt asks for another tenant, `execute` picks the credential from `ctx.session.auth.current`.
|
|
162
165
|
|
|
163
166
|
## Authenticate an OpenAPI connection
|
|
164
167
|
|
|
165
|
-
Attach the
|
|
166
|
-
|
|
168
|
+
Attach the auth helper to the connection. Generated operation tools receive
|
|
169
|
+
the token at call time without exposing it to the model:
|
|
167
170
|
|
|
168
171
|
```ts title="agent/connections/billing.ts"
|
|
169
172
|
import { defineOpenAPIConnection } from "eve/connections";
|
|
@@ -185,7 +188,7 @@ export default defineOpenAPIConnection({
|
|
|
185
188
|
});
|
|
186
189
|
```
|
|
187
190
|
|
|
188
|
-
Do not return `Authorization` from `headers` when `auth` is present. eve
|
|
191
|
+
Do not return `Authorization` from `headers` when `auth` is present. eve builds that header from `getToken` and rejects definitions that set both.
|
|
189
192
|
|
|
190
193
|
## Authenticate an MCP connection
|
|
191
194
|
|
|
@@ -240,12 +243,12 @@ export default defineMcpClientConnection({
|
|
|
240
243
|
});
|
|
241
244
|
```
|
|
242
245
|
|
|
243
|
-
Use the same shape for OpenAPI connections. API keys
|
|
244
|
-
|
|
246
|
+
Use the same shape for OpenAPI connections. eve sends API keys from `headers`
|
|
247
|
+
only on outbound requests. They are not model inputs or tool results.
|
|
245
248
|
|
|
246
249
|
## Supply the credential provider
|
|
247
250
|
|
|
248
|
-
The
|
|
251
|
+
The tools and connections need only this interface:
|
|
249
252
|
|
|
250
253
|
```ts title="agent/lib/tenant-credentials.ts"
|
|
251
254
|
export type TenantService = "billing" | "support";
|
|
@@ -277,20 +280,18 @@ export interface TenantCredentialProvider {
|
|
|
277
280
|
export { tenantCredentials } from "../../lib/tenant-credentials";
|
|
278
281
|
```
|
|
279
282
|
|
|
280
|
-
Implement the provider with the secret system your application already trusts
|
|
281
|
-
a cloud secret manager, an encrypted database table, a token broker,
|
|
282
|
-
out-of-band OAuth flow you own.
|
|
283
|
+
Implement the provider with the secret system your application already trusts.
|
|
284
|
+
Examples are a cloud secret manager, an encrypted database table, a token broker,
|
|
285
|
+
or an out-of-band OAuth flow you own.
|
|
283
286
|
|
|
284
|
-
The provider must fail closed for unknown tenants,
|
|
287
|
+
The provider must fail closed for unknown tenants, keep secrets out of logs and errors, and rotate or refresh credentials before `expiresAt`. Prefer credentials that are themselves restricted to one remote tenant. Treat workspace headers as routing, not authorization.
|
|
285
288
|
|
|
286
289
|
## What the model can and cannot see
|
|
287
290
|
|
|
288
|
-
1. Route auth
|
|
289
|
-
2. Tool code reads `ctx.session.auth.current`, and connection auth receives the
|
|
290
|
-
3.
|
|
291
|
+
1. Route auth adds the verified tenant to the session.
|
|
292
|
+
2. Tool code reads `ctx.session.auth.current`, and connection auth receives the user as `principal`.
|
|
293
|
+
3. Your provider gets the matching credential.
|
|
291
294
|
4. eve sends the resulting token and headers directly to the remote service.
|
|
292
295
|
5. Neither becomes a model message or tool result.
|
|
293
296
|
|
|
294
|
-
Also
|
|
295
|
-
|
|
296
|
-
No framework-native tenant object is involved. The implementation is the composition of route auth, `ctx.session`, tool execution, and async connection auth/header resolvers.
|
|
297
|
+
Also check which tenant a session belongs to on the session create, continue, and stream routes. Route authentication identifies the caller. Your application's access list decides which session IDs that caller may access.
|
|
@@ -3,17 +3,18 @@ title: "Multi-Tenant Memory"
|
|
|
3
3
|
description: "Bind an eve memory provider to an authenticated tenant and caller scope."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
A memory slot's `scope` decides who shares its memory. For multi-tenant memory,
|
|
7
|
+
return a scope built from the signed-in tenant and user. eve passes the
|
|
8
|
+
resulting key to every [memory provider](../memory) call, so each tenant and
|
|
9
|
+
user gets separate memory.
|
|
9
10
|
|
|
10
|
-
The example below uses the built-in `fileMemory()` provider.
|
|
11
|
-
Supermemory or a custom provider without changing
|
|
12
|
-
isolation
|
|
11
|
+
The example below uses the built-in `fileMemory()` provider. You can swap in
|
|
12
|
+
Supermemory or a custom provider without changing `scope`, because tenant
|
|
13
|
+
isolation lives in the memory definition, not the store.
|
|
13
14
|
|
|
14
15
|
## Derive scope from authenticated context
|
|
15
16
|
|
|
16
|
-
Never accept the tenant or user ID from the model.
|
|
17
|
+
Never accept the tenant or user ID from the model. Read both from verified
|
|
17
18
|
session authentication and return a tuple:
|
|
18
19
|
|
|
19
20
|
```ts title="agent/memory/profile.ts"
|
|
@@ -30,57 +31,59 @@ export default defineMemory({
|
|
|
30
31
|
const tenantId = caller?.attributes.tenantId;
|
|
31
32
|
const principal = byPrincipal(ctx);
|
|
32
33
|
|
|
34
|
+
// no memory for non-users, callers without a tenant, or anonymous callers
|
|
33
35
|
if (caller?.principalType !== "user" || typeof tenantId !== "string" || principal === null) {
|
|
34
36
|
return null;
|
|
35
37
|
}
|
|
36
38
|
|
|
39
|
+
// one memory per user within each tenant
|
|
37
40
|
return [tenantId, principal];
|
|
38
41
|
},
|
|
39
42
|
});
|
|
40
43
|
```
|
|
41
44
|
|
|
42
|
-
Returning `null`
|
|
43
|
-
|
|
44
|
-
`byPrincipal(ctx)` includes the authenticated principal type, authenticator,
|
|
45
|
-
issuer, and principal ID, so the tuple separates callers even if the same
|
|
46
|
-
principal ID exists in two authentication systems.
|
|
45
|
+
Returning `null` turns memory off for anonymous or incorrectly scoped callers.
|
|
46
|
+
eve does not call the provider and never substitutes a shared scope.
|
|
47
47
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
`byPrincipal(ctx)` combines the caller's `principalType`, `authenticator`,
|
|
49
|
+
`issuer`, and `principalId`. This keeps two callers apart even when the same
|
|
50
|
+
user ID exists in two sign-in systems.
|
|
51
|
+
|
|
52
|
+
Use `auth.current` for the caller of the active turn. If only the person who
|
|
53
|
+
started a conversation may use it, use `auth.initiator` and enforce that rule
|
|
54
|
+
at the channel boundary.
|
|
51
55
|
|
|
52
56
|
## Understand the locked provider boundary
|
|
53
57
|
|
|
54
|
-
eve
|
|
55
|
-
|
|
56
|
-
custom provider receives the same key in every recall, capture, and tools call.
|
|
58
|
+
eve derives an opaque `memory.scope.key` from the namespace and scope tuple.
|
|
59
|
+
The provider receives that key in every recall, capture, and tools call.
|
|
57
60
|
|
|
58
|
-
The model never supplies or changes the key. Provider tools
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
61
|
+
The model never supplies or changes the key. Provider tools are locked to the
|
|
62
|
+
key, so a tool cannot redirect itself to another tenant or caller. A provider
|
|
63
|
+
must keep that boundary by using `memory.scope.key` in every read and write to
|
|
64
|
+
its store.
|
|
62
65
|
|
|
63
|
-
For semantic retrieval,
|
|
64
|
-
|
|
65
|
-
|
|
66
|
+
For semantic retrieval, filter by the key in the database or service query
|
|
67
|
+
itself, not after a global search. For custom capture, use the provider's
|
|
68
|
+
stable `operationId` as an idempotency key. See
|
|
66
69
|
[Build a memory provider](../memory/custom-provider) for the full contract.
|
|
67
70
|
|
|
68
71
|
## When the caller changes
|
|
69
72
|
|
|
70
|
-
eve recalls again when the
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
what an earlier assistant response already said
|
|
74
|
-
see each other's memory separate sessions.
|
|
73
|
+
eve recalls again when the signed-in caller changes within one session. With
|
|
74
|
+
the scope above, a new caller gets a new scope, and the slot starts empty.
|
|
75
|
+
Memory recalled for the earlier caller leaves the model's context. eve can't
|
|
76
|
+
remove what an earlier assistant response already said. Give participants who
|
|
77
|
+
must not see each other's memory separate sessions.
|
|
75
78
|
|
|
76
79
|
## Set the trust policy
|
|
77
80
|
|
|
78
|
-
Recalled values become user-role messages. Tell the agent
|
|
79
|
-
untrusted
|
|
81
|
+
Recalled values become user-role messages. Tell the agent to treat memories as
|
|
82
|
+
untrusted information, not instructions, and tell it what it may save. See
|
|
80
83
|
[Tell the model how to use memory](../memory#tell-the-model-how-to-use-memory)
|
|
81
84
|
for an instructions snippet. A custom provider can also set `approval` on its
|
|
82
|
-
tools when product
|
|
83
|
-
deleting memory.
|
|
85
|
+
tools when your product requires confirmation before saving or deleting memory.
|
|
84
86
|
|
|
85
|
-
Do not use `defineState` for
|
|
86
|
-
session
|
|
87
|
+
Do not use `defineState` for data that must outlive a session. State belongs
|
|
88
|
+
to one session. Memory providers share data across sessions through their own
|
|
89
|
+
storage.
|
|
@@ -3,9 +3,9 @@ title: "Voice Notes"
|
|
|
3
3
|
description: "Transcribe voice notes, voice messages, and other audio attachments with an AI Gateway transcription model so an eve agent can answer them."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Voice notes and other audio files reach your agent, but
|
|
6
|
+
Voice notes and other audio files reach your agent as files in its sandbox, but the model does not transcribe them. To let your agent answer a voice note, add a tool that transcribes the file.
|
|
7
7
|
|
|
8
|
-
This works for any channel that delivers audio as a file
|
|
8
|
+
This works for any channel that delivers audio as a file. Examples are iMessage voice notes through [Photon](../channels/photon), [Slack](../channels/slack#attachments) voice clips, and files sent through the [eve](../channels/eve) and [Chat SDK](../channels/chat-sdk#attachments) channels. See [Inbound attachments](../sandbox#inbound-attachments) for where eve saves these files.
|
|
9
9
|
|
|
10
10
|
## Add a transcription tool
|
|
11
11
|
|
|
@@ -64,4 +64,4 @@ When a message has an audio attachment (`Attached file ... (audio/...)`), such a
|
|
|
64
64
|
|
|
65
65
|
## When transcription fails
|
|
66
66
|
|
|
67
|
-
When `execute` throws,
|
|
67
|
+
When `execute` throws, the model receives the error as a tool error and can relay it to the user. See [When a tool throws](../tools#when-a-tool-throws). A file eve can't download reaches the agent as a short note instead of a file. So does a file over the channel's upload limit, which is 25 MB by default.
|
package/docs/protocols/acp.md
CHANGED
|
@@ -3,19 +3,19 @@ title: "Editor Integration (ACP)"
|
|
|
3
3
|
description: "Use local or deployed eve agents from Agent Client Protocol clients."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Agent Client Protocol (ACP) clients
|
|
6
|
+
`eve acp` lets Agent Client Protocol (ACP) clients, such as editors, run an eve application as a local subprocess. eve serves stable ACP v1 over stdio, and its development server runs the agent.
|
|
7
7
|
|
|
8
8
|
```sh
|
|
9
9
|
eve acp
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Without a URL, the client starts one process from the eve application root.
|
|
12
|
+
Without a URL, the client starts one `eve acp` process from the eve application root. That process runs a local development server until the ACP connection closes. To connect ACP to a deployed eve agent, pass its URL:
|
|
13
13
|
|
|
14
14
|
```sh
|
|
15
15
|
eve acp --url https://agent.example.com
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
For a recognized Vercel deployment, eve verifies the exact origin and
|
|
18
|
+
For a recognized Vercel deployment, eve verifies the exact origin and gets a short-lived OIDC token for that project from the local Vercel session. Remote access requires an existing authorized Vercel session; account login runs during local deployment. Configure any required Trusted Sources access in the target project before launching ACP. For a deployment with a Protection Bypass for Automation token, set `VERCEL_AUTOMATION_BYPASS_SECRET`.
|
|
19
19
|
|
|
20
20
|
## Configure Zed
|
|
21
21
|
|
|
@@ -36,7 +36,7 @@ Open the eve application root as the Zed workspace. In **Agent Settings → Exte
|
|
|
36
36
|
|
|
37
37
|
Use an absolute command path if Zed cannot find `pnpm` in its environment. The workspace must be the same directory as the eve application root; eve rejects a different `session/new.cwd` instead of running the wrong application.
|
|
38
38
|
|
|
39
|
-
Disable Zed project MCP servers for this agent
|
|
39
|
+
Disable Zed project MCP servers for this agent, because eve doesn't accept client-provided MCP servers.
|
|
40
40
|
|
|
41
41
|
## Supported behavior
|
|
42
42
|
|
|
@@ -50,30 +50,30 @@ ACP clients receive:
|
|
|
50
50
|
- independent concurrent ACP sessions;
|
|
51
51
|
- session closure and process cleanup.
|
|
52
52
|
|
|
53
|
-
|
|
53
|
+
When the development server rebuilds, work already running finishes on its original build. The next turn uses the newest successful build.
|
|
54
54
|
|
|
55
55
|
## Security and capability limits
|
|
56
56
|
|
|
57
|
-
ACP mode
|
|
57
|
+
ACP mode gives the agent no access to the editor's host filesystem or terminal. `session/new.cwd` identifies the eve application being launched and isn't mounted into the agent sandbox.
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
eve's ACP adapter doesn't support:
|
|
60
60
|
|
|
61
61
|
- a deployed ACP HTTP or WebSocket endpoint;
|
|
62
|
-
- ACP authentication (remote
|
|
62
|
+
- ACP authentication (a remote connection uses the deployed eve agent's existing HTTP authentication);
|
|
63
63
|
- ACP v2;
|
|
64
64
|
- client filesystem or terminal methods;
|
|
65
65
|
- client-provided MCP servers;
|
|
66
66
|
- images, audio, files, or embedded resources in prompts;
|
|
67
|
-
- session loading, listing, resumption, or
|
|
67
|
+
- session loading, listing, or resumption, or ACP IDs that survive process restarts;
|
|
68
68
|
- ACP model or mode configuration.
|
|
69
69
|
|
|
70
|
-
The agent continues to use the connections, tools, credentials, and sandbox policy authored in the eve application. Prompt text and ACP metadata never
|
|
70
|
+
The agent continues to use the connections, tools, credentials, and sandbox policy authored in the eve application. Prompt text and ACP metadata never authenticate an end user.
|
|
71
71
|
|
|
72
72
|
## Diagnose a connection
|
|
73
73
|
|
|
74
|
-
ACP reserves stdout for newline-delimited JSON-RPC
|
|
74
|
+
ACP reserves stdout for newline-delimited JSON-RPC, so eve sends compilation output, server logs, and diagnostics to stderr.
|
|
75
75
|
|
|
76
|
-
For a
|
|
76
|
+
For a headless smoke test, run an ACP client such as `acpx` from the application root. `acpx` launches the ACP process itself, so don't start `eve acp` separately.
|
|
77
77
|
|
|
78
78
|
```sh
|
|
79
79
|
npx acpx@latest \
|
|
@@ -81,7 +81,7 @@ npx acpx@latest \
|
|
|
81
81
|
exec 'Reply with exactly: ACP works'
|
|
82
82
|
```
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
In the eve source checkout, test from an authored fixture, because the monorepo root has no `eve` executable:
|
|
85
85
|
|
|
86
86
|
```sh
|
|
87
87
|
cd apps/fixtures/weather-agent
|
package/docs/protocols/ucp.mdx
CHANGED
|
@@ -3,9 +3,9 @@ title: "Serve a UCP Profile"
|
|
|
3
3
|
description: "Serve a UCP profile at /.well-known/ucp from a custom eve channel."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The [Universal Commerce Protocol](https://ucp.dev/) (UCP) is an open standard for agentic commerce. A business declares
|
|
6
|
+
The [Universal Commerce Protocol](https://ucp.dev/) (UCP) is an open standard for agentic commerce. A business declares UCP support by serving a JSON **profile** at `/.well-known/ucp`. The profile lists supported spec versions, services, capabilities, payment handlers, and the public keys agents use to verify signed responses.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
To support UCP with eve:
|
|
9
9
|
|
|
10
10
|
1. [Author the profile](#author-the-profile)
|
|
11
11
|
2. [Serve it from a channel](#serve-it-from-a-channel)
|
|
@@ -13,7 +13,7 @@ With eve, you can support UCP in three steps:
|
|
|
13
13
|
|
|
14
14
|
## Author the profile
|
|
15
15
|
|
|
16
|
-
Your profile is a plain JSON object that follows the [UCP spec](https://ucp.dev/2026-08-25/specification/overview#profile-structure). The `ucp` object declares the `version`, `services`, `capabilities`, and `payment_handlers` of your business. The top-level `keys` array
|
|
16
|
+
Your profile is a plain JSON object that follows the [UCP spec](https://ucp.dev/2026-08-25/specification/overview#profile-structure). The `ucp` object declares the `version`, `services`, `capabilities`, and `payment_handlers` of your business. The top-level `keys` array is a standard JWK Set of the public keys agents use to verify your signed messages. The same document also works as a key source for [Web Bot Auth](https://ucp.dev/2026-08-25/specification/overview#deployment-patterns-for-wba-interop).
|
|
17
17
|
|
|
18
18
|
```ts
|
|
19
19
|
// agent/ucp-profile.ts
|
|
@@ -90,7 +90,7 @@ export const profile = {
|
|
|
90
90
|
|
|
91
91
|
## Serve it from a channel
|
|
92
92
|
|
|
93
|
-
|
|
93
|
+
Serve the profile at `/.well-known/ucp` from a custom channel:
|
|
94
94
|
|
|
95
95
|
```ts
|
|
96
96
|
// agent/channels/ucp.ts
|
|
@@ -120,7 +120,7 @@ export default defineChannel({
|
|
|
120
120
|
|
|
121
121
|
## Add your commerce endpoints
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
Each `services[].endpoint` URL must point at endpoints you serve, for example from a custom channel:
|
|
124
124
|
|
|
125
125
|
```ts
|
|
126
126
|
// agent/channels/ucp-shopping.ts
|
|
@@ -155,7 +155,7 @@ Routes are relative to the `endpoint` base in your profile, per the service's Op
|
|
|
155
155
|
|
|
156
156
|
## Verify
|
|
157
157
|
|
|
158
|
-
|
|
158
|
+
Run `eve dev` and fetch the profile locally:
|
|
159
159
|
|
|
160
160
|
```sh
|
|
161
161
|
curl -i http://localhost:2000/.well-known/ucp
|
|
@@ -177,7 +177,7 @@ cache-control: public, max-age=300
|
|
|
177
177
|
|
|
178
178
|
## What's not covered
|
|
179
179
|
|
|
180
|
-
|
|
180
|
+
You implement the commerce behavior yourself: the checkout, cart, and order state machines; payment-handler execution; and request signing and verification.
|
|
181
181
|
|
|
182
182
|
## Read next
|
|
183
183
|
|
|
@@ -3,7 +3,7 @@ title: "Agent Files"
|
|
|
3
3
|
description: "Look up agent directory slots, path-derived names, subagent files, and filesystem discovery rules."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
eve builds an agent from files
|
|
6
|
+
eve builds an agent from files in its agent directory, and each file's path determines how eve loads it. For recommended project layouts and when to split agents, read [Project Structure](/docs/concepts/project-structure).
|
|
7
7
|
|
|
8
8
|
## Agent directory layout
|
|
9
9
|
|
|
@@ -27,11 +27,11 @@ agent/
|
|
|
27
27
|
└── subagents/
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
Add only the files you need.
|
|
30
|
+
Add only the files you need. A file replaces the framework default at the same path. Evals live beside `agent/`, not inside it.
|
|
31
31
|
|
|
32
32
|
## Naming from paths
|
|
33
33
|
|
|
34
|
-
eve derives
|
|
34
|
+
eve derives names from file paths:
|
|
35
35
|
|
|
36
36
|
| Path | Resolves to |
|
|
37
37
|
| ------------------------------------- | --------------------- |
|
|
@@ -53,9 +53,9 @@ Paths below are relative to the agent directory. Root agents can use every path;
|
|
|
53
53
|
| `instrumentation/` | Telemetry providers and destinations | No | One path-named provider per file. See [Instrumentation](/docs/observability/instrumentation). |
|
|
54
54
|
| `channels/` | HTTP and messaging entry points | No | See [Channels](/docs/channels/overview). |
|
|
55
55
|
| `connections/` | External MCP and OpenAPI services | Yes | Static files define path-named connections; dynamic sources can resolve caller-specific connections. |
|
|
56
|
-
| `extensions/` | Mounted
|
|
57
|
-
| `hooks/` |
|
|
58
|
-
| `skills/` | On-demand procedures and
|
|
56
|
+
| `extensions/` | Mounted extension packages | Yes | File or directory mounts. See [Extensions](/docs/extensions). |
|
|
57
|
+
| `hooks/` | Handlers for session stream events | Yes | Module-backed only; recursive directories are supported. |
|
|
58
|
+
| `skills/` | On-demand procedures and supporting files | Yes | Flat Markdown, module-backed skills, or packaged skills. |
|
|
59
59
|
| `lib/` | Shared authored helper code | Yes | Import-only; not copied into the sandbox. Helpers can import data files such as JSON from here. |
|
|
60
60
|
| `memory.ts` or `memory/<name>.ts` | Cross-session memory | Yes | Provider-backed slots. See [Memory](/docs/memory). |
|
|
61
61
|
| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. When `sandbox/` exists, use `sandbox/sandbox.ts`; a root `sandbox.ts` beside that folder is an error. |
|