eve 0.86.0 → 0.87.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 (261) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +1 -1
  3. package/dist/src/acp/adapter.d.ts +2 -26
  4. package/dist/src/acp/adapter.js +1 -1
  5. package/dist/src/acp/server.d.ts +0 -3
  6. package/dist/src/ai/decision-adapter.d.ts +5 -3
  7. package/dist/src/ai/decision-adapter.js +1 -1
  8. package/dist/src/ai/decision-types.d.ts +4 -3
  9. package/dist/src/channel/adapter.d.ts +0 -14
  10. package/dist/src/channel/auth/definitions.d.ts +0 -4
  11. package/dist/src/channel/channel-address.d.ts +1 -1
  12. package/dist/src/channel/channel-address.js +1 -1
  13. package/dist/src/channel/channel-operations.d.ts +2 -2
  14. package/dist/src/channel/channel-operations.js +1 -1
  15. package/dist/src/channel/prompt-queue.d.ts +0 -2
  16. package/dist/src/channel/session-not-active-error.d.ts +10 -5
  17. package/dist/src/channel/session-not-active-error.js +1 -1
  18. package/dist/src/channel/session-stranded-error.d.ts +1 -1
  19. package/dist/src/channel/session.d.ts +3 -4
  20. package/dist/src/channel/session.js +1 -1
  21. package/dist/src/channel/types.d.ts +5 -14
  22. package/dist/src/chunks/{use-eve-agent-B2jCfcnG.js → use-eve-agent-BExXjBv6.js} +82 -72
  23. package/dist/src/chunks/{use-eve-agent-DCLFi26P.js → use-eve-agent-C0KHCyb9.js} +82 -72
  24. package/dist/src/cli/dev/command-options.d.ts +4 -4
  25. package/dist/src/cli/dev/command.js +1 -1
  26. package/dist/src/cli/dev/tui/runner.js +1 -1
  27. package/dist/src/cli/dev/tui/test/fake-eve-server.js +1 -1
  28. package/dist/src/cli/dev/tui/tool-format.d.ts +2 -2
  29. package/dist/src/cli/dev/ui-options.d.ts +4 -4
  30. package/dist/src/cli/dev/ui-options.js +1 -1
  31. package/dist/src/client/agent-info-error.d.ts +4 -1
  32. package/dist/src/client/agent-info-error.js +1 -1
  33. package/dist/src/client/agent-session.d.ts +1 -4
  34. package/dist/src/client/agent-session.js +1 -1
  35. package/dist/src/client/agent-stream-follower.js +1 -1
  36. package/dist/src/client/client-error.d.ts +13 -4
  37. package/dist/src/client/client-error.js +1 -1
  38. package/dist/src/client/delivery.d.ts +2 -17
  39. package/dist/src/client/health-response-error.d.ts +4 -1
  40. package/dist/src/client/health-response-error.js +1 -1
  41. package/dist/src/client/index.d.ts +5 -3
  42. package/dist/src/client/index.js +1 -1
  43. package/dist/src/client/open-stream.d.ts +7 -12
  44. package/dist/src/client/open-stream.js +1 -1
  45. package/dist/src/client/session-controls.d.ts +2 -2
  46. package/dist/src/client/session-controls.js +1 -1
  47. package/dist/src/client/session-event-stream.d.ts +2 -2
  48. package/dist/src/client/session-event-stream.js +1 -1
  49. package/dist/src/client/session-store.d.ts +2 -6
  50. package/dist/src/client/session-store.js +1 -1
  51. package/dist/src/client/session.d.ts +4 -13
  52. package/dist/src/client/session.js +1 -1
  53. package/dist/src/client/sessions.d.ts +3 -6
  54. package/dist/src/client/types.d.ts +23 -32
  55. package/dist/src/compiled/.vendor-stamp.json +3 -3
  56. package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
  57. package/dist/src/compiler/manifest.js +1 -1
  58. package/dist/src/compiler/normalize-agent-config.js +1 -1
  59. package/dist/src/compiler/normalize-connection.d.ts +1 -1
  60. package/dist/src/compiler/normalize-connection.js +1 -1
  61. package/dist/src/compiler/normalize-instructions.js +1 -1
  62. package/dist/src/compiler/normalize-skill.js +1 -1
  63. package/dist/src/compiler/resolve-workspace-subagent.js +1 -1
  64. package/dist/src/context/memory-tools.d.ts +9 -5
  65. package/dist/src/discover/sandbox.js +1 -1
  66. package/dist/src/dynamic/definition.d.ts +11 -5
  67. package/dist/src/dynamic/definition.js +1 -1
  68. package/dist/src/evals/mock-model.d.ts +1 -1
  69. package/dist/src/evals/session-manager.d.ts +0 -2
  70. package/dist/src/evals/session.d.ts +1 -11
  71. package/dist/src/evals/session.js +1 -1
  72. package/dist/src/eve-channel/index.js +1 -1
  73. package/dist/src/eve-channel/support.js +1 -1
  74. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  75. package/dist/src/execution/effective-agent-config.js +1 -1
  76. package/dist/src/execution/sandbox/bindings/just-bash-runtime.d.ts +1 -2
  77. package/dist/src/execution/sandbox/bindings/just-bash-runtime.js +1 -1
  78. package/dist/src/execution/sandbox/bindings/just-bash.js +1 -1
  79. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  80. package/dist/src/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  81. package/dist/src/instrumentation/providers.d.ts +1 -38
  82. package/dist/src/instrumentation/providers.js +1 -1
  83. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  84. package/dist/src/internal/application/package.d.ts +1 -0
  85. package/dist/src/internal/application/package.js +1 -1
  86. package/dist/src/internal/application/stamped-package-version.js +1 -1
  87. package/dist/src/internal/authored-definition/core.js +1 -1
  88. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  89. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  90. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  91. package/dist/src/internal/runtime-model.d.ts +9 -4
  92. package/dist/src/internal/runtime-model.js +1 -1
  93. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  94. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  95. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  96. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  97. package/dist/src/models/auto.js +1 -1
  98. package/dist/src/protocol/delivery.d.ts +1 -0
  99. package/dist/src/protocol/reset-session.d.ts +0 -2
  100. package/dist/src/protocol/routes.d.ts +9 -2
  101. package/dist/src/protocol/routes.js +1 -1
  102. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  103. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  104. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  105. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  106. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  107. package/dist/src/public/channels/github/state.d.ts +0 -2
  108. package/dist/src/public/channels/index.d.ts +1 -2
  109. package/dist/src/public/channels/index.js +1 -1
  110. package/dist/src/public/channels/linear/index.d.ts +1 -1
  111. package/dist/src/public/channels/linear/index.js +1 -1
  112. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  113. package/dist/src/public/channels/linq/index.d.ts +1 -1
  114. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  115. package/dist/src/public/channels/photon/index.d.ts +1 -1
  116. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  117. package/dist/src/public/channels/slack/api.d.ts +1 -1
  118. package/dist/src/public/channels/slack/api.js +1 -1
  119. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  120. package/dist/src/public/channels/slack/blocks.js +2 -2
  121. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  122. package/dist/src/public/channels/slack/cards.js +1 -1
  123. package/dist/src/public/channels/slack/index.d.ts +2 -2
  124. package/dist/src/public/channels/slack/index.js +1 -1
  125. package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
  126. package/dist/src/public/channels/slack/session-operations.js +1 -1
  127. package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
  128. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  129. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  130. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  131. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  132. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  133. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  134. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  135. package/dist/src/public/definitions/agent.d.ts +15 -7
  136. package/dist/src/public/definitions/agent.js +1 -1
  137. package/dist/src/public/definitions/channel.d.ts +7 -5
  138. package/dist/src/public/definitions/channel.js +1 -1
  139. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  140. package/dist/src/public/definitions/connections/protocol.js +1 -1
  141. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  142. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  143. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  144. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  145. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  146. package/dist/src/public/experimental/workspace/index.js +1 -0
  147. package/dist/src/public/index.d.ts +2 -2
  148. package/dist/src/public/index.js +1 -1
  149. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  150. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  151. package/dist/src/public/instrumentation/provider.js +1 -1
  152. package/dist/src/public/memory/file/backend.d.ts +1 -1
  153. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  154. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  155. package/dist/src/public/memory/file/provider.js +1 -1
  156. package/dist/src/public/memory/index.d.ts +3 -11
  157. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  158. package/dist/src/public/models/index.d.ts +1 -0
  159. package/dist/src/public/models/openai/index.d.ts +2 -2
  160. package/dist/src/public/next/index.d.ts +2 -2
  161. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  162. package/dist/src/public/sandbox/just-bash.d.ts +0 -1
  163. package/dist/src/public/sessions/index.d.ts +1 -0
  164. package/dist/src/public/sessions/index.js +1 -1
  165. package/dist/src/public/tools/index.d.ts +1 -1
  166. package/dist/src/public/tools/index.js +1 -1
  167. package/dist/src/public/workflow/api.d.ts +25 -0
  168. package/dist/src/public/workflow/api.js +1 -0
  169. package/dist/src/public/workflow/index.d.ts +76 -0
  170. package/dist/src/public/workflow/index.js +1 -0
  171. package/dist/src/public/workflow-modules.d.ts +2 -17
  172. package/dist/src/react/use-eve-agent.d.ts +3 -2
  173. package/dist/src/react/use-eve-agent.js +1 -1
  174. package/dist/src/reactions/kinds/model.js +1 -1
  175. package/dist/src/runtime/agent/resolve-model.js +1 -1
  176. package/dist/src/runtime/resolve-agent.js +1 -1
  177. package/dist/src/runtime/resolve-dynamic.js +1 -1
  178. package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
  179. package/dist/src/runtime/subagents/workflow.js +1 -1
  180. package/dist/src/sandbox/providers/default.js +1 -1
  181. package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
  182. package/dist/src/self-modification/sandbox.js +1 -1
  183. package/dist/src/setup/integrations/discord/daemon.js +2 -2
  184. package/dist/src/setup/scaffold/create/project.js +2 -2
  185. package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
  186. package/dist/src/setup/scaffold/create/web-template.js +2 -2
  187. package/dist/src/setup/verified-remote-agent.d.ts +1 -3
  188. package/dist/src/shared/agent-definition.d.ts +18 -9
  189. package/dist/src/shared/eve-error.d.ts +22 -0
  190. package/dist/src/shared/eve-error.js +1 -0
  191. package/dist/src/shared/session.d.ts +2 -2
  192. package/dist/src/shared/token-usage.d.ts +7 -1
  193. package/dist/src/svelte/index.js +1 -1
  194. package/dist/src/svelte/use-eve-agent.d.ts +2 -1
  195. package/dist/src/svelte/use-eve-agent.js +1 -1
  196. package/dist/src/tools/definition.d.ts +7 -5
  197. package/dist/src/tools/definition.js +1 -1
  198. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  199. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  200. package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
  201. package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
  202. package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
  203. package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
  204. package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
  205. package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
  206. package/dist/src/tracing/local/traces.d.ts +0 -13
  207. package/dist/src/vue/index.js +1 -1
  208. package/dist/src/vue/use-eve-agent.d.ts +3 -2
  209. package/dist/src/vue/use-eve-agent.js +1 -1
  210. package/docs/agent-config.md +15 -11
  211. package/docs/channels/custom.mdx +26 -10
  212. package/docs/channels/discord.mdx +10 -10
  213. package/docs/channels/eve.mdx +14 -8
  214. package/docs/channels/linear.mdx +11 -0
  215. package/docs/channels/linq.mdx +5 -1
  216. package/docs/channels/photon.mdx +6 -1
  217. package/docs/channels/slack.mdx +73 -14
  218. package/docs/channels/telegram.mdx +6 -0
  219. package/docs/code-extension.mdx +25 -0
  220. package/docs/concepts/default-harness.md +2 -2
  221. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  222. package/docs/concepts/security-model.md +2 -2
  223. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  224. package/docs/concepts/upgrade-to-v27-events.md +2 -1
  225. package/docs/connections/overview.mdx +4 -0
  226. package/docs/evals/reporters.mdx +21 -0
  227. package/docs/extensions.md +12 -0
  228. package/docs/getting-started.mdx +5 -1
  229. package/docs/guides/auth-and-route-protection.md +1 -1
  230. package/docs/guides/client/continuations.mdx +12 -10
  231. package/docs/guides/client/messages.mdx +24 -1
  232. package/docs/guides/client/overview.mdx +8 -6
  233. package/docs/guides/client/streaming.mdx +24 -6
  234. package/docs/guides/decide.md +3 -3
  235. package/docs/guides/deployment/vercel.mdx +1 -1
  236. package/docs/guides/dev-tui.md +2 -2
  237. package/docs/guides/frontend/overview.mdx +1 -1
  238. package/docs/guides/frontend/use-eve-agent-svelte.mdx +13 -11
  239. package/docs/guides/frontend/use-eve-agent-vue.mdx +13 -11
  240. package/docs/guides/frontend/use-eve-agent.mdx +4 -4
  241. package/docs/guides/instrumentation/otel.mdx +3 -1
  242. package/docs/guides/prepare-for-1-0.md +255 -0
  243. package/docs/guides/remote-agents.md +22 -20
  244. package/docs/instructions.mdx +1 -1
  245. package/docs/memory/custom-provider.md +1 -1
  246. package/docs/memory/file.md +11 -2
  247. package/docs/meta.json +1 -0
  248. package/docs/reference/agent-files.md +17 -17
  249. package/docs/reference/cli.md +14 -9
  250. package/docs/reference/typescript-api.md +46 -20
  251. package/docs/sandbox/custom-providers.mdx +2 -0
  252. package/docs/sandbox/default.mdx +6 -6
  253. package/docs/sandbox/index.mdx +5 -5
  254. package/docs/sandbox/just-bash.mdx +30 -21
  255. package/docs/subagents/index.mdx +4 -4
  256. package/docs/tools/human-in-the-loop.md +1 -1
  257. package/docs/tools/workflows.mdx +52 -8
  258. package/docs/tutorial/first-agent.mdx +1 -1
  259. package/package.json +36 -9
  260. package/dist/CHANGELOG.md +0 -38
  261. package/dist/src/public/channels/discord/gateway/index.js +0 -1
@@ -20,15 +20,15 @@ export default defineRemoteAgent({
20
20
 
21
21
  `defineRemoteAgent` accepts:
22
22
 
23
- | Parameter | Type | Required | Default | Description |
24
- | ------------------ | ----------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
25
- | `url` | `string` | Yes | n/a | Base URL of the remote eve deployment. Compute runtime URLs in a dynamic definition (see [Runtime URLs](#runtime-urls)). |
26
- | `description` | `string` | Yes | n/a | Model-visible delegation description. |
27
- | `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
28
- | `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
29
- | `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
30
- | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
31
- | `tool` | `boolean \| "deferred"` | No | `true` | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools. |
23
+ | Parameter | Type | Required | Default | Description |
24
+ | ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Use a function for [runtime URLs](#runtime-urls). |
26
+ | `description` | `string` | Yes | n/a | Model-visible delegation description. |
27
+ | `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
28
+ | `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
29
+ | `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
30
+ | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
31
+ | `tool` | `boolean \| "deferred"` | No | `true` | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools. |
32
32
 
33
33
  ## Dynamic remote agents
34
34
 
@@ -71,7 +71,7 @@ export default defineDynamic((ctx) => {
71
71
  ```
72
72
 
73
73
  A child keeps the parent context and memo results used to select its remote configuration.
74
- Later messages, answers, cancellation, reset, and stream reads use that original selection when
74
+ Later messages, answers, cancellation, session retirement, and stream reads use that original selection when
75
75
  rebuilding transport credentials. Only saved memo results are available: a missing result or a
76
76
  changed child name or URL fails before credentials are sent. `ctx.messages()` is unavailable
77
77
  during this reconstruction, including when eve opens the child; keep conversation-based
@@ -81,20 +81,22 @@ selection inside a memo. This does not change the per-message caller identity de
81
81
 
82
82
  ## Runtime URLs
83
83
 
84
- A static `url` is read at compile time. When an environment variable supplies the URL only at runtime, compute it inside `defineDynamic`:
84
+ A string `url` is read at compile time. Use a function when an environment variable
85
+ supplies the URL only at runtime. eve invokes it when resolving the runtime agent graph;
86
+ it can return a string or a promise:
85
87
 
86
88
  ```ts title="agent/subagents/weather.ts"
87
- import { defineDynamic, defineRemoteAgent } from "eve";
89
+ import { defineRemoteAgent } from "eve";
88
90
 
89
- export default defineDynamic(() =>
90
- defineRemoteAgent({
91
- url: process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
92
- description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
93
- }),
94
- );
91
+ export default defineRemoteAgent({
92
+ url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
93
+ description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
94
+ });
95
95
  ```
96
96
 
97
- `url` must be a non-empty string. `auth` and `headers` remain lazy callbacks resolved per request.
97
+ The resolved `url` must be a non-empty string. Use `defineDynamic` when the current
98
+ session determines which agent is exposed or whether it is available.
99
+ `auth` and `headers` remain lazy callbacks resolved per request.
98
100
 
99
101
  ## Calling a remote agent
100
102
 
@@ -236,7 +238,7 @@ Clients follow a remote child through the parent. [`session.agent(opened).stream
236
238
 
237
239
  Cancelling the parent turn or the agent task with `eve__task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.settled` with `outcome: "cancelled"` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
238
240
 
239
- When the workflow run that opened a remote child finishes, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for it. An agent task's run finishes when the parent session ends. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
241
+ When the workflow run that opened a remote child finishes, eve sends an authenticated request to end it. An agent task's run finishes when the parent session ends. Ending retires the parked remote session and recursively cleans up its descendants. Parent cleanup retains its earlier wire path so independently deployed parents and children can run different eve versions. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
240
242
 
241
243
  The parent names its remote agent protocol version when it creates the child, and the remote
242
244
  answers with the version it serves. This release serves protocols 2 and 3. A protocol-3 parent
@@ -82,7 +82,7 @@ See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failu
82
82
 
83
83
  ## History controls and prompt caching
84
84
 
85
- [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-reset) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
85
+ [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-end) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
86
86
 
87
87
  Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix. Framework announcements about available skills and parked agents are retained in user-role history: changed snapshots append after earlier steps instead of replacing the context sent with those steps. Unchanged announcements are skipped until history is cleared or compacted. eve does not promise a cache hit.
88
88
 
@@ -148,7 +148,7 @@ context. The `id` also identifies the record in
148
148
 
149
149
  ### Tools
150
150
 
151
- `tools()` returns a map of `defineTool()` values or `null`. eve qualifies each
151
+ `tools()` returns a `MemoryToolSet`, a map of `defineTool()` values, or `null`. eve qualifies each
152
152
  key as `<slot>__<key>`; the qualified name must start with a letter, contain
153
153
  only letters, digits, underscores, or dashes, and be at most 64 characters.
154
154
  Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for
@@ -159,11 +159,13 @@ import { MemoryDocumentConflictError, type MemoryDocumentBackend } from "eve/mem
159
159
 
160
160
  export function kvBackend(store: KvStore): MemoryDocumentBackend {
161
161
  return {
162
- async read({ key }) {
162
+ async read({ key, signal }) {
163
+ signal.throwIfAborted();
163
164
  const row = await store.get(key);
164
165
  return row ? { content: row.content, version: row.version } : null;
165
166
  },
166
- async write({ key, content, expectedVersion }) {
167
+ async write({ key, content, expectedVersion, signal }) {
168
+ signal.throwIfAborted();
167
169
  const ok = await store.compareAndSet(key, content, expectedVersion);
168
170
  if (!ok) throw new MemoryDocumentConflictError(key);
169
171
  return { content, version: await store.version(key) };
@@ -176,6 +178,13 @@ export function kvBackend(store: KvStore): MemoryDocumentBackend {
176
178
  `MemoryDocumentConflictError` when `expectedVersion` no longer matches. An
177
179
  `expectedVersion` of `null` means the document must not exist yet.
178
180
 
181
+ Both methods receive a `signal: AbortSignal`. Check it before starting work and
182
+ pass it to storage operations that support cancellation. When upgrading from
183
+ `eve@0.84.x`, rename the backend input's `abortSignal` property to `signal`.
184
+ Backends written for `0.83.x` or earlier already use `signal` and need no change.
185
+ Memory and tool execution contexts still expose `ctx.abortSignal`; pass that
186
+ value as the backend's `signal`.
187
+
179
188
  A backend changes only where the document is stored. It does not change file
180
189
  memory's recall format or tools. When you need different retrieval, capture, or
181
190
  tools, [build a memory provider](./custom-provider) instead.
package/docs/meta.json CHANGED
@@ -31,6 +31,7 @@
31
31
  "evals",
32
32
  "guides/instrumentation",
33
33
  "---Reference---",
34
+ "guides/prepare-for-1-0",
34
35
  "guides/dev-tui",
35
36
  "guides/self-modification",
36
37
  "...reference",
@@ -46,23 +46,23 @@ A standalone root agent uses its package name (without an npm scope), or its app
46
46
 
47
47
  Paths below are relative to the agent directory. Root agents can use every path; subagents can use paths marked **Yes**.
48
48
 
49
- | Path | Purpose | Available to subagents | Notes |
50
- | ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
51
- | `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](/docs/agent-config). |
52
- | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Yes | A flat file or directory of `.md` and `.ts` files. Required on the root, optional on subagents. See [Instructions](/docs/instructions). |
53
- | `instrumentation/` | Telemetry providers and destinations | No | One path-named provider per file. See [Instrumentation](/docs/observability/instrumentation). |
54
- | `channels/` | HTTP and messaging entry points | No | See [Channels](/docs/channels/overview). |
55
- | `connections/` | External MCP and OpenAPI services | Yes | Static files define path-named connections; dynamic sources can resolve caller-specific connections. |
56
- | `extensions/` | Mounted reusable capabilities | Yes | File or directory mounts. See [Extensions](/docs/extensions). |
57
- | `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only; recursive directories are supported. |
58
- | `skills/` | On-demand procedures and capability packs | Yes | Flat Markdown, module-backed skills, or packaged skills. |
59
- | `lib/` | Shared authored helper code | Yes | Import-only; not copied into the sandbox. Helpers can import data files such as JSON from here. |
60
- | `memory.ts` or `memory/<name>.ts` | Cross-session memory | Yes | Provider-backed slots. See [Memory](/docs/memory). |
61
- | `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. When `sandbox/` exists, only `sandbox/sandbox.ts` is read. |
62
- | `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Copied into the prepared environment; each new session sandbox starts with them in the workspace root. |
63
- | `tools/` | Typed executable integrations | Yes | Module-backed only. |
64
- | `schedules/` | Recurring jobs | No | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported. |
65
- | `subagents/` | Specialist child agents | Yes | Local directories or remote-agent definitions; nested subagents are supported. |
49
+ | Path | Purpose | Available to subagents | Notes |
50
+ | ------------------------------------------------------- | ----------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
51
+ | `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](/docs/agent-config). |
52
+ | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Yes | A flat file or directory of `.md` and `.ts` files. Required on the root, optional on subagents. See [Instructions](/docs/instructions). |
53
+ | `instrumentation/` | Telemetry providers and destinations | No | One path-named provider per file. See [Instrumentation](/docs/observability/instrumentation). |
54
+ | `channels/` | HTTP and messaging entry points | No | See [Channels](/docs/channels/overview). |
55
+ | `connections/` | External MCP and OpenAPI services | Yes | Static files define path-named connections; dynamic sources can resolve caller-specific connections. |
56
+ | `extensions/` | Mounted reusable capabilities | Yes | File or directory mounts. See [Extensions](/docs/extensions). |
57
+ | `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only; recursive directories are supported. |
58
+ | `skills/` | On-demand procedures and capability packs | Yes | Flat Markdown, module-backed skills, or packaged skills. |
59
+ | `lib/` | Shared authored helper code | Yes | Import-only; not copied into the sandbox. Helpers can import data files such as JSON from here. |
60
+ | `memory.ts` or `memory/<name>.ts` | Cross-session memory | Yes | Provider-backed slots. See [Memory](/docs/memory). |
61
+ | `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. When `sandbox/` exists, use `sandbox/sandbox.ts`; a root `sandbox.ts` beside that folder is an error. |
62
+ | `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Copied into the prepared environment; each new session sandbox starts with them in the workspace root. |
63
+ | `tools/` | Typed executable integrations | Yes | Module-backed only. |
64
+ | `schedules/` | Recurring jobs | No | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported. |
65
+ | `subagents/` | Specialist child agents | Yes | Local directories or remote-agent definitions; nested subagents are supported. |
66
66
 
67
67
  ## Colocated tests
68
68
 
@@ -51,11 +51,13 @@ Existing packages do not need a target-selection prompt: run `eve init` from the
51
51
 
52
52
  After scaffolding in an interactive human terminal, eve opens the TUI directly. Pass `-n` or `--non-interactive` to return after scaffolding instead. It still installs dependencies and follows the normal Git setup behavior. Noninteractive and coding-agent invocations return without starting an interactive session. Fresh projects use the parent workspace's package manager when there is one; otherwise they use the manager that launched `eve init`.
53
53
 
54
- | Flag | Type | Default | Description |
55
- | ----------------------- | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
56
- | `--model <model>` | string | `openai/gpt-6-luna-fast` | Set the root agent's AI Gateway model ID. |
57
- | `--reasoning <effort>` | enum | `high` without `--model`; otherwise provider default | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
58
- | `-n, --non-interactive` | flag | off | Scaffold and install dependencies without starting development. |
54
+ | Flag | Type | Default | Description |
55
+ | ----------------------- | ------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
56
+ | `--model <model>` | string | `openai/gpt-6-luna-fast` | Set the root agent's AI Gateway model ID. |
57
+ | `--reasoning <effort>` | enum | `high` without `--model`; otherwise provider default | Set reasoning to `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `provider-default` leaves the field unauthored. |
58
+ | `--agents <names>` | string | unset | Create a new workspace with comma-separated agent names, such as `support,research`, or add members to an existing workspace. |
59
+ | `-y, --yes` | flag | off | Accepted for compatibility; warns and has no effect. |
60
+ | `-n, --non-interactive` | flag | off | Scaffold and install dependencies without starting development. |
59
61
 
60
62
  ## `eve extension`
61
63
 
@@ -76,6 +78,7 @@ Creates a new extension package, installs dependencies, and initializes Git. Pri
76
78
  | No target | Same as `.` for humans; coding agents get a short setup guide |
77
79
 
78
80
  Create-only: cannot target an existing project that already has a `package.json`.
81
+ `-y` and `--yes` are accepted for compatibility; they warn and have no effect.
79
82
 
80
83
  See [Extensions](/docs/extensions) for authoring and mount details.
81
84
 
@@ -278,10 +281,10 @@ Starts a local development server and terminal UI. To connect the UI to an exist
278
281
  | `--no-default-extensions` | flag | extensions on | Do not mount bundled development extensions |
279
282
  | `--name <name>` | string | app folder name | Title shown in the terminal UI |
280
283
  | `--input <text>` | string | none | Pre-fill the prompt input |
281
- | `--tools <mode>` | enum | `auto-collapsed` | Tool-call rendering |
282
- | `--reasoning <mode>` | enum | `full` | Reasoning rendering |
283
- | `--subagents <mode>` | enum | `collapsed` | Subagent task rendering: `full`, `collapsed`, or `hidden` |
284
- | `--connection-auth <mode>` | enum | `full` | Connection-authorization rendering |
284
+ | `--show-tools <mode>` | enum | `auto-collapsed` | Tool-call rendering |
285
+ | `--show-reasoning <mode>` | enum | `auto-collapsed` | Reasoning rendering |
286
+ | `--show-subagents <mode>` | enum | `collapsed` | Subagent task rendering: `full`, `collapsed`, or `hidden` |
287
+ | `--show-connection-auth <mode>` | enum | `full` | Connection-authorization rendering |
285
288
  | `--assistant-response-stats <mode>` | enum | `tokensPerSecond` | Assistant header statistic |
286
289
  | `--context-size <tokens>` | number | none | Model context window size |
287
290
  | `--logs <mode>` | enum | `error` | Display `none`, `error`, `warn`, `debug`, or `all` logs |
@@ -341,6 +344,8 @@ eve remote connect --url <url> --print <prompt> [-H "Name: value"]
341
344
 
342
345
  Without `--print`, `connect` requires a terminal and opens the interactive UI. Pass `--print` and a prompt to send one message without a terminal UI. eve writes only the final assistant text to stdout, then exits. It writes errors to stderr and exits nonzero if the turn fails, is cancelled, needs input or authorization, or the stream ends before the turn settles. The error includes the session ID when the server has accepted the message. `--print` starts a new conversation each time and does not answer pending requests; to answer that session's pending request or script multi-turn sessions, use the `eve/client` API. `--input` only pre-fills the interactive UI and cannot be used with `--print`.
343
346
 
347
+ Interactive `connect` accepts the same display flags as [`eve dev`](#eve-dev): `--show-tools`, `--show-reasoning`, `--show-subagents`, `--show-connection-auth`, `--assistant-response-stats`, `--context-size`, and `--logs`. The `--show-*` flags control rendering, not model reasoning effort. Set effort with `eve set model --reasoning <effort>` or `eve init --reasoning <effort>`.
348
+
344
349
  Use `-H, --header <header>` for a bearer token or another custom request header; repeat it for multiple headers. For HTTP Basic authentication, put credentials in the URL. eve sends them as a Basic `Authorization` header and removes them from the target URL.
345
350
 
346
351
  ### `eve remote info`
@@ -5,6 +5,8 @@ description: "The define* helpers, the runtime ctx, and where each one is import
5
5
 
6
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.
7
7
 
8
+ For changes to an existing application, follow [Prepare for 1.0](../guides/prepare-for-1-0).
9
+
8
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`.
9
11
 
10
12
  Most files look the same: import a helper, default-export the result.
@@ -33,18 +35,18 @@ export default defineTool({
33
35
  Install the framework packages for the integration you import. These are optional peers of eve;
34
36
  using another entry does not require them.
35
37
 
36
- | Entry | Required integration packages |
37
- | ------------------------------------------ | ----------------------------------------------------- |
38
- | `eve/react` | `react` 19 (and its React typings in TypeScript apps) |
39
- | `eve/vue` | `vue` 3.5 or later in v3 |
40
- | `eve/svelte` | `svelte` 5 |
41
- | `eve/next` | `next` 16 and `react` 19 |
42
- | `eve/sveltekit`, `eve/tanstack` | `vite` 8.3.1 or later in v8 |
43
- | `eve/nuxt` | `@nuxt/kit` 4 and `@nuxt/schema` 4 |
44
- | Chat SDK, Linq, and Photon channels | `chat` 4.42 or later in v4 |
45
- | `eve/channels/linq` | Also `@linqapp/sdk` 0.47.1 or later in v0.47 |
46
- | `eve/sandbox/just-bash` | `just-bash` 3.6 or later in v3 |
47
- | `@vercel/connect/eve` with eve connections | `@vercel/connect` 2.5.2 or later in v2 |
38
+ | Entry | Required integration packages |
39
+ | ------------------------------------------------------------- | ----------------------------------------------------- |
40
+ | `eve/react` | `react` 19 (and its React typings in TypeScript apps) |
41
+ | `eve/vue` | `vue` 3.5 or later in v3 |
42
+ | `eve/svelte` | `svelte` 5 |
43
+ | `eve/next` | `next` 16 and `react` 19 |
44
+ | `eve/sveltekit`, `eve/tanstack` | `vite` 8.3.1 or later in v8 |
45
+ | `eve/nuxt` | `@nuxt/kit` 4 and `@nuxt/schema` 4 |
46
+ | Chat SDK, Linq, and Photon channels | `chat` 4.42 or later in v4 |
47
+ | `eve/channels/linq` | Also `@linqapp/sdk` 0.47.1 or later in v0.47 |
48
+ | `eve/sandbox/just-bash`, `eve/experimental/sandbox/just-bash` | `just-bash` 3.6 or later in v3 |
49
+ | `@vercel/connect/eve` with eve connections | `@vercel/connect` 2.5.2 or later in v2 |
48
50
 
49
51
  Connections with `experimental.events` require a static Connect auth provider with its events bridge.
50
52
  SDK-backed handles use the SDK classes installed in your app, not copies bundled with eve.
@@ -137,7 +139,7 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
137
139
 
138
140
  | Import | Holds |
139
141
  | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
140
- | `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |
142
+ | `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types, `TokenUsage` |
141
143
  | `eve/tools` | `defineTool`, `defineWorkflowTool`, `defineDynamic`, `disableTool`, tool types |
142
144
  | `eve/tools/{bash,read_file,write_file,web_fetch,glob,grep}` | Individual reusable tool definitions |
143
145
  | `eve/tools/approval` | Approval types and `auto`, `always`, `once`, `never` |
@@ -146,6 +148,8 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
146
148
  | `eve/tools/workflow` | Runtime-generated `workflow` tool factory |
147
149
  | `eve/tools/sleep` | Opt-in durable `sleep` tool |
148
150
  | `eve/tools/no_reply` | Opt-in `noReply` tool definition |
151
+ | [`eve/workflow`](../tools/workflows#workflow-imports) | Durable `createHook`, `createWebhook`, `sleep`, `FatalError`, `RetryableError`, `getWorkflowMetadata`, hook types |
152
+ | [`eve/workflow/api`](../tools/workflows#workflow-imports) | `start`, `getRun`, `resumeHook`, `WorkflowRun`, and `WorkflowRunStatus` for routes and steps |
149
153
  | `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic` |
150
154
  | `eve/channels` | `defineChannel`, `disableRoute`, route verbs, `isChannel`, channel metadata types |
151
155
  | `eve/channels/eve` | `eveChannel` |
@@ -166,9 +170,9 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
166
170
  | [`eve/sandbox/vercel`](../sandbox/vercel) | `VercelSandbox` and Vercel environment, session, and mount types |
167
171
  | [`eve/sandbox/just-bash`](../sandbox/just-bash) | `JustBashSandbox` and just-bash environment types |
168
172
  | `eve/instrumentation` | `defineInstrumentation`, `disableInstrumentation`, `InstrumentationEvent<K>`, lifecycle provider types |
169
- | `eve/instrumentation/otel` | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types |
173
+ | `eve/instrumentation/otel` | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy, span processor, and exporter types |
170
174
  | `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |
171
- | [`eve/models`](../guides/decide) | Automatic model selection with `auto` |
175
+ | [`eve/models`](../guides/decide) | Automatic model selection with `auto`, `EveLanguageModel` |
172
176
  | `eve/models/openai` | `openai`, `chatgpt` |
173
177
  | `eve/models/anthropic` | `anthropic` |
174
178
  | [`eve/ai`](../guides/decide#decide-inside-a-tool) | Standalone `decide` |
@@ -178,8 +182,8 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
178
182
  | `eve/evals/loaders` | `loadJson`, `loadYaml` |
179
183
  | `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
180
184
  | `eve/next`, `eve/nuxt`, `eve/sveltekit`, `eve/tanstack` | framework bundler plugins |
181
- | [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, response errors |
182
- | [`eve/sessions`](../guides/client/messages#reusable-delivery-reads) | `Delivery`, `DeliveryResult`, read options, `SessionReader`, authenticated `Session`, and `SessionNotActiveError` |
185
+ | [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, `EveError` and the typed client errors |
186
+ | [`eve/sessions`](../guides/client/messages#reusable-delivery-reads) | `Delivery`, `DeliveryResult`, read options, `SessionReader`, `Session`, `EveError`, and `SessionNotActiveError` |
183
187
  | [`eve/events`](../concepts/sessions-runs-and-streaming#query-session-state) | Facts, opaque `SessionView`, immutable observations, and query/fold functions |
184
188
  | [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process |
185
189
 
@@ -188,13 +192,35 @@ have one home, `eve/sessions`; client factories and transport-specific types sta
188
192
  `SessionInfo` from `eve/context` is callback metadata, not a reader or an operable session.
189
193
  `ChannelContext` from `eve/channels` separates session information from continuation aliasing.
190
194
 
191
- `HistoryMessage` and the sandbox session, process, result, and method-option types are eve-owned. Their declarations do not change with your app's AI SDK peer version. Named judge, mock-model, approval, and disabled-marker types remain public for reusable helpers and declaration emission.
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.
196
+
197
+ ## Stability policy
198
+
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 })`.
204
+
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.
208
+
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.
213
+
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.
192
217
 
193
- The `exports` field in `packages/eve/package.json` lists every package entry point. `eve/experimental/*` and `eve/internal/*` have no compatibility promise. The CLI setup wizard is not a public authoring API; Agent Builder's scaffold integration lives at `eve/internal/scaffold`.
218
+ The CLI setup wizard is not a public authoring API; Agent Builder's scaffold
219
+ integration lives at `eve/internal/scaffold`.
194
220
 
195
221
  ## Direct provider models
196
222
 
197
- `openai(model?)` from `eve/models/openai` and `anthropic(model?)` from `eve/models/anthropic` return eve-owned model instances using the vendored providers. They accept only an optional model ID. Defaults are `gpt-6-luna-fast` and `claude-sonnet-5`, respectively.
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.
198
224
 
199
225
  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.
200
226
 
@@ -176,6 +176,8 @@ Validate the shape of your own state in `resume()`. When you change it incompati
176
176
 
177
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.
178
178
 
179
+ 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
+
179
181
  ## Bake files into templates
180
182
 
181
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.
@@ -57,12 +57,12 @@ export const environment = DefaultSandbox.environment({
57
57
  export default defineSandbox(() => environment.open());
58
58
  ```
59
59
 
60
- | Option | Used when | Accepts |
61
- | ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
62
- | `prepare` | Any provider | Setup captured in the prepared environment. Replaces a `prepare` set inside the provider options. |
63
- | `docker` | Docker is selected | The options of [`DockerSandbox.environment()`](/docs/sandbox/docker#environment-options), such as `image`, `env`, and `pullPolicy`. |
64
- | `vercel` | Vercel is selected | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials. |
65
- | `justBash` | just-bash is selected | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash) for `customCommands` or `filesystem`. |
60
+ | Option | Used when | Accepts |
61
+ | ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | `prepare` | Any provider | Setup captured in the prepared environment. Replaces a `prepare` set inside the provider options. |
63
+ | `docker` | Docker is selected | The options of [`DockerSandbox.environment()`](/docs/sandbox/docker#environment-options), such as `image`, `env`, and `pullPolicy`. |
64
+ | `vercel` | Vercel is selected | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials. |
65
+ | `justBash` | just-bash is selected | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash#experimental-options) for experimental `customCommands` or `filesystem`. |
66
66
 
67
67
  Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. just-bash runs no native binaries, so commands such as `apt-get` fail there during `eve dev`.
68
68
 
@@ -43,7 +43,7 @@ For example, a Vercel environment returns a handle with `setNetworkPolicy()`. Th
43
43
 
44
44
  ## Define an environment
45
45
 
46
- A sandbox module exports an environment and returns a sandbox from `defineSandbox()`. Put it at `agent/sandbox.ts`, or at `agent/sandbox/sandbox.ts` when the agent also has [workspace seeds](#managed-workspace-and-skills) or a Docker `Dockerfile` in `agent/sandbox/`. When the `agent/sandbox/` folder exists, eve reads the definition only from `agent/sandbox/sandbox.ts`.
46
+ A sandbox module exports an environment and returns a sandbox from `defineSandbox()`. Put it at `agent/sandbox.ts`, or at `agent/sandbox/sandbox.ts` when the agent also has [workspace seeds](#managed-workspace-and-skills) or a Docker `Dockerfile` in `agent/sandbox/`. When the `agent/sandbox/` folder exists, put the definition at `agent/sandbox/sandbox.ts`. Keeping `agent/sandbox.ts` beside that folder is a build error, even when the folder only contains workspace seeds or a Dockerfile.
47
47
 
48
48
  ```ts title="agent/sandbox.ts"
49
49
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -168,15 +168,15 @@ To run sandboxes on a backend eve does not ship, define a provider with `defineS
168
168
  | [Docker](/docs/sandbox/docker) | Local containers from the default image, an existing OCI image, or a Dockerfile. |
169
169
  | [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation. |
170
170
 
171
- For SDK-specific just-bash commands or filesystem factories, use `JustBashSandbox.environment()`
172
- from `eve/sandbox/just-bash`. `DefaultSandbox` keeps only `autoInstall` and `prepare` for its
173
- just-bash fallback.
171
+ For SDK-specific just-bash commands or filesystem factories, use the experimental options of
172
+ `JustBashSandbox.environment()` from `eve/sandbox/just-bash`. `DefaultSandbox` keeps only
173
+ `autoInstall` and `prepare` for its just-bash fallback.
174
174
 
175
175
  ## Lifecycle
176
176
 
177
177
  Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` deletes the sandbox and clears provider state, so the next `ctx.getSandbox()` reruns the selector, and the provider starts a fresh sandbox under the same session key from the current environment. If the native sandbox is gone when a session resumes, for example after a local daemon restart, a removed container, or a deleted just-bash session directory, eve does the same: the session continues in a fresh sandbox, without the lost sandbox's files. eve also starts a fresh sandbox when the recorded state belongs to another provider or state protocol than the current environment, for example after you change providers; the old sandbox is not deleted. When the durable session reaches a terminal outcome, eve calls the provider's `onSessionEnd()` hook to delete what remains under the session's key.
178
178
 
179
- Before that cleanup, session end ends the session's task runs, and each run resets the subagent sessions it opened. eve does not wait for those subagents to stop. A subagent step that is still running at that moment can open the sandbox again after cleanup, and eve does not remove a sandbox created that late.
179
+ Before that cleanup, session end ends the session's task runs, and each run ends the subagent sessions it opened. eve does not wait for those subagents to stop. A subagent step that is still running at that moment can open the sandbox again after cleanup, and eve does not remove a sandbox created that late.
180
180
 
181
181
  Changing sandbox source, preparation code, Dockerfile content, environment options, workspace resources, or skills produces a new environment generation. Existing durable sessions keep their sandbox, because its identity comes from the session key alone; new sessions use the current generation.
182
182
 
@@ -21,13 +21,18 @@ When an environment uses just-bash during `eve dev`, eve installs the package in
21
21
 
22
22
  For pnpm projects, automatic installation adds `@mongodb-js/zstd` and `node-liblzma` to `ignoredOptionalDependencies` in the owning `pnpm-workspace.yaml` when they have no explicit package policy. These optional native codecs are not needed for basic shell and filesystem operations. Commands that require those codecs may be unavailable without them. eve preserves existing package-specific build decisions and does not automatically approve build scripts.
23
23
 
24
- ## Custom commands
24
+ ## Experimental options
25
25
 
26
- `customCommands` registers your own functions as commands in each live just-bash shell, where they work in pipelines and redirections. Write a `JustBashCommand` from `eve/sandbox/just-bash`:
26
+ `experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they are experimental and have no compatibility promise. Their types, such as `JustBashCommand` and `JustBashFilesystem`, come from `eve/experimental/sandbox/just-bash`. `autoInstall` and `prepare` are stable.
27
+
28
+ ### Custom commands
29
+
30
+ `experimental.customCommands` registers your own functions as commands in each live just-bash shell, where they work in pipelines and redirections:
27
31
 
28
32
  ```ts
29
33
  import { defineSandbox } from "eve/sandbox";
30
- import { JustBashSandbox, type JustBashCommand } from "eve/sandbox/just-bash";
34
+ import type { JustBashCommand } from "eve/experimental/sandbox/just-bash";
35
+ import { JustBashSandbox } from "eve/sandbox/just-bash";
31
36
 
32
37
  const today: JustBashCommand = {
33
38
  name: "today",
@@ -36,7 +41,9 @@ const today: JustBashCommand = {
36
41
  },
37
42
  };
38
43
 
39
- export const environment = JustBashSandbox.environment({ customCommands: [today] });
44
+ export const environment = JustBashSandbox.environment({
45
+ experimental: { customCommands: [today] },
46
+ });
40
47
  export default defineSandbox(() => environment.open());
41
48
  ```
42
49
 
@@ -44,30 +51,32 @@ A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. Wh
44
51
 
45
52
  Custom commands run as application code in the app runtime process, outside the virtual filesystem. They are not available while eve prepares the template.
46
53
 
47
- ## Custom filesystem
54
+ ### Custom filesystem
48
55
 
49
- `filesystem` composes the filesystem of each live sandbox. eve calls it with `defaultFilesystem`, the session's durable filesystem that holds `/workspace`, and `justBash`, the loaded `just-bash` module. Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:
56
+ `experimental.filesystem` composes the filesystem of each live sandbox. eve calls it with `defaultFilesystem`, the session's durable filesystem that holds `/workspace`, and `justBash`, the loaded `just-bash` module. Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:
50
57
 
51
58
  ```ts
52
59
  import { defineSandbox } from "eve/sandbox";
53
60
  import { JustBashSandbox } from "eve/sandbox/just-bash";
54
61
 
55
62
  export const environment = JustBashSandbox.environment({
56
- async filesystem({ defaultFilesystem, justBash, resolveProjectPath }) {
57
- await defaultFilesystem.mkdir("/reference", { recursive: true });
58
- return new justBash.MountableFs({
59
- base: defaultFilesystem,
60
- mounts: [
61
- {
62
- filesystem: new justBash.OverlayFs({
63
- mountPoint: "/",
64
- readOnly: true,
65
- root: resolveProjectPath("reference"),
66
- }),
67
- mountPoint: "/reference",
68
- },
69
- ],
70
- });
63
+ experimental: {
64
+ async filesystem({ defaultFilesystem, justBash, resolveProjectPath }) {
65
+ await defaultFilesystem.mkdir("/reference", { recursive: true });
66
+ return new justBash.MountableFs({
67
+ base: defaultFilesystem,
68
+ mounts: [
69
+ {
70
+ filesystem: new justBash.OverlayFs({
71
+ mountPoint: "/",
72
+ readOnly: true,
73
+ root: resolveProjectPath("reference"),
74
+ }),
75
+ mountPoint: "/reference",
76
+ },
77
+ ],
78
+ });
79
+ },
71
80
  },
72
81
  });
73
82
  export default defineSandbox(() => environment.open());
@@ -86,10 +86,10 @@ Local `eve dev` makes the bundled `self-modification__agent` subagent available
86
86
 
87
87
  ### Vercel workspace peers
88
88
 
89
- In a Vercel agent workspace, expose one other workspace member as a remote subagent with `defineWorkspaceAgent`. Create an ordinary file under the caller's `agent/subagents/` directory. Its filename gives the model-visible tool name; `name` identifies the peer under `agents/`.
89
+ In a Vercel agent workspace, expose one other workspace member as a remote subagent with `defineWorkspaceAgent` from `eve/experimental/workspace`. The helper and its `WorkspaceAgentDefinition` and `WorkspaceAgentTransport` types are experimental and have no compatibility promise. The `agents/<name>/` workspace layout and `eve/vercel` integration remain stable. Create an ordinary file under the caller's `agent/subagents/` directory. Its filename gives the model-visible tool name; `name` identifies the peer under `agents/`.
90
90
 
91
91
  ```ts title="agents/foreman/agent/subagents/research.ts"
92
- import { defineWorkspaceAgent } from "eve";
92
+ import { defineWorkspaceAgent } from "eve/experimental/workspace";
93
93
 
94
94
  export default defineWorkspaceAgent({
95
95
  name: "research",
@@ -99,7 +99,7 @@ export default defineWorkspaceAgent({
99
99
  The helper uses the peer's root `defineAgent({ description })` value as the model-visible tool description. Pass `description` to override it for this caller. When `transport` is omitted, eve selects the built-in transport for the Vercel runtime environment. Local `vercel dev` routes workspace calls without deployment credentials; Vercel deployments route calls through the current deployment and authenticate with the caller's Vercel OIDC token. Named peers use their `/eve/<name>` mount. Outside those environments, provide an explicit transport with `url` and optional `auth` or `headers`:
100
100
 
101
101
  ```ts title="agents/foreman/agent/subagents/research.ts"
102
- import { defineWorkspaceAgent } from "eve";
102
+ import { defineWorkspaceAgent } from "eve/experimental/workspace";
103
103
  import { bearer } from "eve/agents/auth";
104
104
 
105
105
  export default defineWorkspaceAgent({
@@ -240,7 +240,7 @@ A call with the `taskId` of a child that is still working joins the child's curr
240
240
 
241
241
  eve adds a framework-injected `[Tasks]` note to the conversation that lists the working and idle tasks by `taskId` and tool, so the model can find a child to continue. See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels agent tasks.
242
242
 
243
- The parent holds each child for the life of the task's run, which lasts until the parent session ends or its task is cancelled. Then eve requests child shutdown, using authenticated reset requests for remote children. Cleanup is best effort: a child whose inbox or deployment is unavailable may remain running or parked. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or reset behavior introduced by a newer eve version.
243
+ The parent holds each child for the life of the task's run, which lasts until the parent session ends or its task is cancelled. Then eve requests child shutdown, using authenticated end-session requests for remote children. Cleanup is best effort: a child whose inbox or deployment is unavailable may remain running or parked. For [remote agents](./guides/remote-agents), upgrade both deployments before relying on continuation or end-session behavior introduced by a newer eve version.
244
244
 
245
245
  ## When to split
246
246
 
@@ -100,7 +100,7 @@ approval: ({ session, toolInput }) => {
100
100
  },
101
101
  ```
102
102
 
103
- For compatibility with the previous predicate shape, policies may return booleans: `true` is treated as `"user-approval"` and `false` as `"not-applicable"`. Boolean promises are supported too.
103
+ A boolean is a supported shorthand, returned synchronously or as a promise: `true` means `"user-approval"` and `false` means `"not-applicable"`.
104
104
 
105
105
  Policies can also return `"approved"` or `"denied"` to decide automatically. Use `{ type: "denied", reason }` when the model should receive a reason for denying the call. A denied call never starts: it settles `call.settled` with `outcome: "rejected"`, `cause: { policy: "approval" }`, and a `TOOL_EXECUTION_DENIED` output, whether the policy denies it as the model calls it or when an approved call is checked again. A tool that runs and throws settles `failed`. An explicit `"approved"` result records `clearedBy: { policy: "approval" }` on `call.started`. A call cleared by a remembered `once()` approval records the same `{ policy: "approval" }`; a call approved by a person records `{ interactionId }`. Calls that need no approval omit `clearedBy`. The `Approval`, `ApprovalConfiguration`, `ApprovalContext`, `ApprovalPolicy`, and `ApprovalStatus` types are exported from `eve/tools/approval`.
106
106