eve 0.86.0 → 0.88.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 (282) hide show
  1. package/CHANGELOG.md +25 -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/extensions/git/extension/extension.d.ts +5 -2
  81. package/dist/src/extensions/git/extension/extension.js +1 -1
  82. package/dist/src/extensions/git/extension/instructions/github.js +1 -1
  83. package/dist/src/extensions/git/extension/lib/connect-user-auth.d.ts +15 -0
  84. package/dist/src/extensions/git/extension/lib/connect-user-auth.js +1 -0
  85. package/dist/src/extensions/git/extension/lib/gh-tool.d.ts +8 -1
  86. package/dist/src/extensions/git/extension/lib/gh-tool.js +1 -1
  87. package/dist/src/extensions/git/extension/lib/github-guidance.d.ts +2 -1
  88. package/dist/src/extensions/git/extension/lib/github-guidance.js +14 -1
  89. package/dist/src/extensions/git/extension/lib/github-shell.d.ts +12 -4
  90. package/dist/src/extensions/git/extension/lib/github-shell.js +1 -1
  91. package/dist/src/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  92. package/dist/src/instrumentation/providers.d.ts +1 -38
  93. package/dist/src/instrumentation/providers.js +1 -1
  94. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  95. package/dist/src/internal/application/package.d.ts +1 -0
  96. package/dist/src/internal/application/package.js +1 -1
  97. package/dist/src/internal/application/stamped-package-version.js +1 -1
  98. package/dist/src/internal/authored-definition/core.js +1 -1
  99. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  100. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  101. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  102. package/dist/src/internal/runtime-model.d.ts +9 -4
  103. package/dist/src/internal/runtime-model.js +1 -1
  104. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  105. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  106. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  107. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  108. package/dist/src/models/auto.js +1 -1
  109. package/dist/src/protocol/delivery.d.ts +1 -0
  110. package/dist/src/protocol/reset-session.d.ts +0 -2
  111. package/dist/src/protocol/routes.d.ts +9 -2
  112. package/dist/src/protocol/routes.js +1 -1
  113. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  114. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  115. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  116. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  117. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  118. package/dist/src/public/channels/github/state.d.ts +0 -2
  119. package/dist/src/public/channels/index.d.ts +1 -2
  120. package/dist/src/public/channels/index.js +1 -1
  121. package/dist/src/public/channels/linear/index.d.ts +1 -1
  122. package/dist/src/public/channels/linear/index.js +1 -1
  123. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  124. package/dist/src/public/channels/linq/index.d.ts +1 -1
  125. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  126. package/dist/src/public/channels/photon/index.d.ts +1 -1
  127. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  128. package/dist/src/public/channels/slack/api.d.ts +1 -1
  129. package/dist/src/public/channels/slack/api.js +1 -1
  130. package/dist/src/public/channels/slack/app-manifest.d.ts +4 -0
  131. package/dist/src/public/channels/slack/app-manifest.js +1 -1
  132. package/dist/src/public/channels/slack/auth.d.ts +1 -0
  133. package/dist/src/public/channels/slack/auth.js +1 -1
  134. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  135. package/dist/src/public/channels/slack/blocks.js +2 -2
  136. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  137. package/dist/src/public/channels/slack/cards.js +1 -1
  138. package/dist/src/public/channels/slack/defaults.js +1 -1
  139. package/dist/src/public/channels/slack/inbound.d.ts +7 -0
  140. package/dist/src/public/channels/slack/index.d.ts +3 -2
  141. package/dist/src/public/channels/slack/index.js +1 -1
  142. package/dist/src/public/channels/slack/model-context.d.ts +3 -2
  143. package/dist/src/public/channels/slack/model-context.js +3 -3
  144. package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
  145. package/dist/src/public/channels/slack/session-operations.js +1 -1
  146. package/dist/src/public/channels/slack/slackChannel.d.ts +37 -72
  147. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  148. package/dist/src/public/channels/slack/user-info.d.ts +64 -0
  149. package/dist/src/public/channels/slack/user-info.js +1 -0
  150. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  151. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  152. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  153. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  154. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  155. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  156. package/dist/src/public/definitions/agent.d.ts +15 -7
  157. package/dist/src/public/definitions/agent.js +1 -1
  158. package/dist/src/public/definitions/channel.d.ts +7 -5
  159. package/dist/src/public/definitions/channel.js +1 -1
  160. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  161. package/dist/src/public/definitions/connections/protocol.js +1 -1
  162. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  163. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  164. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  165. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  166. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  167. package/dist/src/public/experimental/workspace/index.js +1 -0
  168. package/dist/src/public/index.d.ts +2 -2
  169. package/dist/src/public/index.js +1 -1
  170. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  171. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  172. package/dist/src/public/instrumentation/provider.js +1 -1
  173. package/dist/src/public/memory/file/backend.d.ts +1 -1
  174. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  175. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  176. package/dist/src/public/memory/file/provider.js +1 -1
  177. package/dist/src/public/memory/index.d.ts +3 -11
  178. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  179. package/dist/src/public/models/index.d.ts +1 -0
  180. package/dist/src/public/models/openai/index.d.ts +2 -2
  181. package/dist/src/public/next/index.d.ts +2 -2
  182. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  183. package/dist/src/public/sandbox/just-bash.d.ts +0 -1
  184. package/dist/src/public/sessions/index.d.ts +1 -0
  185. package/dist/src/public/sessions/index.js +1 -1
  186. package/dist/src/public/tools/index.d.ts +1 -1
  187. package/dist/src/public/tools/index.js +1 -1
  188. package/dist/src/public/workflow/api.d.ts +25 -0
  189. package/dist/src/public/workflow/api.js +1 -0
  190. package/dist/src/public/workflow/index.d.ts +76 -0
  191. package/dist/src/public/workflow/index.js +1 -0
  192. package/dist/src/public/workflow-modules.d.ts +2 -17
  193. package/dist/src/react/use-eve-agent.d.ts +3 -2
  194. package/dist/src/react/use-eve-agent.js +1 -1
  195. package/dist/src/reactions/kinds/model.js +1 -1
  196. package/dist/src/runtime/agent/resolve-model.js +1 -1
  197. package/dist/src/runtime/resolve-agent.js +1 -1
  198. package/dist/src/runtime/resolve-dynamic.js +1 -1
  199. package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
  200. package/dist/src/runtime/subagents/workflow.js +1 -1
  201. package/dist/src/sandbox/providers/default.js +1 -1
  202. package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
  203. package/dist/src/self-modification/sandbox.js +1 -1
  204. package/dist/src/setup/integrations/discord/daemon.js +2 -2
  205. package/dist/src/setup/scaffold/create/project.js +2 -2
  206. package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
  207. package/dist/src/setup/scaffold/create/web-template.js +2 -2
  208. package/dist/src/setup/verified-remote-agent.d.ts +1 -3
  209. package/dist/src/shared/agent-definition.d.ts +18 -9
  210. package/dist/src/shared/eve-error.d.ts +22 -0
  211. package/dist/src/shared/eve-error.js +1 -0
  212. package/dist/src/shared/session.d.ts +2 -2
  213. package/dist/src/shared/token-usage.d.ts +7 -1
  214. package/dist/src/svelte/index.js +1 -1
  215. package/dist/src/svelte/use-eve-agent.d.ts +2 -1
  216. package/dist/src/svelte/use-eve-agent.js +1 -1
  217. package/dist/src/tools/definition.d.ts +7 -5
  218. package/dist/src/tools/definition.js +1 -1
  219. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  220. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  221. package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
  222. package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
  223. package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
  224. package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
  225. package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
  226. package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
  227. package/dist/src/tracing/local/traces.d.ts +0 -13
  228. package/dist/src/vue/index.js +1 -1
  229. package/dist/src/vue/use-eve-agent.d.ts +3 -2
  230. package/dist/src/vue/use-eve-agent.js +1 -1
  231. package/docs/agent-config.md +15 -11
  232. package/docs/channels/custom.mdx +26 -10
  233. package/docs/channels/discord.mdx +10 -10
  234. package/docs/channels/eve.mdx +14 -8
  235. package/docs/channels/linear.mdx +11 -0
  236. package/docs/channels/linq.mdx +5 -1
  237. package/docs/channels/photon.mdx +6 -1
  238. package/docs/channels/slack.mdx +141 -15
  239. package/docs/channels/telegram.mdx +6 -0
  240. package/docs/code-extension.mdx +76 -12
  241. package/docs/concepts/default-harness.md +2 -2
  242. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  243. package/docs/concepts/security-model.md +2 -2
  244. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  245. package/docs/concepts/upgrade-to-v27-events.md +2 -1
  246. package/docs/connections/overview.mdx +4 -0
  247. package/docs/evals/reporters.mdx +21 -0
  248. package/docs/extensions.md +12 -0
  249. package/docs/getting-started.mdx +5 -1
  250. package/docs/guides/auth-and-route-protection.md +1 -1
  251. package/docs/guides/client/continuations.mdx +12 -10
  252. package/docs/guides/client/messages.mdx +24 -1
  253. package/docs/guides/client/overview.mdx +8 -6
  254. package/docs/guides/client/streaming.mdx +24 -6
  255. package/docs/guides/decide.md +3 -3
  256. package/docs/guides/deployment/vercel.mdx +1 -1
  257. package/docs/guides/dev-tui.md +2 -2
  258. package/docs/guides/frontend/overview.mdx +1 -1
  259. package/docs/guides/frontend/use-eve-agent-svelte.mdx +13 -11
  260. package/docs/guides/frontend/use-eve-agent-vue.mdx +13 -11
  261. package/docs/guides/frontend/use-eve-agent.mdx +4 -4
  262. package/docs/guides/instrumentation/otel.mdx +3 -1
  263. package/docs/guides/prepare-for-1-0.md +255 -0
  264. package/docs/guides/remote-agents.md +22 -20
  265. package/docs/instructions.mdx +1 -1
  266. package/docs/memory/custom-provider.md +1 -1
  267. package/docs/memory/file.md +11 -2
  268. package/docs/meta.json +1 -0
  269. package/docs/reference/agent-files.md +17 -17
  270. package/docs/reference/cli.md +14 -9
  271. package/docs/reference/typescript-api.md +46 -20
  272. package/docs/sandbox/custom-providers.mdx +2 -0
  273. package/docs/sandbox/default.mdx +6 -6
  274. package/docs/sandbox/index.mdx +5 -5
  275. package/docs/sandbox/just-bash.mdx +30 -21
  276. package/docs/subagents/index.mdx +4 -4
  277. package/docs/tools/human-in-the-loop.md +1 -1
  278. package/docs/tools/workflows.mdx +52 -8
  279. package/docs/tutorial/first-agent.mdx +1 -1
  280. package/package.json +36 -9
  281. package/dist/CHANGELOG.md +0 -38
  282. package/dist/src/public/channels/discord/gateway/index.js +0 -1
@@ -43,6 +43,12 @@ Forum topics carry `message_thread_id` in the continuation token, so each topic
43
43
 
44
44
  To customize auth or filtering, override `onMessage`. Return `title` alongside `auth` to set the title when the dispatch starts a run. Group privacy mode itself lives in BotFather, not here.
45
45
 
46
+ Custom `onMessage` hooks can import `defaultTelegramAuth` from
47
+ `eve/channels/telegram` and return `{ auth: defaultTelegramAuth(message) }` to
48
+ keep the default actor identity. The helper uses the message's `from` user,
49
+ scopes group identities to the chat, and returns `null` when no user is present.
50
+ For a button press, pass the button presser as `from`, not the message's author.
51
+
46
52
  ### Delivery
47
53
 
48
54
  The default `content.completed` handler sends each reply part as plain text via `sendMessage`. It passes no `parse_mode`, so any Markdown shows up literally. Replies longer than Telegram's 4096-char limit are split across messages. Custom handlers use `ctx.channel.telegram`.
@@ -98,19 +98,35 @@ export default git({});
98
98
 
99
99
  Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
100
100
 
101
- | Option | Required | Effect |
102
- | -------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
103
- | `github.connector` | With `github` | Connector that mints a GitHub token |
104
- | `github.org` | With `github` | Organization whose repositories the `gh` tool can access |
105
- | `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
106
- | `github.authorize` | No | `authorize({ auth, repository, token })` callback that allows or denies each `gh` tool invocation |
107
- | `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
101
+ | Option | Required | Effect |
102
+ | ---------------------- | ------------- | -------------------------------------------------------------------------------------------- |
103
+ | `github.connector` | With `github` | Connector that mints a GitHub token |
104
+ | `github.broker` | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
105
+ | `github.authorize` | With `github` | `authorize({ auth, repository, token })` decides whether each `gh` tool invocation may run |
106
+ | `github.principalType` | No | `"app"` (default) for GitHub App installation tokens, or `"user"` for the caller's own token |
107
+ | `github.attribution` | No | `attribution(ctx)` returns the current turn's `{ name, email }` co-author, or `null` |
108
108
 
109
- The `gh` tool requests a token scoped to exactly one repository in `github.org` for each invocation. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
109
+ Each `gh` invocation declares exactly one `owner/name` repository, and every explicit command target must match it. By default the tool requests a GitHub App installation token for that owner's installation, scoped to that one repository; with `github.principalType` set to `"user"` it resolves the caller's own token instead. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
110
110
 
111
- `github.authorize` runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the repository-scoped app token, await `authorize({ auth, repository, token })`, install the credential lease, then run the command. `auth` is the session's current caller at tool invocation, or `null`. Returning `false` stops execution before the lease is installed or the command runs. The decision applies to that invocation only; it is neither cached for the session nor repeated for each GitHub API request.
111
+ `github.authorize` is the agent's only repository access control, so it is required: a command runs only when it returns `true`. It runs during each `gh` tool execution, not when the session starts. The order is: validate the command and repository, mint the token, await `authorize({ auth, repository, token })`, install the credential lease, then run the command. `auth` is the session's current caller at tool invocation, or `null`. Returning `false` stops execution before the lease is installed or the command runs, so the token never reaches the sandbox or GitHub. The decision applies to that invocation only; it is neither cached for the session nor repeated for each GitHub API request.
112
112
 
113
- For example, use the token to check collaborator status (allowed commands still use the app token's permissions, not the collaborator's):
113
+ The simplest policy limits the agent to one organization. Compare owners case-insensitively, as GitHub does:
114
+
115
+ ```ts title="agent/extensions/git.ts"
116
+ import git from "eve/extensions/git";
117
+
118
+ import { brokerGitHubLease } from "../lib/github";
119
+
120
+ export default git({
121
+ github: {
122
+ connector: "github/my-agent",
123
+ broker: brokerGitHubLease,
124
+ authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
125
+ },
126
+ });
127
+ ```
128
+
129
+ `authorize` can also use the token to check the caller, for example their collaborator status (allowed commands still use the app token's permissions, not the collaborator's):
114
130
 
115
131
  ```ts title="agent/extensions/git.ts"
116
132
  import git from "eve/extensions/git";
@@ -120,10 +136,10 @@ import { brokerGitHubLease } from "../lib/github";
120
136
  export default git({
121
137
  github: {
122
138
  connector: "github/my-agent",
123
- org: "acme",
124
139
  broker: brokerGitHubLease,
125
140
  // GitHub channel sessions carry the commenter's login as `auth.subject`.
126
141
  async authorize({ auth, repository, token }) {
142
+ if (!repository.toLowerCase().startsWith("acme/")) return false;
127
143
  if (auth?.authenticator !== "github-webhook" || !auth.subject) return false;
128
144
  const response = await fetch(
129
145
  `https://api.github.com/repos/${repository}/collaborators/${auth.subject}`,
@@ -135,6 +151,29 @@ export default git({
135
151
  });
136
152
  ```
137
153
 
154
+ ### Run commands as the caller
155
+
156
+ By default each `gh` invocation mints a GitHub App installation token, so commands run with the installation's permissions. Set `github.principalType` to `"user"` to run them with the caller's own GitHub permissions instead, as `connect({ connector, principalType: "user" })` does for connections:
157
+
158
+ ```ts title="agent/extensions/git.ts"
159
+ import git from "eve/extensions/git";
160
+
161
+ import { brokerGitHubLease } from "../lib/github";
162
+
163
+ export default git({
164
+ github: {
165
+ connector: "github/my-agent",
166
+ broker: brokerGitHubLease,
167
+ authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
168
+ principalType: "user",
169
+ },
170
+ });
171
+ ```
172
+
173
+ The tool resolves the caller's token from `github.connector` through `ctx.getToken`. When the caller has no grant, eve signs them in and re-runs the call. The token request carries no repository details, so one grant covers every repository and later commands resolve tokens without another sign-in. When GitHub rejects the token (`HTTP 401`, `Bad credentials`, `Authentication failed`, or a `gh-signed-commit` `failed: 401`), the tool calls `ctx.requireAuth`, which evicts the token and signs the caller in again.
174
+
175
+ A user token carries the caller's GitHub permissions across every account where the GitHub App is installed, not only the declared repository. The tool description and GitHub instructions tell the model that access is limited to what the caller can reach. `github.authorize` still runs before every command, with the caller's token, and remains the agent's repository policy.
176
+
138
177
  ### Credit the person behind a turn
139
178
 
140
179
  Commits made by the `gh` tool are authored by the GitHub App. Return a verified user mapping from
@@ -153,8 +192,8 @@ import { brokerGitHubLease, coAuthorFor } from "../lib/github";
153
192
  export default git({
154
193
  github: {
155
194
  connector: "github/my-agent",
156
- org: "acme",
157
195
  broker: brokerGitHubLease,
196
+ authorize: ({ repository }) => repository.toLowerCase().startsWith("acme/"),
158
197
  attribution: (ctx) => coAuthorFor(ctx.session.auth.current),
159
198
  },
160
199
  });
@@ -164,6 +203,31 @@ export default git({
164
203
 
165
204
  `code({ github })` is rejected. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.
166
205
 
206
+ ## Override bundled tools
207
+
208
+ `eve/extensions/code/tools` exports the reusable `apply_patch` and `grep` tool
209
+ definitions. Import one in an override to change approval or other tool options
210
+ without copying its implementation. With the file mount above, put the override
211
+ in the agent-root slot named after the qualified tool, `code__apply_patch`:
212
+
213
+ ```ts title="agent/tools/code__apply_patch.ts"
214
+ import { apply_patch } from "eve/extensions/code/tools";
215
+ import { defineTool } from "eve/tools";
216
+ import { always } from "eve/tools/approval";
217
+
218
+ export default defineTool({ ...apply_patch, approval: always() });
219
+ ```
220
+
221
+ `agent/extensions/code/tools/apply_patch.ts` works only when the mount is a
222
+ directory, `agent/extensions/code/extension.ts`.
223
+
224
+ For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
225
+ `executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
226
+ The execution helper enforces repository and command constraints and brokers a
227
+ credential lease; dependencies supply the session ID and sandbox access. Reuse
228
+ `githubShellApproval` to reject invalid command inputs through the approval
229
+ policy rather than bypassing those constraints.
230
+
167
231
  ## Prepare the sandbox
168
232
 
169
233
  Install the CLI tooling in your sandbox environment's `prepare` callback:
@@ -7,13 +7,13 @@ The default harness is eve's built-in agent loop. It manages model calls, compac
7
7
 
8
8
  ## Compaction
9
9
 
10
- The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `thresholdPercent` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
10
+ The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `compaction.threshold` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
11
11
 
12
12
  ```ts title="agent/agent.ts"
13
13
  export default defineAgent({
14
14
  model: "anthropic/claude-opus-5.5",
15
15
  compaction: {
16
- thresholdPercent: 0.75,
16
+ threshold: 0.75,
17
17
  },
18
18
  });
19
19
  ```
@@ -58,7 +58,7 @@ eve treats every world other than Vercel Workflow as running one eve version at
58
58
 
59
59
  eve ends a stranded session without running any of its code. When that happens depends on the kind of run:
60
60
 
61
- - **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, a reset ends it, or its session timeout elapses, whichever comes first.
61
+ - **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, an explicit end retires it, or its session timeout elapses, whichever comes first.
62
62
  - **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it, for example when the local world or Postgres recovers active runs at startup. No later message could resume its interrupted work, so eve does not wait.
63
63
 
64
64
  See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
@@ -66,18 +66,18 @@ See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
66
66
  For a root session, what happens next depends on how the message is addressed:
67
67
 
68
68
  - **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. The fresh session names the session it replaced, whose recorded conversation your instructions can read; see [What a replacement session receives](#what-a-replacement-session-receives). A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).
69
- - **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `reset()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
69
+ - **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `end()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
70
70
  - **A session ID** is never reset implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).
71
71
  - **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`; the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.
72
- - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to reset it.
73
- - **Reset** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. Reset the session instead.
74
- - **Session timeouts** end a stranded session the same way a reset does; see [How a stranded session ends](#how-a-stranded-session-ends).
72
+ - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to end it.
73
+ - **End** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. End the session instead.
74
+ - **Session timeouts** end a stranded session the same way an explicit end does; see [How a stranded session ends](#how-a-stranded-session-ends).
75
75
 
76
- A reset ends the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, the reset fails without ending the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the reset delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. A reset that fails partway through can be retried.
76
+ An explicit `end()` retires the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, ending fails without retiring the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the end delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. An end that fails partway through can be retried.
77
77
 
78
- Each reset logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`.
78
+ Each retirement logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`. The internal command and log value remain `reset` for compatibility; the public control is `end()`.
79
79
 
80
- A reset cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit reset leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session is reset. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
80
+ Ending a session cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit end leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session ends. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
81
81
 
82
82
  #### What a replacement session receives
83
83
 
@@ -135,9 +135,9 @@ The transcript is context only: tools, approvals, files, sandbox contents, autho
135
135
 
136
136
  #### How a stranded session ends
137
137
 
138
- A stranded root session ends on its next channel message, a reset, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
138
+ A stranded root session ends on its next channel message, an explicit end, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
139
139
 
140
- The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or a reset, just as a healthy one would stay open.
140
+ The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or an explicit end, just as a healthy one would stay open.
141
141
 
142
142
  Ending a root session does not immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. A run that never receives a delivery, such as one parked in a dormant `eve dev` generation, can stay active; cancel it in your Workflow world if you need to. Cancellation does not run authored cleanup or lifecycle hooks, undo side effects, or stop independent external jobs, and results and approvals do not carry over to a replacement session.
143
143
 
@@ -262,7 +262,7 @@ session claims both its stable session-ID inbox and its initial channel address
262
262
  before processing the first turn, and fails creation if another run already
263
263
  owns the channel address. Aliasing adds another continuation address to the
264
264
  same session; every previously claimed address remains active until the session
265
- ends or resets. An ID-only HTTP session has the stable inbox and no channel
265
+ ends. An ID-only HTTP session has the stable inbox and no channel
266
266
  continuation address. When cold starts race for the same address, the losing
267
267
  candidate forwards its accepted message to the owner and exits.
268
268
 
@@ -18,7 +18,7 @@ The app runtime is the trusted side. Your tool implementations, model calls, con
18
18
 
19
19
  The sandbox is the isolated side. The model runs shell commands and accesses files there through the default `bash`, `read_file`, and `write_file` tools and any opt-in sandbox tools such as `glob` and `grep`. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) Only shell commands execute in the sandbox. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
20
20
 
21
- The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
21
+ The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `experimental.customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
22
22
 
23
23
  A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
24
24
 
@@ -41,7 +41,7 @@ flowchart LR
41
41
  eve sends data where your agent configuration and runtime choices send it:
42
42
 
43
43
  - Inbound channel data flows through the channel provider you configure, then into the eve app runtime.
44
- - Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider-authored `LanguageModel`.
44
+ - Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider model instance (`EveLanguageModel`).
45
45
  - Tool and connection calls flow to the external services, MCP servers, OpenAPI endpoints, and channels you configure.
46
46
  - Sandbox commands can reach network destinations allowed by the sandbox network policy.
47
47
  - Telemetry flows to destinations configured under `agent/instrumentation/`.
@@ -32,8 +32,11 @@ A session completes after 30 idle days by default; configure
32
32
  timeout. The idle window restarts each time a turn settles, and a session never
33
33
  expires while a turn is open. At expiration, eve emits `session.ended` with `outcome: "completed"` and
34
34
  releases the session's continuation addresses so the next qualifying channel
35
- message starts fresh. Stored session data is not deleted. See
36
- [Agent config](../agent-config#runtime-limits).
35
+ message starts fresh. Stored data follows the session's
36
+ [run-data retention policy](../agent-config#run-data-retention). Under the default
37
+ policy outside development, eve requests deletion when private and unknown-audience
38
+ sessions end. The Workflow World must support deletion to enforce it. See
39
+ [Agent config](../agent-config#runtime-limits) for timeout settings.
37
40
 
38
41
  React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
39
42
 
@@ -115,6 +118,13 @@ The full catalog, its outcome sets, and TypeScript types are exported from `eve/
115
118
  import { FACT_CATALOG, foldEvents, activeTurn, reply } from "eve/events";
116
119
  ```
117
120
 
121
+ The family-specific arrays `SESSION_OUTCOMES`, `DELIVERY_OUTCOMES`, `TURN_OUTCOMES`,
122
+ `MODEL_OUTCOMES`, `CALL_OUTCOMES`, `TASK_OUTCOMES`, `INTERACTION_OUTCOMES`,
123
+ `RESPONSE_OUTCOMES`, and `CONTEXT_OUTCOMES` list the outcomes known to this release.
124
+ `TERMINAL_OUTCOMES` maps terminal fact types to those arrays. `isTerminal(fact)`
125
+ narrows a fact to one that ends its entity; it does not test whether the whole
126
+ session has ended. These helpers come from `eve/events`.
127
+
118
128
  #### What a later release can add
119
129
 
120
130
  Within stream version 27, a later minor release can add:
@@ -152,7 +162,7 @@ Spend is recorded on `usage.recorded`, once per model run (`owner: { runId }`) a
152
162
 
153
163
  ### Deliveries and responses
154
164
 
155
- Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `reset`, or a sign-in callback. `delivery.admitted` records it, with the sender's `principal` and its `source`. A message that a turn takes in is `delivery.consumed`, with the `parts` it received: text, plus file metadata without raw bytes or internal sandbox paths. A delivery that brought [prior history](../channels/eve#start-from-prior-history) also carries it there, in `history`. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
165
+ Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `end`, or a sign-in callback. `delivery.admitted` records it, with the sender's `principal` and its `source`. A message that a turn takes in is `delivery.consumed`, with the `parts` it received: text, plus file metadata without raw bytes or internal sandbox paths. A delivery that brought [prior history](../channels/eve#start-from-prior-history) also carries it there, in `history`. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
156
166
 
157
167
  | Outcome | Meaning |
158
168
  | ---------------- | --------------------------------------------------------------------------------------------------- |
@@ -165,8 +175,9 @@ Everything that reaches a session arrives as a delivery: a message, an answer, a
165
175
 
166
176
  `POST /eve/v1/session/:sessionId` returns the message's `deliveryId`, so a client resuming from an old cursor knows which `delivery.settled` ends its response. Steering and coalesced messages each keep their own delivery. The id is assigned before dispatch,
167
177
  not derived from stream position. An answer-only delivery stops on its own `delivery.settled`.
168
- A stranded reset records its control's admission and settlement before ending the session, with
169
- `session.ended.data.cause.deliveryId` naming the reset.
178
+ Ending a stranded session records the control's admission and settlement, with
179
+ `session.ended.data.cause.deliveryId` naming that delivery. Its stream control value
180
+ remains `"reset"` for compatibility with recorded history.
170
181
  An answer and message sent together by someone other than the turn's caller become separate deliveries: the answer reaches the waiting turn, and the message retains the receipt and waits. Follow the answer through its interaction.
171
182
 
172
183
  To follow an accepted receipt in a client view, use `delivery(view, receipt.deliveryId)` from
@@ -232,6 +243,8 @@ const observed = call(agent.view, callId);
232
243
  if (observed?.state === "failed") console.error(observed.error.message);
233
244
  ```
234
245
 
246
+ `callOutputSource(view, callId)` returns the observation of the call that produced a call's output. `call(view, callId)?.output` already follows `outputOf`, so use `callOutputSource` when you need the producing call itself, such as its `callId` or label.
247
+
235
248
  Calls include their resolved `turnId`, `runId`, and `taskId` when known, so applications do not
236
249
  join calls to runs to find their turn. `turns`, `deliveries`, `tasks`, `runs`, `parts`, and
237
250
  `children` return curated observations. Identity lookups include `turn`,
@@ -362,14 +375,14 @@ Custom channel routes request the same cancellation through
362
375
  `from(address).cancel()` or `attachSession(sessionId).cancel()`. See
363
376
  [custom channels](../channels/custom#channel-operations-and-session-handles).
364
377
 
365
- ## Compact, clear, and reset
378
+ ## Compact, clear, and end
366
379
 
367
380
  All session controls are ID-addressed and accept no continuation token:
368
381
 
369
382
  ```bash
370
383
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/compact
371
384
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/clear
372
- curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
385
+ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/end \
373
386
  -H 'content-type: application/json' \
374
387
  -d '{"reason":"Start over"}'
375
388
  ```
@@ -380,9 +393,9 @@ Clear removes model-message history in place, including static and dynamic user-
380
393
 
381
394
  A cancel stops turns, not a compaction or clear: one that arrives while either runs settles `ignored`, and the change finishes. A cancel, clear, or compact sent to a prewarmed session before its first message has nothing to act on, and settles `ignored` once the session starts.
382
395
 
383
- Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. All controls return delivery receipts when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
396
+ End terminally retires the exact session ID. An ended ID never becomes a new session; create another session explicitly for a fresh conversation. All controls return delivery receipts when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
384
397
 
385
- A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. Reset still works: eve retires the stranded workflow run and returns its delivery. Its settlement follows retirement and address release. Clear and compact cannot repair a stranded owner; use reset instead.
398
+ A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. End still works: eve retires the stranded workflow run and returns its delivery. Its settlement follows retirement and address release. Clear and compact cannot repair a stranded owner; use end instead.
386
399
 
387
400
  ## Reconnect and rewind
388
401
 
@@ -431,7 +444,7 @@ for await (const event of events) {
431
444
  }
432
445
  ```
433
446
 
434
- `stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `streamReconnectPolicy`. Key stored events on [`meta.position`](#positions), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
447
+ `stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `reconnect: false` or a `ReconnectOptions` object from `eve/client`. Key stored events on [`meta.position`](#positions), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
435
448
 
436
449
  A read reflects events that are already durable. A hook runs after its line is written, so a bounded read there includes the event that triggered it. `sessions` reads any session ID without channel auth, so check that a caller may read a session before passing an ID from a request. It is available only in code that runs inside the eve server.
437
450
 
@@ -120,7 +120,7 @@ export default defineHook({
120
120
 
121
121
  **Instrumentation** uses `session.ended`, `turn.settled`, `call.requested`/`call.settled`, and `interaction.opened`/`interaction.settled`, with terminal `outcome` instead of separate success/failure event names. `channel.delivery.*` becomes `delivery.consumed`/`delivery.settled`; `step.attempt.*` becomes `model.started`/`model.retried`/`model.settled`. See [Instrumentation](/docs/observability/instrumentation#lifecycle-events).
122
122
 
123
- **Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `reset()` retires the server session. Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
123
+ **Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `end()` retires the server session (renamed from `reset()`). Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
124
124
 
125
125
  **Evals** match v27 facts and use `view` queries. Rename `loadedSkill` to `calledSkill`, `calledSubagent` to `calledAgent`, `noFailedActions` to `noFailedCalls`, and `parked()` to `awaitingInput()`. Use `t.target.attach(id)` instead of `attachSession(id)` and `turn.waitForToolCall()` instead of the old action matcher. See [Evals](../evals/overview).
126
126
 
@@ -134,6 +134,7 @@ export default defineHook({
134
134
  - Replace connection auth's `credentialOwner` with `principalType: "app" | "user"`. With `getToken` alone, omitted ownership defaults to `"app"`; set `"user"` for per-user tokens. See [connection credential ownership](/docs/connections#choose-app-vs-user-auth).
135
135
  - Dynamic capabilities use `defineDynamic(ctx => value)`, not lifecycle event maps. Replace `defineDurableCallback` and `defineDurableSchema` wrappers with ordinary functions and schemas; put external JSON observations in `ctx.memo(key, fn)`. See [Dynamic capabilities](../guides/dynamic-capabilities).
136
136
  - Recalled memory stays outside durable conversation history and is recalled before turns, not during compaction. Remove memory `visibility` options; a failed memory capture now prevents compaction. See [Memory providers](../memory/custom-provider).
137
+ - Memory document backend `read()` and `write()` inputs use `signal` again, restoring the pre-`0.84.0` contract. Backends written for `0.83.x` or earlier need no change; replace `abortSignal` only in backends and calls written for `0.84.x`. Memory and tool execution contexts keep `ctx.abortSignal`. See [Custom backends](../memory/file#custom-backend).
137
138
  - `grep` lists matching files by default. Set `outputMode: "content"` when the caller needs matching lines; see [Built-in tools](./built-in-tools#grep).
138
139
  - Replace `eve remote invoke` with `eve remote connect --print <prompt>` for one-shot requests. Use `eve/client` for scripted multi-turn sessions and answers; see the [CLI reference](../reference/cli#eve-remote-connect).
139
140
  - MCP's `input_required` now covers sign-ins as well as approvals and questions. Answer non-sign-in interactions using `responses: [{ interactionId, optionId?, text? }]`; complete sign-ins externally. Direct `invokeTool` calls return call-shaped outcomes, not conversational pauses. See [MCP](../channels/mcp).
@@ -10,6 +10,10 @@ Connections live under `agent/connections/`. A static connection's runtime name
10
10
 
11
11
  A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve, except that a dynamic connection with exactly a static connection's name replaces that static connection; see [Naming and conflicts](/docs/guides/dynamic-capabilities#naming-and-conflicts). Both errors name the two sides of the conflict; rename either one.
12
12
 
13
+ Static and dynamic connection definitions must use `defineMcpClientConnection`
14
+ or `defineOpenAPIConnection` from `eve/connections`. Plain object exports are
15
+ rejected because they do not identify a protocol.
16
+
13
17
  ## MCP connections
14
18
 
15
19
  Use an MCP connection when the external service already exposes an MCP server. The server publishes its tools and schemas, and eve makes the matched tools callable by the model. Each tool's JSON Schema reaches the model as published, minus any arguments you supply with `toolCall.providedArguments`, and eve checks the model's arguments against it before it calls the server.
@@ -9,6 +9,27 @@ You are responsible for ensuring any observability or eval provider is approved
9
9
 
10
10
  Reporters attach in two places. Declare them in `evals.config.ts` to observe **every** eval in the run, the usual choice for a shared destination like one Braintrust experiment, so you don't repeat the reporter in each file. Or list them on an individual eval's `reporters` to scope a destination to that eval (or to a group of evals that share one instance).
11
11
 
12
+ ## Console
13
+
14
+ The CLI adds `consoleReporter()` from `eve/evals/reporters` unless you pass
15
+ `--json`. There is no public runner API, so reporters compose only through
16
+ `evals.config.ts` and per-eval `reporters`. A custom console reporter mostly
17
+ makes sense with `--json`, for example logging to stderr so stdout stays valid
18
+ JSON:
19
+
20
+ ```ts title="evals/evals.config.ts"
21
+ import { defineEvalConfig } from "eve/evals";
22
+ import { consoleReporter } from "eve/evals/reporters";
23
+
24
+ export default defineEvalConfig({
25
+ reporters: [consoleReporter({ color: false, log: (line) => console.error(line) })],
26
+ });
27
+ ```
28
+
29
+ Both options are optional; the default logger is `console.log` and color
30
+ follows whether stdout is a terminal. Without `--json`, another console reporter
31
+ duplicates the CLI's output.
32
+
12
33
  ## Braintrust
13
34
 
14
35
  `braintrustReporter(...)` uploads eval results to Braintrust experiments. Put one instance in the config so it covers the whole run:
@@ -340,6 +340,18 @@ Hooks and instruction fragments are additive, so they cannot be replaced. To rep
340
340
 
341
341
  You can also place an override in the corresponding agent-root slot by using the final qualified name. For example, `agent/tools/crm__search.ts` replaces `tools/search.ts` from the extension package or its directory override. Application sources have the highest precedence, so an agent-root override wins when both forms exist.
342
342
 
343
+ ### Computer-use overrides
344
+
345
+ The bundled `eve/extensions/computer-use` extension exports `computer_use` from
346
+ `eve/extensions/computer-use/tools`. Reuse that tool definition in a same-named
347
+ override, as with the [code extension's tools](/docs/code-extension#override-bundled-tools).
348
+
349
+ For a custom sandbox, `eve/extensions/computer-use/sandbox` exports
350
+ `installComputerUse(sandbox)` and `startComputerUse(sandbox)`. Run the installer
351
+ in the environment's preparation callback to install desktop packages and the
352
+ driver; it requires an apt-based image with root or passwordless sudo. Start
353
+ the managed display and driver after opening each session sandbox.
354
+
343
355
  ### Use an extension tool result in a hook
344
356
 
345
357
  To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
@@ -84,7 +84,11 @@ npm install eve@latest ai zod
84
84
 
85
85
  Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
86
86
 
87
- When present, the installed package's `node_modules/eve/dist/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. Older packages contain the full history at `node_modules/eve/CHANGELOG.md` instead. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at `https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md`.
87
+ The installed package's `node_modules/eve/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at `https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md`.
88
+
89
+ ## Upgrade an existing project
90
+
91
+ For the coordinated pre-1.0 API cleanup, follow [Prepare for 1.0](./guides/prepare-for-1-0) before updating an existing server, client, or authored agent.
88
92
 
89
93
  ## Continue with the tutorial
90
94
 
@@ -16,7 +16,7 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
16
16
 
17
17
  - `POST /eve/v1/session`
18
18
  - `POST /eve/v1/session/:sessionId`
19
- - `POST /eve/v1/session/:sessionId/{cancel,compact,clear,reset}`
19
+ - `POST /eve/v1/session/:sessionId/{cancel,compact,clear,end}`
20
20
  - `GET /eve/v1/session/:sessionId/stream`
21
21
 
22
22
  These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
@@ -27,6 +27,8 @@ The state is deliberately small:
27
27
  interface ClientSessionState {
28
28
  sessionId: string;
29
29
  streamIndex: number;
30
+ /** Opaque; persist it and pass it back unchanged. eve may extend it. */
31
+ inbox?: string;
30
32
  }
31
33
  ```
32
34
 
@@ -41,15 +43,14 @@ Attach a fixed handle to the saved ID and restore its cursor:
41
43
  import type { ClientSessionState } from "eve/client";
42
44
 
43
45
  const saved = (await loadSessionState()) as ClientSessionState;
44
- const session = client.sessions.attach(saved.sessionId, {
45
- streamIndex: saved.streamIndex,
46
- });
46
+ const session = client.sessions.attach(saved.sessionId, saved);
47
47
 
48
48
  const response = await session.send("Now shorten it.");
49
49
  console.log((await response.result()).message);
50
50
  ```
51
51
 
52
- `attach()` performs no request. Every later operation targets exactly
52
+ Pass the whole saved state so its optional [`inbox`](./overview#faster-sends-with-inbox) value
53
+ reaches later sends. `attach()` performs no request. Every later operation targets exactly
53
54
  `saved.sessionId`; it never follows or creates a replacement.
54
55
 
55
56
  `send()` correlates its response with the message accepted by the server. If the
@@ -63,14 +64,17 @@ If a configured reconnect limit ends the stream before the accepted turn reaches
63
64
  a boundary, collecting its response throws. A partial stream is not a completed
64
65
  result.
65
66
 
66
- ## Waiting, completed, and reset sessions
67
+ <a id="waiting-completed-and-reset-sessions" />
68
+
69
+ ## Waiting, completed, and ended sessions
67
70
 
68
71
  A session that hasn't ended (`session.ended`) accepts another message through the
69
- same handle. A terminal or reset session does not. Start a fresh conversation
72
+ same handle. An ended session does not. Start a fresh conversation
70
73
  explicitly with another `client.sessions.create(firstTurn)` call.
71
74
 
72
75
  ```ts
73
- const reset = await session.reset({ reason: "Start over" });
76
+ const ended = await session.end({ reason: "Start over" });
77
+ await ended.result();
74
78
  const { session: fresh, delivery } = await client.sessions.create({ message: "Begin again." });
75
79
  ```
76
80
 
@@ -102,9 +106,7 @@ The shared `Client` owns the base URL, auth, headers, and redirect policy. Each
102
106
  read:
103
107
 
104
108
  ```ts
105
- const session = client.sessions.attach(saved.sessionId, {
106
- streamIndex: saved.streamIndex,
107
- });
109
+ const session = client.sessions.attach(saved.sessionId, saved);
108
110
 
109
111
  for await (const event of session.stream()) {
110
112
  console.log(event.type);
@@ -54,13 +54,36 @@ or terminal session throws `SessionNotActiveError` immediately with `retryable:
54
54
  [stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
55
55
  `ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
56
56
  `eveVersion` that built the session when it recorded one. It is never retried automatically. Call
57
- `session.reset()` and create a new session.
57
+ `session.end()` and create a new session.
58
58
  The client never creates a replacement session. Following or reconnecting to a stranded session's
59
59
  stream reports the same typed error without retrying, including when you were waiting for a
60
60
  response to a message accepted before the upgrade. That accepted message is not redelivered.
61
61
  `session.clear()` throws the same error, because clearing would keep a session that cannot run.
62
62
  `session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
63
63
 
64
+ The typed errors `eve/client` throws (`ClientError` and its subclasses, `SessionNotActiveError`,
65
+ `HealthResponseError`, and `AgentInfoResponseError`) extend `EveError` and have a stable snake_case
66
+ `code`: `SessionNotActiveError` uses `session_not_active` or `session_not_ready`; `ClientError` carries
67
+ the response's code (such as `session_stranded` or `session_expired`), or `http_error` when the
68
+ response had none. Narrow with the static `is()` of the class you expect instead of `instanceof`,
69
+ so errors from a separately bundled copy of eve still match:
70
+
71
+ ```ts
72
+ import { ClientError, SessionNotActiveError } from "eve/client";
73
+
74
+ try {
75
+ await session.send("Continue.");
76
+ } catch (error) {
77
+ if (SessionNotActiveError.is(error) && !error.retryable) {
78
+ // Start a new session.
79
+ } else if (ClientError.is(error) && error.code === "unauthorized") {
80
+ // Sign in again.
81
+ } else {
82
+ throw error;
83
+ }
84
+ }
85
+ ```
86
+
64
87
  ## Send a full turn payload
65
88
 
66
89
  Pass the full payload to `create()` for the first turn or `send()` for a follow-up:
@@ -113,11 +113,13 @@ await response.result();
113
113
 
114
114
  Per-request headers override client-level values with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` continues to send the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
115
115
 
116
- ## Reusing a session inbox
116
+ ## Faster sends with `inbox`
117
117
 
118
118
  Keep the complete `session.state` when saving and restoring a conversation. It can include an
119
- opaque `inbox` handle returned by the server. The client sends this handle with later messages
120
- to avoid another hook lookup. Treat it as transport state: do not inspect or edit it.
119
+ opaque `inbox` value issued by the server. The client sends it back with later messages to avoid
120
+ another hook lookup. Persist it and pass it back unchanged: do
121
+ not inspect, edit, or construct it, because eve may change or extend its contents in any release.
122
+ A missing, stale, or rejected value only costs a slower lookup.
121
123
 
122
124
  Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret (at least 32 characters)
123
125
  on the deployments that share sessions. Without this key, handles are neither issued nor used.
@@ -131,7 +133,7 @@ is configured. This change keeps the released SDK dependencies; adopting the SDK
131
133
  enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
132
134
  which may contain private server baggage. The signature authenticates a handle; it does not hide its contents.
133
135
 
134
- The server checks that the handle addresses the requested inbox. Workflow still validates the
136
+ The server checks that the handle addresses the requested session's inbox. Workflow still validates the
135
137
  hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
136
138
  the current inbox again. An uncertain write is surfaced without submitting a second delivery.
137
139
 
@@ -182,10 +184,10 @@ for await (const event of session.stream({ follow: false })) {
182
184
  console.log(event.type);
183
185
  }
184
186
 
185
- await session.reset({ reason: "User requested a fresh session" });
187
+ await session.end({ reason: "User requested a fresh session" });
186
188
  ```
187
189
 
188
- `client.sessions` stores the session ID, stream cursor, and optional opaque inbox handle. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and reset leaves the handle pinned to the retired ID.
190
+ `client.sessions` stores the session ID, stream cursor, and optional opaque `inbox` value. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and `end()` leaves the handle pinned to the retired ID. Replace calls to the old `reset()` method with `end()`; use `client.sessions.create()` to start a different session. Upgrade the server before using a new client's `end()` method: earlier servers do not serve `/end`.
189
191
 
190
192
  A client can own many independent fixed sessions at once:
191
193