Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 sessio
HTTP 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 manually
Use `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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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