eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,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 is an async policy hook. It receives the active session, qualified tool name, and tool input. That is enough to ask your application whether this tenant should allow, deny, or require human confirmation for any authored or connection tool.
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 and the connection
10
- credential is selected from your credential store rather than OAuth.
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
- The pattern has two pieces:
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
- The current caller and initiating caller are both available on the session. This example requires them to belong to the same tenant before consulting policy:
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 is qualified, such as `billing__updateSubscription` or `support__add_internal_note`. Your policy service can match exact names, connection-wide patterns, roles, amounts, environments, or any other tenant-owned rule.
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 callback evaluates every call. Return `"user-approval"` when each tenant-specific action needs a separate decision. [`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 tenant-specific grants.
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`. The executor must still derive and enforce tenancy again because approval is a gate, not authorization:
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 application idempotency key for side effects. Human approval and replay safety solve different problems.
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 callback gates every generated operation. The qualified operation name lets tenant policy distinguish reads from writes:
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 what the model can discover. Approval independently decides whether a discovered operation may run.
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 eve code needs only this interface:
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 active tenant membership, finds an exact resource rule before a connection-wide fallback, evaluates role and input thresholds, and defaults to deny. Keep those choices in application code rather than encoding a database design into the agent.
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
- Policy lookup failures should throw or deny, never silently allow. Recheck authorization inside side-effecting executors because membership or policy can change while a run is parked.
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 durably pauses the session and a later request resumes it. Your HTTP boundary must ensure a caller cannot continue or stream a session owned by another tenant. Persist session ownership in your application and check it before proxying:
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
- Built-in approval confirms that a human with access to the session approved the call. To restrict who may respond, add an [approval response policy](/docs/human-in-the-loop#authorizing-approval-responses): it receives who responded as `response.principal` and who asked for the call as `request.principal`, and runs for both Approve and Cancel. For a four-eyes workflow, where a different person or role must approve, branch on `response.decision`: allow `cancel` so the requester can still withdraw the call, and for `approve` reject a `response.principal` that matches `request.principal` and check the responder's role.
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
- The complete eve integration is one async adapter reused by tools and both connection protocols. The tenant's rule storage and governance model remain application concerns.
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
- eve carries verified inbound identity into every turn. Authored tools and connections can use that context to select outbound credentials for the current tenant:
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 executors receive `ctx` directly;
9
- - OpenAPI and MCP `auth` may be async functions of `ctx`;
10
- - connection headers may be an async map or async individual values.
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
- That is the entire pattern. Your application still owns tenant membership and credential storage; eve ensures the model never needs to see or choose those credentials.
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 principal contains a string `tenantId` attribute. Then centralize the runtime check:
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 stamp the tenant onto the session:
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. It can validate an API key, verify a
74
- JWT, or read an app session, but it should return only after the user belongs
75
- to the tenant they are claiming. Keep `principalId` stable for the same user,
76
- include an `issuer` when ids can come from more than one identity system, and
77
- put routing facts such as `tenantId` in `attributes`.
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
- session create or continue request and stamp that selected `tenantId` onto the
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 authenticated to your app;
84
- eve uses that verified principal to pick the correct outbound credential.
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-scoped JWTs, write one non-interactive auth helper
89
- and reuse it across OpenAPI and MCP connections. `principalType: "user"` tells
90
- eve to require the authenticated user from route auth, key the step-local token
91
- cache by that user, and pass the projected principal into `getToken`:
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 tenant-level credentials shared by multiple users, keep the
128
- credential lookup keyed by `tenantId` in your provider; user-scoped connection
129
- auth is still useful because it rejects unauthenticated sessions and keeps
130
- eve's token cache from crossing caller identities.
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
- Derive the tenant inside `execute`, fetch its credential from your application provider, and construct the outbound request:
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, the executor selects the credential from `ctx.session.auth.current`.
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 reusable auth helper to the connection. Generated operation tools
166
- receive the token at call time without exposing it to the model:
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 constructs that header from `getToken` and rejects conflicting definitions.
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 resolved in `headers` are
244
- sent only on outbound requests; they are not model inputs or tool results.
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 eve-facing files need only this application contract:
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, or an
282
- out-of-band OAuth flow you own. eve does not prescribe that choice.
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, avoid returning secrets in logs or 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.
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 stamps the verified tenant onto the session.
289
- 2. Tool code reads `ctx.session.auth.current`, and connection auth receives the projected `principal`.
290
- 3. The application provider resolves the corresponding credential.
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 enforce tenant ownership for session create, continue, and stream routes. Route authentication identifies the caller, but your application owns the ACL that decides which session ids that caller may access.
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
- Multi-tenant memory is a scope decision, not a storage implementation. Bind any
7
- [memory provider](../memory) to a trusted tenant and caller tuple, and eve
8
- passes the resulting locked scope key to every provider operation.
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. Replace it with
11
- Supermemory or a custom provider without changing the scope resolver; tenant
12
- isolation stays in the definition, not the store.
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. Resolve both from verified
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` disables memory for unauthenticated or incorrectly scoped
43
- traffic. eve does not call the provider and never substitutes a shared scope.
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
- Use `auth.current` for the caller of the active turn. If a conversation is
49
- permanently owned by its creator, use `auth.initiator` and enforce that
50
- ownership at the channel boundary.
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 validates the namespace and scope tuple, then derives an opaque
55
- `memory.scope.key`. `fileMemory()` uses that key for its document. A hosted or
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 close over the
59
- locked scope for the active operation, so a tool cannot redirect itself to a
60
- different tenant or caller. A provider must preserve that boundary by using
61
- `memory.scope.key` in every downstream read and write.
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, include the locked scope in the database or service
64
- query itself, not as a filter after a global search. For custom capture, use
65
- the provider's stable `operationId` as an idempotency key. See
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 authenticated caller changes within one session.
71
- With the scope above, a new caller is a new scope, and the slot starts over:
72
- what eve recalled for the earlier caller leaves model context. It can't remove
73
- what an earlier assistant response already said; give participants who must not
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 that memories are
79
- untrusted facts, not instructions, and what it may save; see
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 policy calls for explicit confirmation before saving or
83
- deleting memory.
85
+ tools when your product requires confirmation before saving or deleting memory.
84
86
 
85
- Do not use `defineState` for cross-session data. State belongs to one durable
86
- session; memory providers bridge sessions through provider-owned storage.
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 by default the model does not transcribe them. To give your agent the ability to answer a voice note, you will need to add a tool that transcribes the staged file.
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, such as 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 how eve stages files.
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, eve gives the error to the model as a tool error, which it can relay to the user. See [When a tool throws](../tools#when-a-tool-throws). A file over the channel's upload limit, 25 MB by default, or a file eve can't download reaches the agent as a short note instead of a file.
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.
@@ -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 can launch an authored eve application as a local subprocess. eve serves stable ACP v1 over stdio while its normal development server remains the execution runtime.
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. It supervises a local development server, and closing the ACP connection stops that owned server. To bridge ACP to a deployed eve agent, pass its URL:
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 resolves a short-lived project-scoped OIDC token from the local Vercel session. Remote access requires an existing authorized Vercel session; account login runs during local deployment. Configure required Trusted Sources access in the target project before launching ACP. `VERCEL_AUTOMATION_BYPASS_SECRET` remains available for deployments configured with a Protection Bypass for Automation token.
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. The initial eve adapter does not accept client-provided MCP servers.
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
- Development rebuilds retain normal eve semantics. In-flight work stays pinned to its generation, and the next turn uses the newest successful generation.
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 does not give the agent access to the editor's host filesystem or terminal. `session/new.cwd` identifies the eve application being launched; it is not mounted into the agent sandbox.
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
- The initial adapter does not support:
59
+ eve's ACP adapter doesn't support:
60
60
 
61
61
  - a deployed ACP HTTP or WebSocket endpoint;
62
- - ACP authentication (remote bridges use the deployed eve agent's existing HTTP authentication);
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 durable ACP IDs across process restarts;
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 establish an authenticated end-user principal.
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. eve sends compilation output, server logs, and diagnostics to stderr so they cannot corrupt the protocol stream.
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 quick headless smoke test, run an ACP client such as `acpx` from the application root. `acpx` launches the ACP process itself; do not start `eve acp` separately.
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
- When testing from the eve source checkout, use an authored fixture rather than the monorepo root, which does not provide an `eve` executable:
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
@@ -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 its UCP support by serving a JSON **profile** from the `/.well-known/ucp` path. This is a document listing the spec versions it supports, its services and capabilities, its payment handlers, and the public keys agents use to verify signed responses.
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
- With eve, you can support UCP in three steps:
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 lists the public keys agents use to verify your business's signed messages. It's a standard JWK Set, so 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).
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
- Use a custom channel to serve the profile from the `/.well-known/ucp` endpoint.
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
- The URLs in `services[].endpoint` must point at endpoints you serve. You can use a custom channel for these endpoints:
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
- Start the dev server with `eve dev` and fetch the well-known document locally:
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
- Commerce operation semantics are author-owned: the checkout, cart, and order state machines; payment-handler execution; and request signing and verification.
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 under its agent directory. Each supported path determines how eve loads the file. For recommended project layouts and when to split agents, read [Project Structure](/docs/concepts/project-structure).
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. Framework defaults use the same slots, so a file at the same path replaces the default when eve compiles the agent. Evals live beside `agent/`, not inside it.
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 capability names from file paths:
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 reusable capabilities | Yes | File or directory mounts. See [Extensions](/docs/extensions). |
57
- | `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only; recursive directories are supported. |
58
- | `skills/` | On-demand procedures and capability packs | Yes | Flat Markdown, module-backed skills, or packaged skills. |
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. |