The Open Framework for Building Agents
docs: clarify persisted chat sessions (#247)
Allen Zhou6f55819cce3f
diff --git a/docs/channels/eve.mdx b/docs/channels/eve.mdxindex f924c9353..dda6631aa 100644--- a/docs/channels/eve.mdx+++ b/docs/channels/eve.mdx@@ -39,7 +39,7 @@ Stream that session's events as newline-delimited JSON (`application/x-ndjson; c```bashcurl -N https://<deployment>/eve/v1/session/ses_01h.../stream# {"type":"turn.started",...}-# {"type":"text.delta","delta":"It is "}+# {"type":"message.appended","data":{"messageDelta":"It is ",...}}# {"type":"message.completed",...}```diff --git a/docs/guides/client/continuations.mdx b/docs/guides/client/continuations.mdxindex 070e01c59..8dff70716 100644--- a/docs/guides/client/continuations.mdx+++ b/docs/guides/client/continuations.mdx@@ -35,6 +35,8 @@ interface SessionState {The continuation token resumes the conversation. The session ID and stream index let the client reconnect to the right stream position without replaying events it already consumed.+`SessionState` is a cursor, not a chat transcript. If your app shows historical messages, persist the stream events separately and store them under your own chat or thread ID. On reload, pass the saved `SessionState` back to `client.session(savedState)` or `useEveAgent({ initialSession })`, and pass the saved events to your renderer or `useEveAgent({ initialEvents })`.+## Resume a saved sessionPass the saved state back into `client.session()`:@@ -97,6 +99,8 @@ await save("support", support.state);The shared `Client` only owns host, auth, headers, and reconnect settings. Conversation state lives on each `ClientSession`.+For a multi-chat UI, this usually means one application row per chat with two eve fields: the latest `SessionState` and the ordered event log for rendering. Do not reuse one `ClientSession` across sidebar conversations, and do not treat `streamIndex` as your database row index; it is only the remote stream cursor for that eve session.+## Reconnect an existing streamWhen a session already has a `sessionId`, `session.stream()` reattaches to its stream from the saved cursor. Resuming a saved `SessionState` after a restart is the common reason to do this:diff --git a/docs/guides/client/streaming.mdx b/docs/guides/client/streaming.mdxindex 054e27d4f..b85dc0f21 100644--- a/docs/guides/client/streaming.mdx+++ b/docs/guides/client/streaming.mdx@@ -76,6 +76,12 @@ The most common UI events are:For the complete event table, see [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).+## Authorization pauses++`authorization.required` is different from the normal `session.waiting` boundary. It means a connection needs OAuth or another authorization challenge before the parked turn can continue. Chat UIs should render the authorization prompt, disable ordinary text input for that session, and persist the event with the rest of the chat history.++If you support refresh while an authorization prompt is pending, keep the session cursor from the started session and rehydrate the saved events on load. Do not treat a missing `session.waiting` after `authorization.required` as a finished conversation; the callback or a structured decline should resume the same eve session.+## ReconnectionThe client reconnects after transient stream disconnects. It resumes from the number of events already consumed in the current session:diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdxindex 63dc4c589..4766b8676 100644--- a/docs/guides/frontend/overview.mdx+++ b/docs/guides/frontend/overview.mdx@@ -186,23 +186,43 @@ const agent = useEveAgent({ reducer: toolCounter });## Resumable sessions-The browser conversation lives durably on the server. Persist the `session` cursor to pick it back up after a reload:+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:```tsx-const [initialSession] = useState(() => {- const raw = localStorage.getItem("eve-session");- return raw ? JSON.parse(raw) : undefined;+import type { HandleMessageStreamEvent, SessionState } from "eve/client";++type SavedEveChat = {+ events?: readonly HandleMessageStreamEvent[];+ session?: SessionState;+};++const [saved] = useState<SavedEveChat>(() => {+ const raw = localStorage.getItem("eve-chat");+ return raw ? JSON.parse(raw) : {};});const agent = useEveAgent({- initialSession,- onSessionChange(session) {- localStorage.setItem("eve-session", JSON.stringify(session));+ initialEvents: saved.events ?? [],+ initialSession: saved.session,+ onFinish(snapshot) {+ localStorage.setItem(+ "eve-chat",+ JSON.stringify({+ events: snapshot.events,+ session: snapshot.session,+ }),+ );},});```-Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field.+Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field. The session cursor lets eve continue the durable conversation; the event log lets your UI render historical messages without replaying the whole stream. A database-backed chat app should usually persist stream events as they arrive with `onEvent` and then save a final snapshot in `onFinish`.++For multiple chat threads, keep one saved event log and session cursor per thread. `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `maxReconnectAttempts`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.++If the user can refresh or navigate immediately after pressing send, create your app-level chat row and store the pending user message before calling `send()`. After the request starts, persist the session state as soon as it contains a `sessionId`, then reconnect an interrupted in-flight turn with `session.stream({ startIndex: savedEvents.length })` from the lower-level client.++Connection authorization prompts need one extra bit of UI state. eve emits `authorization.required` when a tool needs OAuth or another connection grant. Treat that as a parked chat turn for rendering and persistence: show the authorization prompt, disable ordinary text input for that thread, and keep the session cursor so the callback or a structured decline can continue the same session.## Custom hosts and headers