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.mdnew file mode 100644index 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.mdxindex 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.mdindex 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 TypeScriptFor 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.mdxindex 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 requestdiff --git a/packages/eve/src/channel/cancel.test.ts b/packages/eve/src/channel/cancel.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: Ruasync 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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");},