eve 0.90.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 (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. 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,35 +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 a complete agent-info version 5 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
- The response 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. It includes authored instruction content, skill and schedule markdown, and server paths, so the server answers only operator principals (`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 principal gets a `ClientError` with `status` `403` and `code` `"info_forbidden"`.
46
+ The response contains:
47
47
 
48
- The version changes only for breaking reshapes; a server adds fields and enum values within a version. The client ignores fields it does not know, and enum-like fields holding a string it cannot interpret (such as `mode`, `sourceKind`, or a channel `method`) read as `"unrecognized"`, so handle that value when you switch on them. A missing or non-string value still throws `AgentInfoResponseError`. `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 version bump, and an unknown one throws `AgentInfoResponseError`.
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
49
52
 
50
- A non-success response throws `ClientError`. Invalid JSON, a different agent-info version, duplicate identities, inconsistent totals, or mismatched source provenance throws `AgentInfoResponseError`. For a version mismatch, its `issues` name which side to upgrade: eve in the agent, or the eve package the client runs from.
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.
51
62
 
52
63
  ## Authentication
53
64
 
@@ -76,7 +87,7 @@ const client = new Client({
76
87
  });
77
88
  ```
78
89
 
79
- 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:
80
91
 
81
92
  ```ts
82
93
  import { getVercelOidcToken } from "@vercel/oidc";
@@ -91,7 +102,7 @@ const client = new Client({
91
102
  });
92
103
  ```
93
104
 
94
- 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:
95
106
 
96
107
  ```ts
97
108
  const client = new Client({
@@ -103,9 +114,15 @@ const client = new Client({
103
114
  });
104
115
  ```
105
116
 
106
- 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.
107
118
 
108
- Per-request headers can be attached to an individual turn:
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. |
124
+
125
+ Attach per-request headers to an individual turn:
109
126
 
110
127
  ```ts
111
128
  const response = await session.send("Run the check.", {
@@ -115,36 +132,23 @@ const response = await session.send("Run the check.", {
115
132
  await response.result();
116
133
  ```
117
134
 
118
- 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`.
119
136
 
120
137
  ## Faster sends with `inbox`
121
138
 
122
- Keep the complete `session.state` when saving and restoring a conversation. It can include an
123
- opaque `inbox` value issued by the server. The client sends it back with later messages to avoid
124
- another hook lookup. Persist it and pass it back unchanged: do
125
- not inspect, edit, or construct it, because eve may change or extend its contents in any release.
126
- 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.
127
142
 
128
- Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret (at least 32 characters)
129
- on the deployments that share sessions. Without this key, handles are neither issued nor used.
130
- The signature authenticates all routing and encryption fields before use. Rotation falls back
131
- 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.
132
144
 
133
- Reuse also requires a Workflow SDK with `parseHookResumeHandle`, an adapter that declares
134
- `resolvedHookResume`, and a backend with the guarded resolved-hook endpoint.
135
- Older SDKs do not issue or use handles, even when the secret
136
- is configured. This change keeps the released SDK dependencies; adopting the SDK update
137
- enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
138
- 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.
139
146
 
140
- The server checks that the handle addresses the requested session's inbox. Workflow still validates the
141
- hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
142
- 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.
143
148
 
144
149
  ## Sessions
145
150
 
146
- Create and park an ID-addressed conversation before its first turn when you can start session work
147
- while the user is still composing:
151
+ Create a session before its first turn so it starts while the user is still typing:
148
152
 
149
153
  ```ts
150
154
  const { session } = await client.sessions.create();
@@ -153,9 +157,7 @@ const response = await session.send("Summarize account A.");
153
157
  await response.result();
154
158
  ```
155
159
 
156
- The create promise resolves when the server accepts the durable workflow. It does not open the
157
- event stream or wait for initialization; an early `session.send()` uses the
158
- 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.
159
161
 
160
162
  To create the session and start its first turn in one request, include the message:
161
163
 
@@ -168,13 +170,13 @@ await session.compact();
168
170
  await session.clear();
169
171
  ```
170
172
 
171
- 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:
172
174
 
173
175
  ```ts
174
176
  const session = client.sessions.attach("wrun_A");
175
177
  ```
176
178
 
177
- 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:
178
180
 
179
181
  ```ts
180
182
  const response = await session.send("Continue the analysis.");
@@ -191,9 +193,9 @@ for await (const event of session.stream({ follow: false })) {
191
193
  await session.end({ reason: "User requested a fresh session" });
192
194
  ```
193
195
 
194
- `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.
195
197
 
196
- A client can own many independent fixed sessions at once:
198
+ One client can run many independent sessions at once:
197
199
 
198
200
  ```ts
199
201
  const { session: alice, delivery: aliceDelivery } = await client.sessions.create({
@@ -206,7 +208,7 @@ const { session: bob, delivery: bobDelivery } = await client.sessions.create({
206
208
  await Promise.all([aliceDelivery.result(), bobDelivery.result()]);
207
209
  ```
208
210
 
209
- The next pages cover the session lifecycle:
211
+ Read more about working with sessions:
210
212
 
211
213
  - [Messages](./messages): send turns and collect results
212
214
  - [Continuations](./continuations): persist and resume sessions