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.
Files changed (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,13 +3,13 @@ title: "TypeScript API Reference"
3
3
  description: "The define* helpers, the runtime ctx, and where each one is imported from."
4
4
  ---
5
5
 
6
- This is the public surface of the `eve` package: the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The package's export map defines the full contract; source files that are not reachable through an exported package subpath are framework internals.
6
+ The `eve` package's public surface is the `define*` helpers you author with, the `ctx` they receive at runtime, and the import path for each. The package's export map defines the full contract; anything not reachable through an exported subpath is internal.
7
7
 
8
8
  For changes to an existing application, follow [Prepare for 1.0](../guides/prepare-for-1-0).
9
9
 
10
10
  Identity comes from the filesystem, not a field you set. A tool at `agent/tools/get_weather.ts` is `get_weather`, and a connection at `agent/connections/linear.ts` is `linear`, so no definition carries a `name` or `id`.
11
11
 
12
- Most files look the same: import a helper, default-export the result.
12
+ Most files import a helper and default-export the result:
13
13
 
14
14
  ```ts title="agent/agent.ts"
15
15
  import { defineAgent } from "eve";
@@ -32,8 +32,7 @@ export default defineTool({
32
32
 
33
33
  ## Integration dependencies
34
34
 
35
- Install the framework packages for the integration you import. These are optional peers of eve;
36
- using another entry does not require them.
35
+ Install the packages for each integration entry you import. They are optional peers of eve, so other entries don't need them.
37
36
 
38
37
  | Entry | Required integration packages |
39
38
  | ------------------------------------------------------------- | ----------------------------------------------------- |
@@ -84,29 +83,35 @@ The AI SDK is a required peer and has its own Zod peer requirement. To type the
84
83
  | `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) |
85
84
  | `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |
86
85
 
87
- Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `agentRouter` comes from `eve/tools/agent_router`, `sleep` comes from `eve/tools/sleep`, `noReply` comes from `eve/tools/no_reply`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
86
+ Tool-wide helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Built-in tool definitions use their own subpaths; see [Built-in tools](../concepts/built-in-tools):
88
87
 
89
- `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
88
+ - Reusable definitions such as `bash` and `glob` from `eve/tools/<name>`.
89
+ - `webSearch` from `eve/tools/web_search`, `agentRouter` from `eve/tools/agent_router`, `sleep` from `eve/tools/sleep`, and `noReply` from `eve/tools/no_reply`.
90
+ - Approval policies and types from `eve/tools/approval`.
90
91
 
91
- `webSearch({ provider })` selects `"exa"`, `"parallel"`, `"browserbase"`, or `"native"` for AI Gateway search using the Gateway model's credentials. `"native"` uses the model vendor's own search for OpenAI, Anthropic, and Gemini 3 and later models; set `fallback` to `"exa"`, `"parallel"`, or `"browserbase"` to give other Gateway models search, which they otherwise don't get. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.
92
+ The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` and `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`.
92
93
 
93
- `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Dynamic instructions use `defineDynamic(ctx => defineInstructions(...))` or return `null`. The retired `{ markdown: string }` definition is rejected.
94
+ `eve` exports `AgentReasoningDefinition` for `defineAgent({ reasoning })`, `AgentLimitsDefinition` for `defineAgent({ limits })`, and `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` for `defineAgent({ experimental: { workflow } })`. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
94
95
 
95
- Dynamic connections use `defineDynamic(ctx => value)`, returning one MCP or OpenAPI connection definition, a map, or `null`. Functions read committed session context and can load conversation history with `ctx.messages()`. Set `instanceKey` to a stable, non-secret account or tenant identifier so authorization resumes cannot cross resolved instances. See [Dynamic capabilities](../guides/dynamic-capabilities).
96
+ `webSearch({ provider })` selects `"exa"`, `"parallel"`, `"browserbase"`, or `"native"` for AI Gateway search with the Gateway model's credentials. `"native"` uses the model vendor's own search for OpenAI, Anthropic, and Gemini 3 and later models. Other Gateway models get no search unless you set `fallback` to `"exa"`, `"parallel"`, or `"browserbase"`. Direct provider models keep their native search implementation when supported. See [Built-in tools](../concepts/built-in-tools#web_search) for setup and provider behavior.
97
+
98
+ `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omit `role` for `"system"`. Dynamic instructions use `defineDynamic(ctx => defineInstructions(...))` or return `null`.
99
+
100
+ Dynamic connections use `defineDynamic(ctx => value)`, returning one MCP or OpenAPI connection definition, a map, or `null`. Functions read the saved session context and can load conversation history with `ctx.messages()`. Set `instanceKey` to a stable, non-secret account or tenant identifier. eve rejects a pending sign-in callback when its resolved connection instance changes. See [Dynamic capabilities](../guides/dynamic-capabilities).
96
101
 
97
102
  ## Authored module lifecycle
98
103
 
99
- eve evaluates TypeScript definition modules during compilation so it can validate and normalize the agent. Within one agent node, each module namespace loads at most once during that compile. The resolved definition then determines whether the module is also an entry in the runtime bundle:
104
+ eve evaluates TypeScript definition modules at build time to validate the agent, at most once per agent. The resolved definition decides whether the module also loads at runtime:
100
105
 
101
- | Lifecycle | Authored definitions |
106
+ | When it loads | Authored definitions |
102
107
  | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
103
108
  | Compile only | Static instructions and skills, prompt-form TypeScript schedules, static Gateway or default agent config, provider-managed web search, Workflow SDK configuration, fully shadowed channels, and a child sandbox that selects its parent's sandbox |
104
109
  | Compile and runtime | Dynamic instructions, skills, tools, models, and subagents; executable tools; effective channels; connections; hooks; memory; handler schedules; direct-provider models; independent sandboxes; and remote subagents |
105
110
  | Runtime only | Instrumentation modules and extension mount initialization |
106
111
 
107
- A compile-only module is not imported when the deployed runtime starts. For example, eve stores the resolved content from a static `instructions.ts` in the compiled manifest. A compile-and-runtime module is evaluated during compilation and imported again when a runtime process loads the module map. Keep module-top-level work deterministic, and put request- or session-specific work in the definition's runtime callbacks.
112
+ The deployed runtime doesn't import a compile-only module; for example, a static `instructions.ts` runs only at build time. A compile-and-runtime module runs at build time and again in each runtime process. Keep module top-level work deterministic, and put request- or session-specific work in runtime callbacks.
108
113
 
109
- The runtime bundler follows the normal ESM graph from every runtime entry. A helper remains runtime code when a tool or other runtime entry imports it, even if static instructions also import that helper. Lifecycle selection applies to definition entries, not as tree-shaking permission for their ordinary dependencies.
114
+ These load rules apply to definition modules, not their ordinary imports. A helper that a tool imports stays runtime code even if static instructions also import it.
110
115
 
111
116
  ### Asset imports
112
117
 
@@ -119,21 +124,30 @@ import template from "../../prompts/template.txt?raw";
119
124
 
120
125
  `?raw` embeds any file as UTF-8 text, including code files such as `.json` and files without an extension, such as a `Dockerfile`. Other non-code asset imports produce a data URL with an inferred media type. Compilation, local development, and production builds use the same resolution behavior.
121
126
 
122
- A workspace package bundled from TypeScript source can import its own assets the same way. Each import may reach files inside the project package or inside the package that contains the importing module. Imports that escape both are rejected; package those files with the application or the workspace package instead.
127
+ A workspace package bundled from TypeScript source can import its own assets the same way. Each import may reach files inside the project package or the importing module's package. eve rejects imports that escape both, so package those files with the application or the workspace package.
123
128
 
124
129
  ## Runtime context (`ctx`)
125
130
 
126
- `ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It is live only while authored code is running, so reaching for it at module top level throws. See [Session context](../guides/session-context) for the full model.
131
+ `ctx` is passed to your tool `execute`, hook handlers, channel event handlers, and connection auth/header resolvers. It exists only while authored code runs, so reading it at module top level throws. See [Session context](../guides/session-context) for the full model.
127
132
 
128
133
  | Member | Use |
129
134
  | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
130
135
  | `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) |
131
- | `ctx.getSandbox()` | Live sandbox handle; `stop()` releases compute but preserves durable state |
136
+ | `ctx.getSandbox()` | Live sandbox handle; `stop()` releases compute and keeps the sandbox's files |
132
137
  | `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` |
133
138
  | `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
134
139
  | `ctx.approval` | Present only while a call runs after a person approved it: `responder` is who approved it and `responder.getToken(provider)` resolves their token. The call still runs as `ctx.session.auth.current`; see [Human-in-the-loop](/docs/human-in-the-loop) |
135
140
 
136
- Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions, and `deferred: true` to keep the tool out of the model's tool list so the model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list). `defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call). Authored workflow bodies also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name)`, which returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. A `"use step"` helper that receives the context directly should type it as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`; its `getSandbox()` opens the sandbox of the session that called the tool (see [Use the session sandbox in a step](../tools/workflows#use-the-session-sandbox-in-a-step)). The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
141
+ Tool definitions accept these options:
142
+
143
+ - `availableInSubagents: false` restricts the tool to top-level root sessions.
144
+ - `deferred: true` keeps the tool out of the model's tool list. The model finds it with `eve__search` and calls it with `eve__tool`; see [Tools](../tools#keep-a-tool-out-of-the-tool-list).
145
+
146
+ `defineTool` definitions accept `endsTurn: true`, or a function that receives the `execute` output, to end the turn without a reply after a successful call; see [Tools](../tools#end-the-turn-after-a-tool-call).
147
+
148
+ Authored workflow bodies also receive `ctx.agents`, a map that describes the agents the workflow can call. It stays the same across workflow replays. `ctx.agent(name)` returns an `AgentSession` whose `send(message, options?)` resolves to a response with `result()`. The `agent` entry is a copy of the root agent, and its description is empty when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
149
+
150
+ Type the context in a `"use step"` helper as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`. Its `getSandbox()` opens the sandbox of the session that called the tool (see [Use the session sandbox in a step](../tools/workflows#use-the-session-sandbox-in-a-step)).
137
151
 
138
152
  ## Imports at a glance
139
153
 
@@ -184,43 +198,30 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
184
198
  | `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack` | framework bundler plugins |
185
199
  | [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, `EveError` and the typed client errors |
186
200
  | [`eve/sessions`](../guides/client/messages#reusable-delivery-reads) | `Delivery`, `DeliveryResult`, read options, `SessionReader`, `Session`, `EveError`, and `SessionNotActiveError` |
187
- | [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state) | Facts, opaque `SessionView`, immutable observations, and query/fold functions |
201
+ | [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state) | Event types, opaque `SessionView`, immutable observations, and query/fold functions |
188
202
  | [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process |
189
203
 
190
- Exported types ship from the entry point that owns them (for example `ToolDefinition` and `ToolContext` from `eve/tools`). Import fact and view types from `eve/events`, `SessionContext` and `HistoryMessage` from `eve/context`, and assertion types and `ToolStub` from `eve/evals`. Frontend hook entries also export the types their hooks return. Shared delivery/session contracts
191
- have one home, `eve/sessions`; client factories and transport-specific types stay in `eve/client`.
192
- `SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session.
193
- `ChannelContext` from `eve/channels` separates session information from continuation aliasing.
204
+ Exported types ship from the entry point that owns them, such as `ToolDefinition` and `ToolContext` from `eve/tools`. Import event and view types from `eve/events`, `SessionContext` and `HistoryMessage` from `eve/context`, and assertion types and `ToolStub` from `eve/evals`. Frontend hook entries also export the types their hooks return.
194
205
 
195
- `HistoryMessage`, `EveLanguageModel`, `TokenUsage`, the sandbox session, process, result, and method-option types, the `SpanProcessor`, `SpanProcessorOrName`, and `SpanExporter` types from `eve/instrumentation/otel`, and the Linq and Photon credential and webhook-verifier types are eve-owned. Their declarations do not change with your app's AI SDK, OpenTelemetry, or channel-adapter versions. Named judge, mock-model, approval, and disabled-marker types remain public for reusable helpers and declaration emission.
206
+ Types for reading sent messages and sessions live in `eve/sessions`; client factories and transport-specific types stay in `eve/client`. `SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session. `ChannelContext` from `eve/channels` holds the session's `id` and `auth`, plus an optional `continuation` routing token that `alias()` can extend.
196
207
 
197
- ## Stability policy
208
+ `HistoryMessage`, `EveLanguageModel`, `TokenUsage`, and the sandbox session, process, result, and method-option types are eve-owned. So are the `SpanProcessor`, `SpanProcessorOrName`, and `SpanExporter` types from `eve/instrumentation/otel`, and the Linq and Photon credential and webhook-verifier types. Their declarations don't change with your app's AI SDK, OpenTelemetry, or channel-adapter versions. Named judge, mock-model, approval, and disabled-marker types are public for reusable helpers and declaration emission.
198
209
 
199
- The `exports` field in `packages/eve/package.json` lists every package entry point.
200
- `eve/experimental/*` and `eve/internal/*` have no compatibility promise. The same
201
- applies to `experimental` fields in stable definitions, such as
202
- `defineAgent({ experimental })`, connection `experimental.events`, and
203
- `JustBashSandbox.environment({ experimental })`.
210
+ ## Stability policy
204
211
 
205
- Event union types name today's values. Adding fact types, outcomes, or interaction
206
- kinds under the [stream evolution rules](../concepts/sessions-runs-and-streaming#what-a-later-release-can-add)
207
- is not a breaking change. Keep a default branch when switching on those values.
212
+ The `exports` field in eve's `package.json` lists every entry point. `eve/experimental/*` and `eve/internal/*` have no compatibility promise. Neither do `experimental` fields in stable definitions, such as `defineAgent({ experimental })`, connection `experimental.events`, and `JustBashSandbox.environment({ experimental })`. The CLI setup wizard is not a public authoring API.
208
213
 
209
- Values eve passes into code you implement can also gain members in a minor
210
- release, such as a sandbox provider's `onSessionEnd()` `reason`, the provider
211
- context's `kind`, and `SandboxNetworkRule` variants. Handle unknown values, for
212
- example with a default branch, instead of switching exhaustively.
214
+ Event union types name today's values. A release can add event types, outcomes, and request kinds under the [stream evolution rules](../concepts/sessions-runs-and-streaming#what-a-later-release-can-add) without a breaking change, so keep a default branch when you switch on them.
213
215
 
214
- `eve/channels/chat-sdk`, `eve/channels/linq`, and `eve/channels/photon` expose
215
- types from the `chat` package (Chat SDK v4) as part of their contract. They track
216
- `chat` v4, so a future breaking `chat` major may require a corresponding eve change.
216
+ Values eve passes into code you implement can also gain members in a minor release. Examples are a sandbox provider's `onSessionEnd()` `reason`, the provider context's `kind`, and `SandboxNetworkRule` variants. Handle unknown values with a default branch instead of switching exhaustively.
217
217
 
218
- The CLI setup wizard is not a public authoring API; Agent Builder's scaffold
219
- integration lives at `eve/internal/scaffold`.
218
+ `eve/channels/chat-sdk`, `eve/channels/linq`, and `eve/channels/photon` expose types from the `chat` package (Chat SDK v4) as part of their contract. A future breaking `chat` major can require a matching eve change.
220
219
 
221
220
  ## Direct provider models
222
221
 
223
- `openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return AI SDK language models that use eve's credentials, so you can also pass them to AI SDK functions such as `generateText`. They accept only an optional model ID. `EveLanguageModel`, exported from `eve` and `eve/models`, is the model instance type `agent.ts` accepts; every AI SDK language model satisfies it. Defaults are `gpt-6-luna-fast` and `claude-sonnet-5`, respectively.
222
+ `openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return AI SDK language models that use eve's credentials, so you can also pass them to AI SDK functions such as `generateText`. They accept only an optional model ID; omit it for `gpt-6-luna-fast` and `claude-sonnet-5`, respectively.
223
+
224
+ `EveLanguageModel`, exported from `eve` and `eve/models`, is the model type `agent.ts` accepts. Every AI SDK language model satisfies it.
224
225
 
225
226
  Use `/login` for local credentials, or set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Local secret-store discovery is disabled in deployments; provision server credentials explicitly. See [Set the model](../agent-config#set-the-model) for an example.
226
227
 
@@ -237,32 +238,30 @@ export default defineAgent({
237
238
  });
238
239
  ```
239
240
 
240
- Pass another bare OpenAI model slug to override the default. The retired `experimental_chatgpt` alias is not exported.
241
+ Pass another bare OpenAI model slug to override the default.
241
242
 
242
- `chatgpt()` uses stateless requests (`store: false`). eve retains reasoning summaries and encrypted reasoning in session history and replays them after tool calls and on later turns. You do not need to configure `reasoning.encrypted_content` explicitly.
243
+ `chatgpt()` sends stateless requests (`store: false`). eve preserves reasoning across tool calls and later turns, so you don't configure `reasoning.encrypted_content`.
243
244
 
244
- eve uses one local authentication path with two credential owners:
245
+ To sign in, use one local path. Who stores the credential depends on whether Codex is installed:
245
246
 
246
247
  1. Run `eve dev`, open `/login`, and select **ChatGPT subscription**.
247
248
  2. If `codex` is on `PATH`, eve uses `codex app-server` and launches `codex login` when sign-in is needed. Codex owns credential storage and refresh.
248
249
  3. If the Codex binary is not found, eve falls back to direct browser sign-in and owns the saved session and refresh. If the browser does not open, use the URL printed in the terminal.
249
250
 
250
- When Codex is available, eve asks app-server for tokens and does not read or write Codex login files. App-server errors other than a missing binary are reported instead of silently switching credential owners.
251
-
252
- For the eve-owned fallback, eve stores your refresh token and account details in your operating system's credential store through [just-secrets](https://github.com/vercel-labs/just-secrets): the login Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Access tokens stay in process memory; a new eve process refreshes the saved session when it first needs a token. The fallback login is separate from Codex and is never written to your project.
251
+ With Codex, eve asks app-server for tokens and doesn't read or write Codex login files. eve reports app-server errors other than a missing binary instead of switching credential owners.
253
252
 
254
- If you previously used eve's `~/.eve/auth/chatgpt.json` file, sign in once through the eve-owned fallback after upgrading. A successful save removes the old plaintext session file. eve does not fall back to file storage if the OS credential store is unavailable.
253
+ The eve-owned fallback stores your refresh token and account details through [just-secrets](https://github.com/vercel-labs/just-secrets). It uses the login Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Access tokens stay in process memory, and a new eve process refreshes the saved session when it first needs a token. The fallback login is separate from Codex and never written to your project. eve doesn't fall back to file storage when the OS credential store is unavailable.
255
254
 
256
- Linux, including WSL, requires `/usr/bin/secret-tool` (commonly provided by `libsecret-tools`), a session D-Bus, and an unlocked Secret Service keyring. On macOS, unlock your login keychain and allow credential access if prompted. On Windows, PowerShell and Credential Manager must be available in your user session. OS credential storage protects secrets at rest; it does not guarantee isolation from malicious processes running as your OS user.
255
+ Linux, including WSL, requires `/usr/bin/secret-tool` (commonly provided by `libsecret-tools`), a session D-Bus, and an unlocked Secret Service keyring. On macOS, unlock your login keychain and allow credential access if prompted. On Windows, PowerShell and Credential Manager must be available in your user session. OS credential storage protects secrets at rest, not from malicious processes running as your OS user.
257
256
 
258
- For the eve-owned fallback, SSH sessions or a busy localhost port 1455 use a device code. Open the displayed link in a browser and enter the code. Device sign-in requires enabling device code authorization in **ChatGPT Settings → Security**, or having a workspace admin enable it in workspace permissions. Sign-in times out after five minutes; press **Ctrl+C** to cancel sooner. Device sign-in still requires an available OS credential store; use an API-key model in headless environments without one.
257
+ The fallback uses a device code in SSH sessions or when localhost port 1455 is busy: open the displayed link and enter the code. Device sign-in requires device code authorization, enabled in **ChatGPT Settings → Security** or by a workspace admin in workspace permissions. Sign-in times out after five minutes; press **Ctrl+C** to cancel sooner. Device sign-in still needs an OS credential store; use an API-key model in headless environments without one.
259
258
 
260
- ChatGPT subscription credentials are local user credentials. `eve deploy` blocks agents whose active model is `chatgpt()` because those credentials are not uploaded to a deployment. Use an environment branch with a deployable model, or switch to an AI Gateway model before deploying.
259
+ `eve deploy` blocks agents whose active model is `chatgpt()`, because these local user credentials aren't uploaded to a deployment. Use an environment branch with a deployable model, or switch to an AI Gateway model before deploying.
261
260
 
262
261
  Troubleshooting:
263
262
 
264
263
  - **`chatgpt-sub login`**: open `/login` and select **ChatGPT subscription** to sign in again. eve launches `codex login` when Codex is available, or its direct sign-in flow when it is not.
265
- - **`chatgpt-sub unavailable` with Codex installed**: update or restart Codex and retry. eve does not mask app-server failures by switching to a different saved session.
264
+ - **`chatgpt-sub unavailable` with Codex installed**: update or restart Codex and retry.
266
265
  - **`chatgpt-sub unavailable` without Codex**: follow the reported OS credential-store recovery steps, or check your network connection if token refresh failed. Retry from `/login`. If eve reports an invalid stored session, sign in again to replace it.
267
266
  - **Model rejected by the backend**: model availability depends on the signed-in ChatGPT account. Pick another supported OpenAI model.
268
267
  - **Device sign-in unavailable**: enable device code authorization in ChatGPT security settings, or sign in from a local terminal with port 1455 available.
@@ -7,8 +7,8 @@ As the deployer, it is your responsibility to ensure your agent complies with ap
7
7
 
8
8
  You are responsible for configuring approval policies, tool restrictions, connection scopes, route/session authorization, sandbox controls, telemetry exports, and other safeguards appropriate for your use case.
9
9
 
10
- Before using eve with non-public, sensitive, regulated, or production data, review which default tools, custom tools, MCP tools, shell/file/web tools, connected services, subagents, schedules, and external actions are available to the agent.
10
+ Before using eve with non-public, sensitive, regulated, or production data, review what the agent can reach. Check its default tools, custom tools, MCP tools, shell/file/web tools, connected services, subagents, schedules, and external actions.
11
11
 
12
12
  Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
13
13
 
14
- Unless you configure stricter controls, eve agents may operate with permissive settings, including tool execution without human approval where approval is omitted and sandbox network egress that is not deny-all. Do not rely on model behavior alone to prevent sensitive or irreversible actions.
14
+ Unless you configure stricter controls, eve agents may operate with permissive settings. Tools without an approval setting run without human approval, and sandbox network egress is not deny-all. Do not rely on model behavior alone to prevent sensitive or irreversible actions.
@@ -3,11 +3,11 @@ title: "Custom Sandbox Providers"
3
3
  description: "Connect eve to your own sandbox backend with defineSandboxProvider()."
4
4
  ---
5
5
 
6
- A custom sandbox provider connects eve to a backend that eve does not ship, such as your own container service or virtual machine pool. You implement a byte-level connection to one sandbox and four lifecycle methods. eve derives the full sandbox session from the connection, seeds workspace and skill files into templates, hashes template keys, and maps `sandbox.stop()`, `sandbox.delete()`, and server shutdown onto the lifecycle.
6
+ A custom sandbox provider connects eve to a backend eve doesn't ship, such as your own container service or virtual machine pool. You write a connection that runs commands and moves file bytes in one sandbox, and four methods that build, create, reconnect, and delete sandboxes. eve builds the rest of the sandbox API from them.
7
7
 
8
8
  ## Define a provider
9
9
 
10
- `defineSandboxProvider()` from `eve/sandbox/provider` takes a name and an `environment()` function that returns the lifecycle. This example targets `@acme/sdk`, a hypothetical client for a snapshot-capable machine service:
10
+ `defineSandboxProvider()` from `eve/sandbox/provider` takes a name and an `environment()` function that returns the four methods. This example targets `@acme/sdk`, a hypothetical client for a machine service that can take snapshots:
11
11
 
12
12
  ```ts title="agent/lib/acme-sandbox.ts"
13
13
  import { createHash } from "node:crypto";
@@ -104,85 +104,101 @@ export const environment = AcmeSandbox.environment({
104
104
  export default defineSandbox(() => environment.open({ egress: "deny-all" }));
105
105
  ```
106
106
 
107
- `environment(options)` always receives an object, without `prepare`: `{}` when the sandbox file passes no options, so make every field optional or require the caller to pass it. TypeScript infers the environment options, open options, artifact, state, and connection extensions from the implementation, so you do not pass type arguments. Write `start()` before `resume()` so the state type comes from `start()`'s return value, or annotate `resume()`'s `state` parameter.
107
+ `environment(options)` receives the caller's options without `prepare`, or `{}` when the sandbox file passes none. Make every field optional, or require the caller to pass it.
108
+
109
+ TypeScript infers the option, artifact, state, and extension types from the implementation. Write `start()` before `resume()` so the state type comes from `start()`'s return value, or annotate `resume()`'s `state` parameter.
108
110
 
109
111
  ## Implement the connection
110
112
 
111
- A `SandboxConnection` is the byte-level link to one sandbox. Each method has a fixed contract:
113
+ A `SandboxConnection` runs commands and reads and writes file bytes in one sandbox:
112
114
 
113
- - `spawn({ command, workingDirectory, env, signal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus `env`. `env` holds only the per-call variables. Aborting kills the process tree. It resolves to a process with `stdout` and `stderr` byte streams, `wait()`, and `kill()`. When the call passes `stdin: true`, the process must also have a writable `stdin` stream; without one, eve kills the process and rejects the call.
115
+ - `spawn({ command, workingDirectory, env, signal })` runs `command` as a Bash login-shell script (`bash -lc`) in `workingDirectory`, with the sandbox's environment plus the per-call `env`. Aborting kills the process tree. It resolves to a process with `stdout` and `stderr` byte streams, `wait()`, and `kill()`. When the call passes `stdin: true`, the process must also have a writable `stdin` stream, or eve kills the process and rejects the call.
114
116
  - `readFile({ path, signal })` resolves to the file's bytes or a byte stream, or to `null` only when the path does not exist. A directory or an unreadable path rejects.
115
117
  - `writeFiles({ files, signal })` writes every file, creating missing parent directories and overwriting existing files. It is the only write primitive.
116
118
  - `removePath({ path, force, recursive, signal })` removes a file or directory. `force` ignores a missing path, and `recursive` removes a non-empty directory.
117
119
  - `stop()` releases compute and keeps the sandbox's files.
118
- - `close()` is optional. It releases what this process holds for the connection, such as a local interpreter or child processes, without touching the sandbox. eve calls it whenever it lets go of a connection: when the step that opened it ends, after `stop()`, and before deletion. A connection lasts at most one step, so the next step resumes the sandbox through a new connection.
119
- - `extensions` is optional. It is a plain object whose own properties eve merges onto the session, such as `setNetworkPolicy()`. Use closures rather than class methods, because eve does not copy inherited members.
120
- - `workspaceRoot` is optional. It is the session's workspace root: the absolute sandbox directory where commands start by default. It defaults to `/workspace`, which every built-in provider uses. Set it when your sandbox keeps its working files somewhere else, such as `/home/user/project`. The directory must exist before eve runs a command in it.
120
+ - `close()`, optional, releases what this process holds for the connection, such as a local interpreter or child processes, without touching the sandbox. eve calls it when the step that opened the connection ends, after `stop()`, and before deletion. A connection lasts at most one step, and the next step resumes the sandbox through a new connection.
121
+ - `extensions`, optional, is a plain object whose own properties eve adds to the sandbox, such as `setNetworkPolicy()`. Use closures rather than class methods, because eve doesn't copy inherited members.
122
+ - `workspaceRoot`, optional, is the absolute sandbox directory where commands start and relative paths resolve. Omit it to use `/workspace`, as every built-in provider does. The directory must exist before eve runs a command in it.
121
123
 
122
- Every path a connection receives is absolute, and `workingDirectory` is always set. eve resolves relative paths and a missing or relative working directory from the workspace root before it calls the connection, and `session.resolvePath(".")` returns the root. The built-in file tools, attachment staging, and GitHub checkouts use the same root. eve throws when it opens a connection whose `workspaceRoot` is not absolute:
124
+ Every path a connection receives is absolute, and `workingDirectory` is always set. The built-in file tools, inbound attachments, and GitHub checkouts use the same root. eve throws when it opens a connection whose `workspaceRoot` is not absolute:
123
125
 
124
126
  ```text
125
127
  Sandbox connection workspaceRoot must be an absolute path, but received "project".
126
128
  ```
127
129
 
128
- eve builds the rest of the session from these methods: `run()` over `spawn()`, the binary and text read and write variants, encodings and line ranges, `writeFiles()`, `resolvePath()`, and abort-signal binding. An extension member named like a session method, or `stop` or `delete`, is a type error, and eve throws when it opens the connection:
130
+ eve builds the rest of the sandbox API from these methods, including `run()`, the binary and text read and write variants, and `resolvePath()`. An extension member with the name of one of those methods, or `stop` or `delete`, is a type error. eve also throws when it opens the connection:
129
131
 
130
132
  ```text
131
133
  Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
132
134
  ```
133
135
 
134
- Type the connection with its extensions, such as `SandboxConnection<{ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void> }>`, and `environment.open()` and `ctx.getSandbox(environment)` return a session that includes them.
136
+ Type the connection with its extensions, such as `SandboxConnection<{ setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void> }>`. `environment.open()` and `ctx.getSandbox(environment)` then return a sandbox that includes them.
135
137
 
136
138
  ## Implement the lifecycle
137
139
 
138
- eve calls the lifecycle methods at these points:
140
+ eve calls the provider's methods at these points:
141
+
142
+ | When | eve calls |
143
+ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
144
+ | `eve build`, or the first sandbox access in `eve dev` | `prepare(ctx)`, and stores the artifact it returns with the deployment |
145
+ | The first sandbox access in a session, or prewarming | `start(ctx, options, artifact)` from `environment.open(options)` in the selector |
146
+ | A later workflow step or process, or a turn starting | `resume(ctx, artifact, state)` |
147
+ | The step that opened a connection ends | `connection.close()`, for a turn's step, a `"use step"` function, or an `invokeTool` call |
148
+ | `sandbox.stop()` | `connection.stop()`, then `connection.close()` |
149
+ | `sandbox.delete()` | `connection.close()`, then `onSessionEnd(ctx, state, { reason: "deleted" })` |
150
+ | The eve server shuts down | `connection.stop()`, then `connection.close()`, on every connection eve still holds |
151
+ | The session that owns the sandbox ends | `connection.close()` on a connection the ending step still holds, then `onSessionEnd(ctx, state, { reason })` with `"completed"`, `"expired"`, or `"failed"` |
139
152
 
140
- | When | eve calls |
141
- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
142
- | `eve build`, or the first sandbox access in `eve dev` | `prepare(ctx)`, and stores the artifact it returns with the deployment |
143
- | The first sandbox access in a session, or prewarming | `start(ctx, options, artifact)` from `environment.open(options)` in the selector. A prewarmed session calls it in the background before its first message, and its first turn can call it again concurrently |
144
- | A later workflow step or process, or a turn starting | `resume(ctx, artifact, state)`. Each turn of a session that recorded a sandbox calls it in the background as the turn starts, whether or not the turn uses the sandbox |
145
- | The step that opened a connection ends | `connection.close()`, for a turn's step, a `"use step"` function, or an `invokeTool` call |
146
- | `sandbox.stop()` | `connection.stop()`, then `connection.close()` |
147
- | `sandbox.delete()` | `connection.close()`, then `onSessionEnd(ctx, state, { reason: "deleted" })` |
148
- | The eve server shuts down | `connection.stop()`, then `connection.close()`, on every connection eve still holds: any connection mid-step, and between steps a connection without `close()`; eve logs failures and does not throw them |
149
- | The owning session reaches a terminal outcome | `connection.close()` on a connection the ending step still holds, then `onSessionEnd(ctx, state, { reason })` with `"completed"`, `"expired"`, or `"failed"` |
153
+ - A prewarmed session calls `start()` before its first message, and its first turn can call it again at the same time.
154
+ - Each turn of a session that recorded a sandbox calls `resume()` as the turn starts, whether or not the turn uses the sandbox.
155
+ - Server shutdown always stops connections that are mid-step. eve logs shutdown failures and doesn't throw them.
156
+ - eve calls `close()` at most once per connection, and calls it again only after a failure. A failed `close()` never prevents `onSessionEnd()` from deleting the sandbox.
157
+ - `stop()` can run again after the session uses a stopped connection, so make it a no-op when the sandbox is already stopped.
150
158
 
151
- eve calls `close()` at most once per connection, retrying only after a failure. After a turn's step ends, eve keeps a connection without `close()` registered, so server shutdown still stops the session's sandbox. eve lets go of a connection with `close()` at the end of its step or after `stop()`, so server shutdown between steps does not stop that sandbox. If your provider defines `close()` and runs remote compute, bound idle compute yourself, for example with an idle timeout. `stop()` can run again after the session uses a stopped connection, so make it a no-op when the sandbox is already stopped. A failed `close()` never prevents `onSessionEnd()` from deleting the sandbox.
159
+ Defining `close()` changes shutdown behavior. Without `close()`, eve keeps the connection between steps, so server shutdown stops its sandbox. With `close()`, eve releases the connection at the end of its step, so server shutdown between steps doesn't stop that sandbox. If your provider defines `close()` and runs remote compute, limit idle compute yourself, for example with an idle timeout.
152
160
 
153
161
  ### `prepare()`
154
162
 
155
- `prepare()` builds a reusable template and returns a JSON-compatible artifact, such as a snapshot or image id. It runs during `eve build`, so the deployment ships with the artifact, and the production runtime never calls it. A running sandbox keeps the template it started from: `resume()` receives the current deployment's artifact, but reconnects existing state.
163
+ `prepare()` builds a reusable template and returns a JSON-compatible artifact, such as a snapshot or image id. It runs during `eve build`, so the deployment ships with the artifact. The production runtime never calls it.
164
+
165
+ A running sandbox keeps the template it started from. `resume()` receives the current deployment's artifact, but it reconnects to the existing sandbox.
156
166
 
157
- `ctx.isEmpty` is `true` when the agent has no workspace files, no skill files, and no authored `prepare`. A provider can skip building a template in that case. See [Bake files into templates](#bake-files-into-templates) for `ctx.populate()` and `ctx.templateKey()`.
167
+ `ctx.isEmpty` is `true` when the agent has no workspace files, skill files, or authored `prepare`, so the provider can skip building a template. See [Bake files into templates](#bake-files-into-templates) for `ctx.populate()` and `ctx.templateKey()`.
158
168
 
159
169
  ### `start()`
160
170
 
161
- `start()` returns the sandbox for `ctx.session.id`, creating it when none exists, together with the minimal JSON-compatible state eve checkpoints for the session. It must be an idempotent upsert: repeated, concurrent, cross-process, and cross-deployment calls for one session id return the same sandbox while it exists and is usable. A subagent that shares its parent's sandbox can open it before the parent does, and two processes can race to create it.
171
+ `start()` returns the sandbox for `ctx.session.id`, and creates it when none exists. It also returns the smallest JSON-compatible state that `resume()` needs, which eve saves with the session.
162
172
 
163
- Derive the sandbox's native identity from `ctx.session.id` and a provider-level namespace, such as a project or account, only. Never derive it from the open options or the artifact, which can differ between callers and deployments. Apply them only when `start()` creates the sandbox.
173
+ Every call for one session id must return the same sandbox while it exists and is usable. This includes concurrent calls from other processes or deployments, which can race to create it.
164
174
 
165
- `ctx.session.id` is the id of the session that owns the sandbox. For a subagent that shares its parent's sandbox it is the parent's id. `ctx.kind` is `"tool-session"` for a keyed `invokeTool` call's sandbox and `"session"` otherwise.
175
+ Derive the sandbox's native name only from `ctx.session.id` and a provider-level namespace, such as a project or account. Never derive it from the open options or the artifact, which can differ between callers and deployments. Apply them only when `start()` creates the sandbox.
176
+
177
+ `ctx.session.id` is the id of the session the sandbox belongs to. For a subagent that shares its parent's sandbox, it is the parent's id. `ctx.kind` is `"tool-session"` for a keyed `invokeTool` call's sandbox and `"session"` otherwise.
166
178
 
167
179
  ### `resume()`
168
180
 
169
- `resume()` reconnects to the sandbox that `state` names and never recreates it. Open options are not passed to `resume()`, so put anything reconnection needs in the state. When the sandbox no longer exists, throw `SandboxSessionGoneError`: eve clears the session's state and reruns the selector, which starts a fresh sandbox without the lost sandbox's files. Let other failures, such as an outage, surface unchanged.
181
+ `resume()` reconnects to the sandbox that `state` names and never recreates it. It doesn't receive open options, so put anything reconnection needs in the state.
182
+
183
+ When the sandbox no longer exists, throw `SandboxSessionGoneError`. eve then runs the selector again, which starts a fresh sandbox without the lost files. Let other failures, such as an outage, surface unchanged.
170
184
 
171
- Validate the shape of your own state in `resume()`. When you change it incompatibly, raise `stateProtocolVersion` in the provider definition: state recorded under another version starts a fresh sandbox instead of reaching `resume()`.
185
+ Validate the shape of your own state in `resume()`. When you change the shape incompatibly, raise `stateProtocolVersion` in the provider definition. State saved under another version starts a fresh sandbox instead of reaching `resume()`.
172
186
 
173
187
  ### `onSessionEnd()`
174
188
 
175
- `onSessionEnd()` deletes whatever exists for `ctx.session.id`. `state` is `null` when the session never recorded it, for example when only a subagent that shares the sandbox opened it, or when a step failed before its checkpoint, so find the sandbox from the session id. The method must succeed when nothing exists and must be idempotent, because eve retries the cleanup step. eve logs an exhausted failure without replacing the session's outcome.
189
+ `onSessionEnd()` deletes whatever exists for `ctx.session.id`. `state` is `null` when the session never saved it, so find the sandbox from the session id. This happens, for example, when only a subagent opened the shared sandbox, or a step failed before saving state.
190
+
191
+ eve retries cleanup, so `onSessionEnd()` must be safe to repeat and must succeed when nothing exists. When every retry fails, eve logs the failure and the session's outcome doesn't change.
176
192
 
177
- `sandbox.delete()` uses the same method with `reason: "deleted"` and the caller's `signal`, so a provider has one deletion path. A subagent that shares its parent's sandbox never calls it, because cleanup belongs to the parent. An `invokeTool` call without a key calls it when the call ends if the tool requested the sandbox.
193
+ `sandbox.delete()` calls the same method with `reason: "deleted"` and the caller's `signal`. An `invokeTool` call without a key calls it when the call ends, if the tool requested the sandbox. A subagent that shares its parent's sandbox never calls it, because cleanup belongs to the parent.
178
194
 
179
195
  The sets of `reason` and `ctx.kind` values, like other values eve passes into a provider, can grow in a minor release, so handle unknown values instead of switching exhaustively. See [Stability policy](/docs/reference/typescript-api#stability-policy).
180
196
 
181
197
  ## Bake files into templates
182
198
 
183
- Call `ctx.populate(connection)` on the build instance before you capture it. `populate()` writes the agent's workspace files to the connection's workspace root and its skill files to `$HOME/.agents/skills` in one `writeFiles()` batch, then runs the authored `prepare` callback with a session over the same connection. eve finds `$HOME` by running a command through `spawn()`. When the sandbox has no usable home directory, skills go to `skills/` under the workspace root.
199
+ In `prepare()`, call `ctx.populate(connection)` on the build instance before you capture it. `populate()` writes the agent's workspace files to the connection's workspace root and its skill files to `$HOME/.agents/skills` in one `writeFiles()` call. It then runs the authored `prepare` callback over the same connection. eve finds `$HOME` by running a command through `spawn()`. When the sandbox has no usable home directory, skills go to `skills/` under the workspace root.
184
200
 
185
- A provider that can mount host directories can avoid writing every file. `ctx.resourcesDirectory()` resolves to a stable read-only host directory that contains `workspace/` and `skills/`, or to `undefined` when there is none. Mount it in the build instance and pass its sandbox path:
201
+ A provider that can mount host directories can skip writing every file. `ctx.resourcesDirectory()` resolves to a read-only host directory that contains `workspace/` and `skills/`, or to `undefined`. Mount it in the build instance and pass its sandbox path:
186
202
 
187
203
  ```ts
188
204
  const resources = await ctx.resourcesDirectory();
@@ -198,13 +214,17 @@ await ctx.populate(
198
214
 
199
215
  With `mountedAt`, `populate()` copies `<mountedAt>/workspace/.` into the workspace root and `<mountedAt>/skills/.` into `$HOME/.agents/skills` with `cp -a`. When eve has no resource directory, `populate()` ignores `mountedAt` and writes the files instead.
200
216
 
201
- `ctx.templateKey(identity)` returns a SHA-256 hex key that changes whenever `identity`, the workspace files, the skill files, or the sandbox file's source changes. Pass every option that affects the template, such as the base image, and use the key to name or look up a cached template. `identity` accepts JSON values, `undefined` (omitted), plain objects and arrays, and functions (hashed by their source). `resources` and `sourceRevision` are reserved, and eve throws if `identity` sets either one. The source revision covers only the sandbox file, so a `prepare` callback imported from another module does not change the key.
217
+ `ctx.templateKey(identity)` returns a SHA-256 hex key. The key changes whenever `identity`, the workspace files, the skill files, or the sandbox file's source changes. Pass every option that affects the template, such as the base image, and use the key to name or look up a cached template.
202
218
 
203
- Only build time seeds files. A sandbox that `start()` creates gets them from the template, so a provider whose templates cannot hold files cannot provide workspace or skill files.
219
+ - `identity` accepts JSON values, `undefined` (omitted), plain objects and arrays, and functions (hashed by their source).
220
+ - `resources` and `sourceRevision` are reserved, and eve throws if `identity` sets either.
221
+ - Only the sandbox file's own source counts. Changing a `prepare` callback imported from another module doesn't change the key.
222
+
223
+ Only `prepare()` seeds files. A sandbox that `start()` creates gets them from the template, so a provider whose templates can't hold files can't provide workspace or skill files.
204
224
 
205
225
  ## Keep sandboxes for keyed tool calls
206
226
 
207
- Set `toolSessions: true` on the implementation to let keyed `invokeTool` calls keep their sandbox between calls, as Vercel Sandbox and just-bash do. A keyed call does not own its sandbox: eve runs the selector and `start()` on every call, calls `connection.close()` when the call ends, and never calls `onSessionEnd()`. Because nothing ever ends a keyed sandbox, the provider must bound its retention, for example with snapshot expiration.
227
+ Set `toolSessions: true` on the implementation to let keyed `invokeTool` calls keep their sandbox between calls, as Vercel Sandbox and just-bash do. eve runs the selector and `start()` on every keyed call, and calls `connection.close()` when the call ends. eve never calls `onSessionEnd()` for these sandboxes, so the provider must limit how long it keeps them, for example with snapshot expiration.
208
228
 
209
229
  Without `toolSessions`, a keyed call fails when its tool requests the sandbox:
210
230
 
@@ -216,11 +236,11 @@ A keyed call whose tool never requests the sandbox runs normally. See [MCP tool
216
236
 
217
237
  ## Enforce network policy
218
238
 
219
- eve has no built-in network control for custom providers. To offer one, accept a `SandboxNetworkPolicy` from `eve/sandbox` as an open option, as a `setNetworkPolicy()` extension, or both. Reject any part of a policy that the backend cannot enforce instead of weakening it. For example, a backend that can only switch egress on or off accepts `"allow-all"` and `"deny-all"` and throws on allow-lists, subnets, and header transforms, as the Docker provider does.
239
+ eve has no built-in network control for custom providers. To offer one, accept a `SandboxNetworkPolicy` from `eve/sandbox` as an open option, a `setNetworkPolicy()` extension, or both. Reject any part of a policy the backend can't enforce instead of weakening it. The Docker provider, for example, accepts `"allow-all"` and `"deny-all"` and throws on anything else.
220
240
 
221
241
  ## Set environment variables
222
242
 
223
- `SANDBOX_AGENT_ENV` is `{ AI_AGENT: "eve" }`, which tells agent-aware CLIs to skip interactive prompts. Apply it beneath your environment-level variables when you create the sandbox, as the built-in providers do. A per-call `env` passed to `spawn()` overrides both. If the backend has no sandbox-level environment, merge it beneath the per-call `env` in `spawn()` instead, as in `{ ...SANDBOX_AGENT_ENV, ...env }`.
243
+ `SANDBOX_AGENT_ENV` is `{ AI_AGENT: "eve" }`, which tells agent-aware CLIs to skip interactive prompts. Apply it beneath your environment-level variables when you create the sandbox, as the built-in providers do. A per-call `env` passed to `spawn()` overrides both. If the backend has no sandbox-level environment, merge it in `spawn()` instead: `{ ...SANDBOX_AGENT_ENV, ...env }`.
224
244
 
225
245
  ## Report missing templates
226
246
 
@@ -236,20 +256,4 @@ throw new SandboxTemplateNotProvisionedError({
236
256
  });
237
257
  ```
238
258
 
239
- eve surfaces the error to the caller and never retries or rebuilds the template at runtime. eve throws the same error when a deployment has no artifact for the sandbox. Template retention and pruning stay with the provider. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#sandbox-template--is-not-available-to-this-runtime).
240
-
241
- ## Migrate from the handle-based API
242
-
243
- Earlier releases asked a provider to return a handle with a complete sandbox session. To move a provider to the current API:
244
-
245
- - Return `{ connection, state }` from `start()` and a connection from `resume()`, instead of a handle. Move provider-specific session methods to `extensions`.
246
- - Remove `onSandboxStop()` and `onRuntimeShutdown()`; implement `connection.stop()`. Move `onSandboxDelete()` into `onSessionEnd()`, which receives `reason: "deleted"`.
247
- - Replace hashes of `ctx.resources` and `ctx.sourceRevision` with `ctx.templateKey()`, and replace writes of resource files plus your own `prepare` call with `ctx.populate()`. Remove `prepare` from your environment options; eve owns it.
248
- - Replace `ctx.host.resolveProjectPath()` with `ctx.resolveProjectPath()`. `ctx.host.loadOptionalPackage()` is no longer available; import your SDK directly.
249
- - Drop the explicit type arguments to `defineSandboxProvider()` and let TypeScript infer them. `environment()` now receives `{}` instead of `undefined` when the sandbox file passes no options.
250
- - Rename `SandboxPreparedArtifact` to `SandboxJson`, `SandboxProviderSessionContext` to `SandboxSessionContext`, and `SandboxProviderPrepareContext` to `SandboxPrepareContext`. `SandboxProviderHandle`, `SandboxProviderResources`, `SandboxProviderResourceTree`, `SandboxProviderResourceFile`, `SandboxProviderResourceSource`, and `SandboxProviderTargetFile` are removed.
251
-
252
- Two changes in `eve/sandbox` also affect code outside providers:
253
-
254
- - `SandboxSession` has a required `writeFiles()` method, so an object you build by hand as a `SandboxSession`, such as a test double, needs one.
255
- - `SandboxNetworkPolicy` is an eve-owned type with `readonly` members instead of the Vercel Sandbox SDK's `NetworkPolicy`. Code that passes a policy to the SDK directly needs its own conversion.
259
+ eve returns the error to the caller and never retries or rebuilds the template at runtime. eve throws the same error when a deployment has no artifact for the sandbox. The provider decides how long to keep templates and when to delete them. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#sandbox-template--is-not-available-to-this-runtime).