The Open Framework for Building Agents
feat(eve): add ability to disable reconnection on send() / stream() (#1092)
OwenKepharteb92ee310fa8
diff --git a/.changeset/quiet-streams-return.md b/.changeset/quiet-streams-return.mdnew file mode 100644index 000000000..15f04c305--- /dev/null+++ b/.changeset/quiet-streams-return.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Allow `session.send()` and `session.stream()` callers to disable automatic stream reconnection with `streamReconnectPolicy: { reconnect: false }`, so relays and proxies can own cursor recovery and retry policy.diff --git a/docs/guides/client/streaming.mdx b/docs/guides/client/streaming.mdxindex f9e705b28..8ba6fb3fd 100644--- a/docs/guides/client/streaming.mdx+++ b/docs/guides/client/streaming.mdx@@ -105,6 +105,21 @@ If you support refresh while an authorization prompt is pending, keep the sessioHTTP connections can end before a run does. The client reconnects from the number of events already consumed, so long turns continue without replaying events. It stops at a turn boundary, when aborted, or when the stream can no longer make progress.+Set `streamReconnectPolicy: { reconnect: false }` when a relay or proxy owns the cursor and reconnection policy. This makes a single stream GET attempt and returns when that connection ends; it does not stop the server-side turn:++```ts+const response = await session.send({+ message: "Run the long operation.",+ streamReconnectPolicy: { reconnect: false },+});++for await (const event of response) {+ console.log(event.type);+}+```++The same option is available on manual attachments as `session.stream({ streamReconnectPolicy: { reconnect: false } })`.+## Open a stream manuallyUse `session.stream()` when you already have a session cursor and only need to attach to the existing stream:diff --git a/packages/eve/src/client/index.ts b/packages/eve/src/client/index.tsindex 0ab0f5cfe..d531d3795 100644--- a/packages/eve/src/client/index.ts+++ b/packages/eve/src/client/index.ts@@ -49,10 +49,13 @@ export type {HeadersValue,HealthResult,MessageResult,+ ResolvedStreamReconnectPolicy,SendTurnInput,SendTurnPayload,SessionState,StreamOptions,+ StreamReconnectPolicy,+ StreamReconnectRetryPolicy,TokenValue,} from "#client/types.js";diff --git a/packages/eve/src/client/open-stream.ts b/packages/eve/src/client/open-stream.tsindex 47c4c3d21..e5d01265c 100644--- a/packages/eve/src/client/open-stream.ts+++ b/packages/eve/src/client/open-stream.ts@@ -2,23 +2,80 @@ import type { HandleMessageStreamEvent } from "#protocol/message.js";import { createEveMessageStreamRoutePath } from "#protocol/routes.js";import { ClientError } from "#client/client-error.js";import { isStreamDisconnectError, readNdjsonStream } from "#client/ndjson.js";-import type { ClientRedirectPolicy } from "#client/types.js";+import type {+ ClientRedirectPolicy,+ ResolvedStreamReconnectPolicy as StreamReconnectPolicyOptions,+ StreamReconnectPolicy,+ StreamReconnectRetryPolicy,+} from "#client/types.js";import { createClientUrl } from "#client/url.js";-const STREAM_OPEN_RETRY_ATTEMPTS = 12;-const STREAM_OPEN_RETRY_BASE_DELAY_MS = 250;-const STREAM_OPEN_RETRY_MAX_DELAY_MS = 5_000;-const STREAM_OPEN_RETRYABLE_STATUS = new Set([404, 409, 425, 500, 502, 503, 504]);+interface RetryPolicy {+ readonly baseDelayMs: number;+ readonly maxAttempts: number;+ readonly maxDelayMs: number;+}-const STREAM_RECONNECT_BASE_DELAY_MS = 250;-const STREAM_RECONNECT_MAX_DELAY_MS = 4_000;-const STREAM_MAX_IDLE_RECONNECTS = 5;+interface ResolvedStreamReconnectPolicy {+ readonly retryableErrorStatuses: ReadonlySet<number>;+ readonly streamIdleReconnectPolicy: RetryPolicy;+ readonly streamOpenReconnectPolicy: RetryPolicy;+}++const DEFAULT_STREAM_RECONNECT_POLICY: ResolvedStreamReconnectPolicy = {+ retryableErrorStatuses: new Set([404, 409, 425, 500, 502, 503, 504]),+ streamIdleReconnectPolicy: { baseDelayMs: 250, maxAttempts: 5, maxDelayMs: 4_000 },+ streamOpenReconnectPolicy: { baseDelayMs: 250, maxAttempts: 12, maxDelayMs: 5_000 },+};++const NO_STREAM_RECONNECT_POLICY: ResolvedStreamReconnectPolicy = {+ ...DEFAULT_STREAM_RECONNECT_POLICY,+ streamIdleReconnectPolicy: {+ ...DEFAULT_STREAM_RECONNECT_POLICY.streamIdleReconnectPolicy,+ maxAttempts: 0,+ },+ streamOpenReconnectPolicy: {+ ...DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy,+ maxAttempts: 1,+ },+};++function resolveRetryPolicy(+ policy: StreamReconnectRetryPolicy | undefined,+ defaults: RetryPolicy,+): RetryPolicy {+ return { ...defaults, ...policy };+}++function resolveStreamReconnectPolicy(+ policy: StreamReconnectPolicy | undefined,+): ResolvedStreamReconnectPolicy {+ if (policy && "reconnect" in policy && policy.reconnect === false) {+ return NO_STREAM_RECONNECT_POLICY;+ }++ const configured = policy as StreamReconnectPolicyOptions | undefined;+ return {+ retryableErrorStatuses: configured?.retryableErrorStatuses+ ? new Set(configured.retryableErrorStatuses)+ : DEFAULT_STREAM_RECONNECT_POLICY.retryableErrorStatuses,+ streamIdleReconnectPolicy: resolveRetryPolicy(+ configured?.streamIdleReconnectPolicy,+ DEFAULT_STREAM_RECONNECT_POLICY.streamIdleReconnectPolicy,+ ),+ streamOpenReconnectPolicy: resolveRetryPolicy(+ configured?.streamOpenReconnectPolicy,+ DEFAULT_STREAM_RECONNECT_POLICY.streamOpenReconnectPolicy,+ ),+ };+}/*** Internal configuration for following a durable event stream.*/interface FollowStreamInput {readonly host: string;+ readonly streamReconnectPolicy?: StreamReconnectPolicy;readonly resolveHeaders: () => Promise<Headers>;readonly redirect?: ClientRedirectPolicy;readonly sessionId: string;@@ -38,15 +95,17 @@ interface FollowStreamInput {export async function* followStreamIterable(input: FollowStreamInput,): AsyncGenerator<HandleMessageStreamEvent> {+ const retryPolicy = resolveStreamReconnectPolicy(input.streamReconnectPolicy);+ const idleRetryPolicy = retryPolicy.streamIdleReconnectPolicy;let startIndex = input.startIndex;- let reconnectDelayMs = STREAM_RECONNECT_BASE_DELAY_MS;+ let reconnectDelayMs = idleRetryPolicy.baseDelayMs;let idleReconnects = 0;let initialConnection = true;while (true) {let body: ReadableStream<Uint8Array>;try {- body = await openStreamBody({ ...input, startIndex });+ body = await openStreamBody({ ...input, retryPolicy, startIndex });} catch (error) {if (input.signal?.aborted) {return;@@ -59,7 +118,7 @@ export async function* followStreamIterable(for await (const event of readNdjsonStream(body)) {startIndex += 1;deliveredEvent = true;- reconnectDelayMs = STREAM_RECONNECT_BASE_DELAY_MS;+ reconnectDelayMs = idleRetryPolicy.baseDelayMs;idleReconnects = 0;yield event;}@@ -69,14 +128,14 @@ export async function* followStreamIterable(}}- if (input.signal?.aborted || input.startIndex < 0) {+ if (input.signal?.aborted || input.startIndex < 0 || idleRetryPolicy.maxAttempts === 0) {return;}if (!deliveredEvent &&!initialConnection &&- (idleReconnects += 1) >= STREAM_MAX_IDLE_RECONNECTS+ (idleReconnects += 1) >= idleRetryPolicy.maxAttempts) {return;}@@ -86,7 +145,7 @@ export async function* followStreamIterable(if (input.signal?.aborted) {return;}- reconnectDelayMs = Math.min(reconnectDelayMs * 2, STREAM_RECONNECT_MAX_DELAY_MS);+ reconnectDelayMs = Math.min(reconnectDelayMs * 2, idleRetryPolicy.maxDelayMs);}}@@ -97,14 +156,16 @@ export async function* followStreamIterable(* readable from the stream route.*/export async function openStreamBody(- input: FollowStreamInput,+ input: FollowStreamInput & { readonly retryPolicy?: ResolvedStreamReconnectPolicy },): Promise<ReadableStream<Uint8Array>> {+ const retryPolicy = input.retryPolicy ?? DEFAULT_STREAM_RECONNECT_POLICY;+ const openRetryPolicy = retryPolicy.streamOpenReconnectPolicy;let lastStatus: number | undefined;let lastBody: string | undefined;let lastHeaders: Headers | undefined;- let retryDelayMs = STREAM_OPEN_RETRY_BASE_DELAY_MS;+ let retryDelayMs = openRetryPolicy.baseDelayMs;- for (let attempt = 0; attempt < STREAM_OPEN_RETRY_ATTEMPTS; attempt += 1) {+ for (let attempt = 0; attempt < openRetryPolicy.maxAttempts; attempt += 1) {const url = createClientUrl(input.host,createEveMessageStreamRoutePath(input.sessionId),@@ -123,12 +184,12 @@ export async function openStreamBody(if (input.signal?.aborted ||!isStreamDisconnectError(error) ||- attempt === STREAM_OPEN_RETRY_ATTEMPTS - 1+ attempt === openRetryPolicy.maxAttempts - 1) {throw error;}await sleep(retryDelayMs, input.signal);- retryDelayMs = Math.min(retryDelayMs * 2, STREAM_OPEN_RETRY_MAX_DELAY_MS);+ retryDelayMs = Math.min(retryDelayMs * 2, openRetryPolicy.maxDelayMs);continue;}@@ -143,13 +204,13 @@ export async function openStreamBody(lastBody = await response.text();lastHeaders = response.headers;- if (!STREAM_OPEN_RETRYABLE_STATUS.has(response.status)) {+ if (!retryPolicy.retryableErrorStatuses.has(response.status)) {throw new ClientError(response.status, lastBody, response.headers);}- if (attempt < STREAM_OPEN_RETRY_ATTEMPTS - 1) {+ if (attempt < openRetryPolicy.maxAttempts - 1) {await sleep(retryDelayMs, input.signal);- retryDelayMs = Math.min(retryDelayMs * 2, STREAM_OPEN_RETRY_MAX_DELAY_MS);+ retryDelayMs = Math.min(retryDelayMs * 2, openRetryPolicy.maxDelayMs);}}diff --git a/packages/eve/src/client/session.test.ts b/packages/eve/src/client/session.test.tsindex f1897d045..0f720905c 100644--- a/packages/eve/src/client/session.test.ts+++ b/packages/eve/src/client/session.test.ts@@ -418,6 +418,86 @@ describe("ClientSession", () => {expect(fetchMock).toHaveBeenCalledOnce();});+ it("does not reconnect a manually opened stream when disabled", async () => {+ const fetchMock = vi+ .spyOn(globalThis, "fetch")+ .mockResolvedValue(createStreamResponse([{ type: "turn.started", data: {} }]));+ const session = createSession({ sessionId: "session_1", streamIndex: 0 });++ const eventTypes: string[] = [];+ for await (const event of session.stream({ streamReconnectPolicy: { reconnect: false } })) {+ eventTypes.push(event.type);+ }++ expect(eventTypes).toEqual(["turn.started"]);+ expect(fetchMock).toHaveBeenCalledOnce();+ expect(session.state.streamIndex).toBe(1);+ });++ it("does not reconnect a sent turn's response stream when disabled", async () => {+ const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (_request, init) => {+ if ((init?.method ?? "GET") === "POST") {+ return createAcceptedResponse();+ }++ return createStreamResponse([{ type: "turn.started", data: {} }]);+ });+ const session = createSession();++ const eventTypes: string[] = [];+ for await (const event of await session.send({+ message: "first",+ streamReconnectPolicy: { reconnect: false },+ })) {+ eventTypes.push(event.type);+ }++ expect(eventTypes).toEqual(["turn.started"]);+ expect(fetchMock).toHaveBeenCalledTimes(2);+ expect(session.state.streamIndex).toBe(1);+ });++ it("does not retry a failed stream open when reconnection is disabled", async () => {+ const fetchMock = vi+ .spyOn(globalThis, "fetch")+ .mockRejectedValue(new TypeError("fetch failed"));+ const session = createSession({ sessionId: "session_1", streamIndex: 0 });++ await expect(async () => {+ for await (const _event of session.stream({ streamReconnectPolicy: { reconnect: false } })) {+ // The stream fails before producing an event.+ }+ }).rejects.toThrow("fetch failed");+ expect(fetchMock).toHaveBeenCalledOnce();+ });++ it("uses a configured stream-open reconnect policy", async () => {+ const fetchMock = vi+ .spyOn(globalThis, "fetch")+ .mockRejectedValue(new TypeError("fetch failed"));+ const session = createSession({ sessionId: "session_1", streamIndex: 0 });++ vi.useFakeTimers();+ try {+ const consumed = (async () => {+ for await (const _event of session.stream({+ streamReconnectPolicy: {+ streamOpenReconnectPolicy: { baseDelayMs: 10, maxAttempts: 2 },+ },+ })) {+ // The stream fails before producing an event.+ }+ })();+ const assertion = expect(consumed).rejects.toThrow("fetch failed");+ await vi.advanceTimersByTimeAsync(10);+ await assertion;+ } finally {+ vi.useRealTimers();+ }++ expect(fetchMock).toHaveBeenCalledTimes(2);+ });+it("retries a transient fetch failure while reopening an active turn stream", async () => {const encoder = new TextEncoder();const streamUrls: string[] = [];diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.tsindex 33e5710c3..69b922d0e 100644--- a/packages/eve/src/client/session.ts+++ b/packages/eve/src/client/session.ts@@ -145,8 +145,9 @@ export class ClientSession {* Opens this session's event stream for the current session ID.** Resumes from the session's stored stream cursor unless `options.startIndex`- * overrides it. The stream reconnects from its cursor when the connection- * ends. Negative indices read relative to the current tail on one connection+ * overrides it. By default, the stream reconnects from its cursor when the+ * connection ends; pass `streamReconnectPolicy: { reconnect: false }` to use+ * one connection. Negative indices read relative to the current tail on one connection* and do not advance the stored absolute cursor.** @throws {Error} If the session has no session ID (no message has been sent@@ -230,6 +231,7 @@ export class ClientSession {host: this.#context.host,resolveHeaders: () => this.#context.resolveHeaders(input.headers),redirect: this.#context.redirect,+ streamReconnectPolicy: input.streamReconnectPolicy,sessionId,signal: input.signal,startIndex: initialState.sessionId === sessionId ? initialState.streamIndex : 0,@@ -265,6 +267,7 @@ export class ClientSession {host: this.#context.host,resolveHeaders: () => this.#context.resolveHeaders(),redirect: this.#context.redirect,+ streamReconnectPolicy: options?.streamReconnectPolicy,sessionId,signal: options?.signal,startIndex: streamIndex,diff --git a/packages/eve/src/client/types.ts b/packages/eve/src/client/types.tsindex 3ac95009c..e0675f11e 100644--- a/packages/eve/src/client/types.ts+++ b/packages/eve/src/client/types.ts@@ -152,6 +152,12 @@ export interface SendTurnPayload<TOutput = unknown> {*/readonly outputSchema?: StandardJSONSchemaV1<unknown, TOutput> | JsonObject;+ /**+ * Reconnection policy for the response event stream. Omit to use the default+ * policy, or pass `{ reconnect: false }` when the caller owns cursor recovery.+ */+ readonly streamReconnectPolicy?: StreamReconnectPolicy;+/*** Abort signal for cancelling the request.*/@@ -163,10 +169,43 @@ export interface SendTurnPayload<TOutput = unknown> {readonly headers?: Readonly<Record<string, string>>;}+/** Retry and backoff settings for one kind of stream reconnection. */+export interface StreamReconnectRetryPolicy {+ /** Initial delay before retrying, in milliseconds. */+ readonly baseDelayMs?: number;++ /** Maximum number of attempts governed by this retry policy. */+ readonly maxAttempts?: number;++ /** Maximum delay between retries, in milliseconds. */+ readonly maxDelayMs?: number;+}++/** Configurable policy used when automatic stream reconnection is enabled. */+export interface ResolvedStreamReconnectPolicy {+ /** Retry policy for opening an HTTP stream connection. */+ readonly streamOpenReconnectPolicy?: StreamReconnectRetryPolicy;++ /** Retry policy for reconnecting streams that make no progress. */+ readonly streamIdleReconnectPolicy?: StreamReconnectRetryPolicy;++ /** HTTP response statuses that may be retried while opening a stream. */+ readonly retryableErrorStatuses?: readonly number[];+}++/** Automatic stream reconnection configuration. */+export type StreamReconnectPolicy = ResolvedStreamReconnectPolicy | { readonly reconnect: false };+/*** Options for {@link ClientSession.stream}.*/export interface StreamOptions {+ /**+ * Reconnection policy for the event stream. Omit to use the default policy,+ * or pass `{ reconnect: false }` when the caller owns cursor recovery.+ */+ readonly streamReconnectPolicy?: StreamReconnectPolicy;+/*** Absolute event index to start from. Negative values read relative to the* current tail (`-1` starts at the latest event). Relative-tail streams do