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,57 +3,31 @@ title: "Sessions, Runs & Streaming"
3
3
  description: "The ID-addressed session contract: messages, controls, the NDJSON event stream, and reconnecting."
4
4
  ---
5
5
 
6
- Every eve app speaks the same stable HTTP API to a [durable session](./execution-model-and-durability). This page is the contract you hold: the handles you get back, the events you stream, and how to reconnect.
6
+ Every eve app serves the same stable HTTP API for [sessions](./execution-model-and-durability). The API returns a session handle, streams the session's events, and lets a reader reconnect from a cursor.
7
7
 
8
8
  ## Identity by surface
9
9
 
10
- The HTTP API and TypeScript client use one durable `sessionId` for messages,
11
- controls, and streams. Every operation targets that exact session; none follows
12
- or creates a replacement implicitly.
13
-
14
- The session ID currently identifies the original Workflow run that owns the
15
- event stream. A deployment or compaction handoff changes the executing run, not
16
- the session ID or stream. Stream namespaces belong to a run; eve does not support
17
- caller-assigned session IDs or globally addressed streams.
18
-
19
- Before handoff, eve validates that the saved session state has no pending work
20
- inside the workflow. The current owner keeps its inbox while the successor
21
- starts and validates the checkpoint. Once the successor takes over the session
22
- hooks, the original owner forwards messages it accepted during the move and
23
- parks on the stream anchor until the final owner reports the session result.
24
-
25
- Authored channels also have channel-local continuation tokens. A token addresses
26
- whichever session currently owns a platform conversation, such as a Slack thread.
27
- That identity stays behind the channel boundary and is never accepted or returned
28
- by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
29
-
30
- A session completes after 30 idle days by default; configure
31
- `limits.sessionTimeoutMs` in `agent.ts`, or set it to `false` to disable the
32
- timeout. The idle window restarts each time a turn settles, and a session never
33
- expires while a turn is open. At expiration, eve emits `session.ended` with `outcome: "completed"` and
34
- releases the session's continuation addresses so the next qualifying channel
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.
40
-
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.
10
+ The HTTP API and TypeScript client address a session by one `sessionId` for messages, controls, and streams. Every operation targets that exact session and never follows or creates a replacement implicitly.
11
+
12
+ The session ID and its event stream stay the same across a deployment or [compaction handoff](./execution-model-and-durability#compaction-handoff). eve doesn't support caller-assigned session IDs or globally addressed streams.
13
+
14
+ Authored channels also use channel-local continuation tokens. A token addresses whichever session currently holds a platform conversation, such as a Slack thread. The eve HTTP session API never accepts or returns these tokens. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
15
+
16
+ A session completes after 30 idle days by default. Set `limits.sessionTimeoutMs` in `agent.ts` to change the window, or `false` to disable it. The idle window restarts each time a turn ends. A session never expires while a turn is open. At expiration, eve emits `session.ended` with `outcome: "completed"` and releases the session's channel addresses. The next qualifying channel message then starts a fresh session. Stored data follows the session's [run-data retention policy](../agent-config#run-data-retention). Outside development, the default policy requests deletion when private and unknown-audience sessions end, if the Workflow world supports deletion. See [Agent config](../agent-config#runtime-limits).
17
+
18
+ React, Vue, and Svelte apps use [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes directly. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
42
19
 
43
20
  ## Start a session
44
21
 
45
- Create and park a conversation session before its first turn by omitting `message`:
22
+ Omit `message` to create a prewarmed session that waits for its first message:
46
23
 
47
24
  ```bash
48
25
  curl -X POST http://127.0.0.1:2000/eve/v1/session
49
26
  ```
50
27
 
51
- eve starts the durable workflow, establishes its inbox, and waits for the first message before
52
- running session-scoped initialization or emitting `session.started`. The first message sent to the returned
53
- `sessionId` remains `turn_0`. Message-free creation does not accept turn-scoped `clientContext`,
54
- `outputSchema`, callbacks, or activity observers.
28
+ The stream stays empty until the first message. Session setup and `session.started` are then recorded in the same line as that message's `delivery.admitted`, and the message is still `turn_0`. Creating a session without a message doesn't accept per-turn `clientContext`, `outputSchema`, callbacks, or activity observers.
55
29
 
56
- To create the session and start its first turn in one request, include the message:
30
+ Include `message` to create the session and start its first turn in one request:
57
31
 
58
32
  ```bash
59
33
  curl -X POST http://127.0.0.1:2000/eve/v1/session \
@@ -61,13 +35,7 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session \
61
35
  -d '{"message":"Summarize the latest forecast."}'
62
36
  ```
63
37
 
64
- In both forms, eve responds with `202` and the durable `sessionId` in the JSON body and
65
- `x-eve-session-id` header as soon as Workflow accepts the run. The command inbox can still be
66
- starting at that point. An immediate follow-up can return `409 session_not_ready`; retry that
67
- code with bounded backoff. The TypeScript client retries sends for up to 20 seconds and respects
68
- the caller's abort signal. A prewarmed session's stream stays empty until its first message:
69
- initialization and `session.started` wait for it, and commit in the same line as that message's
70
- `delivery.admitted`.
38
+ Both forms return `202` with the `sessionId` in the JSON body and the `x-eve-session-id` header as soon as the run is accepted. The session may not accept input yet, so an immediate follow-up can return `409 session_not_ready`. Retry that code with bounded backoff. The TypeScript client retries sends for up to 20 seconds and respects the caller's abort signal.
71
39
 
72
40
  ## Stream a session
73
41
 
@@ -75,44 +43,50 @@ initialization and `session.started` wait for it, and commit in the same line as
75
43
  curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
76
44
  ```
77
45
 
78
- The stream is newline-delimited JSON (NDJSON), stream version 27 (`x-eve-stream-version: 27`). Each stored line is either a **commit** or a **progress record**:
46
+ The stream is newline-delimited JSON (NDJSON), stream version 27 (`x-eve-stream-version: 27`). Each stored line is either an **event line** or a **progress record**:
79
47
 
80
48
  ```json
81
49
  {"at":"2026-07-27T18:04:11.912Z","facts":[{"type":"turn.settled","scope":{"turnId":"turn_0"},"data":{"turnId":"turn_0","outcome":"completed","reply":["part_0"]}},{"type":"delivery.settled","data":{"deliveryId":"d_1","outcome":"handled","turnId":"turn_0"}}]}
82
50
  {"progress":{"type":"content.delta","scope":{"turnId":"turn_1","runId":"run_2"},"data":{"partId":"part_3","delta":"Sunny"}}}
83
51
  ```
84
52
 
85
- - A **commit** (`{at, facts}`) holds every fact one state change produced, in order. Readers never see half of a commit: a turn that ends, the deliveries it answered, and the work it closed land together.
53
+ - An **event line** (`{at, facts}`) holds, in its `facts` array, every event one state change produced, in order. Readers never see half of a line: a turn that ends, the deliveries it answered, and the work it closed land together.
86
54
  - A **progress record** (`{progress}`) carries streamed output that no state depends on: text and reasoning deltas, streamed tool input, and preliminary tool output.
87
55
 
88
- The stream route also sends transport records that are not session events: `{"$eve":"heartbeat"}` while the stream is quiet, `{"$eve":"stream.lease-ended"}` when a renewable read ends so the reader reconnects, and `{"$eve":"stream.ended"}` once the session has ended and its stream is closed.
56
+ The stream route also sends transport records that aren't session events:
57
+
58
+ - `{"$eve":"heartbeat"}` while the stream is quiet.
59
+ - `{"$eve":"stream.lease-ended"}` when a renewable read ends. Reconnect from your cursor.
60
+ - `{"$eve":"stream.ended"}` once the session has ended and its stream is closed.
89
61
 
90
62
  ### Facts
91
63
 
92
- Facts are grouped into families. Lifecycle facts introduce, update, or settle an entity. Informational facts, such as `usage.recorded` and `child.sent`, record additional data without opening work that must later settle. Every fact carries `type` and `data`, and most carry a `scope` naming the turn, run, task, or context change it belongs to.
64
+ Each entry in `facts` is an event, and events are grouped into families. Most events open, update, or end an item, such as a turn or a call. Informational events, such as `usage.recorded` and `child.sent`, add data without opening anything that must end. Every event carries `type` and `data`, and most carry a `scope` naming the turn, run, task, or context change it belongs to.
65
+
66
+ | Family | Events | What it is |
67
+ | ------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
+ | `session` | `session.started`, `session.ended` | The session. `session.started` carries `runtime`, `parent` for a child session, `predecessor` when the session [replaced a stranded one](./execution-model-and-durability#what-a-replacement-session-receives), and `trace` when traced. `session.ended` has `outcome` `"completed"` or `"failed"`. |
69
+ | `delivery` | `delivery.admitted`, `delivery.consumed`, `delivery.settled` | One accepted message, answer, control, or callback. `delivery.consumed` carries the `parts` a turn received, and any `history` the delivery imported; `delivery.settled` reports what became of it. |
70
+ | `turn` | `turn.started`, `turn.paused`, `turn.settled` | A turn. `turn.paused` lists the requests for input it's `awaiting`. `turn.settled` has `outcome` `"completed"`, `"failed"`, or `"cancelled"` and, when completed, the `reply` part ids. |
71
+ | `model` | `model.requested`, `model.started`, `model.retried`, `model.settled` | One model run, for a turn or a context change. `model.started` names the `modelId` and `attempt` for each attempt. `model.retried` records a failed attempt that runs again. `model.settled` carries `outcome` and `finishReason`. |
72
+ | `content` | `content.completed` | One finished part of model output: `kind` `"text"`, `"reasoning"`, `"result"`, or `"file"`, its `value`, and its `phase`: `"reply"` or `"narration"`. |
73
+ | `call` | `call.requested`, `call.started`, `call.settled` | One tool, agent, or skill call. `call.requested` names the tool, agent, or skill in `capability` (`remote: true` for a remote agent) and its `input`. `call.started` carries `taskId` for a task and `clearedBy` when an approval or policy let it run. `call.settled` carries `outcome` and `output` or `error`. |
74
+ | `task` | `task.started`, `task.ended` | Work that outlives the call that started it, such as an agent tool's child session. See [Task events](#task-facts). |
75
+ | `interaction` | `interaction.opened`, `interaction.settled` | A person's approval, question, budget prompt, or sign-in. |
76
+ | `response` | `response.submitted`, `response.admitted`, `response.settled` | One answer to a request for input, tied to the delivery it arrived in. |
77
+ | `child` | `child.opened`, `child.sent` | A child session a call opened. `child.opened` carries its `sessionId`, `name`, and `stream` path. `child.sent` links a delivery the child accepted, as `childDeliveryId`, to the `callId` that sent it. |
78
+ | `context` | `context.started`, `context.settled` | A context change: `kind` `"compaction"` or `"clear"`. |
79
+ | `usage` | `usage.recorded` | Model spend, tied to the run, call, or context change that spent it. |
93
80
 
94
- | Family | Facts | What it is |
95
- | ------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96
- | `session` | `session.started`, `session.ended` | The session. `session.started` carries `runtime`, `parent` for a child session, `predecessor` when the session [replaced a stranded one](./execution-model-and-durability#what-a-replacement-session-receives), and `trace` when traced. `session.ended` has `outcome` `"completed"` or `"failed"`. |
97
- | `delivery` | `delivery.admitted`, `delivery.consumed`, `delivery.settled` | One accepted message, answer, control, or callback. `delivery.consumed` carries the `parts` a turn received, and any `history` the delivery imported; `delivery.settled` reports what became of it. |
98
- | `turn` | `turn.started`, `turn.paused`, `turn.settled` | A turn. `turn.paused` lists the interactions it's `awaiting`. `turn.settled` has `outcome` `"completed"`, `"failed"`, or `"cancelled"` and, when completed, the `reply` part ids. |
99
- | `model` | `model.requested`, `model.started`, `model.retried`, `model.settled` | One model run, owned by a turn or a context change. `model.started` names the `modelId` and the `attempt`, once per attempt; `model.retried` records an attempt that failed and is tried again; `model.settled` carries `outcome` and `finishReason`. |
100
- | `content` | `content.completed` | One finished part of model output: `kind` `"text"`, `"reasoning"`, `"result"`, or `"file"`, its `value`, and its `phase`: `"reply"` or `"narration"`. |
101
- | `call` | `call.requested`, `call.started`, `call.settled` | One tool, agent, or skill call. `call.requested` names its `capability` and `input`, and a remote agent's capability has `remote: true`; `call.started` carries `taskId` when the call reaches a task and `clearedBy` when an approval or policy let it run; `call.settled` carries `outcome` and `output` or `error`. |
102
- | `task` | `task.started`, `task.ended` | Work that outlives the call that started it, such as an agent tool's child session. See [Task facts](#task-facts). |
103
- | `interaction` | `interaction.opened`, `interaction.settled` | A person's approval, question, budget prompt, or sign-in. |
104
- | `response` | `response.submitted`, `response.admitted`, `response.settled` | One answer to an interaction, tied to the delivery it arrived in. |
105
- | `child` | `child.opened`, `child.sent` | A child session a call opened; `child.opened` carries its `sessionId`, `name`, and the `stream` path to follow. `child.sent` links a delivery the child accepted to the `callId` that sent it, with the delivery's `childDeliveryId` in the child's stream. |
106
- | `context` | `context.started`, `context.settled` | A context change: `kind` `"compaction"` or `"clear"`. |
107
- | `usage` | `usage.recorded` | Model spend, owned by the run, call, or context change that spent it. |
81
+ Progress records come in three types:
108
82
 
109
- The conversation is a chain of turns. Each `turn.started` names the turn it `follows`, the one whose conversation it continues, or `null` for a first turn. A completed `context.settled` can change the conversation with `selects`: `null` empties it, as a clear does, and `{ turnId }` makes that earlier turn its newest, leaving out the turns after it. The next turn then follows the selected one. Either can name any earlier turn, so read the conversation with `conversation(view)` instead of assuming it holds every turn in order.
83
+ - `content.delta`: a text or reasoning delta for a `partId`.
84
+ - `call.input`: a raw tool-input delta for a `callId`.
85
+ - `call.progress`: a preliminary output snapshot for a `callId`.
110
86
 
111
- Progress records are `content.delta` (a text or reasoning delta for a `partId`), `call.input` (a raw tool-input delta for a `callId`), and `call.progress` (a preliminary output snapshot for a `callId`).
87
+ A call's label is `capability.label` before execution, `call.progress.data.label` in a progress snapshot, and `call.settled.data.label` at completion; `call(view, callId)?.label` reads the final one. A prompt's heading is `request.title`.
112
88
 
113
- Call labels use `capability.label` before execution, `call.progress.data.label` for a progress
114
- snapshot, and `call.settled.data.label` at completion. Read the final label with
115
- `call(view, callId)?.label`. A prompt's heading is `request.title`.
89
+ The conversation is a chain of turns. Each `turn.started` names the turn it `follows`, or `null` for a first turn. A completed `context.settled` can change the conversation with `selects`: `null` empties it, as a clear does, and `{ turnId }` makes that earlier turn the newest, leaving out the turns after it. The next turn then follows the selected turn. Because either can name any earlier turn, read the conversation with `conversation(view)` instead of assuming it holds every turn in order.
116
90
 
117
91
  The full catalog, its outcome sets, and TypeScript types are exported from `eve/events`, along with the shared fold and queries over [opaque session snapshots](#query-session-state):
118
92
 
@@ -131,59 +105,59 @@ session has ended. These helpers come from `eve/events`.
131
105
 
132
106
  Within stream version 27, a later minor release can add:
133
107
 
134
- - fact types that only add information: a new family, or an update to a row such as `model.retried`, never the only way an entity opens or ends;
108
+ - informational event types, such as a new family or a row update like `model.retried`;
135
109
  - progress record types;
136
110
  - optional fields;
137
111
  - outcomes, interaction kinds, context-change kinds, displays, and option styles.
138
112
 
139
- It never removes or renames a fact or field, changes what a fact means or which role it plays in its entity's lifecycle, or adds a required field. Anything else is a new stream version, which readers refuse.
113
+ A new event type is never the only way an item opens or ends. A minor release never removes or renames an event type or field, and never adds a required field. It never changes what an event means or whether it opens, updates, or ends its item. Any other change is a new stream version, which readers refuse.
140
114
 
141
- Readers stay correct across these additions: they ignore fact and progress types and fields they don't know, and a terminal fact with an outcome they don't know still ends its row, keeping the outcome as sent. The TypeScript types name today's values only, so when you switch on an outcome, kind, display, or style, keep a default branch.
115
+ Readers ignore event types, progress types, and fields they don't know. An ending event with an unknown outcome still ends its row and keeps the outcome as sent. The TypeScript types name only current values, so keep a default branch when you switch on an outcome, kind, display, or style.
142
116
 
143
- The fold skips positions it has already seen after reconnect. For retained lifecycle rows, repeated introductions and terminals are ignored; status-gated updates cannot reopen ended rows. Progress and usage at new positions are not deduplicated.
117
+ After a reconnect, `foldEvents` skips positions it has already seen. It ignores a repeated start or end of a row it holds, and an update can't reopen an ended row. It doesn't deduplicate progress and usage at new positions.
144
118
 
145
- The optional `data.trace` on `session.started` and `turn.started` contains eve-owned W3C trace coordinates: `traceId`, `spanId`, and `traceFlags`. Use it to correlate stream consumers such as eval reporters with an observability backend. An uninstrumented target omits it.
119
+ `session.started` and `turn.started` carry an optional `data.trace` with W3C trace coordinates: `traceId`, `spanId`, and `traceFlags`. Use them to correlate stream consumers, such as eval reporters, with an observability backend. An uninstrumented target omits it.
146
120
 
147
121
  ### Streamed output
148
122
 
149
- `content.delta` and `call.input` carry only their new text. Accumulate them in stream order, per `partId` or `callId`, when you need the text so far. When the durable writer is busy, eve may merge adjacent deltas for the same part or call; the resulting text and ordering stay the same. `content.completed` carries the authoritative value of each finished part, so a reader that reconnects without its accumulated text can wait for it instead of replaying the deltas.
123
+ `content.delta` and `call.input` carry only new text; accumulate them in stream order per `partId` or `callId`. eve may merge adjacent deltas for the same part or call without changing the text or its order. `content.completed` carries each finished part's final value. A reader that reconnects without its accumulated text can wait for it instead of replaying deltas.
150
124
 
151
- When a streamed tool input becomes a validated call, its `call.input` records precede its `call.requested`. The client shows the potentially incomplete JSON as a `tool` part with `state: "streaming"` and its `inputText`, then as `state: "requested"` with the validated `input` on `call.requested`.
125
+ A streamed tool input's `call.input` records precede its `call.requested`. The client shows the possibly incomplete JSON as a `tool` part with `state: "streaming"` and its `inputText`, then as `state: "requested"` with the validated `input`.
152
126
 
153
- `call.progress` carries one complete preliminary output snapshot from an authored async-generator tool. A later snapshot for the same `callId` replaces it, and `call.settled` carries the final output. Treat snapshots as last-write-wins. Provider-executed tool progress and MCP progress notifications are not projected as `call.progress`.
127
+ `call.progress` carries one complete preliminary output snapshot from an authored async-generator tool. Treat snapshots for a `callId` as last-write-wins; `call.settled` carries the final output. Provider-executed tool progress and MCP progress notifications don't appear as `call.progress`.
154
128
 
155
- A call the model makes through [`eve__tool` or `eve__skill`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) is reported as a call to the entry it names. Its `call.requested` carries that entry's name and input, such as `linear__list_issues`, never the catalog tool's. An `eve__skill` call has `capability: { kind: "skill", name }`. The model's own task controls, `eve__task_wait` and `eve__task_cancel`, have `kind: "control"`; activity views usually leave them out. A `call.input` that announces a call carries the same `kind` beside its `name`. Calls through either tool publish no `call.input`, because their entry is known only once their input is complete.
129
+ A call through [`eve__tool` or `eve__skill`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) is reported as a call to the entry it names. Its `call.requested` carries that entry's name and input, such as `linear__list_issues`. An `eve__skill` call has `capability: { kind: "skill", name }`. The task controls `eve__task_wait` and `eve__task_cancel` have `kind: "control"`, and activity views usually leave them out. A `call.input` that announces a call carries the same `kind` beside its `name`. Calls through `eve__tool` or `eve__skill` publish no `call.input`, because eve knows the entry only once the input is complete.
156
130
 
157
131
  Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning content in your application.
158
132
 
159
133
  ### Replies and narration
160
134
 
161
- A model often writes text before it calls a tool. Each text part's `content.completed.data.phase` tells you which it is: `"narration"` for text written on the way to more work, `"reply"` for the turn's answer. `turn.settled.data.reply` lists the reply's part ids, so a reader that only needs the answer can wait for the turn to settle and read those parts. `reply(ctx.view, turnId)` returns those parts in a hook or channel handler without exposing the backing table. When a turn requested an output schema, the structured result is a `content.completed` with `kind: "result"`.
135
+ Each text part's `content.completed.data.phase` is `"reply"` for the turn's answer. It's `"narration"` for text written on the way to more work, such as before a tool call. `turn.settled.data.reply` lists the reply's part ids, so a reader that needs only the answer can wait for the turn to end. In a hook or channel handler, `reply(ctx.view, turnId)` returns them. A turn that requested an output schema reports the structured result as a `content.completed` with `kind: "result"`.
162
136
 
163
- Spend is recorded on `usage.recorded`, once per model run (`owner: { runId }`) and once per delegated call for what the agent it called spent (`owner: { callId }`). Model spend includes compaction summary calls: the summary run belongs to its context change, not to an ordinary model step. A completed summary's usage stays counted even when a hook cancels the turn as compaction settles. Spend a task reports after its calls settled has no owner and `kind: "delegated-late"`. A session's total is the sum of its records; `usage(view).total` returns it. `costUsd` is absent when no recorded spend reported a cost. The usage window that [`limits.sessionUsage`](../agent-config#runtime-limits) reads starts at that total on the line where the session's own budget prompt settles `accepted`.
137
+ `usage.recorded` records spend once per model run (`owner: { runId }`). It also records once per delegated call for what the called agent spent (`owner: { callId }`). A compaction summary run belongs to its context change. Its usage stays counted even when a hook cancels the turn as compaction finishes. Spend a task reports after its calls end has no `owner` and has `kind: "delegated-late"`. `usage(view).total` returns the sum of the session's records. `costUsd` is absent when no record reported a cost. The usage window that [`limits.sessionUsage`](../agent-config#runtime-limits) reads starts at that total on the line where the session's own budget prompt is accepted.
164
138
 
165
139
  ### Deliveries and responses
166
140
 
167
- 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):
141
+ A delivery is anything that reaches a session: a message, an answer, a control such as `cancel` or `end`, or a sign-in callback. `delivery.admitted` records it with the sender in `principal` and its `source`. When a turn takes in a message, `delivery.consumed` carries the `parts` it received and any imported [prior history](../channels/eve#start-from-prior-history) in `history`. Parts hold text and file metadata, without raw bytes or sandbox paths. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
142
+
143
+ | Outcome | Meaning |
144
+ | ---------------- | --------------------------------------------------------------------------------------- |
145
+ | `handled` | The turn that took it in ended. |
146
+ | `awaiting-input` | The turn paused for an approval, question, or sign-in. A later answer resumes the turn. |
147
+ | `applied` | A control or answer took effect. |
148
+ | `ignored` | It had nothing to act on, or a cancel or clear ended its turn before the turn read it. |
149
+ | `refused` | Its sender may not do what it asked; `reason` says why. |
150
+ | `failed` | It couldn't be handled, such as when the session ended first. |
151
+
152
+ `POST /eve/v1/session/:sessionId` returns the message's `deliveryId`. A client resuming from an old cursor uses it to find the `delivery.settled` that ends its response. Steering and coalesced messages each keep their own delivery. An answer-only delivery stops on its own `delivery.settled`.
168
153
 
169
- | Outcome | Meaning |
170
- | ---------------- | --------------------------------------------------------------------------------------------------- |
171
- | `handled` | The turn that consumed it settled. |
172
- | `awaiting-input` | The turn paused on an interaction. The delivery's answer is the pause; the answer resumes the turn. |
173
- | `applied` | A control or answer took effect. |
174
- | `ignored` | It had nothing to act on, or a cancel or clear ended its turn before the turn read it. |
175
- | `refused` | Its sender may not do what it asked; `reason` says why. |
176
- | `failed` | It couldn't be handled, such as when the session ended first. |
154
+ Ending a stranded session records the end's `delivery.admitted` and `delivery.settled` before the session ends, with `session.ended.data.cause.deliveryId` naming that delivery. The recorded control is `source: { control: "reset" }`.
177
155
 
178
- `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,
179
- not derived from stream position. An answer-only delivery stops on its own `delivery.settled`.
180
- Ending a stranded session records the control's admission and settlement, with
181
- `session.ended.data.cause.deliveryId` naming that delivery. Its stream control value
182
- remains `"reset"` for compatibility with recorded history.
183
- 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.
156
+ A control that the session's eve version doesn't support, such as one added in a later release, settles `failed` with a `reason` that names it. Sessions started by eve versions without this check drop the control, and its delivery never settles.
184
157
 
185
- To follow an accepted receipt in a client view, use `delivery(view, receipt.deliveryId)` from
186
- `eve/events`:
158
+ When someone other than the turn's caller sends an answer and a message together, they become separate deliveries. The answer reaches the waiting turn, and the message keeps the receipt and waits. Follow the answer through the request it answers.
159
+
160
+ To follow an accepted receipt in a client view, use `delivery(view, receipt.deliveryId)` from `eve/events`:
187
161
 
188
162
  | Observation | Meaning |
189
163
  | -------------------- | ----------------------------------------------------------------------------------------- |
@@ -192,47 +166,56 @@ To follow an accepted receipt in a client view, use `delivery(view, receipt.deli
192
166
  | `status: "consumed"` | A turn took the input; `turnId` identifies it. |
193
167
  | `status: "settled"` | The delivery ended; `outcome` says how. |
194
168
 
195
- A `session.ended` event also ends the wait. After a degraded termination that could not record
196
- all closures, a retained delivery may still say `admitted` or `consumed`; do not wait for another
197
- `delivery.settled` on a closed stream.
169
+ A `session.ended` event also ends the wait. A degraded termination may not record every ending, so a retained delivery can still say `admitted` or `consumed`. Don't wait for another `delivery.settled` on a closed stream.
198
170
 
199
- Client views retain observed history; hook and channel views can prune older settled deliveries. An arbitrary ID without an accepted receipt cannot distinguish an unknown delivery from one not yet admitted. `Delivery.result().status` describes a settled request (`completed`, `awaiting-input`, `failed`, or `cancelled`), not a live readiness state.
171
+ Client views retain observed history; hook and channel views can prune older finished deliveries. An ID without an accepted receipt can't distinguish an unknown delivery from one not yet admitted. `Delivery.result().status` describes a finished request (`completed`, `awaiting-input`, `failed`, or `cancelled`), not a live readiness state.
200
172
 
201
173
  ### Turns and interactions
202
174
 
203
- A turn doesn't end while it waits on an interaction; it pauses. `turn.paused.data.awaiting` names the interactions it waits on, as `{ interactionId }`. Nothing announces the turn resuming: the next fact under it, such as its next `model.requested`, shows it's running again, and only `turn.settled` ends it. A turn waiting on its own work, such as its tasks, stays running without pausing. The same pause can be reported more than once, such as when a message arrives that doesn't resume the turn. Each `turn.paused` describes what the turn waits on now, so to notify someone once per pause, compare `awaiting` with the last one you saw.
175
+ A turn waiting for an approval, question, or sign-in pauses rather than ends. `turn.paused.data.awaiting` lists the requests it waits on, as `{ interactionId }`. No event announces the turn resuming: the next event under it, such as `model.requested`, shows it's running. Only `turn.settled` ends it. A turn waiting on its own work, such as its tasks, stays running.
176
+
177
+ The same pause can be reported more than once, such as when a message arrives that doesn't resume the turn. To notify someone once per pause, compare `awaiting` with the last one you saw.
204
178
 
205
- Questions, approvals, and sign-ins raised by the turn or its calls all pause the turn. An answer arrives in a new delivery; `response.submitted` records it, and `interaction.settled` confirms the decision. Relayed requests carry `origin` coordinates for the asking call. Steering can withdraw a pending request; cancellation interrupts it. A submitted answer is not necessarily applied: check `response.settled` and `interaction.settled`. Each answer's `response.settled` reports what became of it: `applied` when it decided its interaction, `refused` when a response policy rejected it, `withdrawn` or `abandoned` when the interaction settled another way, and `expired` or `failed` otherwise.
179
+ Questions, approvals, and sign-ins raised by the turn or its calls all pause the turn. An answer arrives in a new delivery: `response.submitted` records it, and `interaction.settled` confirms the decision. Relayed requests carry `origin` coordinates for the asking call. Steering can withdraw a pending request, and cancellation interrupts it. A submitted answer isn't necessarily applied. Its `response.settled` reports the result:
180
+
181
+ | Outcome | Meaning |
182
+ | ------------------------ | --------------------------------------------- |
183
+ | `applied` | The answer decided its request. |
184
+ | `refused` | A response policy rejected it. |
185
+ | `withdrawn`, `abandoned` | The request ended another way. |
186
+ | `expired`, `failed` | The answer didn't apply for any other reason. |
206
187
 
207
188
  ### Task facts
208
189
 
209
- A call to a tool that runs as a task, such as an agent tool, `agentRouter()`, the `workflow` tool, or a workflow tool that defines [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve), keeps working after the model gets a receipt. `task.started` reports the task once, with its `taskId`, `name`, `kind` (`"agent"` for an agent tool, `"tool"` otherwise), and the call that started it. Each call the task serves, including later calls that reach a resumable task by its `taskId`, publishes `call.started` with that `taskId` and settles with `call.settled` on its own reply. Calls that share one reply reference the first call's output with `outputOf`. `task.ended` comes when the task ends, including immediate cancellation of agent and one-shot tasks, with `outcome` `"completed"`, `"failed"`, or `"cancelled"`. Results reach the model as a message in its history, so read outcomes from `call.settled`. The terminal is `task.ended`, not `task.settled`: the task ends once, while each call it serves settles separately.
190
+ A call to a tool that runs as a task keeps working after the model gets a receipt. Task tools include agent tools, `agentRouter()`, the `workflow` tool, and workflow tools that define [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve). `task.started` reports the task once, with its `taskId`, `name`, `kind` (`"agent"` for an agent tool, `"tool"` otherwise), and the call that started it. Each call the task serves, including later calls that reach a resumable task by its `taskId`, publishes `call.started` with that `taskId` and its own `call.settled`. Calls that share one reply reference the first call's output with `outputOf`.
191
+
192
+ `task.ended` reports the task's end, including immediate cancellation of agent and one-shot tasks. Its `outcome` is `"completed"`, `"failed"`, or `"cancelled"`. The final event is `task.ended`, not `task.settled`, because the task ends once while each call it serves ends separately. Results reach the model as a message in its history, so read outcomes from `call.settled`.
210
193
 
211
- `child.opened` announces a child session. Settling a call does not end that session; later calls with the same `taskId` can reach it. The turn remains running while its tasks work. See [Tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
194
+ `child.opened` announces a child session. Ending a call doesn't end that session; later calls with the same `taskId` can reach it. The turn keeps running while its tasks work. See [Tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
212
195
 
213
- `child.sent` records each delivery a child accepted for one of this session's calls, after the child returns its receipt. It opens nothing: the delivery's lifecycle is on the child's stream, under `childDeliveryId`, and the call's own outcome is its `call.settled`. A remote agent on an earlier protocol returns no receipt, so its deliveries have no `child.sent`.
196
+ `child.sent` records each delivery a child accepted for one of this session's calls, after the child returns its receipt. It opens nothing. The delivery's events are on the child's stream under `childDeliveryId`, and the call's outcome is its `call.settled`. A remote agent on an earlier protocol returns no receipt, so its deliveries have no `child.sent`.
214
197
 
215
198
  ### Failures and cancellation
216
199
 
217
- Before the next model request, eve repairs unambiguous orphaned local tool calls in saved history only when no result was recorded anywhere. An error result states that the execution outcome is unknown and external state must be checked before repeating side effects. This repair never executes the old call, moves recorded results, or settles work still owned by approvals, sign-in, workflows, or tasks. Provider-executed calls, SDK approvals, and duplicate call IDs are left unchanged.
200
+ Before the next model request, eve repairs a local tool call in saved history that has no recorded result. It adds an error result that says the outcome is unknown, so the model checks external state before repeating side effects. The repair never runs the old call or closes work held by approvals, sign-in, workflows, or tasks. eve leaves SDK approvals and duplicate call IDs unchanged, and leaves provider-executed calls unchanged while their results can still arrive. Anthropic returns the result of a server tool called beside local tools, such as `web_search`, at the start of the next response. Once anything else follows those local results, such as a new message or a retry note, that result can't arrive, and eve repairs the server call like a local one.
201
+
202
+ A failed model run, turn, or session carries `error: { code, message, id?, hint? }` on its `model.settled`, `turn.settled`, or `session.ended`. `id` is a support id that eve's server logs also carry, and `hint` is a remedy when eve recognizes the failure.
203
+
204
+ A turn that ends closes what it left open in the same line. Running calls and open requests for input end `interrupted`, and their pending answers end `withdrawn`. A task can outlive its turn and stays open.
205
+
206
+ A session that fails ends its turn `cancelled`, because the session failed, not the turn. The error is on `session.ended`, and `failure(view, turnId)` reads it for that turn. Built-in channels post one notice for it.
218
207
 
219
- A failed model run, turn, or session carries `error: { code, message, id?, hint? }`: `id` is a support id that eve's server logs carry too, and `hint` a remedy when eve recognizes the failure on its `model.settled`, `turn.settled`, or `session.ended`. A turn that ends closes everything it left open in the same commit: running calls settle `interrupted`, open interactions settle `interrupted`, and their pending answers settle `withdrawn`. A task can outlive its turn and stays open. A
220
- session that fails ends the turn it held `cancelled`, since the session failed, not the turn: the
221
- error is on `session.ended`, and `failure(view, turnId)` reads it for that turn. Built-in channels
222
- post one notice for it.
208
+ When cancellation or clear ends a turn, input queued inside it but not yet read ends `ignored` and doesn't carry into the next turn. Messages the session holds for a later turn aren't part of that unread input.
223
209
 
224
- Input queued inside a turn but not yet read settles `ignored` when cancellation or clear ends
225
- that turn. It does not carry into the next turn. Messages still held by the session for a
226
- later turn are not part of that turn's unread input.
210
+ A cancelled turn isn't a failure. It ends with `outcome: "cancelled"` and a `cause` naming the cancel delivery, and the session accepts the next message normally. What the turn streamed stays on the stream. Session history keeps the accepted user input and finished work and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped.
227
211
 
228
- A cancelled turn is not a failure: it settles with `outcome: "cancelled"` and `cause` naming the cancel delivery, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped instead of a request left unanswered. When a model call fails transiently before it published anything, the run records `model.retried` and tries again; once it has published output, its run settles `abandoned`, with its unfinished calls, and a new run tries again.
212
+ When a model call fails transiently before publishing anything, the run records `model.retried` and tries again. Once it has published output, the run ends `abandoned` with its unfinished calls, and a new run tries again.
229
213
 
230
- A provider `content-filter` response fails the run and turn with `MODEL_CALL_FAILED` and a `hint` to review the request against the provider's content policy. eve does not retry the filtered response; deltas already streamed remain visible, and the session can receive another message.
214
+ A provider `content-filter` response fails the run and turn with `MODEL_CALL_FAILED` and a `hint` to review the request against the provider's content policy. eve doesn't retry it; deltas already streamed stay visible, and the session can receive another message.
231
215
 
232
216
  ## Query session state
233
217
 
234
- `SessionView` from `eve/events` is an opaque, immutable snapshot derived from the stream. Use
235
- queries instead of reading tables or joining rows:
218
+ `SessionView` from `eve/events` is an opaque, immutable snapshot derived from the stream. Read it with queries:
236
219
 
237
220
  ```ts
238
221
  import { activeTurn, call, calls, openInteractions, usage } from "eve/events";
@@ -245,35 +228,29 @@ const observed = call(agent.view, callId);
245
228
  if (observed?.state === "failed") console.error(observed.error.message);
246
229
  ```
247
230
 
248
- `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.
249
-
250
- Calls include their resolved `turnId`, `runId`, and `taskId` when known, so applications do not
251
- join calls to runs to find their turn. `turns`, `deliveries`, `tasks`, `runs`, `parts`, and
252
- `children` return curated observations. Identity lookups include `turn`,
253
- `delivery`, `task`, and `interaction`. `waiting`, `activity`, and `reply` answer
254
- the same lifecycle questions used by built-in clients and channels. These queries are
255
- synchronous and perform no I/O; referenced payloads remain references until explicitly read.
256
-
257
- `waiting(view, turnId)` returns `{ on: "session" }` while the session can make progress,
258
- `{ on: "interaction", interactions }` when answers are needed, or
259
- `{ on: "work", calls, tasks }` when calls or tasks hold the turn. It returns `undefined`
260
- when the turn is absent or settled, or once the session has ended, even if a degraded end left the
261
- turn open. `openInteractions(view, { about: { callId } })` includes the
262
- call's approval, questions relayed through it, and interactions belonging to its task;
263
- `{ about: { taskId } }` includes that task's interactions. A turn `about` filter also includes
264
- interactions owned by its inline calls and responses, but not independent task-owned interactions.
265
- A response `about` filter matches that response. Read `interaction.subject` to match the subject
266
- itself. A response
267
- already answered but still being weighed by a response policy remains open and appears in
268
- `openInteractions` until it settles; `callState(view, callId)` distinguishes `approval` and
269
- `blocked` from running work. Both selectors return immutable observations.
270
-
271
- The public view contains no tables or preview dictionaries. Query results cannot mutate the
272
- fold, and a snapshot you retain stays unchanged when later events arrive. Interactions omit
273
- private sign-in callback URLs, including when returned by `waiting`, `activity`, or `openInteractions`. Use
274
- `callPreview(view, callId)` and `contentPreviews(view)` for transient progress held by a client
275
- or a custom fold; committed values remain separate. Hook and channel snapshots describe the
276
- whole committed line, never half of it.
231
+ `callOutputSource(view, callId)` returns 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.
232
+
233
+ Calls include their resolved `turnId`, `runId`, and `taskId` when known, so you don't join calls to runs to find their turn. `turns`, `deliveries`, `tasks`, `runs`, `parts`, and `children` return curated observations, and `turn`, `delivery`, `task`, and `interaction` look one up by ID. `waiting`, `activity`, and `reply` answer the status questions that built-in clients and channels use. Queries are synchronous and perform no I/O; referenced payloads stay references until explicitly read.
234
+
235
+ | `waiting(view, turnId)` returns | When |
236
+ | ------------------------------------- | ------------------------------------------------------------------------------------------- |
237
+ | `{ on: "session" }` | The session can make progress. |
238
+ | `{ on: "interaction", interactions }` | Answers are needed. |
239
+ | `{ on: "work", calls, tasks }` | Calls or tasks hold the turn. |
240
+ | `undefined` | The turn is absent or ended, or the session has ended, even if a degraded end left it open. |
241
+
242
+ `openInteractions(view, { about })` filters by what holds the work:
243
+
244
+ | `about` | Includes |
245
+ | ---------------- | ------------------------------------------------------------------------------------------------------------ |
246
+ | `{ callId }` | The call's approval, questions relayed through it, and requests from its task. |
247
+ | `{ taskId }` | That task's requests. |
248
+ | `{ turnId }` | The turn's requests, including those of its inline calls and responses, but not ones from independent tasks. |
249
+ | `{ responseId }` | That response. |
250
+
251
+ Read `interaction.subject` to match the subject itself. An answered request that a response policy still weighs stays in `openInteractions` until it ends. `callState(view, callId)` distinguishes `approval` and `blocked` from running work. Both selectors return immutable observations.
252
+
253
+ Query results can't change the view, and a snapshot you retain doesn't change when later events arrive. Request observations omit private sign-in callback URLs, including in `waiting`, `activity`, and `openInteractions` results. Use `callPreview(view, callId)` and `contentPreviews(view)` for transient progress held by a client or a custom fold; recorded values stay separate. Hook and channel snapshots always describe a whole recorded line.
277
254
 
278
255
  A custom reader uses the same fold:
279
256
 
@@ -287,13 +264,11 @@ for await (const event of session.stream()) {
287
264
  }
288
265
  ```
289
266
 
290
- `foldEvents` returns a new snapshot without changing its input. It retains incomplete lines
291
- internally until their final event arrives and absorbs overlapping replay. Persist events and
292
- session cursors to reconstruct a view; the opaque value is not a serialization format.
267
+ `foldEvents` returns a new snapshot without changing its input. It holds incomplete lines until their final event arrives and absorbs overlapping replay. The view isn't a serialization format; persist events and session cursors to reconstruct it.
293
268
 
294
269
  ## Positions
295
270
 
296
- A reader materializes each fact and progress record as an event with a `meta` envelope:
271
+ A reader turns each entry in `facts`, and each progress record, into an event with a `meta` field:
297
272
 
298
273
  ```json
299
274
  {
@@ -311,8 +286,8 @@ A reader materializes each fact and progress record as an event with a `meta` en
311
286
  ```
312
287
 
313
288
  - **`meta.position`** is where the event sits: the zero-based stored `line`, and its `index` within that line. A line, once written, never changes or moves, so a position identifies its event across reconnects, rewinds, and replays.
314
- - **`meta.at`** is the time of the commit that holds the event, or, for a progress record, of the latest commit before it.
315
- - **`meta.endOfLine`** is `false` while more events of the same line follow. Readers that stop on a fact finish its line first.
289
+ - **`meta.at`** is the time of the line that holds the event, or, for a progress record, of the latest event line before it.
290
+ - **`meta.endOfLine`** is `false` while more events of the same line follow. Readers that stop on an event finish its line first.
316
291
 
317
292
  That makes `(sessionId, line, index)` the key for ingesting a stream without duplicating rows when you re-read it:
318
293
 
@@ -324,13 +299,13 @@ on conflict (session_id, line, index) do nothing;
324
299
 
325
300
  Positions are also a total order within a session: sort by `line`, then `index`.
326
301
 
327
- A subagent's events live on its own stream. When a parent relays a child's request, the parent's `interaction.opened` is its own fact at its own position; correlate the two through `child.opened.data.sessionId` and the relayed fact's `origin`.
302
+ A subagent's events live on its own stream. When a parent relays a child's request, the parent's `interaction.opened` is its own event at its own position. Correlate the two through `child.opened.data.sessionId` and the relayed event's `origin`.
328
303
 
329
304
  Authored [hooks](../guides/hooks) and channels receive the same events, with their position as `ctx.position`, after the line is written.
330
305
 
331
306
  ## Send a follow-up message
332
307
 
333
- Once the turn has settled, POST your follow-up to its ID-addressed messages endpoint:
308
+ After the turn ends, POST a follow-up to the session's messages endpoint:
334
309
 
335
310
  ```bash
336
311
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
@@ -338,7 +313,7 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
338
313
  -d '{"message":"Now send the short version."}'
339
314
  ```
340
315
 
341
- The follow-up reuses the same durable session: same history, same state. A follow-up accepts exactly one of `message` or `answers`. Use answers to answer one or more open interactions by ID:
316
+ The follow-up continues the same session, with the same history and state. A follow-up accepts exactly one of `message` or `answers`. Send `answers` to answer open requests by ID:
342
317
 
343
318
  ```bash
344
319
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
@@ -346,32 +321,36 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
346
321
  -d '{"answers":[{"interactionId":"req_A","optionId":"approve"}]}'
347
322
  ```
348
323
 
349
- Message sends default to `"steer"`. Before assistant output begins, eve interrupts pending model generation and continues the same turn with the correction. Reasoning and provider search progress do not count as assistant output. An executing eve tool finishes safely, and its result is preserved before the correction reaches the next model call. A steering message aborts the [`ctx.abortSignal`](/docs/tools/workflows#stop-early-for-a-new-message) of each `execute` workflow tool call the turn is waiting on: its questions are withdrawn, `sleep` and `ask_question` stop early, and the call settles with what its body returns. A steering message ends an `eve__task_wait` but never interrupts a task. Only the turn's own caller steers it; another caller's message waits for the turn to end. After assistant output starts, steering applies at the next committed workflow boundary; text already streamed remains visible. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when the active turn should finish first. Structured `answers` answer the interactions they name.
324
+ Message sends default to `turnPolicy: "steer"`: the new message joins the running turn instead of waiting for it. [Message delivery and steering](./execution-model-and-durability#message-delivery-and-steering) explains when it applies.
325
+
326
+ A steering message aborts the [`ctx.abortSignal`](/docs/tools/workflows#stop-early-for-a-new-message) of each `execute` workflow tool call the turn is waiting on. The call's questions end `withdrawn`, `sleep` and `ask_question` stop early, and the call ends with what its body returns. Steering ends an `eve__task_wait` but never interrupts a task, and a task's questions stay open.
327
+
328
+ Only the turn's own caller steers it; another caller's message waits for the turn to end. Channels and TypeScript `Session.send(...)` calls can pass `turnPolicy: "queue"` to let the active turn finish first. Structured `answers` answer the requests they name.
350
329
 
351
- If the session is waiting on a human-in-the-loop approval, respond with the channel’s Approve or Deny controls. Text that doesn't match an option doesn't approve the call. From the person the turn serves, it steers the turn and cancels the approval, even when sent with `turnPolicy: "queue"`, since the turn can't end until that person acts; from anyone else, it waits until the turn ends. If they had already approved some calls in the batch, those calls still run. Cancelling the turn withdraws the approval, and a later answer to it approves nothing.
330
+ Answer a human-in-the-loop approval with the channel's Approve or Deny controls; text that doesn't match an option approves nothing. Such text from the person the turn serves steers the turn and cancels the approval, even with `turnPolicy: "queue"`. The turn can't end until that person acts. From anyone else, it waits until the turn ends. Calls already approved in the batch still run. Cancelling the turn withdraws the approval, and a later answer to it approves nothing.
352
331
 
353
- A pending prompt, whether a `ctx.ask()` question from a tool such as `ask_question`, a tool approval, or the budget prompt, can be answered with plain text, including prompts proxied from a subagent. A message answers the first open prompt, as described in [Several requests at once](/docs/human-in-the-loop#several-requests-at-once): a reply that matches one of its options, such as `approve` or `deny`, answers it as if the sender had pressed that option, and so does any message when the prompt allows free text. Send one message per prompt to answer several. The stream records a message that answers a question as a delivery whose `response.submitted` answers it. A message that doesn't answer the first open prompt follows the normal `turnPolicy`. A steering message withdraws the questions of the `execute` workflow tool calls the turn waits on, which settle `withdrawn`; a task's questions stay open. Use structured responses to target requests unambiguously.
332
+ A pending prompt accepts a plain-text answer. Prompts include a `ctx.ask()` question from a tool such as `ask_question`, a tool approval, and the budget prompt, including ones proxied from a subagent. A message answers the first open prompt, as described in [Several requests at once](/docs/human-in-the-loop#several-requests-at-once). A reply matching one of its options, such as `approve` or `deny`, counts as pressing that option. Any message counts when the prompt allows free text. Send one message per prompt to answer several. On the stream, such a message is a delivery whose `response.submitted` answers the prompt. A message that doesn't answer the first open prompt follows the normal `turnPolicy`. Use structured responses to target requests unambiguously.
354
333
 
355
- A structured response matches any currently pending request by ID, not only the newest batch. It becomes stale only after that request was answered, cleared, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if they are still needed.
334
+ A structured response matches any pending request by ID, not only the newest batch. It becomes stale once that request is answered, cleared, or cancelled. eve delivers a stale response to the model as a new user message, and the model decides whether the old selection still matters. A stale approval never authorizes the earlier tool call; the model must request the action and approval again if still needed.
356
335
 
357
- One delivery can answer requests from several batches. Each answer stands as it arrives (`response.admitted`), and a later answer to the same request replaces it until the request settles. A batch of approvals the model asked for in one step settles together once each has an answer: the approved calls run then, and the model reads their results next. If you answer only some approvals in a batch, those answers stand until the rest arrive. A message that steers the turn instead settles the answered approvals on their answers and withdraws the rest. An answer a response policy weighs stays `response.submitted` until the policy allows it (`response.admitted`) or refuses it (`response.settled`).
336
+ One delivery can answer requests from several batches. Each answer stands as it arrives (`response.admitted`), and a later answer to the same request replaces it until the request is decided. A batch of approvals the model requested in one step is decided together once each has an answer. The approved calls then run, and the model reads their results next. Partial answers stand until the rest arrive. A message that steers the turn instead applies the answers already given and withdraws the rest. An answer a response policy weighs stays `response.submitted` until the policy allows it (`response.admitted`) or refuses it (`response.settled`).
358
337
 
359
- When steering interrupts pending model generation, the interrupted run settles `interrupted`, with any usage the provider reported. The correction's `delivery.consumed` and the next `model.requested` for the same `turnId` follow.
338
+ When steering interrupts model generation, the interrupted run ends `interrupted` with any usage the provider reported. The new message's `delivery.consumed` and the next `model.requested` for the same `turnId` follow.
360
339
 
361
- Multiple steering messages retain their durable arrival order and may be folded into one input at the next boundary. A message accepted after turn settlement starts the next turn. See [message delivery and steering](./execution-model-and-durability#message-delivery-and-steering).
340
+ Multiple steering messages keep their arrival order and may be folded into one input at the next boundary. A message accepted after the turn ends starts the next turn.
362
341
 
363
342
  ## Cancel the in-flight turn
364
343
 
365
- POST to the session's cancel endpoint to stop the turn that is currently running. The body is optional; pass `turnId` (in every turn-scoped fact's `scope`) to scope the cancel to the turn you observed:
344
+ POST to the session's cancel endpoint to stop the running turn. The body is optional; pass `turnId` (in the `scope` of every event that belongs to a turn) to cancel only the turn you observed:
366
345
 
367
346
  ```bash
368
347
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/cancel
369
348
  # {"ok":true,"sessionId":"<sessionId>","deliveryId":"delivery_cancel"}
370
349
  ```
371
350
 
372
- The HTTP route returns `202` with the command's `sessionId` and `deliveryId`. Cancellation completes asynchronously. The cancel arrives as a control delivery; confirm it on the stream as `turn.settled` with `outcome: "cancelled"` and `cause` naming that delivery. Each cancelled child reports its own boundary on its child-session stream. An unguarded cancellation also stops working tasks, including between turns, with `task.ended` facts.
351
+ The route returns `202` with the `sessionId` and the cancel's `deliveryId`, and cancellation completes asynchronously. Confirm it on the stream as `turn.settled` with `outcome: "cancelled"` and a `cause` naming that delivery. Each cancelled child session reports its own cancellation on its own stream. A cancel without a `turnId` guard also stops working tasks, including between turns, with `task.ended` events.
373
352
 
374
- A live idle session accepts a no-op cancellation. A guard for a different turn, including `turnId: null` for no observed turn, cannot cancel unrelated work. The cancellation delivery settles when applied or ignored. An unknown or terminal session returns `409 session_not_active`, not a separate `no_active_turn` result.
353
+ A live idle session accepts a cancel as a no-op. A `turnId` guard for a different turn, including `turnId: null` for no observed turn, can't cancel unrelated work. The cancel's `delivery.settled` reports `applied` or `ignored`. An unknown or terminal session returns `409 session_not_active`, not a separate `no_active_turn` result.
375
354
 
376
355
  Custom channel routes request the same cancellation through
377
356
  `from(address).cancel()` or `attachSession(sessionId).cancel()`. See
@@ -379,7 +358,7 @@ Custom channel routes request the same cancellation through
379
358
 
380
359
  ## Compact, clear, and end
381
360
 
382
- All session controls are ID-addressed and accept no continuation token:
361
+ Session controls are addressed by session ID and accept no continuation token:
383
362
 
384
363
  ```bash
385
364
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/compact
@@ -389,21 +368,21 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/end \
389
368
  -d '{"reason":"Start over"}'
390
369
  ```
391
370
 
392
- Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. Recalled [memory](../memory) stays outside history, so the summary never includes it, and a memory provider can capture the history before compaction rewrites it. If a turn is active, eve queues the request until that turn settles. A compaction is a context change: `context.started` and `context.settled` with `kind: "compaction"`, around the summary's model run. If summarization fails before a checkpoint, the change settles `failed` and the session keeps its previous history.
371
+ Compaction summarizes history without adding a user message. If a turn is active, eve queues the request until that turn ends. User-role instructions are ordinary history and may be summarized; system-role instructions stay outside it. Recalled [memory](../memory) stays outside history, so the summary never includes it, and a memory provider can capture history before compaction rewrites it. On the stream, compaction is a context change: `context.started` and `context.settled` with `kind: "compaction"`, around the summary's model run. If summarization fails before a checkpoint, the compaction ends `failed` and the session keeps its previous history.
393
372
 
394
- Clear removes model-message history in place, including static and dynamic user-role instructions, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It does not delete data from a memory provider's external store, and the next turn recalls again. Unchanged user-role instructions are not inserted again. Approvals, the session-limit prompt, and sign-ins the cleared history asked for are withdrawn: each settles its interaction. Requests relayed from tasks that keep running stay answerable. The clear is a context change with `kind: "clear"`.
373
+ Clear removes model-message history in place, including static and dynamic user-role instructions. It keeps the session identity, system-role instructions, tools, skills, [`defineState`](./state) values, limits, and sandbox. Unchanged user-role instructions aren't inserted again. Clear doesn't delete data from a memory provider's external store, and the next turn recalls again. Approvals, the session-limit prompt, and sign-ins the cleared history asked for are withdrawn. Unlike a compaction, clear doesn't wait for a running turn. It cancels the turn, which ends `cancelled`, stops the calls it waits on, and ends working tasks with `task.ended`. A stopped task never reports into the cleared conversation. On the stream, clear is a context change with `kind: "clear"`.
395
374
 
396
- 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.
375
+ A cancel stops turns, not a compaction or clear. A cancel that arrives while either runs ends `ignored`, and the compaction or clear finishes. A cancel, clear, or compact sent to a prewarmed session before its first message ends `ignored` once the session starts.
397
376
 
398
- 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.
377
+ End permanently retires the session ID; create another session for a fresh conversation. Every control returns a delivery receipt when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
399
378
 
400
- 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.
379
+ A [stranded session](./execution-model-and-durability#stranded-sessions) can't run commands, so clear and compact can't repair it. End still works: eve retires the stranded session and returns the end's delivery receipt. The delivery ends after the session is retired and its addresses are released.
401
380
 
402
381
  ## Reconnect and rewind
403
382
 
404
- The stream is durable. Every line is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is a line position: the next line to read. Pass the last line you read plus one to pick up where you dropped off, or `0` to rewind to the start.
383
+ The stream is stored, so a consumer can reconnect from its cursor when an HTTP connection ends. A nonnegative `startIndex` is the next line to read. Pass the last line you read plus one to resume, or `0` to rewind to the start.
405
384
 
406
- The stream route serves renewable leases over that durable stream. It sends heartbeats during quiet periods, then ends the response with `{"$eve":"stream.lease-ended"}` so the client reconnects from its current cursor. This bounds server-side stream readers even when a host does not report that the client disconnected. A finished session's stream ends with `{"$eve":"stream.ended"}`, so readers stop instead of reconnecting. Leases and heartbeats are transport details: they do not stop the run or appear as session events.
385
+ The stream route serves renewable leases. It sends heartbeats while the stream is quiet, then ends the response with `{"$eve":"stream.lease-ended"}`. The client then reconnects from its cursor. Leases bound each read even when a host doesn't report a client disconnect. A finished session's stream ends with `{"$eve":"stream.ended"}`, so readers stop instead of reconnecting. Leases and heartbeats don't stop the run or appear as session events.
407
386
 
408
387
  If a reconnect overlaps events you already handled, [`meta.position`](#positions) identifies the duplicates.
409
388
 
@@ -417,24 +396,22 @@ A negative `startIndex` reads relative to the stream's current tail. For example
417
396
  curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=-1"
418
397
  ```
419
398
 
420
- For a catch-up read that stops instead of following the live stream, pass `includeTailIndex=1`. The response then carries the `x-eve-stream-tail-index` header: the zero-based position of the last durably recorded line, or `-1` before the first, and the response ends after that line:
399
+ Pass `includeTailIndex=1` for a catch-up read that stops instead of following the live stream. The response carries the `x-eve-stream-tail-index` header, the zero-based position of the last recorded line (`-1` before the first), and ends after that line:
421
400
 
422
401
  ```bash
423
402
  curl -i "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<line>&includeTailIndex=1"
424
403
  # x-eve-stream-tail-index: <tail>
425
404
  ```
426
405
 
427
- The lookup is opt-in; requests without the parameter get no header. Passing `follow=false` instead bounds the response at the durable tail on the server and implies the header. A bounded read only reads recorded history, so it also works for a [stranded session](./execution-model-and-durability#stranded-sessions), whose live stream returns `409 session_stranded`. The TypeScript client wraps this into `stream({ follow: false })`.
406
+ Requests without the parameter get no header. `follow=false` instead bounds the response at the recorded tail on the server and implies the header. A bounded read only reads recorded history, so it also works for a [stranded session](./execution-model-and-durability#stranded-sessions), whose live stream returns `409 session_stranded`. The TypeScript client exposes this as `stream({ follow: false })`.
428
407
 
429
408
  ## Use the client from TypeScript
430
409
 
431
- For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
432
-
433
- Start with the [Client SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
410
+ `eve/client` wraps these routes in a typed client for scripts, server-to-server calls, tests, evals, and custom UIs. Start with the [Client SDK](../guides/client/overview) guide, which covers sending messages, session state, streaming, and per-turn `outputSchema` results.
434
411
 
435
412
  ## Read a session in process
436
413
 
437
- Code running inside the agent's own deployment, such as a hook, tool, schedule, or channel route, can read a session's durable stream without calling its own HTTP route. `eve/server` exposes the same `attach(sessionId).stream(...)` shape as the client, so it needs no deployment URL, credentials, or stream protocol:
414
+ Code inside the agent's deployment, such as a hook, tool, schedule, or channel route, can read a session's stream with `sessions` from `eve/server`. It doesn't call the HTTP route. It has the client's `attach(sessionId).stream(...)` shape and needs no deployment URL, credentials, or stream protocol:
438
415
 
439
416
  ```ts
440
417
  import { sessions } from "eve/server";
@@ -446,38 +423,51 @@ for await (const event of events) {
446
423
  }
447
424
  ```
448
425
 
449
- `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.
426
+ `stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a line position; negative values count back from the tail), `follow`, and `signal`. Client readers also accept `reconnect: false` or a `ReconnectOptions` object from `eve/client`. With `follow: false`, the read ends at the recorded tail observed when it opens. Otherwise it follows new events until the stream closes or the signal aborts. Key stored events on [`meta.position`](#positions), which stays stable across reads.
450
427
 
451
- 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.
428
+ A read sees only recorded events. 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's available only in code that runs inside the eve server.
452
429
 
453
430
  ## Inspect the agent over HTTP
454
431
 
455
- `GET /eve/v1/info` returns agent-info version 6, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Memory tool wrappers include their selected memory-source dependency. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`. Sandbox inspection exposes the opaque `revisionHash` that identifies its compiler-discovered environment inputs.
456
-
457
- The info route belongs to the selected `channels/eve.ts` source and uses its resolved auth policy. Without an authored replacement, eve selects the default channel source with Vercel OIDC, local development access, and the production placeholder. Replacing or disabling that source replaces or removes the info route too; no native fallback serves it.
432
+ `GET /eve/v1/info` returns agent-info version 5, a JSON snapshot of the effective compiled agent:
458
433
 
459
434
  ```bash
460
435
  curl http://127.0.0.1:2000/eve/v1/info
461
436
  ```
462
437
 
463
- With the default auth chain (`[vercelOidc(), localDev(), placeholderAuth()]`), a Vercel OIDC bearer takes precedence, `localDev()` accepts requests to an `eve dev` or `vercel dev` server, and everything else is rejected. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
438
+ The snapshot reports:
439
+
440
+ - the selected config;
441
+ - active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation, each with its source;
442
+ - dynamic resolvers, separately from their session-specific output;
443
+ - local and remote agents, in separate collections;
444
+ - prepared built-in effects;
445
+ - shadowed or disabled source diagnostics.
446
+
447
+ Memory tool wrappers include their selected memory-source dependency, and channel routes appear in the order the HTTP host uses. Static instructions are an ordered array of entries with `content` and `role`. The sandbox's opaque `revisionHash` identifies its compiler-discovered environment inputs.
448
+
449
+ The payload includes authored text and server paths, so the route serves only operator callers: `service` and `runtime` callers, and, when the channel's auth includes `localDev()`, callers it admits on a development server. Any other caller the channel admits, such as a `user` or `anonymous` caller, gets `403` with `{ "code": "info_forbidden", "ok": false }` and an `error` message. To give another credential access, return `principalType: "service"` or `allowAgentInfo: true` from its authenticator. See [Agent info access](../guides/auth-and-route-protection#agent-info-access).
450
+
451
+ The version changes only when the shape breaks. A server can add fields and enum values within a version, so ignore unknown fields and handle unknown enum values. `kind` discriminants, such as an owner's, a model endpoint's, or a module's backing `kind`, are closed: a new variant comes with a new version.
452
+
453
+ The info route belongs to the selected `channels/eve.ts` source and checks its auth policy before the operator check. Replacing or disabling that source replaces or removes the info route too. Without an authored source, eve uses the default auth chain `[vercelOidc(), localDev(), placeholderAuth()]`. A Vercel OIDC bearer takes precedence, and `localDev()` accepts requests to an `eve dev` or `vercel dev` server. Everything else is rejected. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).
464
454
 
465
455
  ## Dispatch order
466
456
 
467
- Every commit runs in this order:
457
+ Each new event line goes through these stages in order:
468
458
 
469
- 1. **Write**: the line is written to the durable stream.
470
- 2. **Channel handler**: the channel's event handler runs for each fact and can update adapter state; the framework then re-evaluates the channel's `metadata(state)` and stores the result.
471
- 3. **Hooks**: authored [hooks](../guides/hooks) subscribed to each fact fire.
459
+ 1. **Write**: the line is written to the stream.
460
+ 2. **Channel handler**: the channel's event handler runs for each event and can update adapter state. eve then re-evaluates the channel's `metadata(state)`.
461
+ 3. **Hooks**: authored [hooks](../guides/hooks) subscribed to each event fire.
472
462
  4. **Intents**: eve acts on cancellation requests queued by `ctx.cancel()`.
473
463
 
474
- Before the next model call, eve evaluates [dynamic capabilities](../guides/dynamic-capabilities), and `ctx.channel.metadata` already holds the freshly projected metadata.
464
+ Before the next model call, eve evaluates [dynamic values](../guides/dynamic-capabilities) from `defineDynamic`. Hooks and dynamic values read the current `ctx.channel.metadata`.
475
465
 
476
- The order is structural, not incidental. Channels and hooks observe what was written; neither can change it. By the time a dynamic capability or hook reads channel metadata, the channel has already updated its state and the projection is current.
466
+ Channels and hooks observe what was written and can't change it.
477
467
 
478
468
  ## What to read next
479
469
 
480
- - [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
481
- - [Channels](../channels/overview): how platform addresses map to durable sessions.
470
+ - [Execution model & durability](./execution-model-and-durability): how a session survives restarts and how parked work resumes.
471
+ - [Channels](../channels/overview): how platform addresses map to sessions.
482
472
  - [Client SDK](../guides/client/overview): call these routes from scripts and server-side code.
483
473
  - [Frontend](../guides/frontend/overview): `useEveAgent` instead of raw routes.