The Open Framework for Building Agents
feat(eve): close the useEveAgent session stream while idle with followIdle: false (#4758)
Matan Kushner624be476e38c
diff --git a/.changeset/follow-idle-session.md b/.changeset/follow-idle-session.mdnew file mode 100644index 000000000..4977270ab--- /dev/null+++ b/.changeset/follow-idle-session.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Pass `followIdle: false` to `useEveAgent()` (React, Vue, and Svelte) or `EveAgentStore` to close the session stream while the session is idle instead of reconnecting it indefinitely. The stream reopens from its cursor on the next send, answer, or resume, and a prewarmed session opens no stream until its first message.diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdxindex 79fa59102..a2a8993dc 100644--- a/docs/guides/frontend/overview.mdx+++ b/docs/guides/frontend/overview.mdx@@ -165,6 +165,15 @@ its cursor after a disconnect or theserver's renewable 60-second lease; lease renewal does not start a turn or clear UI state.Unmounting or resetting closes the local stream without cancelling the old durable session.+An open stream reconnects for as long as the chat stays mounted, even when nothing happens. If+your UI only shows replies to its own messages, such as a help sidebar that stays mounted across+pages, pass `followIdle: false`. The binding then closes the stream once the session is idle: no+turn is running or parked, no task is working, and no sign-in is pending. A prewarmed session+opens no stream until its first message. The next `send()`, `respond()`, or `resume()` reopens+the stream from the session cursor, so events that arrived in between are applied then. Leave+`followIdle` on when other sources, such as schedules, channels, or another tab, can start turns+in the session while your UI is idle.+`reset()` reuses the hook instance and clears the conversation. When `prewarm` is true afterthe reset, it prepares the next owned session; otherwise, the next send creates it. An explicitlysupplied `session` remains externally owned and is never replaced by prewarming or reset. Use@@ -399,7 +408,7 @@ then save a final snapshot in `onFinish`.`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. When the event count matches `initialSession.streamIndex`, catch-up continues from that cursor. A partial or overlapping saved log falls back to index `0`. Every event carries a stable [`meta.id`](/docs/concepts/sessions-runs-and-streaming#the-event-envelope), and the store drops any event whose id it has already applied, so an overlapping replay renders once and `onEvent` only fires for events your UI has not seen.-For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, 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` on every render.+For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, `optimistic`, `followIdle`, 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` on every render.Pass `resume: true` with `initialSession` to rebuild the projection from the durable stream after mount. While `status` is `"resuming"`, render hydrated `data` but disable message and HITL submission; do not present cancellation or active-turn progress controls. If catch-up finds an in-flight turn, `status` changes to `"streaming"` before the binding follows it to a boundary. 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 changes directly to `"ready"`; a newer turn or pending authorization remains `"streaming"`. The connection stays open to receive later events. A terminal session failure changes to `"error"`.diff --git a/packages/eve/src/client/conversation-client.ts b/packages/eve/src/client/conversation-client.tsindex 81c13d71a..43ef15eb2 100644--- a/packages/eve/src/client/conversation-client.ts+++ b/packages/eve/src/client/conversation-client.ts@@ -180,11 +180,16 @@ export class ConversationClient<TData = ConversationState> {return this.#stream;}+ /** Closes the root stream; the next `stream()` call reopens it from the session cursor. */+ closeStream(): void {+ this.#stream?.close();+ this.#stream = undefined;+ }+stop(): void {this.#follower?.abortAll();this.#follower = undefined;- this.#stream?.close();- this.#stream = undefined;+ this.closeStream();}reset(): void {diff --git a/packages/eve/src/client/eve-agent-store-state.ts b/packages/eve/src/client/eve-agent-store-state.tsindex e53cba301..ff3115729 100644--- a/packages/eve/src/client/eve-agent-store-state.ts+++ b/packages/eve/src/client/eve-agent-store-state.ts@@ -71,6 +71,15 @@ export interface EveAgentStoreInit<TData> {* while the store streams its session or a framework binding has it mounted.*/readonly followSubagents?: boolean;+ /**+ * Keep the session stream open while the session is idle, so the store sees events that arrive+ * between turns from schedules, channels, or other clients. When false, the store closes the+ * stream once no turn, task, or sign-in is pending, and reopens it from the session cursor on+ * the next send, answer, or resume.+ *+ * @default true+ */+ readonly followIdle?: boolean;readonly reducer: EveAgentReducer<TData>;readonly session?: ClientSession;}diff --git a/packages/eve/src/client/eve-agent-store.test.ts b/packages/eve/src/client/eve-agent-store.test.tsindex d62ec6fed..728f9afca 100644--- a/packages/eve/src/client/eve-agent-store.test.ts+++ b/packages/eve/src/client/eve-agent-store.test.ts@@ -1037,6 +1037,139 @@ describe("EveAgentStore prewarming", () => {});});+describe("EveAgentStore with followIdle disabled", () => {+ function streamRequests(fetchMock: { mock: { calls: unknown[][] } }) {+ return fetchMock.mock.calls+ .map(([request, init]) => ({ url: String(request), init: init as RequestInit | undefined }))+ .filter(({ init }) => init?.method !== "POST");+ }++ it("opens the stream for each turn and reopens it from the session cursor", async () => {+ const first = controlledStreamResponse();+ const second = controlledStreamResponse();+ let delivery = 0;+ let streams = 0;+ const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (_request, init) => {+ if (init?.method === "POST") return startedResponse(`delivery_${(delivery += 1)}`);+ streams += 1;+ return streams === 1 ? first.response : second.response;+ });+ const store = createStore({ followIdle: false, reducer: defaultMessageReducer() });+ const emitTurn = (live: typeof first, deliveryId: string, idPrefix: string) => {+ for (const event of turnEvents()) {+ live.emit({+ ...event,+ meta: { ...event.meta, deliveryIds: [deliveryId], id: `${idPrefix}-${event.meta.id}` },+ });+ }+ };++ await store.prewarm();+ expect(streamRequests(fetchMock)).toHaveLength(0);++ const firstSend = store.send({ message: "Hello" });+ await vi.waitFor(() => expect(streamRequests(fetchMock)).toHaveLength(1));+ emitTurn(first, "delivery_2", "first");+ await firstSend;+ expect(store.snapshot.status).toBe("ready");+ expect(streamRequests(fetchMock)[0]!.init?.signal?.aborted).toBe(true);++ const secondSend = store.send({ message: "Hello again" });+ await vi.waitFor(() => expect(streamRequests(fetchMock)).toHaveLength(2));+ expect(streamRequests(fetchMock)[1]!.url).toContain("startIndex=3");+ emitTurn(second, "delivery_3", "second");+ await secondSend;++ expect(store.snapshot.events).toHaveLength(6);+ expect(store.snapshot.session?.streamIndex).toBe(6);+ expect(streamRequests(fetchMock)[1]!.init?.signal?.aborted).toBe(true);+ });++ it("keeps the stream open until a task that outlives its turn settles", async () => {+ const live = controlledStreamResponse();+ const fetchMock = vi+ .spyOn(globalThis, "fetch")+ .mockImplementation(async (_request, init) =>+ init?.method === "POST" ? startedResponse() : live.response,+ );+ const store = createStore({+ followIdle: false,+ initialSession: { sessionId: "session_1", streamIndex: 0 },+ reducer: defaultMessageReducer(),+ });+ const withDelivery = (events: MessageStreamEvent[]) =>+ events.map((event) => ({ ...event, meta: { ...event.meta, deliveryIds: ["delivery_1"] } }));++ const send = store.send({ message: "Research Alice's region" });+ await vi.waitFor(() => expect(streamRequests(fetchMock)).toHaveLength(1));+ for (const event of withDelivery(+ stampTestEvents([+ createMessageReceivedEvent({+ message: "Research Alice's region",+ sequence: 0,+ turnId: "turn_1",+ }),+ createTaskStartedEvent({+ callId: "call_1",+ kind: "agent",+ name: "researcher",+ taskId: "task_1",+ turnId: "turn_1",+ }),+ createTurnCompletedEvent({ sequence: 1, turnId: "turn_1" }),+ createSessionWaitingEvent(TEST_USAGE),+ ]),+ ))+ live.emit(event);+ await send;+ const stream = streamRequests(fetchMock)[0]!;+ expect(stream.init?.signal?.aborted).toBe(false);++ for (const event of stampTestEvents([+ createTaskSettledEvent({+ callId: "call_1",+ output: "Alice works in the west region.",+ status: "completed",+ taskId: "task_1",+ turnId: "turn_1",+ }),+ createTurnStartedEvent({ sequence: 0, turnId: "turn_2" }),+ createMessageCompletedEvent({+ finishReason: "stop",+ message: "Alice works in the west region.",+ sequence: 1,+ stepIndex: 0,+ turnId: "turn_2",+ }),+ createTurnCompletedEvent({ sequence: 2, turnId: "turn_2" }),+ createSessionWaitingEvent(TEST_USAGE),+ ]).map((event) => ({ ...event, meta: { ...event.meta, id: `task-${event.meta.id}` } })))+ live.emit(event);++ await vi.waitFor(() => expect(stream.init?.signal?.aborted).toBe(true));+ expect(store.snapshot.status).toBe("ready");+ expect(store.snapshot.events).toHaveLength(9);+ });++ it("closes the stream after resuming a settled session", async () => {+ const fetchMock = vi+ .spyOn(globalThis, "fetch")+ .mockImplementation(async () => boundedStreamResponse(turnEvents()));+ const store = createStore({+ followIdle: false,+ initialSession: { sessionId: "session_1", streamIndex: 0 },+ reducer: defaultMessageReducer(),+ });++ await store.resume();++ expect(store.snapshot.status).toBe("ready");+ expect(store.snapshot.events).toHaveLength(3);+ expect(fetchMock).toHaveBeenCalledOnce();+ expect(streamRequests(fetchMock)[0]!.init?.signal?.aborted).toBe(true);+ });+});+describe("EveAgentStore stream overlap", () => {it("reconstructs a split message across an in-memory stream reconnect", async () => {const events = streamingTurnEvents();diff --git a/packages/eve/src/client/eve-agent-store.ts b/packages/eve/src/client/eve-agent-store.tsindex bf99a90cd..6823a1f48 100644--- a/packages/eve/src/client/eve-agent-store.ts+++ b/packages/eve/src/client/eve-agent-store.ts@@ -71,6 +71,7 @@ export class EveAgentStore<TData> {#attached = false;readonly #conversationClient: ConversationClient<TData>;readonly #followChildStreams: boolean;+ readonly #followIdle: boolean;readonly #externalSession: boolean;readonly #subscribers = new Set<() => void>();#activeTurn: ActiveTurn | undefined;@@ -89,6 +90,7 @@ export class EveAgentStore<TData> {constructor(init: EveAgentStoreInit<TData>) {this.#autoPrewarm = init.prewarm ?? false;this.#followChildStreams = init.followSubagents ?? false;+ this.#followIdle = init.followIdle ?? true;this.#externalSession = init.session !== undefined;this.#client = this.#externalSession? undefined@@ -160,7 +162,8 @@ export class EveAgentStore<TData> {this.#error = undefined;if (this.#status === "error") this.#status = "ready";this.#adoptSession(created.session);- this.#ensureStream();+ // A prewarmed session emits nothing until its first message.+ if (this.#followIdle) this.#ensureStream();} catch (error) {if (generation === this.#prewarmGeneration &&@@ -594,6 +597,7 @@ export class EveAgentStore<TData> {if (!this.#isActiveTurn(turn)) return;turn.resolveResponse(undefined);this.#activeTurn = undefined;+ this.#closeStreamWhenIdle();try {this.#callbacks.onSessionChange?.(this.#session?.state);this.#publish();@@ -639,9 +643,22 @@ export class EveAgentStore<TData> {if (this.#activeTurn === undefined && wasStreaming && settled) {this.#callbacks.onFinish?.(this.#snapshot);}+ if (this.#activeTurn === undefined) this.#closeStreamWhenIdle();return true;}+ #closeStreamWhenIdle(): void {+ if (this.#followIdle) return;+ const { conversation } = this.#conversationClient;+ if (conversation.activeTurnId !== undefined) return;+ // Unsettled tails include sign-ins whose callbacks resume the session from elsewhere.+ if (this.#events.length > 0 && !isSettledSessionTail(this.#events, conversation)) return;+ const working = Object.values(conversation.tasks).some((task) =>+ Object.values(task.calls).some((call) => call.status === "working"),+ );+ if (!working) this.#conversationClient.closeStream();+ }+/** Pairs a submission's echo with the server's copy once its delivery ID is known. */#correlate(submissionId: string | undefined, response: MessageResponse<unknown>): void {const deliveryId = getMessageResponseDeliveryId(response);diff --git a/packages/eve/src/react/use-eve-agent.ts b/packages/eve/src/react/use-eve-agent.tsindex 26f7f6edb..60a770b6f 100644--- a/packages/eve/src/react/use-eve-agent.ts+++ b/packages/eve/src/react/use-eve-agent.ts@@ -114,6 +114,12 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>readonly optimistic?: boolean;/** Follow each subagent call's session into `conversation.agents` while mounted. @default false */readonly followSubagents?: boolean;+ /**+ * Keep the session stream open between turns to show events that arrive from schedules,+ * channels, or other clients. Set to false to close it once the session is idle and reopen it+ * on the next send, answer, or resume. @default true+ */+ readonly followIdle?: boolean;/*** Prewarm an owned session when true. React observes this value across renders;* changing it from false to true prepares the current session, and reset checks@@ -186,6 +192,7 @@ export function useEveAgent<TData>(initialSession: options.initialSession,optimistic: options.optimistic,followSubagents: options.followSubagents,+ followIdle: options.followIdle,reducer,session: options.session,});diff --git a/packages/eve/src/svelte/use-eve-agent.ts b/packages/eve/src/svelte/use-eve-agent.tsindex afdcec020..a478b31bc 100644--- a/packages/eve/src/svelte/use-eve-agent.ts+++ b/packages/eve/src/svelte/use-eve-agent.ts@@ -135,6 +135,12 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>readonly optimistic?: boolean;/** Follow each subagent call's session into `conversation.agents` while mounted. @default false */readonly followSubagents?: boolean;+ /**+ * Keep the session stream open between turns to show events that arrive from schedules,+ * channels, or other clients. Set to false to close it once the session is idle and reopen it+ * on the next send, answer, or resume. @default true+ */+ readonly followIdle?: boolean;/** Prewarm an owned session on mount and after reset. @default false */readonly prewarm?: boolean;/**@@ -265,6 +271,7 @@ export function useEveAgent<TData>(initialSession: options.initialSession,optimistic: options.optimistic,followSubagents: options.followSubagents,+ followIdle: options.followIdle,prewarm: options.prewarm,reducer,session: options.session,diff --git a/packages/eve/src/vue/use-eve-agent.ts b/packages/eve/src/vue/use-eve-agent.tsindex 997001a76..75f2ff286 100644--- a/packages/eve/src/vue/use-eve-agent.ts+++ b/packages/eve/src/vue/use-eve-agent.ts@@ -133,6 +133,12 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>readonly optimistic?: boolean;/** Follow each subagent call's session into `conversation.agents` while mounted. @default false */readonly followSubagents?: boolean;+ /**+ * Keep the session stream open between turns to show events that arrive from schedules,+ * channels, or other clients. Set to false to close it once the session is idle and reopen it+ * on the next send, answer, or resume. @default true+ */+ readonly followIdle?: boolean;/** Prewarm an owned session on mount and after reset. @default false */readonly prewarm?: boolean;/**@@ -186,6 +192,7 @@ export function useEveAgent<TData>(initialSession: options.initialSession,optimistic: options.optimistic,followSubagents: options.followSubagents,+ followIdle: options.followIdle,prewarm: options.prewarm,reducer,session: options.session,