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,20 +3,19 @@ title: "OpenAPI Connections"
3
3
  description: "Turn an OpenAPI 3.x or Swagger 2.0 document into eve connection tools, authorize calls, and control which operations the model can discover."
4
4
  ---
5
5
 
6
- OpenAPI connections turn an OpenAPI 3.x or Swagger 2.0 document into connection tools, one per operation. Use OpenAPI when a service publishes an HTTP API contract and you want eve to derive model-facing tools from that contract.
7
-
8
- Use an [MCP connection](./mcp) instead when the service already exposes an MCP server, when the server should own tool schemas dynamically, or when the remote service has richer MCP semantics than its raw HTTP API.
6
+ An OpenAPI connection turns an OpenAPI 3.x or Swagger 2.0 document into tools for your agent, one per operation. It lives in one file under `agent/connections/`. Use it when a service publishes an HTTP API contract.
9
7
 
10
8
  ## Define an OpenAPI connection
11
9
 
12
- Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/petstore.ts` registers as `petstore`, and events report its operation tools as `petstore__<operation>`.
10
+ The filename is the connection name, so `agent/connections/petstore.ts` registers as `petstore`.
13
11
 
14
12
  ```ts title="agent/connections/petstore.ts"
15
13
  import { defineOpenAPIConnection } from "eve/connections";
16
14
 
17
15
  export default defineOpenAPIConnection({
18
- spec: "https://petstore3.swagger.io/api/v3/openapi.json",
19
- description: "Pet store inventory and orders.",
16
+ spec: "https://petstore3.swagger.io/api/v3/openapi.json", // required: URL or inline object
17
+ description: "Pet store inventory and orders.", // required
18
+ // optional: omit for a public API
20
19
  auth: {
21
20
  principalType: "app",
22
21
  getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
@@ -24,22 +23,21 @@ export default defineOpenAPIConnection({
24
23
  });
25
24
  ```
26
25
 
27
- Each operation becomes a tool named by its `operationId`, reported as `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead. The model calls it with `eve__tool({ name: "petstore__getInventory", input })` and receives `{ status, statusText, body }`.
26
+ The [shared connection options](../connections#options) apply, with `operations` as the filter. OpenAPI adds `baseUrl`; see [Base URL and servers](#base-url-and-servers).
28
27
 
29
- `spec` can be a URL that eve fetches at runtime, or an inline parsed OpenAPI object. A spec URL must use `https` (plain `http` is allowed only for loopback hosts such as `localhost` during local development), and eve re-checks the transport after any redirects. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.
28
+ Each operation becomes a tool named `<connection>__<operationId>`, such as `petstore__getInventory`. An operation without an `operationId` gets a deterministic `<method>_<sanitized-path>` name. The model calls it with `eve__tool({ name: "petstore__getInventory", input })` and receives `{ status, statusText, body }`.
30
29
 
31
- ## Base URL and servers
30
+ `spec` is a URL that eve fetches at runtime, or an inline OpenAPI object. A spec URL must use `https`, also after redirects. Plain `http` works only for loopback hosts such as `localhost`. Use a URL when the provider maintains the contract. Use an inline object for private APIs, specs you pin in source control, or small hand-written contracts.
32
31
 
33
- eve resolves operation paths against `baseUrl` when you provide one. Otherwise, it derives the base URL from the spec:
32
+ ## Base URL and servers
34
33
 
35
- - OpenAPI 3.x: the first usable `servers` entry
36
- - Swagger 2.0: `schemes`, `host`, and `basePath`
34
+ eve builds each operation's URL from `baseUrl` and the operation path. Omit `baseUrl` to take it from the spec: the first usable `servers` entry in OpenAPI 3.x, or `schemes`, `host`, and `basePath` in Swagger 2.0. Set `baseUrl` when the spec lacks server data, points at the wrong environment, or uses a relative server URL.
37
35
 
38
- Use `baseUrl` when the spec is missing server data, points at the wrong environment, uses a relative server URL you do not want, or needs to be pinned for this agent.
36
+ The base URL must use `https`, or `http` for loopback hosts, because operation calls carry the connection's credentials.
39
37
 
40
- The resolved base URL must use `https` too (loopback hosts may use `http` for local development), since operation calls carry the connection's credentials.
38
+ For the same reason, operation calls follow redirects only within the base URL's origin, up to 10 hops. A longer chain fails as a redirect loop.
41
39
 
42
- For the same reason, operation calls follow redirects only within the base URL's origin, up to 10 hops; a longer chain fails the call as a redirect loop. A redirect to another origin is not followed. The tool returns the redirect response with its absolute target in `location`, such as `{ status: 302, statusText, body, location: "https://storage.example.com/..." }`, and the connection's credentials never reach the other host. Endpoints that hand downloads off to a storage host return that `location`, which the agent can fetch without the connection's credentials. If an API has moved to a new domain, point `baseUrl` at the new domain.
40
+ eve doesn't follow a redirect to another origin. The tool returns it with its full target URL, such as `{ status: 302, statusText, body, location: "https://storage.example.com/..." }`. The agent can fetch that `location` without the connection's credentials. If an API moves to a new domain, point `baseUrl` there.
43
41
 
44
42
  ```ts title="agent/connections/crm.ts"
45
43
  import { defineOpenAPIConnection } from "eve/connections";
@@ -53,7 +51,7 @@ export default defineOpenAPIConnection({
53
51
 
54
52
  ## Use Vercel Connect for OAuth
55
53
 
56
- For an OAuth-backed API, follow the shared [Vercel Connect setup](../connections#interactive-oauth-via-vercel-connect), then attach the returned connector UID to the OpenAPI connection:
54
+ For an API that uses OAuth, follow the shared [Vercel Connect setup](../connections#interactive-oauth-via-vercel-connect) and pass the connector UID to `connect()`:
57
55
 
58
56
  ```ts title="agent/connections/github.ts"
59
57
  import { connect } from "@vercel/connect/eve";
@@ -67,39 +65,37 @@ export default defineOpenAPIConnection({
67
65
  });
68
66
  ```
69
67
 
70
- `connect("...")` is user-scoped by default and requires an authenticated user on the active session. Use `connect({ connector, principalType: "app" })` when the API should act as the agent instead. Configure provider-specific scopes, audiences, or authorization details through `tokenParams` on `connect(...)`.
68
+ By default, `connect("...")` uses each user's own sign-in, so the session needs a signed-in user. Use `connect({ connector, principalType: "app" })` to have the API act as the agent. Pass provider-specific scopes, audiences, or authorization details through `tokenParams` on `connect(...)`.
71
69
 
72
70
  ## Static tokens and headers
73
71
 
74
- OpenAPI connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme or API version, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
72
+ OpenAPI connections accept the shared `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme or an API version, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers).
75
73
 
76
- ## Application-provided operation arguments
74
+ ## Operation filters
77
75
 
78
- Some APIs declare operation parameters that should come from the application rather than the model, such as a tenant or organization ID. Configure those values with `toolCall.providedArguments`:
76
+ Narrow the generated tools with exactly one of `operations.allow` or `operations.block`:
79
77
 
80
- ```ts title="agent/connections/crm.ts"
78
+ ```ts title="agent/connections/petstore.ts"
81
79
  import { defineOpenAPIConnection } from "eve/connections";
82
80
 
83
81
  export default defineOpenAPIConnection({
84
- spec: "https://api.example.com/openapi.json",
85
- description: "CRM accounts, contacts, and opportunities.",
86
- toolCall: {
87
- providedArguments: {
88
- tenantId: ({ session }) => String(session.auth.current?.attributes.tenant ?? ""),
89
- },
82
+ spec: "https://petstore3.swagger.io/api/v3/openapi.json",
83
+ description: "Pet store inventory and orders.",
84
+ auth: {
85
+ principalType: "app",
86
+ getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
90
87
  },
88
+ operations: { allow: ["getInventory", "placeOrder"] },
91
89
  });
92
90
  ```
93
91
 
94
- Values may be JSON values, promises, or callbacks. Callbacks receive the active session context, the bare operation `toolName`, and a replay-stable `callId` that is unique to the tool call. Use `callId` when the API needs an idempotency key.
92
+ Filters match an operation's `operationId` and its generated tool name, so `block: ["repos.delete"]` also hides the `repos_delete` tool. For an operation without an `operationId`, use the name eve derives from the method and path.
95
93
 
96
- eve removes configured keys from every operation's model-facing input schema and adds their resolved values immediately before constructing the HTTP request. Values apply to every operation on the connection and replace any conflicting model value. The keys correspond to the generated top-level operation inputs: path, query, header, and cookie parameter names, plus `body` for a request body.
94
+ ## Approval gates
97
95
 
98
- Use `headers` for transport-wide headers that are not operation inputs. Use `providedArguments` when the OpenAPI document declares the value as an operation parameter and it should remain outside model control. Approval policies continue to receive only the model-authored input.
96
+ Operations can change data, like authored tools. Use the shared `approval` option to ask a person first, and `operations.allow` to expose only the operations you need. See [Per-connection approval](../connections#per-connection-approval) for the helpers and [Human-in-the-loop](../human-in-the-loop#approvals) for policy behavior.
99
97
 
100
- ## Operation filters
101
-
102
- Most OpenAPI specs describe far more than the model should use. Narrow generated tools with exactly one of `operations.allow` or `operations.block`:
98
+ A custom policy sees the full tool name, `<connection>__<operationId>`, while `providedArguments` callbacks get the bare `operationId`. Its `toolInput` holds the parameters as top-level properties and the request body under `body`. To ask a person only for large orders:
103
99
 
104
100
  ```ts title="agent/connections/petstore.ts"
105
101
  import { defineOpenAPIConnection } from "eve/connections";
@@ -112,16 +108,19 @@ export default defineOpenAPIConnection({
112
108
  getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
113
109
  },
114
110
  operations: { allow: ["getInventory", "placeOrder"] },
111
+ approval: ({ toolName, toolInput }) => {
112
+ if (toolName !== "petstore__placeOrder") return "not-applicable";
113
+ const order = toolInput?.body as { quantity?: number } | undefined;
114
+ return (order?.quantity ?? 0) >= 10 ? "user-approval" : "not-applicable";
115
+ },
115
116
  });
116
117
  ```
117
118
 
118
- Filters match an operation's `operationId` and its generated tool name, so `block: ["repos.delete"]` also hides the `repos_delete` tool. If an operation does not declare an `operationId`, use the deterministic name eve derives from the method and path.
119
-
120
119
  ## Path parameters
121
120
 
122
- When an operation path contains dynamic segments, the spec must declare matching OpenAPI path parameters. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
121
+ Each dynamic segment in an operation path needs a matching `in: "path"` parameter in the spec. Path, query, header, and cookie parameters are top-level tool inputs, and eve puts each path value into its matching `{name}` placeholder.
123
122
 
124
- Path parameter values must not be exactly `.` or `..`. eve rejects these values before URL parsing can normalize them and change the route, including values resolved through `toolCall.providedArguments`. Other values remain URL-encoded during substitution, including embedded slashes.
123
+ eve rejects a path value of exactly `.` or `..`, including one from `toolCall.providedArguments`, because URL parsing would change the route. Other values are URL-encoded, including embedded slashes.
125
124
 
126
125
  ```ts title="agent/connections/cart.ts"
127
126
  import { defineOpenAPIConnection } from "eve/connections";
@@ -158,40 +157,39 @@ export default defineOpenAPIConnection({
158
157
  });
159
158
  ```
160
159
 
161
- The parameter `name` must exactly match the placeholder inside the path. If the spec omits an `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
160
+ The parameter `name` must exactly match the placeholder. If the spec omits an `in: "path"` parameter, the tool has no input for that segment, and eve can't fill it from query parameters.
162
161
 
163
- ## Schema annotations
164
-
165
- eve removes `default` and `example` annotations when their values conflict with the declared schema type. For example, a boolean property with `default: "false"` loses that annotation, while `default: false` is retained. This prevents invalid examples from guiding model input; eve does not coerce annotation values.
166
-
167
- ## Approval gates
168
-
169
- Generated operations can mutate state like authored tools. Use the shared connection `approval` option for human approval, and combine it with `operations.allow` for the smallest practical surface. See [Per-connection approval](../connections#per-connection-approval) for the helpers and [Human-in-the-loop](../human-in-the-loop#approvals) for policy behavior.
162
+ ## Application-provided operation arguments
170
163
 
171
- A custom policy sees each operation under its full tool name, `<connection>__<operationId>` (unlike `providedArguments` callbacks, which get the bare `operationId`). Its `toolInput` is the generated operation input: path, query, header, and cookie parameters as top-level properties, and the request body under `body`. To ask a person only for large orders:
164
+ Some operation parameters should come from the application, not the model, such as a tenant or organization ID. Set those values with `toolCall.providedArguments`:
172
165
 
173
- ```ts title="agent/connections/petstore.ts"
166
+ ```ts title="agent/connections/crm.ts"
174
167
  import { defineOpenAPIConnection } from "eve/connections";
175
168
 
176
169
  export default defineOpenAPIConnection({
177
- spec: "https://petstore3.swagger.io/api/v3/openapi.json",
178
- description: "Pet store inventory and orders.",
179
- auth: {
180
- credentialOwner: "app",
181
- getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
182
- },
183
- operations: { allow: ["getInventory", "placeOrder"] },
184
- approval: ({ toolName, toolInput }) => {
185
- if (toolName !== "petstore__placeOrder") return "not-applicable";
186
- const order = toolInput?.body as { quantity?: number } | undefined;
187
- return (order?.quantity ?? 0) >= 10 ? "user-approval" : "not-applicable";
170
+ spec: "https://api.example.com/openapi.json",
171
+ description: "CRM accounts, contacts, and opportunities.",
172
+ toolCall: {
173
+ providedArguments: {
174
+ tenantId: ({ session }) => String(session.auth.current?.attributes.tenant ?? ""),
175
+ },
188
176
  },
189
177
  });
190
178
  ```
191
179
 
180
+ Values may be JSON values, promises, or callbacks. Callbacks receive the session context, the bare operation `toolName`, and a `callId`. The `callId` is unique to the tool call and stays the same if eve runs the call again, so it works as an idempotency key.
181
+
182
+ Keys name top-level operation inputs: path, query, header, and cookie parameters, plus `body` for a request body. The model doesn't see these keys in any operation's input schema. eve adds their values just before it builds each request and overwrites any value the model sent. Approval policies see only the model's input.
183
+
184
+ Use `headers` instead for transport-wide headers that the spec doesn't declare as operation parameters.
185
+
186
+ ## Schema annotations
187
+
188
+ eve removes `default` and `example` annotations whose values don't match the declared schema type, so invalid examples don't mislead the model. A boolean property with `default: "false"` loses the annotation; `default: false` keeps it. eve doesn't coerce annotation values.
189
+
192
190
  ## What to read next
193
191
 
194
192
  - [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
195
- - [MCP connections](./mcp): connect to remote MCP servers.
193
+ - [MCP connections](./mcp): use one when the service's MCP server should define the tools, or offers more than the raw HTTP API.
196
194
  - [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
197
195
  - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.