Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 the
server'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 after
the reset, it prepares the next owned session; otherwise, the next send creates it. An explicitly
supplied `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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,