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,7 +3,7 @@ title: "Messages"
3
3
  description: "Send text, full turn payloads, client context, attachments, and HITL responses with eve/client."
4
4
  ---
5
5
 
6
- Create a session with its first turn, then use the returned `ClientSession` for follow-ups. Each handle targets one durable session ID.
6
+ A message is one turn of input to a session. Create a session with its first turn, then send follow-ups through the returned `ClientSession`, which targets that one session ID.
7
7
 
8
8
  ## Send text
9
9
 
@@ -24,42 +24,41 @@ const result = await delivery.result();
24
24
  console.log(result.status, result.reply);
25
25
  ```
26
26
 
27
- `delivery.result()` reads through this delivery's settlement and returns a `DeliveryResult`.
27
+ `delivery.result()` reads until the request finishes or pauses for input, then returns a `DeliveryResult`.
28
28
  Import `Delivery`, `DeliveryReadOptions`, and `DeliveryResult` from `eve/sessions`:
29
29
 
30
- | Field | Meaning |
31
- | -------------- | -------------------------------------------------------------------------------------------------- |
32
- | `reply` | The request's reply text, from the parts `turn.settled.reply` lists. |
33
- | `status` | `awaiting-input`, `completed`, `failed`, or `cancelled` for this settled request. |
34
- | `sessionEnded` | Whether the session ended in the delivery's final commit. |
35
- | `deliveryId` | The accepted command's ID. |
36
- | `outcome` | The delivery's outcome: `handled`, `awaiting-input`, `applied`, `ignored`, `refused`, or `failed`. |
37
- | `error` | Required `ErrorInfo` when `status` is `failed`. |
38
- | `interactions` | Display-safe interactions left open for a person. |
39
- | `sessionId` | Session ID for streaming and inspection. |
40
- | `data` | Structured output when the turn requested an [output schema](./output-schema). |
41
-
42
- A settled request's failure returns `status: "failed"` and `error`; inspect `error.code` and
43
- `error.message` to recover. HTTP failures and reads interrupted before settlement throw rather
44
- than fabricating a result. An `awaiting-input` result is complete: answering the prompt creates
45
- another delivery. Ordinary results do not retain an event log; capture `delivery.stream()`
46
- explicitly when you need one.
47
-
48
- `session.send()` retries `409 session_not_ready` with bounded exponential backoff for up to 20
49
- seconds when a durable run has been accepted but its command inbox is still starting. The caller's
50
- abort signal cancels the wait. Other errors, `session.respond()`, control methods, and raw HTTP
51
- requests do not use this retry. An unknown
52
- or terminal session throws `SessionNotActiveError` immediately with `retryable: false`. A
53
- `session_not_ready` rejection has `retryable: true` if the bounded send retry expires. A
54
- [stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
55
- `ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
56
- `eveVersion` that built the session when it recorded one. It is never retried automatically. Call
57
- `session.end()` and create a new session.
58
- The client never creates a replacement session. Following or reconnecting to a stranded session's
59
- stream reports the same typed error without retrying, including when you were waiting for a
60
- response to a message accepted before the upgrade. That accepted message is not redelivered.
61
- `session.clear()` throws the same error, because clearing would keep a session that cannot run.
62
- `session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
30
+ | Field | Meaning |
31
+ | -------------- | -------------------------------------------------------------------------------------------------------- |
32
+ | `reply` | The request's reply text, from the parts `turn.settled.reply` lists. |
33
+ | `status` | `awaiting-input`, `completed`, `failed`, or `cancelled` for this request. |
34
+ | `sessionEnded` | Whether the session ended when this request finished. |
35
+ | `deliveryId` | The ID of the accepted message or control. |
36
+ | `outcome` | What happened to the request: `handled`, `awaiting-input`, `applied`, `ignored`, `refused`, or `failed`. |
37
+ | `error` | Required `ErrorInfo` when `status` is `failed`. |
38
+ | `interactions` | Approvals, questions, and sign-ins still waiting for a person, safe to display. |
39
+ | `sessionId` | Session ID for streaming and inspection. |
40
+ | `data` | Structured output when the turn requested an [output schema](./output-schema). |
41
+
42
+ A failed request returns `status: "failed"` with `error`; inspect `error.code` and
43
+ `error.message` to recover. HTTP failures and reads interrupted before the request finishes throw instead.
44
+ An `awaiting-input` result is complete. Answering the prompt sends a new request with its own result.
45
+ Results don't include an event log; capture `delivery.stream()` when you need one.
46
+
47
+ `session.send()` retries `409 session_not_ready` with backoff for up to 20 seconds while the
48
+ session starts. The caller's abort signal cancels the wait. Other errors, `session.respond()`,
49
+ control methods, and raw HTTP requests are not retried.
50
+
51
+ | Error | When |
52
+ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
53
+ | `SessionNotActiveError` | Unknown or terminal session, thrown immediately (`retryable: false`), or the `session_not_ready` retry expired (`retryable: true`). |
54
+ | `ClientSessionStrandedError` | [Stranded](../../concepts/execution-model-and-durability#stranded-sessions) session. |
55
+
56
+ `ClientSessionStrandedError` is a `ClientError` with `code: "session_stranded"` and, when recorded,
57
+ the `eveVersion` that built the session. It is never retried, and the client never creates a
58
+ replacement: call `session.end()` and create a new session. Following the stranded session's
59
+ stream, `send()`, and `session.clear()` throw the same error, and a message accepted before the
60
+ session stranded is not redelivered. `session.stream({ follow: false })` and `session.snapshot()`
61
+ still read the recorded history.
63
62
 
64
63
  The typed errors `eve/client` throws (`ClientError` and its subclasses, `SessionNotActiveError`,
65
64
  `HealthResponseError`, and `AgentInfoResponseError`) extend `EveError` and have a stable snake_case
@@ -101,27 +100,11 @@ const { session, delivery } = await client.sessions.create({
101
100
  await delivery.result();
102
101
  ```
103
102
 
104
- `clientContext` is ephemeral context for the current turn. Strings become user-role context messages, arrays of strings become multiple context messages, and objects are JSON-serialized into one context message. The context remains available to every model call in the turn, then disappears before the next turn. It isn't persisted to durable session history and doesn't dispatch a turn by itself.
103
+ `clientContext` is ephemeral context for the current turn. A string becomes a user-role context message, an array of strings becomes several, and an object is JSON-serialized into one. Every model call in the turn sees it. It isn't saved to session history and doesn't start a turn by itself.
105
104
 
106
105
  ## Send attachments
107
106
 
108
- `send()` accepts `MessageContent`, so a message can mix text and file parts. A file part's `data` is the file inline (bytes, base64, or a `data:` URL) or a URL:
109
-
110
- ```ts
111
- const response = await session.send([
112
- { type: "text", text: "Summarize this report." },
113
- {
114
- type: "file",
115
- data: reportDataUrl,
116
- mediaType: "application/pdf",
117
- filename: "report.pdf",
118
- },
119
- ]);
120
-
121
- await response.result();
122
- ```
123
-
124
- For local files, read the file and send a base64 `data:` URL:
107
+ `send()` accepts `MessageContent`, so a message can mix text and file parts. A file part's `data` is the file inline (bytes, base64, or a `data:` URL) or a URL. For a local file, send a base64 `data:` URL:
125
108
 
126
109
  ```ts
127
110
  import { readFile } from "node:fs/promises";
@@ -142,10 +125,9 @@ const response = await session.send([
142
125
  await response.result();
143
126
  ```
144
127
 
145
- The stream confirms the turn with `delivery.consumed`. Its `data.parts` contains structured text and
146
- file metadata for clients that render attachments. File parts never include raw bytes or internal sandbox paths. See [Inbound
147
- attachments](../../sandbox#inbound-attachments) for how eve stages byte-backed files in the session
148
- sandbox and prepares them for each model call.
128
+ The stream confirms the turn with `delivery.consumed`, whose `data.parts` holds text and file
129
+ metadata for rendering attachments, never raw bytes or sandbox paths. See [Inbound
130
+ attachments](../../sandbox#inbound-attachments) for how eve stages files in the session sandbox.
149
131
 
150
132
  ## Answer human input requests
151
133
 
@@ -165,9 +147,9 @@ const resumed = await session.respond(
165
147
  await resumed.result();
166
148
  ```
167
149
 
168
- The reply's delivery records a `response.submitted` for each answer, and each request ends with `interaction.settled`: its `interactionId`, terminal `outcome`, and the `response` that decided it. Persist this authoritative event instead of relying on the submitting client's optimistic state when rebuilding message history.
150
+ The stream records a `response.submitted` event for each answer. Each request then ends with an `interaction.settled` event that carries its `interactionId`, final `outcome`, and the `response` that decided it. Save `interaction.settled`, not the client's optimistic state, when you rebuild message history.
169
151
 
170
- `send(message, options)` and `respond(answers, options)` are separate operations. Put `clientContext`, `outputSchema`, headers, or stream options in the second argument to either method.
152
+ Pass `clientContext`, `outputSchema`, headers, or stream options in the second argument to `send(message, options)` or `respond(answers, options)`.
171
153
 
172
154
  ## Reusable delivery reads
173
155
 
@@ -180,14 +162,13 @@ for await (const event of response.stream()) {
180
162
  const result = await response.result();
181
163
  ```
182
164
 
183
- Each read follows the same interval, from the admitting commit through the complete settlement
184
- commit, independently of other readers. Repeated or concurrent reads are supported; reading the
185
- interval again can open another HTTP stream. A completed summary may be cached.
165
+ Each read covers the request from when the server accepts it until it finishes, independently of other readers.
166
+ Repeated and concurrent reads are supported, and each may open another HTTP stream.
186
167
 
187
- Pass `{ signal }` to `stream()` or `result()` to abort that read. An aborted or failed read does
188
- not consume the handle or cancel the accepted work; retry the same delivery without submitting
189
- another message. Use `session.cancel()` to cancel work. A signal passed to `send()` controls
190
- submission, so pass it to the read too when a timeout must cover both.
168
+ Pass `{ signal }` to `stream()` or `result()` to abort that read. An aborted or failed read doesn't
169
+ consume the handle or cancel the work, so retry the same delivery instead of sending again. Use
170
+ `session.cancel()` to cancel work. A signal passed to `send()` covers only submission, so pass it
171
+ to the read too when a timeout must cover both.
191
172
 
192
173
  ## What to read next
193
174
 
@@ -3,11 +3,11 @@ title: "Output Schema"
3
3
  description: "Request structured results from eve client turns and read typed data from DeliveryResult."
4
4
  ---
5
5
 
6
- Pass `outputSchema` on a client turn when the caller needs structured data instead of only assistant text. The runtime makes the model satisfy the schema before the turn settles, then emits the final payload as a `content.completed` part with `kind: "result"`.
6
+ `outputSchema` requests structured data from a client turn instead of only assistant text. The model must satisfy the schema before the turn ends, and the payload arrives as a `content.completed` part with `kind: "result"`.
7
7
 
8
8
  ## JSON Schema
9
9
 
10
- Raw JSON Schema objects work directly:
10
+ Pass a JSON Schema object directly:
11
11
 
12
12
  ```ts
13
13
  import { Client } from "eve/client";
@@ -42,7 +42,7 @@ console.log(result.data?.count);
42
42
 
43
43
  ## Standard Schema
44
44
 
45
- The client also accepts Standard Schema implementations such as Zod, Valibot, and ArkType. The schema is lowered to JSON Schema before the request is sent:
45
+ The client also accepts Standard Schema implementations such as Zod, Valibot, and ArkType, and converts them to JSON Schema before sending:
46
46
 
47
47
  ```ts
48
48
  import { z } from "zod";
@@ -61,11 +61,11 @@ const response = await session.send<Summary>("Summarize this turn.", {
61
61
  const { data } = await response.result();
62
62
  ```
63
63
 
64
- The server is authoritative for validation. The client types `DeliveryResult.data` from your generic and schema, but it doesn't revalidate the streamed payload client-side.
64
+ The server validates the result. The client types `DeliveryResult.data` from your generic and schema but doesn't revalidate it.
65
65
 
66
66
  ## Stream the result event
67
67
 
68
- If you consume events manually, read the `content.completed` part with `kind: "result"`:
68
+ When you consume events manually, read the `content.completed` part with `kind: "result"`:
69
69
 
70
70
  ```ts
71
71
  const response = await session.send<Summary>("Summarize this turn.", {
@@ -80,11 +80,11 @@ for await (const event of response.stream()) {
80
80
  }
81
81
  ```
82
82
 
83
- If more than one result part appears in the consumed event list, `result()` returns the most recent one as `data`.
83
+ If more than one result part appears, `result()` returns the most recent one as `data`.
84
84
 
85
85
  ## Send payloads with output schema
86
86
 
87
- Pass `outputSchema` in the second argument to `send()` or `respond()` alongside headers, signal, or client context:
87
+ Pass `outputSchema` in the second argument to `send()` or `respond()`, alongside headers, signal, or client context:
88
88
 
89
89
  ```ts
90
90
  const response = await session.send<Summary>("Summarize this PDF.", {
@@ -107,7 +107,7 @@ const result = await response.result();
107
107
 
108
108
  ## Per-turn scope
109
109
 
110
- Client `outputSchema` is scoped to the turn that sends it. It doesn't become a permanent setting for the conversation:
110
+ Client `outputSchema` applies only to the turn that sends it:
111
111
 
112
112
  ```ts
113
113
  const response = await session.send("Return a structured summary.", { outputSchema });
@@ -3,9 +3,9 @@ title: "Client SDK"
3
3
  description: "Call an eve agent from TypeScript with Client, sessions, auth, and health checks."
4
4
  ---
5
5
 
6
- The `eve/client` entrypoint is the typed client for eve's default HTTP API. Use it from scripts, server-to-server integrations, tests, evals, backend jobs, or custom UIs that want the session protocol without hand-writing the POST and NDJSON (newline-delimited JSON) stream loop.
6
+ The `eve/client` entrypoint is the typed TypeScript client for eve's default HTTP API. It replaces a hand-written POST and NDJSON (newline-delimited JSON) stream loop in scripts, server-to-server integrations, tests, evals, backend jobs, and custom UIs.
7
7
 
8
- For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming). The client sits between those two: lower level than the frontend hooks, higher level than raw HTTP.
8
+ For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
9
9
 
10
10
  ## Create a client
11
11
 
@@ -19,31 +19,46 @@ const client = new Client({
19
19
  });
20
20
  ```
21
21
 
22
- `baseUrl` is the URL where the eve routes are mounted. In a same-origin browser integration this is often `""`; scripts and backend services usually name the full URL. Any query parameters on `baseUrl` are included on every request, including session POSTs and event streams. Request-specific parameters, such as a stream cursor, take precedence when names overlap.
22
+ `baseUrl` is the URL where the eve routes are mounted, often `""` in a same-origin browser integration. Query parameters on `baseUrl` are sent on every request, including event streams. When names overlap, request-specific parameters such as a stream cursor win.
23
23
 
24
24
  ## Check health
25
25
 
26
- Use `health()` when a script needs to fail early before creating a session:
26
+ `health()` lets a script fail early before creating a session:
27
27
 
28
28
  ```ts
29
29
  const health = await client.health();
30
30
  console.log(health.status, health.workflowId);
31
31
  ```
32
32
 
33
- The client requires the successful response to match `{ ok: true, status: "ready", workflowId: string }`. Non-2xx responses throw `ClientError`, which carries the HTTP `status` and response `body`; invalid JSON or a malformed successful payload throws `HealthResponseError`.
33
+ A successful response must match `{ ok: true, status: "ready", workflowId: string }`. A non-2xx response throws `ClientError` with the HTTP `status` and response `body`; invalid JSON or a malformed payload throws `HealthResponseError`.
34
34
 
35
35
  ## Inspect an agent
36
36
 
37
- Use `info()` to inspect an agent. The client requires the complete agent-info version 6 response before returning it:
37
+ `info()` returns the agent's inspection payload. The client accepts only a complete agent-info version 5 response:
38
38
 
39
39
  ```ts
40
40
  const info = await client.info();
41
41
  console.log(info.agent.name, info.agent.model.id);
42
42
  ```
43
43
 
44
- Pass `info({ signal })` to cancel the HTTP request. The signal is checked only after custom header and credential callbacks resolve; it does not limit how long those callbacks or the complete `info()` call can take.
44
+ Pass `info({ signal })` to cancel the HTTP request. The signal applies only after custom header and credential callbacks resolve, so it doesn't bound how long those callbacks take.
45
45
 
46
- Version 4 separates active static definitions from dynamic resolvers, includes binding-backed source ownership and composition history, reports first-class memory slots and their provider-tool wrapper dependencies, reports local and remote agents separately, and returns the exact compiled channel route order. A non-success response throws `ClientError`; invalid JSON, an earlier schema version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`.
46
+ The response contains:
47
+
48
+ - static definitions and dynamic resolvers, each with the source that defines it
49
+ - composition diagnostics and memory slots
50
+ - local and remote agents, listed separately
51
+ - the compiled channel route order
52
+
53
+ The response includes authored instructions, skill and schedule Markdown, and server paths. So the server answers only operator callers, with `principalType` `service`, `runtime`, or `local-dev`, unless the channel's auth grants `allowAgentInfo`. Authenticate the client with an operator credential, such as Vercel OIDC, `jwtHmac()`, `jwtEcdsa()`, or a custom `AuthFn` that returns `principalType: "service"`. Any other caller gets a `ClientError` with `status` `403` and `code` `"info_forbidden"`.
54
+
55
+ The version changes only when the response shape breaks. Within a version, a server can add fields and enum values:
56
+
57
+ - The client ignores fields it doesn't know.
58
+ - An enum-like field with a string the client can't interpret, such as `mode`, `sourceKind`, or a channel `method`, reads as `"unrecognized"`. Handle that value when you switch on these fields.
59
+ - `kind` discriminants are closed. A new variant comes with a version change, and an unknown one throws `AgentInfoResponseError`.
60
+
61
+ A non-success response throws `ClientError`. Invalid JSON, a missing or non-string enum value, a different agent-info version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`. For a version mismatch, its `issues` say which side to upgrade: eve in the agent, or the eve package the client runs from.
47
62
 
48
63
  ## Authentication
49
64
 
@@ -72,7 +87,7 @@ const client = new Client({
72
87
  });
73
88
  ```
74
89
 
75
- For a Vercel OIDC-protected deployment, use `vercelOidc`. The client resolves the token once per request and sends it as both the bearer credential and Vercel's trusted-OIDC header:
90
+ For a Vercel OIDC-protected deployment, use `vercelOidc`. The client resolves the token once per request and sends it as both the bearer credential and the `x-vercel-trusted-oidc-idp-token` header:
76
91
 
77
92
  ```ts
78
93
  import { getVercelOidcToken } from "@vercel/oidc";
@@ -87,7 +102,7 @@ const client = new Client({
87
102
  });
88
103
  ```
89
104
 
90
- Use `headers` for route-specific credentials such as bypass tokens or tenant hints. Like `auth`, it can be static or dynamic:
105
+ Use `headers`, static or dynamic, for route-specific credentials such as bypass tokens or tenant hints:
91
106
 
92
107
  ```ts
93
108
  const client = new Client({
@@ -99,9 +114,15 @@ const client = new Client({
99
114
  });
100
115
  ```
101
116
 
102
- Clients reject redirects by default (`redirect: "error"`) so fetch cannot forward custom credentials to a redirected destination. Use `redirect: "manual"` to stop at a redirect without following it. Node.js exposes the response status and headers; browsers return an opaque redirect response with no readable status, headers, or body. The policy applies to inspection requests, custom fetches, session creation, and event streams, and overrides per-request redirect settings. Only opt into `redirect: "follow"` when you trust every possible redirect destination to receive your custom headers and request data.
117
+ Clients reject redirects by default (`redirect: "error"`), so fetch can't forward your custom credentials to another destination. The policy applies to every request the client makes, including event streams, and overrides per-request settings.
118
+
119
+ | `redirect` | Behavior |
120
+ | ------------------- | --------------------------------------------------------------------------------------------------------------- |
121
+ | `"error"` (default) | Rejects any redirect. |
122
+ | `"manual"` | Stops at a redirect. Node.js shows its status and headers; browsers return an opaque response with neither. |
123
+ | `"follow"` | Follows redirects. Use it only when you trust every possible destination with your custom headers and requests. |
103
124
 
104
- Per-request headers can be attached to an individual turn:
125
+ Attach per-request headers to an individual turn:
105
126
 
106
127
  ```ts
107
128
  const response = await session.send("Run the check.", {
@@ -111,36 +132,23 @@ const response = await session.send("Run the check.", {
111
132
  await response.result();
112
133
  ```
113
134
 
114
- Per-request headers override client-level values with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` continues to send the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
135
+ Per-request headers override client-level headers with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` still sends the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
115
136
 
116
137
  ## Faster sends with `inbox`
117
138
 
118
- Keep the complete `session.state` when saving and restoring a conversation. It can include an
119
- opaque `inbox` value issued by the server. The client sends it back with later messages to avoid
120
- another hook lookup. Persist it and pass it back unchanged: do
121
- not inspect, edit, or construct it, because eve may change or extend its contents in any release.
122
- A missing, stale, or rejected value only costs a slower lookup.
139
+ `session.state` can include an opaque `inbox` value from the server, so save the complete state and pass it back unchanged. Later messages that carry it skip a server-side session lookup. Don't inspect, edit, or construct it, because its contents can change in any release. A missing, stale, or rejected value only costs a slower lookup.
140
+
141
+ Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret, at least 32 characters, on every deployment that shares sessions. Omit it to disable handles. The server verifies a handle's signature before using it. After a secret rotation, the server ignores old handles and looks the session up as usual.
123
142
 
124
- Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret (at least 32 characters)
125
- on the deployments that share sessions. Without this key, handles are neither issued nor used.
126
- The signature authenticates all routing and encryption fields before use. Rotation falls back
127
- to ordinary token resolution.
143
+ Handles also require a Workflow SDK that exports `parseHookResumeHandle`, a world adapter that declares `resolvedHookResume`, and a backend that supports resolved hook resumes. Without all three, the server neither issues nor uses handles, even with the secret set.
128
144
 
129
- Reuse also requires a Workflow SDK with `parseHookResumeHandle`, an adapter that declares
130
- `resolvedHookResume`, and a backend with the guarded resolved-hook endpoint.
131
- Older SDKs do not issue or use handles, even when the secret
132
- is configured. This change keeps the released SDK dependencies; adopting the SDK update
133
- enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
134
- which may contain private server baggage. The signature authenticates a handle; it does not hide its contents.
145
+ Handles contain no user metadata, short-lived runtime access, or trace data. The signature proves a handle is authentic but doesn't hide its contents.
135
146
 
136
- The server checks that the handle addresses the requested session's inbox. Workflow still validates the
137
- hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
138
- the current inbox again. An uncertain write is surfaced without submitting a second delivery.
147
+ A handle can't route a message to a session other than the one requested. When a handle is stale, the server looks up the current session again. When a write's outcome is uncertain, the request reports an error instead of delivering the message twice.
139
148
 
140
149
  ## Sessions
141
150
 
142
- Create and park an ID-addressed conversation before its first turn when you can start session work
143
- while the user is still composing:
151
+ Create a session before its first turn so it starts while the user is still typing:
144
152
 
145
153
  ```ts
146
154
  const { session } = await client.sessions.create();
@@ -149,9 +157,7 @@ const response = await session.send("Summarize account A.");
149
157
  await response.result();
150
158
  ```
151
159
 
152
- The create promise resolves when the server accepts the durable workflow. It does not open the
153
- event stream or wait for initialization; an early `session.send()` uses the
154
- same bounded startup retries as other follow-ups.
160
+ `create()` resolves when the server accepts the session. It doesn't open the event stream or wait for the session to start. An early `session.send()` retries for a limited time while the session starts, like any follow-up.
155
161
 
156
162
  To create the session and start its first turn in one request, include the message:
157
163
 
@@ -164,13 +170,13 @@ await session.compact();
164
170
  await session.clear();
165
171
  ```
166
172
 
167
- If you already know the durable ID, attach a fixed handle without performing I/O:
173
+ If you already know the session ID, attach a handle without making a request:
168
174
 
169
175
  ```ts
170
176
  const session = client.sessions.attach("wrun_A");
171
177
  ```
172
178
 
173
- The fixed client handle exposes the full lifecycle around that ID. The calls below show the available shapes independently:
179
+ The handle exposes every session operation for that ID:
174
180
 
175
181
  ```ts
176
182
  const response = await session.send("Continue the analysis.");
@@ -187,9 +193,9 @@ for await (const event of session.stream({ follow: false })) {
187
193
  await session.end({ reason: "User requested a fresh session" });
188
194
  ```
189
195
 
190
- `client.sessions` stores the session ID, stream cursor, and optional opaque `inbox` value. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and `end()` leaves the handle pinned to the retired ID. Replace calls to the old `reset()` method with `end()`; use `client.sessions.create()` to start a different session. Upgrade the server before using a new client's `end()` method: earlier servers do not serve `/end`.
196
+ Each handle stores the session ID, stream cursor, and optional `inbox` value. Every method calls a `/eve/v1/session/:sessionId/...` route for that ID. Sending to an unknown or ended session fails instead of creating a new one. After `end()`, the handle keeps pointing at the retired ID; call `client.sessions.create()` to start a different session. A server must serve `/end` before a client can call `end()` on it.
191
197
 
192
- A client can own many independent fixed sessions at once:
198
+ One client can run many independent sessions at once:
193
199
 
194
200
  ```ts
195
201
  const { session: alice, delivery: aliceDelivery } = await client.sessions.create({
@@ -202,7 +208,7 @@ const { session: bob, delivery: bobDelivery } = await client.sessions.create({
202
208
  await Promise.all([aliceDelivery.result(), bobDelivery.result()]);
203
209
  ```
204
210
 
205
- The next pages cover the session lifecycle:
211
+ Read more about working with sessions:
206
212
 
207
213
  - [Messages](./messages): send turns and collect results
208
214
  - [Continuations](./continuations): persist and resume sessions