Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): bounded catch-up reads at the durable stream tail (#1219)

Matan Kushnere368fcd768e1
diff --git a/.changeset/stream-tail-index.md b/.changeset/stream-tail-index.md
new file mode 100644
index 000000000..13f0eba5f
--- /dev/null
+++ b/.changeset/stream-tail-index.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+The client's `session.stream()` accepts `follow: false` for bounded catch-up reads (`follow` defaults to `true`, following the live stream): it consumes events from the cursor to the durable tail observed when the stream opens — surviving reconnects and still advancing the stored `streamIndex` — then returns instead of following the live stream. The HTTP stream route reports the durable tail as the `x-eve-stream-tail-index` response header when a request opts in with `includeTailIndex=1`, and channel-authoring `Session` objects gain `getStreamTailIndex()` for serving bounded reads from custom routes.
diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdx
index f41776ebb..ecce8e1d7 100644
--- a/docs/channels/custom.mdx
+++ b/docs/channels/custom.mdx
@@ -49,7 +49,7 @@ Declare routes with the `POST()` and `GET()` helpers. Each route handler receive
- `send(message, { auth, continuationToken, state?, title? })` starts or resumes a session. `title` overrides the new workflow session's display title without changing the model message. Returns a `Session`.
- `cancel({ continuationToken, turnId? })` requests cancellation of the active turn on the session that owns the token. See [Cancel a turn](#cancel-a-turn).
- `reset({ continuationToken, reason? })` retires the session that owns the token so the next `send()` starts a fresh session. See [Reset a session](#reset-a-session).
-- `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming and `cancel({ turnId? })` for session-id-addressed cancellation.
+- `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming, `getStreamTailIndex()` for resolving the durable tail when a route wants to serve bounded reads, and `cancel({ turnId? })` for session-id-addressed cancellation.
- `receive(channel, ...)` hands inbound work to a different channel for cross-channel hand-off.
- `params` holds route parameters extracted from the path pattern.
- `waitUntil(promise)` extends the request lifetime for background work.
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index fef752a2d..6e2a9fbb7 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -124,6 +124,15 @@ curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=-1"
This gives a consumer that only persisted `sessionId` a lightweight way to recover the current `continuationToken`. Because a tail-relative position does not resolve to an absolute consumed-event count, client tail reads do not automatically reconnect or advance the stored cursor.
+For a catch-up read that stops instead of following the live stream, pass `includeTailIndex=1`. The response then carries the `x-eve-stream-tail-index` header: the zero-based index of the last durably recorded event, or `-1` before the first. Read from your cursor until it passes that tail, then disconnect — reconnecting from the updated cursor if the connection drops first:
+
+```bash
+curl -i "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<count>&includeTailIndex=1"
+# x-eve-stream-tail-index: <tail>
+```
+
+The lookup is opt-in; requests without the parameter get no header. The TypeScript client wraps this into `stream({ follow: false })`.
+
## Use the client from TypeScript
For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
diff --git a/docs/guides/client/streaming.mdx b/docs/guides/client/streaming.mdx
index 8ba6fb3fd..0fdc6625d 100644
--- a/docs/guides/client/streaming.mdx
+++ b/docs/guides/client/streaming.mdx
@@ -157,6 +157,21 @@ for await (const event of session.stream({ startIndex: -1 })) {
Tail-relative attachments do not automatically reconnect or advance the session's stored absolute `streamIndex`. Break after the event you need when using one as a tail lookup.
+## Bounded catch-up reads
+
+Pass `follow: false` to read from the cursor to the durable tail and then stop, instead of following the live stream (the default):
+
+```ts
+for await (const event of session.stream({ follow: false })) {
+ console.log(event.type);
+}
+// Returns once every event recorded before the stream opened is consumed.
+```
+
+The first connection pins the bound to the tail the server reports at open time; events recorded afterward are not part of the read. Reconnects during the read keep that original bound, and the session's stored `streamIndex` still advances past the consumed events, so a follow-up `stream()` or `send()` picks up exactly where the bounded read ended. When the cursor is already at or past the tail, the iterator returns immediately without yielding.
+
+Because a tail-relative cursor cannot be bounded, `follow: false` throws when combined with a negative `startIndex`. It also fails if the server does not report the durable tail (an agent running an older eve version).
+
`stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
## Abort a request
diff --git a/packages/eve/src/channel/cancel.test.ts b/packages/eve/src/channel/cancel.test.ts
index 7537af253..fae22203f 100644
--- a/packages/eve/src/channel/cancel.test.ts
+++ b/packages/eve/src/channel/cancel.test.ts
@@ -8,6 +8,7 @@ function createRuntime(overrides?: Partial<Runtime>): Runtime {
cancelTurn: vi.fn().mockResolvedValue({ status: "accepted" }),
deliver: vi.fn(),
getEventStream: vi.fn(),
+ getStreamTailIndex: vi.fn(),
resolveSession: vi.fn().mockResolvedValue({ sessionId: "sess_1" }),
run: vi.fn(),
terminateSession: vi.fn(),
diff --git a/packages/eve/src/channel/cross-channel-receive.test.ts b/packages/eve/src/channel/cross-channel-receive.test.ts
index 514b63c10..4edea0e26 100644
--- a/packages/eve/src/channel/cross-channel-receive.test.ts
+++ b/packages/eve/src/channel/cross-channel-receive.test.ts
@@ -13,6 +13,7 @@ function makeRuntime(): Runtime {
cancelTurn: vi.fn(),
deliver: vi.fn(),
getEventStream: vi.fn(),
+ getStreamTailIndex: vi.fn(),
resolveSession: vi.fn(),
run: vi.fn(),
terminateSession: vi.fn(),
@@ -29,6 +30,9 @@ function makeSession(): Session {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
};
}
diff --git a/packages/eve/src/channel/reset-session.test.ts b/packages/eve/src/channel/reset-session.test.ts
index d42024637..62bb07a03 100644
--- a/packages/eve/src/channel/reset-session.test.ts
+++ b/packages/eve/src/channel/reset-session.test.ts
@@ -8,6 +8,7 @@ function createRuntime(overrides?: Partial<Runtime>): Runtime {
cancelTurn: vi.fn(),
deliver: vi.fn(),
getEventStream: vi.fn(),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
resolveSession: vi.fn().mockResolvedValue({ sessionId: "sess_1" }),
run: vi.fn(),
terminateSession: vi.fn().mockResolvedValue({ status: "terminated" }),
diff --git a/packages/eve/src/channel/resolve-active-session.test.ts b/packages/eve/src/channel/resolve-active-session.test.ts
index 0c0f8711d..53ca66773 100644
--- a/packages/eve/src/channel/resolve-active-session.test.ts
+++ b/packages/eve/src/channel/resolve-active-session.test.ts
@@ -8,6 +8,7 @@ function runtime(): Runtime {
cancelTurn: vi.fn(),
deliver: vi.fn(),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
resolveSession: vi.fn(),
run: vi.fn(),
terminateSession: vi.fn(),
diff --git a/packages/eve/src/channel/schedule.test.ts b/packages/eve/src/channel/schedule.test.ts
index 3cb6e58b5..f27bf0e2b 100644
--- a/packages/eve/src/channel/schedule.test.ts
+++ b/packages/eve/src/channel/schedule.test.ts
@@ -29,6 +29,7 @@ function createMockRuntime(): Runtime {
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
}
diff --git a/packages/eve/src/channel/send.test.ts b/packages/eve/src/channel/send.test.ts
index adf07c8fb..3ddc8194e 100644
--- a/packages/eve/src/channel/send.test.ts
+++ b/packages/eve/src/channel/send.test.ts
@@ -21,6 +21,7 @@ function createRuntime(deliverError: unknown): Runtime {
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
}
@@ -84,6 +85,7 @@ describe("createSendFn", () => {
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
@@ -118,6 +120,7 @@ describe("createSendFn", () => {
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
@@ -147,6 +150,7 @@ describe("createSendFn", () => {
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
diff --git a/packages/eve/src/channel/session.test.ts b/packages/eve/src/channel/session.test.ts
index f15a5ceed..16f3612e8 100644
--- a/packages/eve/src/channel/session.test.ts
+++ b/packages/eve/src/channel/session.test.ts
@@ -10,6 +10,7 @@ function createRuntime(): Runtime {
cancelTurn: vi.fn().mockResolvedValue({ status: "accepted" }),
deliver: vi.fn(),
getEventStream: vi.fn(),
+ getStreamTailIndex: vi.fn(),
resolveSession: vi.fn(),
run: vi.fn(),
terminateSession: vi.fn(),
diff --git a/packages/eve/src/channel/session.ts b/packages/eve/src/channel/session.ts
index 89f946e6f..b95383de3 100644
--- a/packages/eve/src/channel/session.ts
+++ b/packages/eve/src/channel/session.ts
@@ -30,6 +30,11 @@ export interface Session {
getEventStream(options?: {
startIndex?: number;
}): Promise<ReadableStream<HandleMessageStreamEvent>>;
+ /**
+ * Resolves the durable tail of the event stream: the zero-based index of
+ * the last recorded event, or `-1` before the first.
+ */
+ getStreamTailIndex(): Promise<number>;
}
/**
@@ -56,6 +61,9 @@ export function createSession(id: string, continuationToken: string, runtime: Ru
async getEventStream(options?: { startIndex?: number }) {
return runtime.getEventStream(id, options);
},
+ async getStreamTailIndex() {
+ return runtime.getStreamTailIndex(id);
+ },
};
}
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index d57472b7c..f8c3e89e6 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -426,6 +426,14 @@ export interface Runtime {
sessionId: string,
options?: GetEventStreamOptions,
): Promise<ReadableStream<HandleMessageStreamEvent>>;
+
+ /**
+ * Resolves the durable tail of a session's event stream: the zero-based
+ * index of the last recorded event, or `-1` before the first. Callers use
+ * it to bound a read at the tail they observed instead of following the
+ * live stream.
+ */
+ getStreamTailIndex(sessionId: string): Promise<number>;
}
/**
diff --git a/packages/eve/src/client/open-stream.ts b/packages/eve/src/client/open-stream.ts
index e5d01265c..c3039b443 100644
--- a/packages/eve/src/client/open-stream.ts
+++ b/packages/eve/src/client/open-stream.ts
@@ -1,4 +1,5 @@
import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { EVE_STREAM_TAIL_INDEX_HEADER } from "#protocol/message.js";
import { createEveMessageStreamRoutePath } from "#protocol/routes.js";
import { ClientError } from "#client/client-error.js";
import { isStreamDisconnectError, readNdjsonStream } from "#client/ndjson.js";
@@ -81,6 +82,13 @@ interface FollowStreamInput {
readonly sessionId: string;
readonly signal?: AbortSignal;
readonly startIndex: number;
+ /** Follow the live stream after the durable tail (default). `false` bounds the read at the tail. */
+ readonly follow?: boolean;
+}
+
+/** One connection open; `requestTailIndex` asks the server to report the durable tail index. */
+interface OpenStreamInput extends FollowStreamInput {
+ readonly requestTailIndex?: boolean;
}
/**
@@ -91,21 +99,37 @@ interface FollowStreamInput {
* idle budget; repeated empty streams eventually stop the follow. Callers own
* boundary handling. Negative tail-relative cursors use one connection because
* they cannot be advanced safely.
+ *
+ * With `follow: false`, the first connection fixes the bound: the iterator
+ * yields events until the cursor passes that tail, reconnecting as needed,
+ * then returns instead of following.
*/
export async function* followStreamIterable(
input: FollowStreamInput,
): AsyncGenerator<HandleMessageStreamEvent> {
+ if (input.follow === false && input.startIndex < 0) {
+ throw new Error(
+ "stream({ follow: false }) requires a nonnegative startIndex; a tail-relative cursor cannot be bounded.",
+ );
+ }
+
const retryPolicy = resolveStreamReconnectPolicy(input.streamReconnectPolicy);
const idleRetryPolicy = retryPolicy.streamIdleReconnectPolicy;
let startIndex = input.startIndex;
let reconnectDelayMs = idleRetryPolicy.baseDelayMs;
let idleReconnects = 0;
let initialConnection = true;
+ let tailIndex: number | undefined;
while (true) {
- let body: ReadableStream<Uint8Array>;
+ let connection: OpenedStream;
try {
- body = await openStreamBody({ ...input, retryPolicy, startIndex });
+ connection = await openStreamBody({
+ ...input,
+ retryPolicy,
+ startIndex,
+ requestTailIndex: input.follow === false && tailIndex === undefined,
+ });
} catch (error) {
if (input.signal?.aborted) {
return;
@@ -113,14 +137,34 @@ export async function* followStreamIterable(
throw error;
}
+ if (input.follow === false && tailIndex === undefined) {
+ tailIndex = connection.tailIndex;
+ if (tailIndex === undefined) {
+ await connection.body.cancel().catch(() => {});
+ throw new Error(
+ `stream({ follow: false }) requires the server to report the ${EVE_STREAM_TAIL_INDEX_HEADER} header. ` +
+ "The agent may be running an older eve version.",
+ );
+ }
+ }
+
+ if (tailIndex !== undefined && startIndex > tailIndex) {
+ await connection.body.cancel().catch(() => {});
+ return;
+ }
+
let deliveredEvent = false;
try {
- for await (const event of readNdjsonStream(body)) {
+ for await (const event of readNdjsonStream(connection.body)) {
startIndex += 1;
deliveredEvent = true;
reconnectDelayMs = idleRetryPolicy.baseDelayMs;
idleReconnects = 0;
yield event;
+
+ if (tailIndex !== undefined && startIndex > tailIndex) {
+ return;
+ }
}
} catch (error) {
if (!isStreamDisconnectError(error)) {
@@ -149,6 +193,12 @@ export async function* followStreamIterable(
}
}
+/** An opened connection: the response body plus the tail index from the response header, if any. */
+interface OpenedStream {
+ readonly body: ReadableStream<Uint8Array>;
+ readonly tailIndex: number | undefined;
+}
+
/**
* Opens one stream response body, retrying transient failures with capped
* exponential backoff (~35s total): brief network outages and the short
@@ -156,8 +206,8 @@ export async function* followStreamIterable(
* readable from the stream route.
*/
export async function openStreamBody(
- input: FollowStreamInput & { readonly retryPolicy?: ResolvedStreamReconnectPolicy },
-): Promise<ReadableStream<Uint8Array>> {
+ input: OpenStreamInput & { readonly retryPolicy?: ResolvedStreamReconnectPolicy },
+): Promise<OpenedStream> {
const retryPolicy = input.retryPolicy ?? DEFAULT_STREAM_RECONNECT_POLICY;
const openRetryPolicy = retryPolicy.streamOpenReconnectPolicy;
let lastStatus: number | undefined;
@@ -165,11 +215,19 @@ export async function openStreamBody(
let lastHeaders: Headers | undefined;
let retryDelayMs = openRetryPolicy.baseDelayMs;
+ const searchParams: Record<string, string> = {};
+ if (input.startIndex !== 0) {
+ searchParams.startIndex = String(input.startIndex);
+ }
+ if (input.requestTailIndex === true) {
+ searchParams.includeTailIndex = "1";
+ }
+
for (let attempt = 0; attempt < openRetryPolicy.maxAttempts; attempt += 1) {
const url = createClientUrl(
input.host,
createEveMessageStreamRoutePath(input.sessionId),
- input.startIndex !== 0 ? { startIndex: String(input.startIndex) } : undefined,
+ Object.keys(searchParams).length > 0 ? searchParams : undefined,
);
const headers = await input.resolveHeaders();
@@ -197,7 +255,7 @@ export async function openStreamBody(
if (!response.body) {
throw new ClientError(response.status, "Response body is null.", response.headers);
}
- return response.body;
+ return { body: response.body, tailIndex: parseTailIndexHeader(response.headers) };
}
lastStatus = response.status;
@@ -217,6 +275,15 @@ export async function openStreamBody(
throw new ClientError(lastStatus ?? 0, lastBody ?? "Failed to open message stream.", lastHeaders);
}
+function parseTailIndexHeader(headers: Headers): number | undefined {
+ const raw = headers.get(EVE_STREAM_TAIL_INDEX_HEADER);
+ if (raw === null || !/^-?\d+$/.test(raw)) {
+ return undefined;
+ }
+ const parsed = Number(raw);
+ return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
if (signal?.aborted) {
return;
diff --git a/packages/eve/src/client/session.test.ts b/packages/eve/src/client/session.test.ts
index c9f184d56..58e47565c 100644
--- a/packages/eve/src/client/session.test.ts
+++ b/packages/eve/src/client/session.test.ts
@@ -459,6 +459,14 @@ describe("ClientSession", () => {
expect(session.state).toEqual(initialState);
});
+ it("rejects a bounded stream from a tail-relative cursor", () => {
+ const session = createSession({ sessionId: "session_1", streamIndex: 0 });
+
+ expect(() => session.stream({ follow: false, startIndex: -1 })).toThrow(
+ /nonnegative startIndex/,
+ );
+ });
+
it("does not reconnect a tail-relative stream after a disconnect", async () => {
const encoder = new TextEncoder();
const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async () => {
diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.ts
index e07096433..0880cdd58 100644
--- a/packages/eve/src/client/session.ts
+++ b/packages/eve/src/client/session.ts
@@ -229,8 +229,12 @@ export class ClientSession {
* one connection. Negative indices read relative to the current tail on one connection
* and do not advance the stored absolute cursor.
*
+ * Pass `follow: false` for a bounded read: yields events up to the durable
+ * tail observed when the stream opens, then returns instead of following.
+ * The stored cursor still advances past the consumed events.
+ *
* @throws {Error} If the session has no session ID (no message has been sent
- * yet).
+ * yet), or if `follow: false` is combined with a negative `startIndex`.
*/
stream(options?: StreamOptions): AsyncIterable<HandleMessageStreamEvent> {
const sessionId = this.#state.sessionId;
@@ -239,6 +243,12 @@ export class ClientSession {
throw new Error("Session has no session ID. Send a message first.");
}
+ if (options?.follow === false && (options.startIndex ?? this.#state.streamIndex) < 0) {
+ throw new Error(
+ "stream({ follow: false }) requires a nonnegative startIndex; a tail-relative cursor cannot be bounded.",
+ );
+ }
+
return this.#streamAndAdvance(sessionId, options);
}
@@ -343,6 +353,7 @@ export class ClientSession {
try {
for await (const event of followStreamIterable({
+ follow: options?.follow,
host: this.#context.host,
resolveHeaders: () => this.#context.resolveHeaders(),
redirect: this.#context.redirect,
diff --git a/packages/eve/src/client/stream-follow.integration.test.ts b/packages/eve/src/client/stream-follow.integration.test.ts
index a50fe39e4..e7aeb9b8b 100644
--- a/packages/eve/src/client/stream-follow.integration.test.ts
+++ b/packages/eve/src/client/stream-follow.integration.test.ts
@@ -27,8 +27,9 @@ function startIndexOf(url: string | undefined): number {
return Number(new URL(url ?? "", "http://127.0.0.1").searchParams.get("startIndex") ?? "0");
}
-function follow(host: string) {
+function follow(host: string, options?: { follow?: boolean }) {
return followStreamIterable({
+ follow: options?.follow,
host,
resolveHeaders: () => Promise.resolve(new Headers()),
sessionId: "s",
@@ -104,6 +105,91 @@ describe("stream following over real sockets", () => {
expect(connections).toBe(6);
}, 20_000);
+ it("bounds a follow: false read at the first connection's tail across reconnects", async () => {
+ const log = [
+ { type: "step.started", data: {} },
+ { type: "step.completed", data: {} },
+ { type: "step.started", data: {} },
+ { type: "step.completed", data: {} },
+ { type: "step.started", data: {} },
+ { type: "step.completed", data: {} },
+ ];
+ const tailRequests: Array<string | null> = [];
+ let connections = 0;
+ const host = await listen(
+ createServer((req, res) => {
+ connections += 1;
+ const index = startIndexOf(req.url);
+ const tailRequested = new URL(req.url ?? "", "http://127.0.0.1").searchParams.get(
+ "includeTailIndex",
+ );
+ tailRequests.push(tailRequested);
+ res.writeHead(200, {
+ "content-type": "application/x-ndjson",
+ ...(tailRequested === "1" ? { "x-eve-stream-tail-index": String(log.length - 1) } : {}),
+ });
+
+ // The first two connections drop after one event; the third serves the
+ // rest and holds the connection open — a live follow would keep waiting.
+ const events = index < 2 ? [log[index]] : log.slice(index);
+ for (const event of events) {
+ res.write(`${JSON.stringify(event)}\n`);
+ }
+ if (index < 2) {
+ setTimeout(() => req.socket.destroy(), 40);
+ }
+ }),
+ );
+
+ const client = new Client({ host });
+ const session = client.session({ sessionId: "s1", streamIndex: 0 });
+
+ const received: string[] = [];
+ for await (const event of session.stream({ follow: false })) {
+ received.push(event.type);
+ }
+
+ expect(received).toEqual(log.map((event) => event.type));
+ expect(connections).toBe(3);
+ expect(tailRequests).toEqual(["1", null, null]);
+ expect(session.state).toMatchObject({ sessionId: "s1", streamIndex: 6 });
+ });
+
+ it("ends a follow: false read immediately when the cursor is already past the tail", async () => {
+ let connections = 0;
+ const host = await listen(
+ createServer((_req, res) => {
+ connections += 1;
+ res.writeHead(200, {
+ "content-type": "application/x-ndjson",
+ "x-eve-stream-tail-index": "-1",
+ });
+ // Send headers without any body: a live follow would idle here
+ // waiting for events that never arrive.
+ res.flushHeaders();
+ }),
+ );
+
+ const received: string[] = [];
+ for await (const event of follow(host, { follow: false })) {
+ received.push(event.type);
+ }
+
+ expect(received).toEqual([]);
+ expect(connections).toBe(1);
+ });
+
+ it("fails a follow: false read when the server does not report a tail index", async () => {
+ const host = await listen(
+ createServer((_req, res) => {
+ res.writeHead(200, { "content-type": "application/x-ndjson" });
+ res.end();
+ }),
+ );
+
+ await expect(follow(host, { follow: false }).next()).rejects.toThrow(/x-eve-stream-tail-index/);
+ });
+
it("never abandons a progressing turn: any event resets the idle budget", async () => {
const events = ["step.started", "step.completed", "step.started", "session.completed"];
const idlesServed = new Map<number, number>();
diff --git a/packages/eve/src/client/types.ts b/packages/eve/src/client/types.ts
index 9ed7d48ec..ae278ab05 100644
--- a/packages/eve/src/client/types.ts
+++ b/packages/eve/src/client/types.ts
@@ -215,6 +215,14 @@ export interface StreamOptions {
*/
readonly startIndex?: number;
+ /**
+ * Follow the live stream after the durable tail (default). Pass `false`
+ * for a bounded catch-up read: yields events until the cursor passes the
+ * tail observed when the stream opened, then returns instead of
+ * following. Requires a nonnegative start cursor.
+ */
+ readonly follow?: boolean;
+
/**
* Abort signal for cancelling the stream.
*/
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index 52d0c8e8c..01848a05b 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -223,6 +223,9 @@ function createNoopRuntime(): Runtime {
getEventStream: vi
.fn()
.mockRejectedValue(new Error("runtime.getEventStream should not be called in this test")),
+ getStreamTailIndex: vi
+ .fn()
+ .mockRejectedValue(new Error("runtime.getStreamTailIndex should not be called in this test")),
terminateSession: vi.fn(),
};
}
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index f4163c1bf..80c55e12f 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -225,6 +225,16 @@ export function createWorkflowRuntime(config: {
);
},
+ async getStreamTailIndex(sessionId: string): Promise<number> {
+ // The readable is never consumed; cancel it so the unread source does not linger.
+ const readable = getRun(sessionId).getReadable();
+ try {
+ return await readable.getTailIndex();
+ } finally {
+ await readable.cancel().catch(() => {});
+ }
+ },
+
async resolveSession(continuationToken: string): Promise<{ sessionId: string } | undefined> {
try {
const hook = await getHookByToken(continuationToken);
diff --git a/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts b/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
index 3118571b3..a12c9db45 100644
--- a/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
+++ b/packages/eve/src/internal/nitro/routes/channel-dispatch.test.ts
@@ -163,6 +163,9 @@ describe("dispatchChannelRequest", () => {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
});
const targetDefinition: CompiledChannel = {
__kind: CHANNEL_SENTINEL,
@@ -236,6 +239,7 @@ describe("dispatchChannelRequest", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "sess_route" }),
resolveSession: vi.fn(),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
run: vi.fn(),
terminateSession: vi.fn(),
};
@@ -283,6 +287,7 @@ describe("dispatchChannelRequest", () => {
cancelTurn: vi.fn(),
deliver: vi.fn(),
getEventStream: vi.fn(),
+ getStreamTailIndex: vi.fn(),
resolveSession: vi.fn().mockResolvedValue({ sessionId: "sess_previous" }),
run: vi.fn(),
terminateSession: vi.fn().mockResolvedValue({ status: "terminated" }),
@@ -335,6 +340,7 @@ describe("dispatchChannelRequest", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "sess_route" }),
resolveSession: vi.fn(),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
run: vi.fn(),
terminateSession: vi.fn(),
};
@@ -378,6 +384,7 @@ describe("dispatchChannelRequest", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "sess_deliver" }),
resolveSession: vi.fn(),
getEventStream: vi.fn().mockResolvedValue(new ReadableStream()),
+ getStreamTailIndex: vi.fn().mockResolvedValue(-1),
run: vi.fn().mockResolvedValue({
continuationToken: "route-token",
events: new ReadableStream(),
diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.ts
index 2ba630452..d782554f9 100644
--- a/packages/eve/src/protocol/message.ts
+++ b/packages/eve/src/protocol/message.ts
@@ -14,6 +14,7 @@ import type { JsonObject, JsonValue } from "#shared/json.js";
export const EVE_SESSION_ID_HEADER = "x-eve-session-id";
export const EVE_STREAM_FORMAT_HEADER = "x-eve-stream-format";
+export const EVE_STREAM_TAIL_INDEX_HEADER = "x-eve-stream-tail-index";
export const EVE_STREAM_VERSION_HEADER = "x-eve-stream-version";
export const EVE_MESSAGE_STREAM_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
export const EVE_MESSAGE_STREAM_FORMAT = "ndjson";
diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
index b47f30337..8fde03791 100644
--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
@@ -106,6 +106,9 @@ async function firePost(
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
});
const waitUntil = vi.fn();
@@ -255,6 +258,9 @@ describe("chatSdkChannel", () => {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
});
await bridge.channel.receive?.(
diff --git a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts
index daf992204..db6813587 100644
--- a/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts
+++ b/packages/eve/src/public/channels/eve-forwarded-principal.integration.test.ts
@@ -63,6 +63,9 @@ function createEveCreateHandler(input: EveChannelInput) {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
} satisfies ChannelSession);
return {
diff --git a/packages/eve/src/public/channels/eve.test.ts b/packages/eve/src/public/channels/eve.test.ts
index ef77801ef..909fcf753 100644
--- a/packages/eve/src/public/channels/eve.test.ts
+++ b/packages/eve/src/public/channels/eve.test.ts
@@ -67,6 +67,9 @@ function createEveCreateHandler(input: EveChannelInput) {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
} satisfies ChannelSession);
return {
@@ -108,6 +111,9 @@ function createEveContinueHandler(input: EveChannelInput) {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
};
const mockSend = vi.fn<SendFn>().mockResolvedValue(mockSession);
@@ -229,15 +235,18 @@ function createEveStreamHandler(input: EveChannelInput) {
if (!streamRoute) throw new Error("No session stream GET route found");
const getEventStream = vi.fn().mockResolvedValue(new ReadableStream());
+ const getStreamTailIndex = vi.fn().mockResolvedValue(-1);
const mockGetSession = vi.fn().mockReturnValue({
cancel: vi.fn(),
continuationToken: "eve:test",
getEventStream,
+ getStreamTailIndex,
id: "test-session-id",
} satisfies ChannelSession);
return {
getEventStream,
+ getStreamTailIndex,
async fetch(url: string) {
const args: RouteHandlerArgs = {
send: vi.fn(),
@@ -456,6 +465,28 @@ describe("eveChannel — stream cursor", () => {
expect(handler.getEventStream).not.toHaveBeenCalled();
},
);
+
+ it("omits the tail index by default without paying for the lookup", async () => {
+ const handler = createEveStreamHandler({ auth: none() });
+
+ const response = await handler.fetch("https://eve.test/eve/v1/session/test-session-id/stream");
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("x-eve-stream-tail-index")).toBeNull();
+ expect(handler.getStreamTailIndex).not.toHaveBeenCalled();
+ });
+
+ it("reports the durable tail index when the request opts in", async () => {
+ const handler = createEveStreamHandler({ auth: none() });
+ handler.getStreamTailIndex.mockResolvedValueOnce(41);
+
+ const response = await handler.fetch(
+ "https://eve.test/eve/v1/session/test-session-id/stream?includeTailIndex=1",
+ );
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get("x-eve-stream-tail-index")).toBe("41");
+ });
});
describe("eveChannel — onMessage", () => {
diff --git a/packages/eve/src/public/channels/eve.ts b/packages/eve/src/public/channels/eve.ts
index 01efce6c2..cba4629c6 100644
--- a/packages/eve/src/public/channels/eve.ts
+++ b/packages/eve/src/public/channels/eve.ts
@@ -18,6 +18,7 @@ import {
EVE_MESSAGE_STREAM_VERSION,
EVE_SESSION_ID_HEADER,
EVE_STREAM_FORMAT_HEADER,
+ EVE_STREAM_TAIL_INDEX_HEADER,
EVE_STREAM_VERSION_HEADER,
} from "#protocol/message.js";
import {
@@ -437,9 +438,15 @@ export function eveChannel(input: EveChannelInput): EveChannel {
const startIndex = parseStartIndex(req);
if (startIndex instanceof Response) return startIndex;
+ const includeTailIndex = parseIncludeTailIndex(req);
+
try {
const session = getSession(sessionId);
+
+ // The tail lookup is opt-in: only requests that bound a read pay for it.
+ const tailIndex = includeTailIndex ? await session.getStreamTailIndex() : undefined;
const events = await session.getEventStream({ startIndex });
+
const ndjson = serializeAsNdjson(events);
return new Response(ndjson, {
headers: {
@@ -452,6 +459,9 @@ export function eveChannel(input: EveChannelInput): EveChannel {
"x-accel-buffering": "no",
[EVE_SESSION_ID_HEADER]: sessionId,
[EVE_STREAM_FORMAT_HEADER]: EVE_MESSAGE_STREAM_FORMAT,
+ ...(tailIndex === undefined
+ ? {}
+ : { [EVE_STREAM_TAIL_INDEX_HEADER]: String(tailIndex) }),
[EVE_STREAM_VERSION_HEADER]: EVE_MESSAGE_STREAM_VERSION,
},
});
@@ -983,6 +993,11 @@ function toClientContextMessage(content: string): string {
return `${CLIENT_CONTEXT_PREFIX}${content}`;
}
+function parseIncludeTailIndex(request: Request): boolean {
+ const raw = new URL(request.url).searchParams.get("includeTailIndex");
+ return raw === "1" || raw === "true";
+}
+
function parseStartIndex(request: Request): number | undefined | Response {
const raw = new URL(request.url).searchParams.get("startIndex");
if (raw === null) return undefined;
diff --git a/packages/eve/src/public/channels/teams/teamsChannel.test.ts b/packages/eve/src/public/channels/teams/teamsChannel.test.ts
index 52b67f8bf..fba2ea53c 100644
--- a/packages/eve/src/public/channels/teams/teamsChannel.test.ts
+++ b/packages/eve/src/public/channels/teams/teamsChannel.test.ts
@@ -34,6 +34,7 @@ async function firePost(
continuationToken: "TOKEN",
cancel: async () => ({ status: "no_active_turn" as const }),
getEventStream: async () => new ReadableStream(),
+ getStreamTailIndex: async () => -1,
id: "SESSION",
}));
const waitUntil = vi.fn();
@@ -329,6 +330,7 @@ describe("teamsChannel", () => {
continuationToken: "TOKEN",
cancel: async () => ({ status: "no_active_turn" as const }),
getEventStream: async () => new ReadableStream(),
+ getStreamTailIndex: async () => -1,
id: "SESSION",
}));
diff --git a/packages/eve/src/public/definitions/channel.test.ts b/packages/eve/src/public/definitions/channel.test.ts
index a9db21800..a2e961d3b 100644
--- a/packages/eve/src/public/definitions/channel.test.ts
+++ b/packages/eve/src/public/definitions/channel.test.ts
@@ -564,6 +564,9 @@ describe("defineChannel", () => {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
};
},
});
diff --git a/packages/eve/test/eve-run-stream-channel.test.ts b/packages/eve/test/eve-run-stream-channel.test.ts
index 2c5f63952..b591d264c 100644
--- a/packages/eve/test/eve-run-stream-channel.test.ts
+++ b/packages/eve/test/eve-run-stream-channel.test.ts
@@ -176,6 +176,9 @@ function createMockGetSession(events: ReadableStream<HandleMessageStreamEvent>)
async getEventStream() {
return events;
},
+ async getStreamTailIndex() {
+ return -1;
+ },
} satisfies Session);
}
diff --git a/packages/eve/test/scenarios/cross-channel-receive.scenario.test.ts b/packages/eve/test/scenarios/cross-channel-receive.scenario.test.ts
index 69d4c9d32..30250f14c 100644
--- a/packages/eve/test/scenarios/cross-channel-receive.scenario.test.ts
+++ b/packages/eve/test/scenarios/cross-channel-receive.scenario.test.ts
@@ -105,6 +105,9 @@ function createCapturingRuntime(captured: CapturedRun[]): Runtime {
async getEventStream() {
return new ReadableStream();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
async terminateSession() {
throw new Error("terminateSession should not be called in this scenario");
},
diff --git a/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts b/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
index 3b9176e51..0996a1d3c 100644
--- a/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
+++ b/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
@@ -82,6 +82,9 @@ function createCapturingRuntime(captured: CapturedRun[]): Runtime {
async getEventStream() {
return new ReadableStream<HandleMessageStreamEvent>();
},
+ async getStreamTailIndex() {
+ return -1;
+ },
async terminateSession() {
throw new Error("terminateSession should not be called in this scenario");
},