eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,19 +3,19 @@ title: "Session Context"
3
3
  description: "Use ctx.session and runtime accessors inside eve-managed execution."
4
4
  ---
5
5
 
6
- eve passes a runtime `ctx` to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to inspect the active session and reach resources bound to that execution.
6
+ The runtime `ctx` is the object eve passes to tool executors, hook handlers, channel event handlers, and connection auth and header resolvers. Use it to read the current session and reach resources for the code that is running.
7
7
 
8
8
  | Accessor | Provides | Full guide |
9
9
  | ---------------------------- | --------------------------------------------------------- | -------------------------- |
10
10
  | `ctx.session` | Session identity, turn metadata, auth, and parent lineage | This page |
11
11
  | `ctx.getSandbox()` | The current agent's live sandbox handle | [Sandbox](../sandbox) |
12
- | `defineState(name, initial)` | Durable typed state shared by runtime code in one session | [State](../concepts/state) |
12
+ | `defineState(name, initial)` | Typed state shared by runtime code in one session | [State](../concepts/state) |
13
13
 
14
- These APIs work only during eve-managed runtime execution. Calling them during module evaluation, discovery, or a build throws.
14
+ These APIs work only while eve runs your code. Calling them while a module loads, during discovery, or during a build throws.
15
15
 
16
16
  ## `ctx.session`
17
17
 
18
- `ctx.session` describes the durable session and active turn:
18
+ `ctx.session` describes the session and the active turn:
19
19
 
20
20
  ```ts title="agent/tools/who_called_me.ts"
21
21
  import { defineTool } from "eve/tools";
@@ -40,28 +40,28 @@ export default defineTool({
40
40
 
41
41
  Public fields include:
42
42
 
43
- - `id`: the durable session ID.
43
+ - `id`: the session ID.
44
44
  - `turn.id`: the current turn ID.
45
45
  - `turn.sequence`: the turn's position in the session.
46
46
  - `auth.current`: the caller for the active inbound turn.
47
47
  - `auth.initiator`: the caller that started the session.
48
48
  - `parent`: the parent call, session, root session, and turn for a child subagent session.
49
- - `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-hosting#recover-a-stranded-session) to read its earlier conversation.
49
+ - `predecessor`: present only when this session replaced a stranded one; `sessionId` names that earlier session. See [Recover a stranded session](./deployment/self-hosted-operations#recover-a-stranded-session) to read its earlier conversation.
50
50
 
51
- Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
51
+ Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Sessions that a top-level schedule starts use eve's app identity (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.
52
52
 
53
53
  ## `ctx.getSandbox()`
54
54
 
55
- Call `ctx.getSandbox()` when authored runtime code needs filesystem or process access in the current agent's sandbox:
55
+ `ctx.getSandbox()` returns a handle for filesystem and process access in the current agent's sandbox:
56
56
 
57
57
  ```ts
58
58
  const sandbox = await ctx.getSandbox();
59
59
  const result = await sandbox.run({ command: "npm test" });
60
60
  ```
61
61
 
62
- The accessor is asynchronous because eve may need to bind or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
62
+ The accessor is asynchronous because eve may need to attach or restore the sandbox. A subagent sees its own sandbox, not its parent's. The returned handle also exposes `stop()` and `delete()`; see [Sandbox lifecycle](../sandbox#lifecycle) for their behavior.
63
63
 
64
- When you need capabilities specific to the configured environment, pass its exported environment object. The return type preserves the environment's session capabilities. Provider-specific methods such as `setNetworkPolicy()` are not available from the no-argument accessor:
64
+ Pass the exported environment object to get methods specific to that environment. Provider-specific methods such as `setNetworkPolicy()` are not available from the no-argument accessor:
65
65
 
66
66
  ```ts
67
67
  import { environment } from "../sandbox";
@@ -70,11 +70,11 @@ const sandbox = await ctx.getSandbox(environment);
70
70
  await sandbox.setNetworkPolicy("deny-all");
71
71
  ```
72
72
 
73
- The environment must be the one configured for the current sandbox. eve rejects a different environment instead of returning a handle with capabilities that may not exist.
73
+ The environment must be the one configured for the current sandbox; eve rejects any other.
74
74
 
75
75
  ## Custom state with `defineState`
76
76
 
77
- Use `defineState` for durable per-session values that tools, hooks, and channel handlers share. Unlike the `ctx` accessors, import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still require active eve execution. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
77
+ `defineState` declares a per-session value that tools, hooks, and channel handlers share. The value survives crashes and redeploys. Import it from `eve/context` and declare the handle at module scope. Its `get()` and `update()` methods still work only while eve runs your code. See [State](../concepts/state) for the read, update, reset, and subagent-isolation model.
78
78
 
79
79
  ## Where these APIs work
80
80
 
@@ -85,14 +85,14 @@ Runtime context is available:
85
85
  - inside channel and agent hook callbacks that receive the full runtime `ctx`;
86
86
  - after asynchronous boundaries within the same authored execution chain.
87
87
 
88
- Runtime context is not available during top-level module evaluation, build scripts, or discovery. Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from an eve-managed callback.
88
+ Declare reusable definitions and state handles at module scope, but call their context-dependent methods only from a callback that eve runs.
89
89
 
90
90
  ## How it works
91
91
 
92
- eve establishes the managed context before invoking authored runtime code and keeps it available across asynchronous work in that execution chain. The framework binds durable session data and step-local resources, then commits mutable state at the step boundary. Authored code uses the public accessors rather than managing this lifecycle.
92
+ eve sets up session data and per-step resources before your code runs. They stay available across asynchronous work in the same call chain. eve saves state changes at the end of the step.
93
93
 
94
94
  ## What to read next
95
95
 
96
- - [State](../concepts/state): durable typed values scoped to one session.
96
+ - [State](../concepts/state): typed values that belong to one session.
97
97
  - [Sandbox](../sandbox): runtime filesystem and process access.
98
- - [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): the durable session and event contract.
98
+ - [Sessions, runs, and streaming](../concepts/sessions-runs-and-streaming): how sessions and their events work.
@@ -4,11 +4,11 @@ description: "Discover and install extensions and other integrations from eve an
4
4
  contentType: "How-to"
5
5
  ---
6
6
 
7
- Install integrations from eve's official catalog, a third-party source, or an integration URL. Integrations are distributed using the [shadcn registry format](https://ui.shadcn.com/docs/registry).
7
+ An integration is a set of project files and dependencies, such as an extension, channel, or memory provider. `eve add` installs integrations from eve's official catalog, a third-party source, or a URL. Integrations use the [shadcn registry format](https://ui.shadcn.com/docs/registry).
8
8
 
9
9
  ## Install an integration
10
10
 
11
- Run `eve add` from an eve agent project. This installs the integration's dependencies and writes its declared files into your project.
11
+ Run `eve add` from an eve agent project to install the integration's dependencies and write its files into your project.
12
12
 
13
13
  ```bash
14
14
  eve add extension/agent-browser
@@ -17,19 +17,27 @@ eve add instrumentation/braintrust
17
17
  eve add memory/file
18
18
  ```
19
19
 
20
- If an item is not found, `eve add` searches the available catalogs and prints close matches without installing anything.
20
+ If an item isn't found, `eve add` prints close matches from the available catalogs without installing anything.
21
21
 
22
- Web Chat installs a shared Next.js or TanStack Start application at `apps/web` for either a standalone agent or a selected member of an agent workspace. The installer asks which framework to use (`web-framework`), then how to deploy it; non-interactive runs use Next.js unless you answer `web-framework="tanstack"`. Choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services, or the framework (**Next.js** or **TanStack Start**) to serve Web Chat and route agent requests through one app. Vercel services run locally without a linked Vercel project; link one when you are ready to deploy. Existing authored Next.js or Vercel configuration is preserved, and eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement, and [Next.js](./guides/frontend/nextjs) or [TanStack Start](./guides/frontend/tanstack) for framework-owned integration.
22
+ Web Chat installs a Next.js or TanStack Start application at `apps/web` for a standalone agent or a selected workspace member. The installer asks for the framework (`web-framework`), then the deployment. Non-interactive runs use Next.js unless you answer `web-framework="tanstack"`.
23
23
 
24
- If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
24
+ For the deployment, choose **Vercel services** (recommended) to deploy Web Chat and agents as separate services. Choose the framework (**Next.js** or **TanStack Start**) to serve Web Chat and route agent requests through one app. Vercel services run locally without a linked Vercel project. If you already have Next.js or Vercel configuration, eve stops with manual composition guidance instead of overwriting it. See [Project Structure](./concepts/project-structure) for browser-app placement, and [Next.js](./guides/frontend/nextjs) or [TanStack Start](./guides/frontend/tanstack) for framework-owned integration.
25
25
 
26
- Extensions may create a mount under `agent/extensions/`. For example, `eve add eve/self-modification` creates an authored self-modification mount. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can install and configure multiple exporters independently. Configure generated files and required environment variables before running your agent.
26
+ Run `eve add` without an argument to see how to search the registry with `eve registry search <query>`.
27
27
 
28
- When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the item's declared flows from the beginning.
28
+ Each kind of integration writes files in its own directory:
29
29
 
30
- For example, `eve add memory/file` can provision its required storage through the same setup flow. After **Install and set up**, eve creates or reuses a dedicated private Vercel Blob store, connects production, preview, and development with namespaced credentials, pulls the environment, and offers to deploy. The review and setup transcript show the project, store, primary function region, environments, and possible Blob usage charges before provisioning.
30
+ - Extensions may create a mount under `agent/extensions/`, as `eve add eve/self-modification` does.
31
+ - Connections write a definition under `agent/connections/` and install `@vercel/connect` when required.
32
+ - Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can configure several exporters independently.
31
33
 
32
- An official item may identify optional pnpm dependencies that have build scripts. Before installation, eve asks whether to skip those optional packages, allow their build scripts, or abort. Your choice updates `ignoredOptionalDependencies` or `allowBuilds` in the pnpm workspace that owns the project. Allow build scripts only when you trust the packages named in the prompt.
34
+ Configure generated files and required environment variables before running your agent.
35
+
36
+ When an official item has interactive setup steps, eve asks whether to run them after installation. To resume a skipped or cancelled setup, run the printed `eve add <item> --skip-install` command, which reruns the setup from the beginning.
37
+
38
+ For example, setup for `eve add memory/file` creates or reuses a private Vercel Blob store, connects it to production, preview, and development, and offers to deploy. Before provisioning, it shows the project, store, region, environments, and possible Blob usage charges. See [File memory](./memory/file).
39
+
40
+ An official item may name optional pnpm dependencies that have build scripts. Before installation, eve asks whether to skip those packages, allow their build scripts, or abort. It records your choice in `ignoredOptionalDependencies` or `allowBuilds` in the owning pnpm workspace. Allow build scripts only when you trust the packages named in the prompt.
33
41
 
34
42
  ## Automate setup
35
43
 
@@ -41,7 +49,7 @@ Use `eve add <item> --non-interactive` when a script or coding agent cannot answ
41
49
  | `1` | Installation or setup failed. |
42
50
  | `2` | Setup needs an answer or an unmet prerequisite. |
43
51
 
44
- On exit code `2`, read the final event and run its `next.command`. For a non-secret question, replace its `<JSON value>` placeholder with the answer you collected. Never pass a secret in `--answer`; use the environment variable or secret store the integration documents. Add `--yes` to accept recommended values; explicit answers take precedence.
52
+ On exit code `2`, read the final event and run its `next.command`. For a non-secret question, replace its `<JSON value>` placeholder with the answer you collected. Never pass a secret in `--answer`. Use the environment variable or secret store the integration documents instead. Add `--yes` to accept recommended values; explicit answers take precedence.
45
53
 
46
54
  A setup may report `eve link` as a prerequisite. Run it, then retry the continuation. See [Deployment](./guides/deployment/vercel.mdx) for the non-interactive `eve link` and `eve deploy` forms.
47
55
 
@@ -55,7 +63,7 @@ List every official integration and configured third-party source:
55
63
  eve registry list
56
64
  ```
57
65
 
58
- Search the catalog when you know what capability you need. Search returns up to 10 matches by default; use `--limit` to request between 1 and 100:
66
+ Search the catalog by what an integration does. Omit `--limit` to return up to 10 matches, or set it between 1 and 100:
59
67
 
60
68
  ```bash
61
69
  eve registry search browser --limit 5
@@ -110,13 +118,11 @@ eve add https://registry.acme.com/r/analytics.json
110
118
 
111
119
  ## Contribute an official integration
112
120
 
113
- Community contributions to the official registry are welcome. Open an issue and get maintainer agreement before submitting a pull request, then follow the [registry contribution guide](https://github.com/vercel/eve/blob/main/CONTRIBUTING.md#adding-an-integration-to-the-registry) for the required source files, metadata, validation, and extension requirements.
121
+ Open an issue and get maintainer agreement before you submit a pull request to the official registry. Then follow the [registry contribution guide](https://github.com/vercel/eve/blob/main/CONTRIBUTING.md#adding-an-integration-to-the-registry) for the required source files, metadata, validation, and extension requirements.
114
122
 
115
123
  ## Host your own registry
116
124
 
117
- Hosting your own registry is the publishing side of the [third-party source workflow](#add-a-third-party-source). Once it is deployed, other eve projects can give it a namespace and pull integrations from it.
118
-
119
- An eve registry is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so it can be hosted by any service that serves JSON over HTTP. It needs two kinds of endpoint:
125
+ A hosted registry is what other eve projects add as a [third-party source](#add-a-third-party-source). It is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so any service that serves JSON over HTTP can host it. It needs two kinds of endpoint:
120
126
 
121
127
  - A catalog such as `https://registry.acme.com/r/registry.json` for `eve registry list` and `eve registry search`
122
128
  - One JSON document per integration, such as `https://registry.acme.com/r/analytics.json`, for `eve registry view` and `eve add`
@@ -156,7 +162,7 @@ registry/
156
162
  }
157
163
  ```
158
164
 
159
- `files[].path` is relative to `registry.json`. `files[].target` is relative to the root of the eve project that installs the item. Use `registry:item` with explicit `registry:file` targets for eve integrations so installation does not depend on a UI framework or shadcn project aliases.
165
+ `files[].path` is relative to `registry.json`, and `files[].target` to the root of the installing eve project. Use `registry:item` with explicit `registry:file` targets so installation doesn't depend on a UI framework or shadcn project aliases.
160
166
 
161
167
  Validate the source registry, then build its static JSON:
162
168
 
@@ -165,7 +171,7 @@ pnpm dlx shadcn@latest registry validate
165
171
  pnpm dlx shadcn@latest build
166
172
  ```
167
173
 
168
- By default, the build writes the catalog to `public/r/registry.json` and each item to `public/r/<name>.json`. Deploy the `public` directory to a static host, or use the shadcn registry APIs to serve the same payloads from dynamic routes.
174
+ The build writes the catalog to `public/r/registry.json` and each item to `public/r/<name>.json`. Deploy the `public` directory to a static host, or use the shadcn registry APIs to serve the same payloads from dynamic routes.
169
175
 
170
176
  Before sharing the registry, test its deployed catalog and item endpoints from an eve project:
171
177
 
@@ -174,7 +180,7 @@ eve registry list --registry https://registry.acme.com/r/registry.json
174
180
  eve registry view https://registry.acme.com/r/analytics.json
175
181
  ```
176
182
 
177
- Share the item URL template with consumers. From another eve project, they can add the hosted registry as a third-party source and pull the integration through its namespace:
183
+ Share the item URL template with consumers, who add it as a third-party source:
178
184
 
179
185
  ```bash
180
186
  eve registry add @acme=https://registry.acme.com/r/{name}.json
@@ -183,17 +189,13 @@ eve add @acme/analytics
183
189
 
184
190
  ## Configure generated files
185
191
 
186
- Integrations add project files. Read the generated mount before you run the agent, then add the configuration the extension requires.
187
-
188
- For an extension, this usually means setting environment variables and editing the file under `agent/extensions/`. See [Extensions](./extensions) for mount configuration, namespacing, and overrides.
192
+ Read the generated files before you run the agent. For an extension, this usually means setting environment variables and editing the mount under `agent/extensions/`. See [Extensions](./extensions) for mount configuration, namespacing, and overrides.
189
193
 
190
194
  Provider-specific setup lives in the [Integrations directory](/integrations). Follow that guidance for credentials, approval policies, and service-specific options.
191
195
 
192
196
  ## Update an installed integration
193
197
 
194
- Treat generated files as project code. Commit or review local changes before you install the integration again.
195
-
196
- Run the same command when the registry publisher provides an updated scaffold:
198
+ Generated files are project code, so commit or review local changes before you install again. Run the same command to get the publisher's updated scaffold:
197
199
 
198
200
  ```bash
199
201
  eve add extension/agent-browser
@@ -3,11 +3,11 @@ title: "Instructions"
3
3
  description: "Add system context or durable user context with instructions.md or instructions.ts."
4
4
  ---
5
5
 
6
- Instructions add context without waiting for a person or channel to send it. Use system-role instructions for the agent's identity and standing rules. Use user-role instructions for application context that should become part of the durable conversation, such as an imported brief or retrieved memory.
6
+ Instructions are text you write for the model in `agent/instructions.md` or `agent/instructions.ts`. Use system-role instructions for the agent's identity and standing rules. Use user-role instructions for application context that belongs in the conversation history, such as an imported brief or retrieved memory.
7
7
 
8
8
  ## Author instructions
9
9
 
10
- At minimum, instructions are a markdown file at the agent root. Whatever you write is the prompt:
10
+ The smallest instructions are a markdown file at the agent root. Its contents are the prompt:
11
11
 
12
12
  ```md title="agent/instructions.md"
13
13
  You are a concise assistant. Use tools when they are available.
@@ -15,82 +15,77 @@ You are a concise assistant. Use tools when they are available.
15
15
 
16
16
  Keep this file to stable behavior such as identity, tone, and standing rules.
17
17
 
18
- ## Markdown vs TypeScript
18
+ ## System and user roles
19
19
 
20
- A static system prompt belongs in markdown (`agent/instructions.md`). Switch to a TypeScript module (`agent/instructions.ts`) when you need typed composition, `lib/` code, build-time values, or a user-role message.
20
+ System-role instructions stay outside the conversation history, and eve includes them on every model call. When you deploy a new version, or `eve dev` reloads, existing sessions use the current system instructions.
21
21
 
22
- ```ts title="agent/instructions.ts"
23
- import { defineInstructions } from "eve/instructions";
24
- import { buildInstructionsPrompt } from "./lib/prompts";
22
+ eve adds static user-role instructions to a new session's history once, in source order. A newer deployment doesn't add them again or replace them.
25
23
 
26
- export default defineInstructions({
27
- content: buildInstructionsPrompt(),
28
- });
29
- ```
24
+ ## Markdown vs TypeScript
30
25
 
31
- `defineInstructions` takes `content` and an optional `role`:
26
+ Put a static system prompt in markdown (`agent/instructions.md`). Switch to a TypeScript module (`agent/instructions.ts`) when you need typed composition, `lib/` code, build-time values, or a user-role message:
32
27
 
33
28
  ```ts title="agent/instructions/brief.ts"
34
29
  import { defineInstructions } from "eve/instructions";
35
30
  import { buildCustomerBrief } from "../lib/customer";
36
31
 
37
32
  export default defineInstructions({
38
- content: buildCustomerBrief(),
39
- role: "user",
33
+ content: buildCustomerBrief(), // blank content adds nothing
34
+ role: "user", // "system" or "user"; omit for "system"
40
35
  });
41
36
  ```
42
37
 
43
- `role` is either `"system"` or `"user"` and defaults to `"system"`. The retired `{ markdown: string }` form is rejected; use `content`. Blank content contributes no context.
38
+ The module, including its ESM and [asset imports](./reference/typescript-api#asset-imports) such as a prompt imported with `?raw`, runs once at build time and never at runtime. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
44
39
 
45
- A module-backed definition runs once at build time. eve stores its resolved content and role in the compiled manifest, so the definition is not a runtime entry.
46
-
47
- This includes its normal ESM and [asset imports](./reference/typescript-api#asset-imports), such as a top-level prompt imported with `?raw`. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle) for the full compile/runtime contract.
48
-
49
- ## System and user roles
40
+ ## Split instructions across a directory
50
41
 
51
- System-role instructions stay outside conversation history and are included on every model call. Existing sessions pick up the current compiled system instructions when a deployment or local development generation changes.
42
+ For more than one file, add an `agent/instructions/` directory. eve reads its `.md` files and `.ts` modules, but not subdirectories. A `.ts` file can export `defineInstructions` or `defineDynamic`. Static system and user entries apply in alphabetical filename order (`localeCompare`).
52
43
 
53
- Static user-role instructions are appended to a new session's history once, in source order. They remain pinned in that durable history: refreshing an existing session does not append them again or replace them with a newer deployment's value.
44
+ A root `agent/instructions.md` (or `.ts`) can sit beside the directory, and the root file comes first. Having both `instructions.md` and `instructions.ts` at the root is a build error.
54
45
 
55
- ## Split instructions across a directory
46
+ ## Dynamic instructions
56
47
 
57
- For more than one file, add an `agent/instructions/` directory. eve reads its entries non-recursively and accepts both `.md` files and `.ts` modules (a `.ts` file can wrap `defineInstructions` or `defineDynamic`). Static entries apply in alphabetical order by filename (`localeCompare`): system entries compose in that order, and user entries enter new-session history in that order.
48
+ To compute instructions from auth, tenant, channel, or external data, use `defineDynamic((ctx) => ...)` and return `defineInstructions(...)` or `null`. The function runs before each ordinary model call. Use `ctx.memo(key, fn)` to keep a JSON result fixed for a key.
58
49
 
59
- A flat `agent/instructions.md` (or `.ts`) at the agent root and the directory can coexist. The root file's content comes first, then the sorted directory entries. You cannot author both `instructions.md` and `instructions.ts` at the root; that pairing is a build error.
50
+ A dynamic system instruction applies, outside history, while the function returns it.
60
51
 
61
- ## Instructions vs skills
52
+ A dynamic user instruction joins the conversation history only when its content changes:
62
53
 
63
- Instructions and [skills](./skills) both feed text into the model's context. The difference is timing:
54
+ - Before a turn's first model call, it joins ahead of the turn's input.
55
+ - During a turn, a change appends at the current position.
56
+ - Returning `null` adds nothing and resets change tracking, so a later return of the earlier text adds it again.
57
+ - Existing history is not removed.
58
+ - Change tracking survives deployments, clear, and compaction.
64
59
 
65
- | | Loaded | Use for |
66
- | ------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
67
- | System-role instructions | Outside history on every model call | Permanent identity and standing rules |
68
- | User-role instructions | Once at their static or dynamic lifecycle boundary | Application context that belongs in conversation history |
69
- | `agent/skills/*` | On demand, when the model loads one with `eve__skill` | Optional procedures that should not bloat every turn |
60
+ See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior.
70
61
 
71
- Keep instructions short and stable. Long or situational procedures belong in [skills](./skills), where they only enter context when the request calls for them.
62
+ A session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) can receive the earlier conversation. In a user-role instruction, read the earlier session's stream with `sessions.attach()` and `transcriptOf()`, memoized by that session's ID.
72
63
 
73
- Static instructions never run code at runtime. When you need typed executable behavior, reach for a [tool](./tools).
64
+ ## History controls and prompt caching
74
65
 
75
- ## Dynamic instructions
66
+ [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-end) treats user-role instructions like any other history, so a summary can replace their text. Clear removes them with the rest of the conversation history and doesn't run static or dynamic instructions again. System-role instructions remain, because they are outside history.
76
67
 
77
- To compute instructions from auth, tenant, channel, or external data, use `defineDynamic((ctx) => ...)` and return `defineInstructions(...)` or `null`. The function runs before each ordinary model call. Use `ctx.memo(key, fn)` for JSON observations that should stay fixed for a key.
68
+ Keep system-role content stable and ahead of frequently changing context when you can, so providers can reuse the prompt prefix. Cache behavior and billing depend on the provider, and eve doesn't promise a cache hit.
78
69
 
79
- A dynamic system instruction applies while its function returns it, outside history. A dynamic user instruction joins durable history only when its content changes. Before a turn's first model call it joins ahead of the turn's input; mid-turn changes append at the current position. Returning `null` adds nothing and resets content tracking, so returning the earlier text later adds it again. Existing history is not removed. Content digests survive deployment changes, clear, and compaction.
70
+ User-role instructions only append, so they keep the earlier prompt prefix the same. eve's notes about available skills and parked agents are user-role history too. A changed note appends after earlier steps. eve skips an unchanged note until history is cleared or compacted.
80
71
 
81
- See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptOf()` in a user-role instruction that memoizes it by the predecessor's ID.
72
+ ## Instructions vs skills
82
73
 
83
- ## History controls and prompt caching
74
+ Instructions and [skills](./skills) both add text to the model's context, at different times:
84
75
 
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.
76
+ | | Loaded | Use for |
77
+ | ------------------------ | ----------------------------------------------------- | -------------------------------------------------------- |
78
+ | System-role instructions | Outside history on every model call | Permanent identity and standing rules |
79
+ | User-role instructions | Once for static ones; on each change for dynamic ones | Application context that belongs in conversation history |
80
+ | `agent/skills/*` | On demand, when the model loads one with `eve__skill` | Optional procedures that should not bloat every turn |
86
81
 
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.
82
+ Keep instructions short and stable. Put long or situational procedures in [skills](./skills). Put typed behavior that runs code in a [tool](./tools), because static instructions never run code at runtime.
88
83
 
89
84
  ## Disclaimer
90
85
 
91
86
  As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
92
87
 
93
- Where an eve agent communicates with people, you may be required to disclose that they are interacting with an automated AI system where law requires it. eve does not add this disclosure automatically; configure it in your instructions and/or channel responses.
88
+ Where an eve agent communicates with people, law may require you to disclose that they are interacting with an automated AI system. eve doesn't add this disclosure; configure it in your instructions or channel responses.
94
89
 
95
90
  ## What to read next
96
91
 
@@ -4,11 +4,10 @@ description: "Implement the recall, capture, and tools contract so any store or
4
4
  ---
5
5
 
6
6
  A memory provider is an object with a `recall` handler and optional `capture`
7
- and `tools` handlers. eve calls those handlers at fixed points in the agent
8
- lifecycle and passes each one a locked scope key, the projected conversation,
9
- and a stable operation ID. Anything that can read and write under that key can
10
- be a provider. Package one as a library that exports a provider factory, or
11
- write one directly inside an agent.
7
+ and `tools` handlers. eve calls the handlers at fixed points in each turn. Each
8
+ handler receives the slot's scope key, the conversation, and an operation ID
9
+ that stays the same when eve runs the handler again. Package a provider as a
10
+ library that exports a factory, or write one inside an agent.
12
11
 
13
12
  ```ts title="agent/lib/notes-memory.ts"
14
13
  import { defineMemoryProvider } from "eve/memory";
@@ -74,15 +73,14 @@ prepended to its description.
74
73
 
75
74
  ## The provider contract
76
75
 
77
- `defineMemoryProvider()` accepts three surfaces. Omit any handler the provider
78
- does not need; `fileMemory()`, for example, implements recall and tools but no
79
- capture.
76
+ `defineMemoryProvider()` accepts three surfaces. Omit any optional handler the
77
+ provider doesn't need; `fileMemory()`, for example, has no capture.
80
78
 
81
- | Surface | Handlers | Responsibility |
82
- | --------- | -------------------------------------------- | -------------------------------------------------------- |
83
- | `recall` | `"turn.started"` (required) | Return messages to place in model context |
84
- | `capture` | `"turn.completed"`, `"compaction.requested"` | Observe settled history and write to the store |
85
- | `tools` | one function | Return model-facing operations bound to the locked scope |
79
+ | Surface | Handlers | Responsibility |
80
+ | --------- | -------------------------------------------- | ----------------------------------------------------- |
81
+ | `recall` | `"turn.started"` (required) | Return messages to place in model context |
82
+ | `capture` | `"turn.completed"`, `"compaction.requested"` | Read the finished conversation and write to the store |
83
+ | `tools` | one function | Return tools for the model, bound to the slot's scope |
86
84
 
87
85
  ### Operation context
88
86
 
@@ -94,7 +92,7 @@ Every handler receives a `MemoryOperationContext`:
94
92
  | `memory.scope.namespace` | The resolved namespace string |
95
93
  | `memory.scope.value` | The resolved scope string or tuple |
96
94
  | `memory.slot` | The path-derived slot name |
97
- | `messages` | Projected conversation history for this phase |
95
+ | `messages` | Conversation history for this phase |
98
96
  | `operationId` | Stable per session, turn, step, phase, and slot. Use it as an idempotency key. |
99
97
  | `abortSignal` | Cancellation for the operation |
100
98
  | `session` | Session ID, authentication, and other `SessionContext` fields |
@@ -125,13 +123,12 @@ return {
125
123
  };
126
124
  ```
127
125
 
128
- eve adds each message to the model calls as a user-role message attributed to
129
- the slot. Provider content is never promoted to system instructions.
126
+ eve adds each message to model calls as a user-role message attributed to the
127
+ slot, never as system instructions.
130
128
 
131
- What a turn recalls stays for the rest of the session: each turn's recall sits
132
- just before that turn's input in every later model call, so the prompt prefix
133
- stays cached. The `id` decides what a later recall
134
- does with it:
129
+ What a turn recalls stays for the rest of the session, just before that turn's
130
+ input in every later model call. The `id` decides what a later recall does with
131
+ it:
135
132
 
136
133
  | Message | Effect |
137
134
  | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -140,47 +137,44 @@ does with it:
140
137
 
141
138
  A result of `null`, `undefined`, or `{ messages: [] }` adds nothing and keeps
142
139
  what earlier turns recalled. Give every message a stable `id` when the provider
143
- returns its current state each turn, as `fileMemory()` does: without one, each
144
- turn adds another copy. Retrieval that returns different records each turn
145
- accumulates them for the session, and they count toward every model call's
146
- context. The `id` also identifies the record in
140
+ returns its current state each turn, as `fileMemory()` does, or each turn adds
141
+ another copy. Records that differ each turn accumulate for the session and
142
+ count toward every model call's context. The `id` also identifies the record in
147
143
  [instrumentation](../observability/instrumentation).
148
144
 
149
145
  ### Tools
150
146
 
151
147
  `tools()` returns a `MemoryToolSet`, a map of `defineTool()` values, or `null`. eve qualifies each
152
- key as `<slot>__<key>`; the qualified name must start with a letter, contain
153
- only letters, digits, underscores, or dashes, and be at most 64 characters.
148
+ key as `<slot>__<key>`. The qualified name must start with a letter, use only
149
+ letters, digits, underscores, or dashes, and be at most 64 characters.
154
150
  Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for
155
151
  authored tools.
156
152
 
157
- A tool closes over the locked scope, so it cannot be redirected to another
158
- tenant or caller by the model. Like recall, eve resolves the scope once per
159
- turn and principal and keeps it for that turn, so the tools and recall use the
160
- same scope. A new turn or principal resolves it again. A fresh process in the
161
- same turn, after a restart, calls `tools()` again with the kept scope rather
162
- than resolving it again.
153
+ A tool keeps the scope it was created with, so the model can't point it at
154
+ another tenant or caller. eve resolves the scope once per turn and caller, so
155
+ tools and recall use the same scope. A new turn or a new caller resolves it
156
+ again. After a restart within the same turn, eve calls `tools()` again with the
157
+ same scope.
163
158
 
164
159
  ## Lifecycle
165
160
 
166
161
  | Phase | Handler | `messages` contains |
167
162
  | ---------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
168
163
  | `turn.started` | `recall["turn.started"]` | The conversation the turn's first model call reads, with the turn's new input |
169
- | `turn.completed` | `capture["turn.completed"]` | Settled history after a successful turn |
164
+ | `turn.completed` | `capture["turn.completed"]` | The finished history after a successful turn |
170
165
  | `compaction.requested` | `capture["compaction.requested"]` | The history compaction is about to rewrite |
171
166
 
172
167
  eve recalls before the first model call of each turn, and again when the
173
- session's principal changes. Recalled messages stay outside history, so
168
+ session's caller changes. Recalled messages stay outside history, so
174
169
  compaction never summarizes them. When compaction summarizes a turn, that
175
170
  turn's recalled messages move to just after the summary.
176
171
 
177
- Before automatic or requested compaction rewrites history, eve calls
178
- `capture["compaction.requested"]` with the history it is about to rewrite, so a
179
- provider can keep detail the summary will lose. The summary waits for it.
172
+ Before compaction rewrites history, eve calls `capture["compaction.requested"]`
173
+ and waits for it, so a provider can keep detail the summary will lose.
180
174
 
181
- Calling `clear()` on a session removes its history and what earlier turns
182
- recalled. It does not touch the provider's store; the next turn recalls again.
183
- A new scope, such as another principal's, also starts over.
175
+ Calling `clear()` on a session removes its history and recalled messages but
176
+ not the provider's store, so the next turn recalls again. A new scope, such as
177
+ another caller's, also starts over.
184
178
 
185
179
  ## Failure behavior
186
180
 
@@ -225,5 +219,5 @@ provider:
225
219
 
226
220
  - [Memory overview](/docs/memory): slots, scope, and namespace.
227
221
  - [File memory](./file): the built-in provider as a reference implementation.
228
- - [Dynamic capabilities](../guides/dynamic-capabilities): how eve evaluates the dynamic tools provider tools run through.
222
+ - [Dynamic capabilities](../guides/dynamic-capabilities): provider tools run as dynamic tools; see how eve evaluates them.
229
223
  - [Default harness](../concepts/default-harness): compaction in the built-in loop.