eve 0.84.1 → 0.86.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 (186) hide show
  1. package/README.md +7 -4
  2. package/dist/CHANGELOG.md +38 -0
  3. package/dist/src/channel/channel-operations.d.ts +2 -18
  4. package/dist/src/channel/compiled-channel.d.ts +3 -7
  5. package/dist/src/channel/cross-channel-receive.d.ts +9 -10
  6. package/dist/src/channel/cross-channel-receive.js +1 -1
  7. package/dist/src/channel/schedule.js +1 -1
  8. package/dist/src/channel/session.d.ts +26 -4
  9. package/dist/src/channel/session.js +1 -1
  10. package/dist/src/chunks/{use-eve-agent-DMeP0JOF.js → use-eve-agent-B2jCfcnG.js} +3 -2
  11. package/dist/src/chunks/{use-eve-agent-DP5Rso9C.js → use-eve-agent-DCLFi26P.js} +3 -2
  12. package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
  13. package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
  14. package/dist/src/cli/dev/tui/runner.d.ts +1 -1
  15. package/dist/src/cli/dev/tui/runner.js +1 -1
  16. package/dist/src/cli/run.js +1 -1
  17. package/dist/src/client/client.js +1 -1
  18. package/dist/src/client/open-stream.js +1 -1
  19. package/dist/src/client/types.d.ts +5 -4
  20. package/dist/src/compiled/.vendor-stamp.json +4 -4
  21. package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
  22. package/dist/src/compiled/@vercel/schedules/index.js +2 -2
  23. package/dist/src/context/keys.d.ts +7 -0
  24. package/dist/src/context/keys.js +1 -1
  25. package/dist/src/execution/agent-sessions/context.d.ts +5 -1
  26. package/dist/src/execution/agent-sessions/context.js +1 -1
  27. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  28. package/dist/src/execution/legacy-session/snapshot.d.ts +1 -2
  29. package/dist/src/execution/legacy-session/snapshot.js +1 -1
  30. package/dist/src/execution/proxied-deliver-step.js +1 -1
  31. package/dist/src/execution/public-destination.d.ts +3 -0
  32. package/dist/src/execution/public-destination.js +1 -1
  33. package/dist/src/execution/publish-session-events.js +1 -1
  34. package/dist/src/execution/session/active-turn.js +1 -1
  35. package/dist/src/execution/session/answer-caller.d.ts +9 -5
  36. package/dist/src/execution/session/answer-caller.js +1 -1
  37. package/dist/src/execution/session/checkpoint-migrations.d.ts +16 -5
  38. package/dist/src/execution/session/checkpoint-migrations.js +1 -1
  39. package/dist/src/execution/session/checkpoint-refusal.d.ts +4 -0
  40. package/dist/src/execution/session/checkpoint-refusal.js +1 -0
  41. package/dist/src/execution/session/entry.js +1 -1
  42. package/dist/src/execution/session/handoff-steps.d.ts +7 -1
  43. package/dist/src/execution/session/handoff-steps.js +1 -1
  44. package/dist/src/execution/session/imported-conversation.d.ts +2 -0
  45. package/dist/src/execution/session/imported-conversation.js +1 -0
  46. package/dist/src/execution/session/interrupted-step.js +1 -1
  47. package/dist/src/execution/session/pre-v27-checkpoint.d.ts +36 -0
  48. package/dist/src/execution/session/pre-v27-checkpoint.js +1 -0
  49. package/dist/src/execution/session/principal.d.ts +8 -0
  50. package/dist/src/execution/session/principal.js +1 -1
  51. package/dist/src/execution/session/program.d.ts +2 -0
  52. package/dist/src/execution/session/program.js +1 -1
  53. package/dist/src/execution/session/turn-step.js +1 -1
  54. package/dist/src/execution/session/turn.js +1 -1
  55. package/dist/src/execution/session-callback-request.js +1 -1
  56. package/dist/src/execution/tool-auth.js +1 -1
  57. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  58. package/dist/src/execution/tools/channel-to.d.ts +12 -0
  59. package/dist/src/execution/tools/channel-to.js +1 -0
  60. package/dist/src/execution/tools/workflow/body.d.ts +3 -0
  61. package/dist/src/execution/tools/workflow/body.js +1 -1
  62. package/dist/src/execution/tools/workflow/step-context.d.ts +5 -0
  63. package/dist/src/execution/tools/workflow/step-execution.js +1 -1
  64. package/dist/src/execution/tools/workflow/step.js +1 -1
  65. package/dist/src/execution/workflow-callback-url.d.ts +2 -3
  66. package/dist/src/execution/workflow-callback-url.js +1 -1
  67. package/dist/src/execution/workflow-runtime.js +1 -1
  68. package/dist/src/harness/attachment-staging.d.ts +2 -2
  69. package/dist/src/harness/attachment-staging.js +1 -1
  70. package/dist/src/harness/compaction/step.js +1 -1
  71. package/dist/src/harness/model-call/call.js +1 -1
  72. package/dist/src/harness/model-call/run.js +1 -1
  73. package/dist/src/harness/session-machine/transitions.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/attachments/limited-read.d.ts +2 -0
  76. package/dist/src/internal/attachments/limited-read.js +1 -1
  77. package/dist/src/internal/attachments/url-refs.js +1 -1
  78. package/dist/src/internal/capability-error.d.ts +3 -0
  79. package/dist/src/internal/capability-error.js +1 -0
  80. package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
  81. package/dist/src/public/channels/chat-sdk/chatSdkChannel.js +1 -1
  82. package/dist/src/public/channels/discord/discordChannel.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/linear/linearChannel.js +1 -1
  85. package/dist/src/public/channels/linq/inboundContent.js +1 -1
  86. package/dist/src/public/channels/slack/answers.d.ts +2 -3
  87. package/dist/src/public/channels/slack/answers.js +1 -1
  88. package/dist/src/public/channels/slack/api.d.ts +23 -3
  89. package/dist/src/public/channels/slack/api.js +1 -1
  90. package/dist/src/public/channels/slack/app-manifest.d.ts +2 -0
  91. package/dist/src/public/channels/slack/app-manifest.js +1 -1
  92. package/dist/src/public/channels/slack/auth.d.ts +2 -1
  93. package/dist/src/public/channels/slack/auth.js +1 -1
  94. package/dist/src/public/channels/slack/code-channel.d.ts +42 -0
  95. package/dist/src/public/channels/slack/code-channel.js +1 -0
  96. package/dist/src/public/channels/slack/defaults.d.ts +7 -3
  97. package/dist/src/public/channels/slack/defaults.js +3 -3
  98. package/dist/src/public/channels/slack/hitl.d.ts +7 -17
  99. package/dist/src/public/channels/slack/hitl.js +1 -1
  100. package/dist/src/public/channels/slack/index.d.ts +4 -3
  101. package/dist/src/public/channels/slack/index.js +1 -1
  102. package/dist/src/public/channels/slack/interaction-cards.d.ts +0 -2
  103. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  104. package/dist/src/public/channels/slack/interactions.js +1 -1
  105. package/dist/src/public/channels/slack/open-code-channel.d.ts +30 -0
  106. package/dist/src/public/channels/slack/open-code-channel.js +1 -0
  107. package/dist/src/public/channels/slack/private-approval-delivery.d.ts +16 -4
  108. package/dist/src/public/channels/slack/private-approval-delivery.js +1 -1
  109. package/dist/src/public/channels/slack/renderers.d.ts +58 -6
  110. package/dist/src/public/channels/slack/renderers.js +1 -1
  111. package/dist/src/public/channels/slack/reply-delivery.d.ts +4 -0
  112. package/dist/src/public/channels/slack/reply-delivery.js +1 -1
  113. package/dist/src/public/channels/slack/request-card-render.d.ts +45 -0
  114. package/dist/src/public/channels/slack/request-card-render.js +1 -0
  115. package/dist/src/public/channels/slack/request-cards.d.ts +35 -0
  116. package/dist/src/public/channels/slack/request-cards.js +3 -0
  117. package/dist/src/public/channels/slack/sign-in-cancel.d.ts +3 -5
  118. package/dist/src/public/channels/slack/sign-in-cancel.js +1 -1
  119. package/dist/src/public/channels/slack/slackChannel.d.ts +109 -22
  120. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  121. package/dist/src/public/channels/slack/task-card.d.ts +3 -3
  122. package/dist/src/public/channels/slack/task-card.js +1 -1
  123. package/dist/src/public/channels/slack/thread-status.js +1 -1
  124. package/dist/src/public/channels/teams/api.js +1 -1
  125. package/dist/src/public/channels/teams/defaults.js +1 -1
  126. package/dist/src/public/channels/teams/teamsChannel.js +1 -1
  127. package/dist/src/public/channels/teams/verify.d.ts +9 -5
  128. package/dist/src/public/channels/teams/verify.js +1 -1
  129. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  130. package/dist/src/public/channels/twilio/twilioChannel.js +1 -1
  131. package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
  132. package/dist/src/public/schedules/providers/vercel.js +1 -1
  133. package/dist/src/public/schedules/subscription.d.ts +10 -1
  134. package/dist/src/runtime/subagents/workflow.js +1 -1
  135. package/dist/src/setup/index.d.ts +1 -1
  136. package/dist/src/setup/primitives/index.d.ts +1 -1
  137. package/dist/src/setup/primitives/pm/run.d.ts +0 -2
  138. package/dist/src/setup/scaffold/create/project.js +1 -1
  139. package/dist/src/shared/channel-definition.d.ts +4 -4
  140. package/dist/src/subagents/adapter.js +1 -1
  141. package/dist/src/subagents/parent-notification.js +1 -1
  142. package/dist/src/svelte/index.js +1 -1
  143. package/dist/src/svelte/use-eve-agent.js +1 -1
  144. package/dist/src/tools/definition.d.ts +21 -0
  145. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  146. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  147. package/dist/src/tools/workflow-definition.d.ts +4 -4
  148. package/dist/src/vue/index.js +1 -1
  149. package/dist/src/vue/use-eve-agent.js +1 -1
  150. package/docs/channels/custom.mdx +16 -3
  151. package/docs/channels/eve.mdx +3 -5
  152. package/docs/channels/linq.mdx +1 -1
  153. package/docs/channels/slack.mdx +185 -18
  154. package/docs/channels/teams.mdx +6 -2
  155. package/docs/concepts/project-structure.mdx +1 -1
  156. package/docs/concepts/security-model.md +4 -0
  157. package/docs/concepts/upgrade-to-v27-events.md +70 -2
  158. package/docs/experimental/dynamic-schedules.mdx +2 -2
  159. package/docs/getting-started.mdx +2 -0
  160. package/docs/guides/auth-and-route-protection.md +1 -0
  161. package/docs/guides/client/overview.mdx +1 -1
  162. package/docs/guides/client/streaming.mdx +1 -1
  163. package/docs/guides/deployment/self-hosting.md +1 -1
  164. package/docs/guides/frontend/meta.json +1 -0
  165. package/docs/guides/frontend/nextjs.mdx +329 -121
  166. package/docs/guides/frontend/overview.mdx +115 -335
  167. package/docs/guides/frontend/tanstack.mdx +1 -1
  168. package/docs/guides/frontend/use-eve-agent-svelte.mdx +5 -5
  169. package/docs/guides/frontend/use-eve-agent-vue.mdx +5 -5
  170. package/docs/guides/frontend/use-eve-agent.mdx +385 -0
  171. package/docs/guides/hooks.md +1 -1
  172. package/docs/guides/remote-agents.md +10 -0
  173. package/docs/guides/self-modification.md +6 -0
  174. package/docs/patterns/fork-conversations-into-new-threads.md +159 -0
  175. package/docs/patterns/meta.json +1 -0
  176. package/docs/reference/cli.md +1 -2
  177. package/docs/sandbox/index.mdx +1 -1
  178. package/docs/schedules.mdx +1 -1
  179. package/docs/tools/overview.mdx +34 -0
  180. package/docs/tools/workflows.mdx +47 -5
  181. package/package.json +13 -21
  182. package/CHANGELOG.md +0 -3076
  183. package/dist/src/public/channels/slack/approval-cards.d.ts +0 -25
  184. package/dist/src/public/channels/slack/approval-cards.js +0 -2
  185. package/dist/src/self-modification/agent.d.ts +0 -12
  186. package/dist/src/self-modification/agent.js +0 -1
@@ -3,40 +3,28 @@ title: "Overview"
3
3
  description: "Put an eve agent behind a browser chat UI with useEveAgent."
4
4
  ---
5
5
 
6
- Use this guide when you already have a browser application and need to connect it to an eve agent. `useEveAgent()` opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface.
6
+ `useEveAgent` connects a browser UI to an eve agent. It starts a session, sends messages, and streams the agent's reply into state you can render. This page uses React; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) work the same way.
7
7
 
8
- ## The integration model
8
+ ## How it works
9
9
 
10
- A browser UI is a client of the agent's HTTP routes (the [eve channel](../../channels/overview)). Two layers wire it up:
10
+ Your app and the agent share an origin. The browser calls the agent at `/eve/v1/*`, and a framework integration or your hosting routes those requests to the agent:
11
11
 
12
- - **Routing** makes the agent reachable from the browser. A framework integration can mount eve on your app's origin: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin), or [TanStack Start](./tanstack) (the `eveTanStack` Vite plugin). If the frontend and agents are peer services, use your deployment platform or reverse proxy instead. The hook works with either setup; pass `baseUrl` for a different origin or a named path mount.
13
- - **The hook** (`useEveAgent`) holds the session state, streaming, errors, and composer status. It defaults to same-origin eve routes such as `/eve/v1/session`.
12
+ - [Next.js](./nextjs)
13
+ - [Nuxt](./nuxt)
14
+ - [SvelteKit](./sveltekit)
15
+ - [TanStack Start](./tanstack)
14
16
 
15
- The framework pages walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), [SvelteKit](./sveltekit), and [TanStack Start](./tanstack). See [Project Structure](../../concepts/project-structure#configure-a-web-deployment) to choose between a framework integration and peer services.
17
+ To generate a working chat app, run `eve add channel/web`. For scripts and server code that don't render UI, use the [Client SDK](../client/overview).
16
18
 
17
- For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [Client SDK](../client/overview) directly.
18
-
19
- ## Authenticate browser requests
20
-
21
- A same-origin framework integration sends your application cookies with every eve request. For bearer tokens or another non-cookie scheme, pass `auth` or `headers` to `useEveAgent`.
22
-
23
- The default eve channel fails closed. Without an authored `agent/channels/eve.ts`, production browser traffic receives `401` from the default `[vercelOidc(), localDev(), placeholderAuth()]` policy. Add the channel file with an `AuthFn` that verifies your application session or token.
24
-
25
- For a public demo, use `none()` from `eve/channels/auth` to admit anonymous requests explicitly. Do not use `none()` for an agent that handles private or production data. See [Authentication](../auth-and-route-protection) for application-session examples, token verifiers, and the default policy.
26
-
27
- ## Basic chat (React)
28
-
29
- The hook lives in `eve/react`. Render `messages`, use `activeTurn(view)` from `eve/events` to steer follow-ups into an open turn, and send text with `send`:
19
+ ## Build a basic chat
30
20
 
31
21
  ```tsx
32
22
  "use client";
33
23
 
34
- import { activeTurn } from "eve/events";
35
24
  import { useEveAgent } from "eve/react";
36
25
 
37
26
  export function Chat() {
38
27
  const agent = useEveAgent();
39
- const turnOpen = activeTurn(agent.view) !== undefined;
40
28
  const isResuming = agent.status === "resuming";
41
29
 
42
30
  return (
@@ -46,7 +34,7 @@ export function Chat() {
46
34
  const form = new FormData(event.currentTarget);
47
35
  const message = String(form.get("message") ?? "").trim();
48
36
  if (message.length > 0 && !isResuming) {
49
- void agent.send(message, turnOpen ? { turnPolicy: "steer" } : undefined);
37
+ void agent.send(message);
50
38
  }
51
39
  }}
52
40
  >
@@ -67,211 +55,31 @@ export function Chat() {
67
55
  }
68
56
  ```
69
57
 
70
- ## Returned state
71
-
72
- `useEveAgent()` returns the current UI state plus commands:
73
-
74
- | Field | What it is |
75
- | ------------------ | ----------------------------------------------------------------------------- |
76
- | `view` | Opaque, immutable snapshot queried through `eve/events`. |
77
- | `messages` | Rendered messages, including local optimistic submissions and answers. |
78
- | `agents` | Followed child sessions and their independent observations. |
79
- | `status` | Outstanding work: `"idle"`, `"busy"`, or `"resuming"`. Errors are separate. |
80
- | `error` | The latest session creation, stream, resume, or turn failure. |
81
- | `events` | Raw eve stream events for this session. |
82
- | `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`). |
83
- | `prewarm` | Create a session or prepare its idle owner without starting a turn. |
84
- | `send`, `respond` | Submit a message or answers; resolve with a `Delivery` receipt when accepted. |
85
- | `resume` | Replay through the durable tail; further following obeys `followWhile`. |
86
- | `follow` | Follow a same-session delivery receipt, including one sent by another store. |
87
- | `cancel` | Request durable cancellation of the active turn. |
88
- | `clear`, `compact` | Queue a context change and return its delivery. |
89
- | `reset` | Retire the server-side session and return its delivery. |
90
- | `newSession` | Clear local state and the local session cursor. |
91
-
92
- Most chat UIs only need `messages`, `status`, and `activeTurn(view)`. Use `view` with queries from `eve/events` for lifecycle state, or `events` when you need the wire log for persistence or audit. Snapshots publish after every fact in a committed line has folded. Retained views and their observations stay unchanged after later updates; tables and preview dictionaries are not public fields.
93
-
94
- Pass `prewarm: true` to start a workflow when the chat mounts and after each `newSession()` call:
95
-
96
- ```tsx
97
- import { useEveAgent } from "eve/react";
98
-
99
- export function Chat() {
100
- const agent = useEveAgent({ prewarm: true });
101
-
102
- return <button onClick={agent.newSession}>New chat</button>;
103
- }
104
- ```
105
-
106
- React can turn `prewarm` on after mount, and its initial or later `true` value also prepares a
107
- restored session. Vue and Svelte read it when their binding is created, so call their returned
108
- `prewarm()` method when typing starts.
109
-
110
- Prewarming defaults to `false`: the first send creates the session. Set it to `true` only after
111
- your application's auth, headers, and any chat-record binding are ready. Applications that
112
- prepare those in the submit handler should keep the default until then.
113
-
114
- Prewarming starts the workflow and establishes its inbox, then parks before session hooks or
115
- dynamic definitions run. Meanwhile, it starts the agent's [sandbox](/docs/sandbox) in the
116
- background. The first message passes through the channel's `onMessage` hook and supplies the
117
- identity and context for initialization and `turn_0`. That turn does not wait for the sandbox;
118
- only a tool or hook that uses the sandbox waits for the rest of its start. If the sandbox fails
119
- to start during prewarming, the first turn that uses it starts it instead. eve deletes the
120
- sandbox when the session ends, including when an unused prewarmed session times out.
121
-
122
- For an existing session, `prewarm()` checks which deployment runs the session against the exact
123
- deployment accepting that request. On Vercel, an idle session on another deployment can move to
124
- the accepting deployment in the background before the next `send()`. The session ID, history,
125
- stream, and expiry stay the same; no model call runs. A session already running on that
126
- deployment is not woken. Active turns are never interrupted; an active turn can finish before
127
- preparation, and a queued real message takes priority. A session with pending tasks or input
128
- requests can skip the hint. A session started by an eve version without preparation support, or
129
- running on a workflow backend without deployment routing, is not moved.
130
-
131
- Call `agent.prewarm()` once when a new typing burst begins, with an application-level cooldown
132
- if you also retry during long drafts. eve shares concurrent calls; it does not listen to inputs
133
- or poll deployments. A production alias targets its current deployment; a preview alias targets
134
- that preview. Requests pinned to an immutable deployment (including deployment-skew routing)
135
- cannot discover a newer deployment. In local development, `prewarm()` can create a new session,
136
- but does not move an existing one.
137
-
138
- `client.sessions.attach(sessionId).prewarm({ signal })` returns `ready`, `accepted`,
139
- `unsupported`, or `no_active_session`. `accepted` means the hint was persisted, not that handoff
140
- has finished. It never replaces an expired session. `send()` retains its existing retry and
141
- handoff behavior if preparation is unavailable, fails, or has not finished.
142
-
143
- The explicit `prewarm()` method resolves after ingress acceptance, as does `client.sessions.create()`.
144
- It does not wait for an initialization event; concurrent calls share the same request.
145
- The composer stays `"idle"`, meaning it can accept input, and prewarming does not run
146
- `prepareSend`. A concurrent `send()` waits for initial creation acceptance when needed, but never
147
- waits for existing-session preparation.
148
- If the inbox is still starting, the client retries `409 session_not_ready` with bounded
149
- exponential backoff for up to 20 seconds. The caller's abort signal cancels the wait. Stream
150
- events are not a prerequisite for sending.
151
-
152
- An existing-session preparation failure rejects the explicit call without setting `error` or
153
- blocking `send()`. A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
154
- fall back to creating a session with its message. After creation succeeds, initialization
155
- failures arrive on the stream during the first turn. The configured session timeout starts
156
- at creation, so an unused prewarmed session can expire before its first message. React does not
157
- retry a failed prewarm on unrelated renders while the option remains `true`; call `prewarm()`,
158
- change the option from `false` to `true` again, call `newSession()`, or send a message to recover.
159
-
160
- The hook keeps consuming one session stream across turns and idle periods. Replies,
161
- authorization updates, and turns started elsewhere all update the same projection. Each message a
162
- person sends is its own bubble, placed where its turn took it in: a message that arrives while the
163
- turn works splits the agent's response, so what the agent did before the message shows above it
164
- and the rest below. The pieces share `metadata.turnId`. A single event that coalesces multiple
165
- deliveries remains one bubble. A turn settling does not close the connection. The transport reconnects from
166
- its cursor after a disconnect or the
167
- server's renewable 60-second lease; lease renewal does not start a turn or clear UI state.
168
- Unmounting or calling `newSession()` closes the local stream without cancelling the old durable session.
169
-
170
- By default, the stream remains open between turns, so events from schedules, channels, or other
171
- clients arrive as they happen. For a help sidebar that only needs updates during machine work,
172
- close it when the committed session view becomes idle. Bind both stores to the same existing
173
- `ClientSession`, kept stable across renders:
174
-
175
- ```tsx
176
- import type { ClientSession } from "eve/client";
177
- import { idle } from "eve/events";
178
- import { useEveAgent } from "eve/react";
179
-
180
- function useSessionPanels(session: ClientSession) {
181
- const chat = useEveAgent({ session });
182
- const sidebar = useEveAgent({ session, followWhile: (view) => !idle(view) });
183
-
184
- async function send(message: string) {
185
- const receipt = await chat.send(message);
186
- sidebar.follow(receipt);
187
- return receipt;
188
- }
189
-
190
- return { chat, sidebar, send };
191
- }
192
- ```
193
-
194
- `followWhile(view)` closes the stream when it returns false at a complete line boundary, after catch-up and any accepted receipt being followed. It can close while a turn is active or waiting on an interaction; the UI then remains at its last observed state, including `status`, until another command or explicit follow reopens the stream. To keep following machine work and open turns, including turns waiting on a person, and close only between turns, pass `followWhile: (view) => !idle(view) || activeTurn(view) !== undefined`. React reads the latest predicate on render; Vue and Svelte read it from their options object.
195
-
196
- Both stores must point to the same session. `follow()` tracks an accepted receipt until it settles, even if the stream catches up before admission. Pass only a receipt returned by `send`, `respond`, `clear`, `compact`, or `reset`. Because a receipt can precede its admission, the store keeps waiting for an id the stream never admits: it stays `"busy"` with the stream open until the session ends or you call `newSession()`. `follow()` does not create a session or grant access. A closed stream cannot see new activity by itself; send a command, call `resume()` or `follow()`, or leave default continuous following on when other sources can start work. Limit retries after stream errors, and resolve authorization failures before retrying.
197
-
198
- `newSession()` reuses the hook instance and clears the local conversation. `reset()` instead retires the server-side session and returns its delivery. Call `newSession()` to clear the retired conversation and prepare a fresh one. If `prewarm` is true, that call prepares the next owned session; otherwise, the next send creates it. An explicitly
199
- supplied `session` remains externally owned and is never replaced by prewarming or `newSession()`. Use
200
- `initialSession` with `resume: true` to restore a saved chat.
201
-
202
- `messages` are eve-owned `EveMessage[]`. Assistant text and reasoning parts have a stable `id` from the event that created the part. Appends and completion retain that ID. Use `part.id` to key streamed assistant content, including successive text parts within one step. Older events without an ID get a best-effort fallback. User text parts may not have an ID.
58
+ Most chat UIs need only a few values from the hook:
203
59
 
204
- A message's parts are `text`, `reasoning`, `file` (an attachment a person sent; its `url` can be absent), `tool` (a call the turn made), and `interaction` (something the turn asked a person that no call carries: a sign-in, the budget prompt, or a question about no call). Each assistant part carries its turn's `stepIndex`. The parts are eve's own; if you pass messages to an API typed as AI SDK `UIMessage[]`, adapt them first.
60
+ | Value | Use it to |
61
+ | ------------------ | --------------------------------------------------------------- |
62
+ | `messages` | Render the conversation |
63
+ | `status` | Disable input while `"resuming"`; show a spinner while `"busy"` |
64
+ | `error` | Show the latest failure |
65
+ | `activeTurn(view)` | Check whether a turn is open, so you can offer to cancel it |
66
+ | `send`, `respond` | Send a message, or answer a question |
67
+ | `cancel` | Stop the running turn |
68
+ | `newSession` | Start a new conversation |
205
69
 
206
- A `tool` part renders the shared call state, with partial input while it streams:
70
+ See the [`useEveAgent` reference](./use-eve-agent) for everything else.
207
71
 
208
- | Field | What it is |
209
- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
210
- | `callId`, `name` | The call, and the tool, agent, or skill it invokes. |
211
- | `kind` | `tool`, `agent`, `skill`, or `control` (task controls, usually hidden in activity displays). |
212
- | `label` | The tool's authored label, its latest output label, or a readable name. |
213
- | `state` | `streaming` while input arrives, then the shared `CallState`: `requested`, `approval`, `running`, `blocked`, `completed`, `failed`, `rejected`, or `cancelled`. |
214
- | `inputText` | Partial input, only when `state` is `streaming`. |
215
- | `input`, `output`, `error` | Validated input, current or final output, and error details after input streaming. |
216
- | `interaction` | The latest approval or question about the call. Its status stays `open` while an answer is submitted; settlement confirms the decision. |
217
-
218
- Read outcomes, reasons, and task identities from `call(view, part.callId)` from `eve/events`
219
- instead of duplicate fields on the renderable part.
220
- A call your stream stopped following stays open; decide yourself what an open call shows once the stream ended. A call a model retry replaced doesn't show: the replacement asks again.
221
-
222
- A delegated call stays running until `call.settled`; its child's detailed events live on a separate stream. Query `call(view, callId)` for the call outcome, and `agents[sessionId]` for the opened child session.
223
-
224
- Detailed child progress lives on the child session's stream, not in the root `messages`. Pass `followAgents: true` to recursively observe recorded children, including children opened inside workflow tools. Following is off by default. React, Vue, and Svelte use the same store-owned traversal.
225
-
226
- To select relationships, pass a synchronous predicate. `true` and `() => true` have the same meaning; an excluded child's descendants are not discovered:
227
-
228
- ```tsx
229
- const agent = useEveAgent({
230
- followAgents: ({ depth }) => depth <= 3,
231
- });
232
- ```
233
-
234
- Root depth is zero. eve admits at most 128 child observations per root generation, follows to depth 8, and allows 8 simultaneous descendant reads independently of the root stream. Each read stops at its captured durable tail or yields its slot after 10 seconds. Caught-up observations are refreshed with delays from 1 to 10 seconds. These bounds do not limit execution or the root transcript. `newSession()` resets admission accounting. The policy is read at store creation and evaluated once per relationship at each known reachable depth; unrelated renders do not replace followers. When authorized readers establish that two paths reach the same session, the store shares its observation and considers both paths' depths.
235
-
236
- Each `agents[sessionId]` describes an opening, with an `owner` naming its call or task. A followed `observation.conversation` has its own `agents`, `messages`, and opaque `view`. Calls that continue a task reuse its child conversation; the opening owner does not change. Read the particular call or delivery's settled result for its outcome, not the child's latest message.
237
-
238
- To show what one call caused in a child it shares with other calls, use `agentCallActivity(state, callId)` from `eve/client`. It follows the `child.sent` links the parent recorded to each delivery the call sent and the child turns that consumed them:
239
-
240
- ```ts
241
- import { agentCallActivity } from "eve/client";
242
-
243
- const activity = agentCallActivity(agent, callId);
244
- if (activity.status === "linked") {
245
- for (const { sessionId, deliveries, turns } of activity.sessions) {
246
- const pending = deliveries.some(({ status }) => status !== "settled");
247
- const turnIds = new Set(turns.map(({ turnId }) => turnId));
248
- // Render agent.agents[sessionId]'s messages whose metadata.turnId is in turnIds.
249
- }
250
- }
251
- ```
252
-
253
- A delivery's `status` is `"unseen"` until this reader reads the child's admission, then the child's own `"admitted"`, `"consumed"`, or `"settled"`. Several calls can reach one turn, as when a call arrives while the agent works; each turn lists the other calls it answered in `sharedWith`, so render it once for all of them rather than splitting it. `"unlinked"` means the parent recorded no delivery for the call, as for a call that sent nothing or reached a remote agent on an earlier protocol.
254
-
255
- | Observation status | Meaning |
256
- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
257
- | `"not-followed"` | Following is disabled, or `reason` identifies a predicate, depth/session limit, or cycle. |
258
- | `"queued"` | Admitted and waiting for a read slot. |
259
- | `"following"` | Reading a finite captured prefix. Silence does not imply settlement. |
260
- | `"caught-up"` | Reached the tail captured for this read; the child may still be working, and another read can discover more activity. |
261
- | `"interrupted"` | A retryable read failure or detached observation scope. |
262
- | `"unavailable"` | History cannot currently be read. `reason` distinguishes authorization, expiry, unsupported readers, and transport failures. |
263
-
264
- Except for `"not-followed"`, an observation exposes `position`, `caughtUp`, and its committed `conversation`, which can be empty before the first successful read. Its server-established `key` identifies the session within this store's authorized reader scope, not across principals or stores. Equal session IDs reached through different remote reader namespaces are not merged. Cursors use source-line positions and remain independent across sessions.
72
+ ## Authenticate browser requests
265
73
 
266
- `caughtUp` describes the tail captured when that read opened, not execution completion or exhaustive subtree coverage. The next read establishes a new horizon. Root call results, `status`, `resume()`, `events`, and callbacks keep their root-session meaning; descendant failures remain on their observations. Parent-relayed interactions remain the source of actionable prompts, so do not render a second set of controls from child observations.
74
+ Because the browser calls the agent on your own origin, it sends your app's cookies with every request. The agent decides whether to accept them in `agent/channels/eve.ts`.
267
75
 
268
- For headless capture, use [`SessionStore.observe()`](../client/streaming#observe-nested-traces-without-a-framework). Archive observed prefixes with their per-session cursors and your own versioned schema, not as atomic or exhaustive execution audits. Preserve prior archives when history expires; later successful reads can enrich them.
76
+ Until you add an auth check there, production browser requests get `401`. Write an `AuthFn` that verifies your app's session; [Authentication](../auth-and-route-protection) shows how. For a public demo, `none()` from `eve/channels/auth` admits everyone; don't use it for private data.
269
77
 
270
- If you manage your own session rather than using the hook, pass a `child.opened` event from `events` to [`session.agent()`](../client/streaming#follow-a-subagent) and follow the child with `stream()`. It follows local and remote children through the parent, so the browser never calls a remote deployment directly. See [What the parent sees](../../subagents#what-the-parent-sees) for the complete contract.
78
+ If your app uses bearer tokens instead of cookies, pass them to the hook. See [Custom hosts and headers](#custom-hosts-and-headers).
271
79
 
272
- ## Sending and streaming
80
+ ## Send messages
273
81
 
274
- Pass the message first and optional per-turn settings second. Use `respond()` for HITL answers:
82
+ Send text, or an array of parts to include files:
275
83
 
276
84
  ```tsx
277
85
  await agent.send("Summarize this session.");
@@ -287,37 +95,15 @@ await agent.send([
287
95
  ]);
288
96
  ```
289
97
 
290
- Assistant text, reasoning, and tool parts update `messages` as they arrive. `status` is `busy`
291
- while a message, answer, or control command is pending, a followed receipt has not settled, or the
292
- session has running or queued work, and `idle` otherwise. `resuming` means the hook is catching up
293
- an attached session; disable message and HITL submission then. `status` describes outstanding
294
- work, not whether a turn is open: a turn waiting only on a person is open while `status` is
295
- `idle`, and the stream stays open by default. Use `activeTurn(view)` to decide whether a turn is
296
- open, can be steered, or can be cancelled. A failure updates `error` without replacing the
297
- transport status.
98
+ `send()` resolves as soon as eve accepts the message. The reply then streams into `messages`.
298
99
 
299
- `send()` and `respond()` resolve on HTTP acceptance, before the agent needs to reply or pause. They reject if preparation or submission fails; a later execution failure arrives through `view`, `error`, and `onError`. A turn stays open while its work or questions are pending. Read `activeTurn(view)`, `waiting(view, turnId)`, and `activity(view)` from `eve/events` instead of maintaining another turn state. By default, the stream continues after the command's promise resolves. The returned `Delivery` also has
300
- independent `stream({ signal })` and `result({ signal })` reads. Those can open another HTTP
301
- stream and remain usable after `newSession()` or unmount; pass a signal when the read should
302
- end with your component. The store's saved cursor tracks only its own committed events, never
303
- another reader's progress.
304
-
305
- To steer an active turn with a follow-up, send the message with `turnPolicy: "steer"`. Before answer output or local tool execution begins, eve interrupts pending model generation and continues the same turn with the correction. Executing tools finish and checkpoint their results first; after answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output. The hook stays attached through completion:
100
+ A message sent while the agent is still working redirects the current turn, called steering. You don't need to do anything extra. To wait for the turn to finish instead, queue the message:
306
101
 
307
102
  ```tsx
308
- await agent.send(message, { turnPolicy: "steer" });
103
+ await agent.send("Then summarize the second file.", { turnPolicy: "queue" });
309
104
  ```
310
105
 
311
- You can submit another message while work runs: use `turnPolicy: "queue"` to wait for the current
312
- turn, or `"steer"` to guide it. Answers are accepted while other work runs. Read interactions with
313
- `interaction(view, id)` from `eve/events`: their originating turn, step, task, request, and answer
314
- are in one projection. `activeTurn(view)?.turnId` identifies the current root turn. Followed
315
- sessions have their own view under `agents[sessionId].observation.conversation`.
316
- Call `cancel()` to stop the durable turn without replacing it.
317
-
318
- `cancel()` targets the currently observed turn and keeps the event stream attached. If no turn is active, it waits for a submission pending when you called `cancel()` to identify its turn. This includes preparation, session creation, and POST acceptance. Cancellation always names the identified turn, so a delayed request cannot stop an unrelated later turn.
319
-
320
- The wait does not withdraw a queued message. If it never reaches a running turn, cancellation is a no-op; an idle `cancel()` does not arm a future request. Cancellation is cooperative, so a turn can finish before it takes effect.
106
+ To stop a running turn, call `cancel()`. Closing the page doesn't stop the turn on the server.
321
107
 
322
108
  ```tsx
323
109
  import { activeTurn } from "eve/events";
@@ -327,18 +113,11 @@ if (activeTurn(agent.view) !== undefined) {
327
113
  }
328
114
  ```
329
115
 
330
- Unmounting the component or closing the page disconnects the local stream but does not cancel server execution. Call `cancel()` before detaching when the user intends to stop the durable turn.
331
-
332
- After eve confirms an attachment turn with `delivery.consumed`, each received attachment shows as
333
- a `file` part on the user message. The part includes `mediaType`, optional
334
- `filename` and `size`, and a `url` only when the original attachment was browser-resolvable.
116
+ See [Sending](./use-eve-agent#sending) and [Cancelling](./use-eve-agent#cancelling) for exact timing.
335
117
 
336
118
  ## Human-in-the-loop prompts
337
119
 
338
- Tools gate calls with approval policies, and workflow tools ask questions with `ctx.ask()`.
339
- See [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Read open prompts from
340
- `view` and answer through the same session. A call's approval or question also appears as
341
- `part.interaction`; other prompts are `interaction` message parts.
120
+ Tools can ask a person to approve a call or answer a question. See [Human-in-the-loop](/docs/human-in-the-loop) for the server side. In the UI, read open prompts from `view` and answer with `respond()`:
342
121
 
343
122
  ```tsx
344
123
  import { openInteractions } from "eve/events";
@@ -364,11 +143,14 @@ return pendingRequests.map(({ interactionId, request }) => (
364
143
  ));
365
144
  ```
366
145
 
367
- For free text, send `{ interactionId, text }`. An interaction stays `open` until `interaction.settled`; a submitted answer alone does not decide it. A refused answer leaves the prompt answerable.
146
+ - For a free-text answer, send `{ interactionId, text }`.
147
+ - A prompt stays `open` until eve settles it, not when you submit an answer. If the answer is refused, the prompt stays answerable.
148
+ - To show how a prompt ended, read its `outcome`. Only `accepted` and `declined` mean a person decided; a prompt can also end because its turn was cancelled. See [Interactions](./use-eve-agent#interactions).
149
+ - A prompt about a tool call also appears on that call's `tool` part as `part.interaction`. Other prompts appear as `interaction` message parts.
368
150
 
369
151
  ## Sign-ins and other interactions
370
152
 
371
- Connections and tools that need OAuth or another grant open a sign-in: an `interaction.opened` with `request.kind: "sign-in"`. Sign-ins are interactions like approvals and questions; query them with `openInteractions(view, { kind: "sign-in" })`. An approval or question about a call shows on that call's tool part; every other interaction, such as a sign-in or the budget prompt, is an `interaction` message part of its own (`EveInteractionPart`). Its `request` is the interaction as asked, a sign-in's challenge in `request.signIn` (the display name, instructions, device code, and user-facing sign-in URL). The part is `open` until its interaction settles, then `settled` with its `outcome`. Render the part as a normal chat message and keep the session cursor so eve can resume the parked turn once the sign-in completes:
153
+ When a tool or connection needs the user to sign in, for example with OAuth, the turn opens a sign-in prompt. It appears in `messages` as an `interaction` part. Render it like any other message; once the user signs in, the turn continues on its own.
372
154
 
373
155
  ```tsx
374
156
  import { signInEnding, type EveMessagePart } from "eve/react";
@@ -393,11 +175,11 @@ function SignInPrompt({ part }: { part: EveMessagePart }) {
393
175
  }
394
176
  ```
395
177
 
396
- A sign-in's `interaction.opened` and `interaction.settled` facts are also available on `events` and `onEvent`.
178
+ `request.signIn` holds the provider's display name, instructions, device code, and sign-in URL. To list open sign-ins, use `openInteractions(view, { kind: "sign-in" })`.
397
179
 
398
180
  ## Attach page context per turn
399
181
 
400
- `clientContext` adds ephemeral context for the current turn. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. The context remains available to every model call in the turn, then disappears before the next turn. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it in the second argument to `send()` or `respond()`:
182
+ `clientContext` tells the agent about the user's current page for one turn. It isn't saved to the conversation history:
401
183
 
402
184
  ```tsx
403
185
  await agent.send("What should I do on this screen?", {
@@ -405,7 +187,9 @@ await agent.send("What should I do on this screen?", {
405
187
  });
406
188
  ```
407
189
 
408
- To attach the same context to every turn without threading it through each call site, use `prepareSend`. It runs right before each send and returns the (possibly augmented) turn. The optimistic message is already visible while asynchronous preparation runs:
190
+ Pass a string, an array of strings, or an object, which eve sends as JSON. The context also rides along with `respond()`.
191
+
192
+ To add context to every message, use `prepareSend`:
409
193
 
410
194
  ```tsx
411
195
  const agent = useEveAgent({
@@ -416,60 +200,9 @@ const agent = useEveAgent({
416
200
  });
417
201
  ```
418
202
 
419
- ## Lifecycle callbacks
420
-
421
- The hook accepts these lifecycle callbacks:
422
-
423
- - `onEvent(event)`: fires for each eve stream event as it arrives.
424
- - `onError(error)`: fires when session creation, streaming, resume, or a live turn fails. Restoring a historical failure updates `error` without replaying this callback. A failed prewarm reports here when no send is waiting to retry creation.
425
- - `onFinish(snapshot)`: fires when a live turn settles, after its whole committed line is visible. Catch-up never fires it, including for a locally submitted turn that already settled. Use `receipt.result()` to read that delivery's result; a delivery can settle while its turn is still awaiting input.
426
- - `onSessionChange(session)`: fires when a session is created, its cursor advances, or `newSession()` clears it. Persist the session state to resume across reloads.
427
-
428
- ```tsx
429
- const agent = useEveAgent({
430
- onEvent: (event) => console.debug(event.type),
431
- onError: (error) => toast.error(error.message),
432
- onFinish: (snapshot) => console.log(snapshot.status),
433
- });
434
- ```
435
-
436
- The `optimistic` option (default `true`) shows submitted user messages in `messages` before eve confirms them with a `delivery.consumed` fact. A follow-up sent while a turn works shows at the end of the conversation and stays there once the turn takes it in; if the send fails, the failed placeholder stays in place, with `metadata.status` `"failed"`. They show in `messages` only; `events` stays the authoritative eve stream. The hook reconciles each placeholder with the server's delivery ID, including the first message. Its message ID stays unchanged when confirmed, so an unrelated or identical message cannot consume it. While POST acknowledgements are pending, stream-driven snapshot publication waits for their identities; `onEvent` still receives the stream events.
437
-
438
- ## Derive your own state
439
-
440
- Read lifecycle state directly from `view`. It is the shared fold's committed snapshot, not a second conversation-specific turn or task model:
441
-
442
- ```tsx
443
- import { activeTurn, activity, waiting } from "eve/events";
444
-
445
- const turn = activeTurn(agent.view);
446
- const currentActivity = activity(agent.view);
447
- const blocked = turn === undefined ? undefined : waiting(agent.view, turn.turnId);
448
- ```
449
-
450
- For event-level queries, use `events`, the authoritative, deduplicated list of the session's stream events, which `newSession()` empties:
451
-
452
- ```tsx
453
- import { useMemo } from "react";
454
- import { useEveAgent } from "eve/react";
455
-
456
- const agent = useEveAgent();
457
- const toolCalls = useMemo(
458
- () => agent.events.filter((event) => event.type === "call.requested").length,
459
- [agent.events],
460
- );
461
- ```
462
-
463
- Use the snapshot's `view` instead of folding `events` again inside a component. Outside the
464
- store, `foldEvents` and `emptySessionView` from `eve/events` fold received events by whole line:
465
- assign `view = foldEvents(view, receivedEvents)`. The input view stays unchanged, and the returned
466
- snapshot holds unfinished lines privately until they complete. Use `callPreview(view, callId)`
467
- or `contentPreviews(view)` for transient progress; renderable messages still include streamed
468
- input. To render a saved log, use `conversationOf(events)` from `eve/client`.
469
-
470
203
  ## Resumable sessions
471
204
 
472
- The browser conversation lives durably on the server. Persist both the rendered event log and the `session` cursor to pick it back up after a reload:
205
+ eve stores every conversation on the server. To reopen one after a reload, save two things, `session` and `events`, and pass them back:
473
206
 
474
207
  ```tsx
475
208
  import { useEffect, useState } from "react";
@@ -500,30 +233,81 @@ useEffect(() => {
500
233
  }, [agent.events, agent.session]);
501
234
  ```
502
235
 
503
- Store the full `session` object (`sessionId`, `streamIndex`). The session cursor
504
- lets eve continue the exact durable conversation; the event log lets your UI
505
- render historical messages without replaying the whole stream. A database-backed
506
- chat app should persist committed events and the matching cursor as they change. Do not save only
507
- in `onFinish`: a turn paused on an interaction has not finished, but its events must survive a reload.
236
+ - `session` tells eve which conversation to continue and where to pick up. Save the whole object, as is.
237
+ - `events` lets you show the saved messages immediately, before eve catches up.
238
+ - If you only have a session ID, pass `initialSession: { sessionId, streamIndex: 0 }` with `resume: true`; eve replays the conversation from the start.
239
+
240
+ A few rules keep restored chats correct:
241
+
242
+ - **Save as you go.** Save on every change, not only when a turn finishes. A turn waiting on the user hasn't finished, but its messages must survive a reload.
243
+ - **Disable input while resuming.** While `status` is `"resuming"`, show the saved messages but disable sending.
244
+ - **One saved chat per conversation.** To switch conversations, remount the chat component, for example with `key={chat.id}`.
245
+ - **Create your chat record first.** If the user can reload right after sending, create your app's chat record before `send()`, and save the session ID from `onSessionChange`.
246
+
247
+ See [Resume a saved session](./use-eve-agent#resume-a-saved-session) for exactly how saved events and catch-up fit together.
248
+
249
+ ## Start a new conversation
250
+
251
+ - `newSession()` clears the chat and starts fresh. The old conversation stays on the server.
252
+ - `reset()` ends the conversation on the server. Call `newSession()` afterward to clear it locally.
508
253
 
509
- `initialEvents` must be an ordered prefix of the same session's stream, but its endpoint does not have to line up exactly with where the stream resumes. Catch-up starts after its complete source coverage, using line positions rather than event counts. Preserve reader metadata unchanged: `meta.next` can record source lines that produced no events, as with [converted v26 history](/docs/concepts/upgrade-to-v27-events). The store's `session.streamIndex` and `position(view)` both track that covered source prefix without changing the facts' original positions. The `initialSession` handle's cursor alone never extends that coverage. A partial line is replayed from its start; already observed events are skipped. Every event carries a stable [`meta.position`](/docs/concepts/sessions-runs-and-streaming#positions), and the store drops any event whose position it has already applied, so an overlapping replay renders once and `onEvent` only fires for events your UI has not seen.
254
+ To make the first reply faster, pass `prewarm: true`. eve then creates the next session before the user sends anything. Turn it on only after your auth headers are ready. See [Prewarming](./use-eve-agent#prewarming).
510
255
 
511
- For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `baseUrl`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, `followAgents`, and `resume` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`. React reads `prewarm` and `followWhile` on every render.
256
+ ## Show subagent progress
512
257
 
513
- Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `messages` but disable message and HITL submission; do not present cancellation or active-turn progress controls. `resume()` resolves when catch-up reaches the durable tail, even if a turn is still running. The binding then reports `"busy"` while the session has running or queued work. The stream reports its initial durable tail so catch-up can finish without closing the connection or waiting for an idle timeout. A settled tail, or a turn waiting only on a person, changes directly to `"idle"`; running or queued work remains `"busy"`. By default, the connection stays open to follow the turn and receive later events. A `followWhile` predicate can close it after catch-up once local obligations clear. A terminal session failure sets `error`.
258
+ When the agent delegates to a subagent, `messages` shows the delegated call, not the subagent's own messages. To follow subagents too, pass `followAgents: true`, then render `agents[sessionId].observation.conversation.messages`:
259
+
260
+ ```tsx
261
+ const agent = useEveAgent({ followAgents: true });
262
+ ```
263
+
264
+ See [Child agents](./use-eve-agent#child-agents) for limits, observation states, and showing what a single call caused.
265
+
266
+ ## Lifecycle callbacks
267
+
268
+ - `onEvent(event)` runs for each stream event.
269
+ - `onError(error)` runs when something fails.
270
+ - `onFinish(snapshot)` runs when a live turn finishes.
271
+ - `onSessionChange(session)` runs when the session cursor changes. Save it here.
514
272
 
515
273
  ```tsx
516
274
  const agent = useEveAgent({
517
- initialSession: { sessionId, streamIndex: 0 },
518
- resume: true,
275
+ onEvent: (event) => console.debug(event.type),
276
+ onError: (error) => toast.error(error.message),
277
+ onFinish: (snapshot) => console.log(snapshot.status),
519
278
  });
520
279
  ```
521
280
 
522
- If the user can refresh or navigate immediately after pressing send, create your app-level chat row before calling `send()`, then persist the session ID from `onSessionChange`. This lets the reloaded UI mount with that ID and pass `resume: true` while the durable turn is still running.
281
+ See [Lifecycle callbacks](./use-eve-agent#lifecycle-callbacks) for exactly when each one fires.
282
+
283
+ ## Derive your own state
284
+
285
+ `view` already tracks turns, calls, and prompts. Query it with functions from `eve/events` instead of building your own state:
286
+
287
+ ```tsx
288
+ import { activeTurn, activity, waiting } from "eve/events";
289
+
290
+ const turn = activeTurn(agent.view);
291
+ const currentActivity = activity(agent.view);
292
+ const blocked = turn === undefined ? undefined : waiting(agent.view, turn.turnId);
293
+ ```
294
+
295
+ See [Use eve's answers](./use-eve-agent#use-eves-answers) for which query answers each common question, from a request's result to call timing and usage.
296
+
297
+ For something `view` doesn't cover, read the raw `events`:
298
+
299
+ ```tsx
300
+ import { useMemo } from "react";
301
+
302
+ const toolCalls = useMemo(
303
+ () => agent.events.filter((event) => event.type === "call.requested").length,
304
+ [agent.events],
305
+ );
306
+ ```
523
307
 
524
308
  ## Custom hosts and headers
525
309
 
526
- Pass `baseUrl` when the eve server isn't same-origin, and pass `auth` or `headers` when the channel needs credentials. Function values are re-resolved before every HTTP request, reconnects included:
310
+ Pass `baseUrl` when the agent is on another origin, and `auth` or `headers` for credentials. Functions run before every request, so tokens stay fresh:
527
311
 
528
312
  ```tsx
529
313
  const agent = useEveAgent({
@@ -534,11 +318,7 @@ const agent = useEveAgent({
534
318
  });
535
319
  ```
536
320
 
537
- Headers supplied to `send()` apply to that turn request and become the credentials used by the
538
- continuous session stream on its next reconnect. A later send replaces them with that turn's
539
- headers.
540
-
541
- When a framework integration mounts multiple named agents, pass `agent` instead of `baseUrl`:
321
+ When your app mounts several named agents, select one with `agent` instead:
542
322
 
543
323
  ```tsx
544
324
  const support = useEveAgent({ agent: "support" });
@@ -548,15 +328,15 @@ const support = useEveAgent({ agent: "support" });
548
328
 
549
329
  | Framework | Integration | Hook |
550
330
  | -------------- | ------------------------------------ | ------------------------------------------------ |
551
- | Next.js | [`withEve`](./nextjs) | [`useEveAgent` (React)](#basic-chat-react) |
331
+ | Next.js | [Next.js guide](./nextjs) | [`useEveAgent` (React)](#build-a-basic-chat) |
552
332
  | Nuxt | [`eve/nuxt` module](./nuxt) | [`useEveAgent` (Vue)](./use-eve-agent-vue) |
553
333
  | SvelteKit | [`eveSvelteKit` plugin](./sveltekit) | [`useEveAgent` (Svelte)](./use-eve-agent-svelte) |
554
- | TanStack Start | [`eveTanStack` plugin](./tanstack) | [`useEveAgent` (React)](#basic-chat-react) |
555
- | Any React | same-origin or `baseUrl` | [`useEveAgent` (React)](#basic-chat-react) |
334
+ | TanStack Start | [`eveTanStack` plugin](./tanstack) | [`useEveAgent` (React)](#build-a-basic-chat) |
335
+ | Any React | same-origin or `baseUrl` | [`useEveAgent` (React)](#build-a-basic-chat) |
556
336
 
557
337
  ## What to read next
558
338
 
559
- - [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): the event stream and session cursor
560
- - [Channels](../../channels/overview): the HTTP routes the hook talks to
561
- - [Client SDK](../client/overview): the lower-level client underneath the frontend hooks
562
- - [Next.js](./nextjs): step-by-step setup for wiring eve into a Next.js app
339
+ - [`useEveAgent` reference](./use-eve-agent): every value, option, and behavior
340
+ - [Next.js](./nextjs): set up a chat app end to end
341
+ - [Client SDK](../client/overview): call the agent from scripts and server code
342
+ - [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): how sessions and the event stream work
@@ -36,7 +36,7 @@ Rerun `eve add channel/web --skip-install` with the other choice to switch modes
36
36
 
37
37
  Sign in with Vercel setup is available only for the Next.js Web Chat app, so the TanStack Start installer doesn't ask about authentication.
38
38
 
39
- The chat has the same URL-addressed durable sessions as the [Next.js Web Chat](./nextjs#use-the-generated-web-chat-routes): `/`, `/s`, and `/s/$sessionId`. Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
39
+ The chat has the same URL-addressed durable sessions as the [Next.js Web Chat](./nextjs#give-each-conversation-a-url): `/`, `/s`, and `/s/$sessionId`. Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).
40
40
 
41
41
  The installer doesn't support selecting a workspace agent for single-app hosting: a workspace agent always deploys as a separate Vercel service. If you already have a TanStack Start app, skip the installer and follow the steps below.
42
42