@effect-uai/ui 0.19.0 → 0.20.0-dev-20261110202152

package/dist/Transport.mjs

@@ -1,8 +1,10 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { StreamId } from "./RunEvent.mjs";
-import { execute, ndjson, resumable, sse } from "./Client.mjs";
+import { Disconnected, execute, ndjson, resumable, sse } from "./Client.mjs";
 import { sequence } from "./Run.mjs";
-import { Effect, Stream } from "effect";
+import { DateTime, Duration, Effect, Function, Option, Predicate, Schedule, Schema, Stream } from "effect";
+import { Sse } from "effect/encoding";
+import { HttpClient, HttpClientError } from "effect/http";
 //#region src/Transport.ts
 /**
 * How a client reaches the server. Every transport turns an input into the
@@ -19,6 +21,7 @@ var Transport_exports = /* @__PURE__ */ __exportAll({
 	durable: () => durable,
 	durableHttp: () => durableHttp,
 	local: () => local,
+	reconnect: () => reconnect,
 	session: () => session,
 	sessionHttp: () => sessionHttp
 });
@@ -36,47 +39,104 @@ const direct = (options) => ({ start: (input, state) => Stream.unwrap(options.re
 * run's events are sequenced under `streamId`.
 */
 const local = (run, options) => ({ start: (input, state) => run(input, state).pipe(sequence(options?.streamId ?? StreamId.make("local"))) });
+const durableOf = (parts) => ({
+	...parts,
+	start: (input, state) => Stream.unwrap(Effect.map(parts.submit(input, state), (streamId) => parts.resume(streamId, 0)))
+});
 /**
 * Durable runs: `submit` starts one on the server and returns its stream id;
-* `events` reads it from `after` (wrap it in `Client.resumable` to survive
-* drops). The run lives on the server, so a reload re-attaches with `resume`.
+* `events` reads it from `after`. The run lives on the server, so a reload
+* re-attaches with `resume`. A stream that ends before the run's terminal
+* fails with `Client.Disconnected`; pipe through `reconnect` to resume it.
 */
-const durable = (options) => ({
-	start: (input, state) => Stream.unwrap(options.submit(input, state).pipe(Effect.map((streamId) => options.events(streamId, 0)))),
-	resume: options.events,
+const durable = (options) => durableOf({
+	submit: options.submit,
+	resume: (streamId, after) => resumable((from) => options.events(streamId, from), { from: after }),
 	...options.stop !== void 0 ? { stop: options.stop } : {}
 });
-const session = (options) => options;
+/**
+* A session stream never ends on its own, so one that completes fails with
+* `Client.Disconnected`; pipe through `reconnect` to resume it.
+*/
+const session = (options) => ({
+	...options,
+	events: (streamId, after) => resumable((from) => options.events(streamId, from), {
+		from: after,
+		until: "never"
+	})
+});
 const stopOver = (stop) => stop === void 0 ? {} : { stop: (streamId) => execute(stop(streamId)).pipe(Effect.asVoid) };
 /**
 * `durable` over HTTP. `submit` starts a run and returns its stream id (the
 * app decodes its own response, e.g. with `HttpClientResponse.schemaJson`);
-* `events` is read as SSE and reconnects per `reconnect`.
+* `events` is read as SSE. Pipe through `reconnect` to survive drops.
 */
 const durableHttp = (options) => durable({
 	submit: options.submit,
-	events: (streamId, after) => resumable((from) => sse(options.events(streamId, from)), {
-		from: after,
-		schedule: options.reconnect
-	}),
+	events: (streamId, after) => sse(options.events(streamId, after)),
 	...stopOver(options.stop)
 });
 /**
 * `session` over HTTP. `send` adds an input and returns the session's stream
 * id (without one, the server starts a session); `events` follows the whole
-* session as SSE. It carries many runs and never ends on its own, so
-* `reconnect` usually retries forever (e.g. `Schedule.spaced("1 second")`).
+* session as SSE. Pipe through `reconnect` to survive drops.
 */
 const sessionHttp = (options) => session({
 	send: options.send,
-	events: (streamId, after) => resumable((from) => sse(options.events(streamId, from)), {
-		from: after,
-		until: "never",
-		schedule: options.reconnect
-	}),
+	events: (streamId, after) => sse(options.events(streamId, after)),
 	...stopOver(options.stop)
 });
+const defaultSchedule = Schedule.min([Schedule.exponential("500 millis"), Schedule.spaced("10 seconds")]).pipe(Schedule.jittered);
+const isDisconnected = (error) => error instanceof Disconnected;
+const isTransient = (error) => Sse.Retry.is(error) || HttpClient.isTransientError(error);
+const parseSeconds = Schema.decodeUnknownOption(Schema.FiniteFromString);
+const retryAfter = (value, now) => parseSeconds(value).pipe(Option.map((seconds) => Duration.seconds(Math.max(0, seconds))), Option.orElse(() => DateTime.make(value).pipe(Option.map((at) => Duration.millis(Math.max(0, DateTime.toEpochMillis(at) - now))))));
+const serverDelay = (error, now) => {
+	if (Sse.Retry.is(error)) return Option.some(error.duration);
+	if (!HttpClientError.isHttpClientError(error)) return Option.none();
+	return Option.fromNullishOr(error.response?.headers["retry-after"]).pipe(Option.flatMap((value) => retryAfter(value, now)));
+};
+const policy = (options) => {
+	const base = options?.schedule ?? defaultSchedule;
+	const extra = options?.while;
+	return (options?.times === void 0 ? base : Schedule.upTo(base, { times: options.times })).pipe(Schedule.while(({ input }) => isDisconnected(input) || isTransient(input) || extra !== void 0 && extra(input)), Schedule.modifyDelay(({ input, duration, now }) => Effect.succeed(Option.match(serverDelay(input, now), {
+		onNone: () => duration,
+		onSome: (asked) => Duration.max(duration, asked)
+	}))));
+};
+const isSession = (self) => "send" in self;
+const isResumable = (u) => Predicate.hasProperty(u, "send") || Predicate.hasProperty(u, "resume");
+/**
+* Resume a dropped event stream from the last seq, as `HttpClient.retryTransient`
+* does for requests. Retries drops (`Client.Disconnected`), timeouts, transport
+* errors, 408 / 429 / 5xx and an SSE `retry:` line, waiting at least what the
+* server asks for (`Retry-After`, `retry:`); anything else (404, 401, a
+* malformed frame) ends the stream with that error. `while` adds the app's own
+* transient errors (e.g. a dropped WebSocket).
+*
+* A session is followed forever; a durable run until its terminal. A durable
+* `submit` is never retried, so an input is never sent twice. Not for `direct`
+* / `local`: there the run is the request, with no position to resume from.
+*
+*   const transport = Transport.reconnect(Transport.sessionHttp({ send, events, stop }))
+*   const ws = pipe(Transport.session({ send, events }), Transport.reconnect({ while: isDropped }))
+*/
+const reconnect = Function.dual((args) => isResumable(args[0]), (self, options) => {
+	const schedule = policy(options);
+	const resumed = (events, until) => (streamId, after) => resumable((from) => events(streamId, from), {
+		from: after,
+		until,
+		schedule
+	});
+	return isSession(self) ? {
+		...self,
+		events: resumed(self.events, "never")
+	} : durableOf({
+		...self,
+		resume: resumed(self.resume, "terminal")
+	});
+});
 //#endregion
-export { direct, durable, durableHttp, local, session, sessionHttp, Transport_exports as t };
+export { direct, durable, durableHttp, local, reconnect, session, sessionHttp, Transport_exports as t };
 
 //# sourceMappingURL=Transport.mjs.map

package/dist/Transport.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Transport.mjs","names":["Client.ndjson","Client.sse","Run.sequence","Client.execute","Client.resumable"],"sources":["../src/Transport.ts"],"sourcesContent":["/**\n * How a client reaches the server. Every transport turns an input into the\n * envelopes of the run it starts; durable transports can also re-attach to a\n * run and stop it. Missing capabilities are absent from the value, so a UI\n * can tell whether stop or resume exists.\n *\n * `I` is the app's input (`Input.Input` for the preset); `S` is the client\n * state passed to `start`, so a request can carry any app data from it (a\n * chat id, settings).\n */\nimport { Effect, type Option, type Schedule, Stream } from \"effect\"\nimport type { HttpClient, HttpClientRequest } from \"effect/http\"\nimport * as Client from \"./Client.js\"\nimport * as Run from \"./Run.js\"\nimport { type Envelope, type RunEvent, StreamId } from \"./RunEvent.js\"\n\nexport type Transport<I, S, E, R> = {\n  /** Start a run for `input` and stream its envelopes. Interrupting the stream abandons it. */\n  readonly start: (input: I, state: S) => Stream.Stream<Envelope, E, R>\n  /** Re-attach to a run after a reload, from `after`. Durable only. */\n  readonly resume?: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n  /** Ask the server to stop a run. Durable only; direct mode stops by interrupting `start`. */\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, E, R>\n}\n\n/**\n * Direct mode: one HTTP request per input whose response body is the run.\n * Stop interrupts the stream, which aborts the request; the server sees the\n * client go away and interrupts its run.\n *\n * Any other source (RPC streams, server functions) is a transport too:\n * write `{ start: (input, state) => stream }` directly.\n */\nexport const direct = <I, S, EB = never, RB = never>(options: {\n  readonly request: (\n    input: I,\n    state: S,\n  ) => Effect.Effect<HttpClientRequest.HttpClientRequest, EB, RB>\n  readonly format?: \"sse\" | \"ndjson\"\n}): Transport<I, S, Client.ClientError | EB, HttpClient.HttpClient | RB> => ({\n  start: (input, state) =>\n    Stream.unwrap(\n      options\n        .request(input, state)\n        .pipe(\n          Effect.map(\n            (request): Stream.Stream<Envelope, Client.ClientError, HttpClient.HttpClient> =>\n              options.format === \"ndjson\" ? Client.ndjson(request) : Client.sse(request),\n          ),\n        ),\n    ),\n})\n\n/**\n * Run the agent in the same process (browser agent, tests, Storybook). The\n * run's events are sequenced under `streamId`.\n */\nexport const local = <I, S, E, R>(\n  run: (input: I, state: S) => Stream.Stream<RunEvent, E, R>,\n  options?: { readonly streamId?: StreamId },\n): Transport<I, S, E, R> => ({\n  start: (input, state) =>\n    run(input, state).pipe(Run.sequence(options?.streamId ?? StreamId.make(\"local\"))),\n})\n\n/** A per-run transport that can re-attach to a run (durable). */\nexport type Durable<I, S, E, R> = Transport<I, S, E, R> & {\n  readonly resume: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n}\n\n/**\n * Durable runs: `submit` starts one on the server and returns its stream id;\n * `events` reads it from `after` (wrap it in `Client.resumable` to survive\n * drops). The run lives on the server, so a reload re-attaches with `resume`.\n */\nexport const durable = <I, S, ES, RS, EE, RE, EX = never, RX = never>(options: {\n  readonly submit: (input: I, state: S) => Effect.Effect<StreamId, ES, RS>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, EE, RE>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, EX, RX>\n}): Durable<I, S, ES | EE | EX, RS | RE | RX> => ({\n  start: (input, state) =>\n    Stream.unwrap(\n      options.submit(input, state).pipe(Effect.map((streamId) => options.events(streamId, 0))),\n    ),\n  resume: options.events,\n  ...(options.stop !== undefined ? { stop: options.stop } : {}),\n})\n\n/**\n * A durable session (a chat): one stream carries every run, and the server\n * owns its history. `send` without a stream id starts a new session and\n * returns its id (the app's own chat id, branded); with one, it adds a run to\n * that session. `events` follows the whole session from `after` (wrap it in\n * `Client.resumable` with `until: \"never\"`). The run arrives on that stream,\n * not as a response to `send`.\n */\nexport type Session<I, S, E, R> = {\n  readonly send: (\n    streamId: Option.Option<StreamId>,\n    input: I,\n    state: S,\n  ) => Effect.Effect<StreamId, E, R>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, E, R>\n}\n\nexport const session = <I, S, ES, RS, EE, RE, EX = never, RX = never>(options: {\n  readonly send: (\n    streamId: Option.Option<StreamId>,\n    input: I,\n    state: S,\n  ) => Effect.Effect<StreamId, ES, RS>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, EE, RE>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, EX, RX>\n}): Session<I, S, ES | EE | EX, RS | RE | RX> => options\n\n// ---------------------------------------------------------------------------\n// Over HTTP: `durable` and `session` with SSE events that reconnect\n// ---------------------------------------------------------------------------\n\n/** What the HTTP helpers can fail with. */\nexport type HttpError = Client.ClientError | Client.Disconnected\n\ntype HttpOptions = {\n  /** The SSE request for a stream from `after`. */\n  readonly events: (streamId: StreamId, after: number) => HttpClientRequest.HttpClientRequest\n  /** The request that stops a stream's active run. */\n  readonly stop?: (streamId: StreamId) => HttpClientRequest.HttpClientRequest\n  /** When to reconnect a dropped event stream (it resumes from the last `seq`). */\n  readonly reconnect: Schedule.Schedule<unknown, HttpError>\n}\n\nconst stopOver = (stop: HttpOptions[\"stop\"]) =>\n  stop === undefined\n    ? {}\n    : { stop: (streamId: StreamId) => Client.execute(stop(streamId)).pipe(Effect.asVoid) }\n\n/**\n * `durable` over HTTP. `submit` starts a run and returns its stream id (the\n * app decodes its own response, e.g. with `HttpClientResponse.schemaJson`);\n * `events` is read as SSE and reconnects per `reconnect`.\n */\nexport const durableHttp = <I, S, ES = never, RS = never>(\n  options: HttpOptions & {\n    readonly submit: (input: I, state: S) => Effect.Effect<StreamId, ES, RS>\n  },\n): Durable<I, S, HttpError | ES, HttpClient.HttpClient | RS> =>\n  durable({\n    submit: options.submit,\n    events: (streamId, after) =>\n      Client.resumable((from) => Client.sse(options.events(streamId, from)), {\n        from: after,\n        schedule: options.reconnect,\n      }),\n    ...stopOver(options.stop),\n  })\n\n/**\n * `session` over HTTP. `send` adds an input and returns the session's stream\n * id (without one, the server starts a session); `events` follows the whole\n * session as SSE. It carries many runs and never ends on its own, so\n * `reconnect` usually retries forever (e.g. `Schedule.spaced(\"1 second\")`).\n */\nexport const sessionHttp = <I, S, ES = never, RS = never>(\n  options: HttpOptions & {\n    readonly send: (\n      streamId: Option.Option<StreamId>,\n      input: I,\n      state: S,\n    ) => Effect.Effect<StreamId, ES, RS>\n  },\n): Session<I, S, HttpError | ES, HttpClient.HttpClient | RS> =>\n  session({\n    send: options.send,\n    events: (streamId, after) =>\n      Client.resumable((from) => Client.sse(options.events(streamId, from)), {\n        from: after,\n        until: \"never\",\n        schedule: options.reconnect,\n      }),\n    ...stopOver(options.stop),\n  })\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAa,UAAwC,aAMwB,EAC3E,QAAQ,OAAO,UACb,OAAO,OACL,QACG,QAAQ,OAAO,KAAK,CAAC,CACrB,KACC,OAAO,KACJ,YACC,QAAQ,WAAW,WAAWA,OAAc,OAAO,IAAIC,IAAW,OAAO,CAC7E,CACF,CACJ,EACJ;;;;;AAMA,MAAa,SACX,KACA,aAC2B,EAC3B,QAAQ,OAAO,UACb,IAAI,OAAO,KAAK,CAAC,CAAC,KAAKC,SAAa,SAAS,YAAY,SAAS,KAAK,OAAO,CAAC,CAAC,EACpF;;;;;;AAYA,MAAa,WAAyD,aAIpB;CAChD,QAAQ,OAAO,UACb,OAAO,OACL,QAAQ,OAAO,OAAO,KAAK,CAAC,CAAC,KAAK,OAAO,KAAK,aAAa,QAAQ,OAAO,UAAU,CAAC,CAAC,CAAC,CACzF;CACF,QAAQ,QAAQ;CAChB,GAAI,QAAQ,SAAS,KAAA,IAAY,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;AAC7D;AAoBA,MAAa,WAAyD,YAQrB;AAkBjD,MAAM,YAAY,SAChB,SAAS,KAAA,IACL,CAAC,IACD,EAAE,OAAO,aAAuBC,QAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,MAAM,EAAE;;;;;;AAOzF,MAAa,eACX,YAIA,QAAQ;CACN,QAAQ,QAAQ;CAChB,SAAS,UAAU,UACjBC,WAAkB,SAASH,IAAW,QAAQ,OAAO,UAAU,IAAI,CAAC,GAAG;EACrE,MAAM;EACN,UAAU,QAAQ;CACpB,CAAC;CACH,GAAG,SAAS,QAAQ,IAAI;AAC1B,CAAC;;;;;;;AAQH,MAAa,eACX,YAQA,QAAQ;CACN,MAAM,QAAQ;CACd,SAAS,UAAU,UACjBG,WAAkB,SAASH,IAAW,QAAQ,OAAO,UAAU,IAAI,CAAC,GAAG;EACrE,MAAM;EACN,OAAO;EACP,UAAU,QAAQ;CACpB,CAAC;CACH,GAAG,SAAS,QAAQ,IAAI;AAC1B,CAAC"}
+{"version":3,"file":"Transport.mjs","names":["Client.ndjson","Client.sse","Run.sequence","Client.resumable","Client.execute","Client.Disconnected"],"sources":["../src/Transport.ts"],"sourcesContent":["/**\n * How a client reaches the server. Every transport turns an input into the\n * envelopes of the run it starts; durable transports can also re-attach to a\n * run and stop it. Missing capabilities are absent from the value, so a UI\n * can tell whether stop or resume exists.\n *\n * `I` is the app's input (`Input.Input` for the preset); `S` is the client\n * state passed to `start`, so a request can carry any app data from it (a\n * chat id, settings).\n */\nimport {\n  DateTime,\n  Duration,\n  Effect,\n  Option,\n  Function,\n  Predicate,\n  Schedule,\n  Schema,\n  Stream,\n} from \"effect\"\nimport { Sse } from \"effect/encoding\"\nimport { HttpClient, HttpClientError, type HttpClientRequest } from \"effect/http\"\nimport * as Client from \"./Client.js\"\nimport * as Run from \"./Run.js\"\nimport { type Envelope, type RunEvent, StreamId } from \"./RunEvent.js\"\n\nexport type Transport<I, S, E, R> = {\n  /** Start a run for `input` and stream its envelopes. Interrupting the stream abandons it. */\n  readonly start: (input: I, state: S) => Stream.Stream<Envelope, E, R>\n  /** Re-attach to a run after a reload, from `after`. Durable only. */\n  readonly resume?: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n  /** Ask the server to stop a run. Durable only; direct mode stops by interrupting `start`. */\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, E, R>\n}\n\n/**\n * Direct mode: one HTTP request per input whose response body is the run.\n * Stop interrupts the stream, which aborts the request; the server sees the\n * client go away and interrupts its run.\n *\n * Any other source (RPC streams, server functions) is a transport too:\n * write `{ start: (input, state) => stream }` directly.\n */\nexport const direct = <I, S, EB = never, RB = never>(options: {\n  readonly request: (\n    input: I,\n    state: S,\n  ) => Effect.Effect<HttpClientRequest.HttpClientRequest, EB, RB>\n  readonly format?: \"sse\" | \"ndjson\"\n}): Transport<I, S, Client.ClientError | EB, HttpClient.HttpClient | RB> => ({\n  start: (input, state) =>\n    Stream.unwrap(\n      options\n        .request(input, state)\n        .pipe(\n          Effect.map(\n            (request): Stream.Stream<Envelope, Client.ClientError, HttpClient.HttpClient> =>\n              options.format === \"ndjson\" ? Client.ndjson(request) : Client.sse(request),\n          ),\n        ),\n    ),\n})\n\n/**\n * Run the agent in the same process (browser agent, tests, Storybook). The\n * run's events are sequenced under `streamId`.\n */\nexport const local = <I, S, E, R>(\n  run: (input: I, state: S) => Stream.Stream<RunEvent, E, R>,\n  options?: { readonly streamId?: StreamId },\n): Transport<I, S, E, R> => ({\n  start: (input, state) =>\n    run(input, state).pipe(Run.sequence(options?.streamId ?? StreamId.make(\"local\"))),\n})\n\n/** A per-run transport that can re-attach to a run (durable). `start` is `submit`, then `resume` from 0. */\nexport type Durable<I, S, E, R> = Transport<I, S, E, R> & {\n  /** Start a run on the server and return its stream id. */\n  readonly submit: (input: I, state: S) => Effect.Effect<StreamId, E, R>\n  readonly resume: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n}\n\nconst durableOf = <I, S, E, R>(parts: Omit<Durable<I, S, E, R>, \"start\">): Durable<I, S, E, R> => ({\n  ...parts,\n  start: (input, state) =>\n    Stream.unwrap(Effect.map(parts.submit(input, state), (streamId) => parts.resume(streamId, 0))),\n})\n\n/**\n * Durable runs: `submit` starts one on the server and returns its stream id;\n * `events` reads it from `after`. The run lives on the server, so a reload\n * re-attaches with `resume`. A stream that ends before the run's terminal\n * fails with `Client.Disconnected`; pipe through `reconnect` to resume it.\n */\nexport const durable = <I, S, ES, RS, EE, RE, EX = never, RX = never>(options: {\n  readonly submit: (input: I, state: S) => Effect.Effect<StreamId, ES, RS>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, EE, RE>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, EX, RX>\n}): Durable<I, S, ES | EE | EX | Client.Disconnected, RS | RE | RX> =>\n  durableOf<I, S, ES | EE | EX | Client.Disconnected, RS | RE | RX>({\n    submit: options.submit,\n    resume: (streamId, after) =>\n      Client.resumable((from) => options.events(streamId, from), { from: after }),\n    ...(options.stop !== undefined ? { stop: options.stop } : {}),\n  })\n\n/**\n * A durable session (a chat): one stream carries every run, and the server\n * owns its history. `send` without a stream id starts a new session and\n * returns its id (the app's own chat id, branded); with one, it adds a run to\n * that session. `events` follows the whole session from `after`. The run\n * arrives on that stream, not as a response to `send`.\n */\nexport type Session<I, S, E, R> = {\n  readonly send: (\n    streamId: Option.Option<StreamId>,\n    input: I,\n    state: S,\n  ) => Effect.Effect<StreamId, E, R>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, E, R>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, E, R>\n}\n\n/**\n * A session stream never ends on its own, so one that completes fails with\n * `Client.Disconnected`; pipe through `reconnect` to resume it.\n */\nexport const session = <I, S, ES, RS, EE, RE, EX = never, RX = never>(options: {\n  readonly send: (\n    streamId: Option.Option<StreamId>,\n    input: I,\n    state: S,\n  ) => Effect.Effect<StreamId, ES, RS>\n  readonly events: (streamId: StreamId, after: number) => Stream.Stream<Envelope, EE, RE>\n  readonly stop?: (streamId: StreamId) => Effect.Effect<void, EX, RX>\n}): Session<I, S, ES | EE | EX | Client.Disconnected, RS | RE | RX> => ({\n  ...options,\n  events: (streamId, after) =>\n    Client.resumable((from) => options.events(streamId, from), { from: after, until: \"never\" }),\n})\n\n// ---------------------------------------------------------------------------\n// Over HTTP: `durable` and `session` with SSE events\n// ---------------------------------------------------------------------------\n\n/** What the HTTP helpers can fail with. */\nexport type HttpError = Client.ClientError | Client.Disconnected\n\ntype HttpOptions = {\n  /** The SSE request for a stream from `after`. */\n  readonly events: (streamId: StreamId, after: number) => HttpClientRequest.HttpClientRequest\n  /** The request that stops a stream's active run. */\n  readonly stop?: (streamId: StreamId) => HttpClientRequest.HttpClientRequest\n}\n\nconst stopOver = (stop: HttpOptions[\"stop\"]) =>\n  stop === undefined\n    ? {}\n    : { stop: (streamId: StreamId) => Client.execute(stop(streamId)).pipe(Effect.asVoid) }\n\n/**\n * `durable` over HTTP. `submit` starts a run and returns its stream id (the\n * app decodes its own response, e.g. with `HttpClientResponse.schemaJson`);\n * `events` is read as SSE. Pipe through `reconnect` to survive drops.\n */\nexport const durableHttp = <I, S, ES = never, RS = never>(\n  options: HttpOptions & {\n    readonly submit: (input: I, state: S) => Effect.Effect<StreamId, ES, RS>\n  },\n): Durable<I, S, HttpError | ES, HttpClient.HttpClient | RS> =>\n  durable({\n    submit: options.submit,\n    events: (streamId, after) => Client.sse(options.events(streamId, after)),\n    ...stopOver(options.stop),\n  })\n\n/**\n * `session` over HTTP. `send` adds an input and returns the session's stream\n * id (without one, the server starts a session); `events` follows the whole\n * session as SSE. Pipe through `reconnect` to survive drops.\n */\nexport const sessionHttp = <I, S, ES = never, RS = never>(\n  options: HttpOptions & {\n    readonly send: (\n      streamId: Option.Option<StreamId>,\n      input: I,\n      state: S,\n    ) => Effect.Effect<StreamId, ES, RS>\n  },\n): Session<I, S, HttpError | ES, HttpClient.HttpClient | RS> =>\n  session({\n    send: options.send,\n    events: (streamId, after) => Client.sse(options.events(streamId, after)),\n    ...stopOver(options.stop),\n  })\n\n// ---------------------------------------------------------------------------\n// Reconnect: resume a dropped event stream from the last seq\n// ---------------------------------------------------------------------------\n\nexport type ReconnectOptions<E> = {\n  /**\n   * When to retry. Default: exponential from 500 ms, capped at 10 s, jittered.\n   * Cap your own exponential: the schedule resets only when a frame arrives,\n   * so an idle session's backoff otherwise grows without bound.\n   */\n  readonly schedule?: Schedule.Schedule<unknown, E | Client.Disconnected>\n  /** More errors to treat as transient, on top of drops, timeouts, 408 / 429 / 5xx and SSE `retry:`. */\n  readonly while?: Predicate.Predicate<E>\n  /** Max attempts in a row; the count resets once a frame arrives. Default: unlimited. */\n  readonly times?: number\n}\n\nconst defaultSchedule = Schedule.min([\n  Schedule.exponential(\"500 millis\"),\n  Schedule.spaced(\"10 seconds\"),\n]).pipe(Schedule.jittered)\n\nconst isDisconnected = (error: unknown): error is Client.Disconnected =>\n  error instanceof Client.Disconnected\n\nconst isTransient = (error: unknown) => Sse.Retry.is(error) || HttpClient.isTransientError(error)\n\nconst parseSeconds = Schema.decodeUnknownOption(Schema.FiniteFromString)\n\n// `Retry-After` is either seconds or an HTTP date.\nconst retryAfter = (value: string, now: number): Option.Option<Duration.Duration> =>\n  parseSeconds(value).pipe(\n    Option.map((seconds) => Duration.seconds(Math.max(0, seconds))),\n    Option.orElse(() =>\n      DateTime.make(value).pipe(\n        Option.map((at) => Duration.millis(Math.max(0, DateTime.toEpochMillis(at) - now))),\n      ),\n    ),\n  )\n\n// The wait the server asked for: an SSE `retry:` line or a `Retry-After` header.\nconst serverDelay = (error: unknown, now: number): Option.Option<Duration.Duration> => {\n  if (Sse.Retry.is(error)) return Option.some(error.duration)\n  if (!HttpClientError.isHttpClientError(error)) return Option.none()\n  return Option.fromNullishOr(error.response?.headers[\"retry-after\"]).pipe(\n    Option.flatMap((value) => retryAfter(value, now)),\n  )\n}\n\nconst policy = <E>(\n  options: ReconnectOptions<E> | undefined,\n): Schedule.Schedule<unknown, E | Client.Disconnected> => {\n  const base = options?.schedule ?? defaultSchedule\n  const extra = options?.while\n  return (options?.times === undefined ? base : Schedule.upTo(base, { times: options.times })).pipe(\n    Schedule.while(\n      ({ input }) =>\n        isDisconnected(input) || isTransient(input) || (extra !== undefined && extra(input)),\n    ),\n    Schedule.modifyDelay(({ input, duration, now }) =>\n      Effect.succeed(\n        Option.match(serverDelay(input, now), {\n          onNone: () => duration,\n          onSome: (asked) => Duration.max(duration, asked),\n        }),\n      ),\n    ),\n  )\n}\n\n/** A transport `reconnect` applies to: one with a position to resume from. */\nexport type Resumable = Session<any, any, any, any> | Durable<any, any, any, any>\n\n/** What a transport can fail with. */\nexport type ErrorOf<T extends Resumable> =\n  T extends Session<any, any, infer E, any>\n    ? E\n    : T extends Durable<any, any, infer E, any>\n      ? E\n      : never\n\ntype WithDisconnected<F> = F extends (...args: infer A) => Stream.Stream<infer X, infer E, infer R>\n  ? (...args: A) => Stream.Stream<X, E | Client.Disconnected, R>\n  : F\n\n/** `T` with `Client.Disconnected` added to its streams; `send` / `submit` keep their exact types. */\nexport type Reconnected<T extends Resumable> = { readonly [K in keyof T]: WithDisconnected<T[K]> }\n\nconst isSession = (self: Resumable): self is Session<any, any, any, any> => \"send\" in self\n\nconst isResumable = (u: unknown): u is Resumable =>\n  Predicate.hasProperty(u, \"send\") || Predicate.hasProperty(u, \"resume\")\n\n/**\n * Resume a dropped event stream from the last seq, as `HttpClient.retryTransient`\n * does for requests. Retries drops (`Client.Disconnected`), timeouts, transport\n * errors, 408 / 429 / 5xx and an SSE `retry:` line, waiting at least what the\n * server asks for (`Retry-After`, `retry:`); anything else (404, 401, a\n * malformed frame) ends the stream with that error. `while` adds the app's own\n * transient errors (e.g. a dropped WebSocket).\n *\n * A session is followed forever; a durable run until its terminal. A durable\n * `submit` is never retried, so an input is never sent twice. Not for `direct`\n * / `local`: there the run is the request, with no position to resume from.\n *\n *   const transport = Transport.reconnect(Transport.sessionHttp({ send, events, stop }))\n *   const ws = pipe(Transport.session({ send, events }), Transport.reconnect({ while: isDropped }))\n */\nexport const reconnect: {\n  <E>(options?: ReconnectOptions<E>): <T extends Resumable>(self: T) => Reconnected<T>\n  <T extends Resumable>(self: T, options?: ReconnectOptions<ErrorOf<T>>): Reconnected<T>\n} = Function.dual(\n  (args) => isResumable(args[0]),\n  (self: Resumable, options?: ReconnectOptions<unknown>): Resumable => {\n    const schedule = policy(options)\n    const resumed =\n      (events: Session<any, any, any, any>[\"events\"], until: \"terminal\" | \"never\") =>\n      (streamId: StreamId, after: number) =>\n        Client.resumable((from) => events(streamId, from), { from: after, until, schedule })\n    return isSession(self)\n      ? { ...self, events: resumed(self.events, \"never\") }\n      : durableOf({ ...self, resume: resumed(self.resume, \"terminal\") })\n  },\n)\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { t as RunEvent_d_exports } from "./RunEvent.mjs";
 import { s as Input_d_exports } from "./Input-Cz-Kxusm.mjs";
 import { u as RunView_d_exports } from "./RunView-nHfJwN8t.mjs";
 import { l as Thread_d_exports } from "./Thread-CAXsjhpX.mjs";
-import { n as Client_d_exports } from "./Client-C9UYN_VK.mjs";
+import { n as Client_d_exports } from "./Client-B2Eqo39q.mjs";
 import { t as Transport_d_exports } from "./Transport.mjs";
 import { t as UiContract_d_exports } from "./UiContract.mjs";
 import { t as Atoms_d_exports } from "./Atoms.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/ui",
-  "version": "0.19.0",
+  "version": "0.20.0-dev-20261110202152",
   "description": "Agentic UI primitives for @effect-uai/core: a resumable run-event protocol, projection, client folds and Effect atoms.",
   "keywords": [
     "agents",
@@ -89,11 +89,11 @@
     "@effect/vitest": "4.1.2",
     "effect": "4.1.2",
     "typescript": "^7.0.2",
-    "@effect-uai/core": "0.19.0"
+    "@effect-uai/core": "0.20.0-dev-20261110202152"
   },
   "peerDependencies": {
-    "@effect-uai/core": ">=0.17.0 <1",
-    "effect": ">=4.0.1 <5.0.0"
+    "@effect-uai/core": "0.20.0-dev-20261110202152",
+    "effect": ">=4.1.0 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/Atoms.test.ts

@@ -160,4 +160,34 @@ describe("Atoms.sessionThread", () => {
       expect(replayed.messages.map((m) => m.role)).toEqual(["assistant", "assistant"])
     }),
   )
+
+  it.effect("a hydrated thread starts as `initial` and opens from its last seq", () =>
+    Effect.gen(function* () {
+      const { chatId, transport } = yield* fakeSession
+      const first = Atoms.sessionThread({ runtime, transport })
+      const elsewhere = AtomRegistry.make()
+      elsewhere.set(first.submit, Input.submit("first"))
+      const hydrated = yield* settledCount(elsewhere, first.state, 2)
+      elsewhere.set(first.submit, Input.submit("second"))
+      yield* settledCount(elsewhere, first.state, 4)
+
+      const opened = yield* Ref.make<ReadonlyArray<number>>([])
+      const spied = Transport.session({
+        send: transport.send,
+        events: (id, after) =>
+          Stream.unwrap(
+            Ref.update(opened, (a) => [...a, after]).pipe(Effect.as(transport.events(id, after))),
+          ),
+      })
+      const chat = Atoms.sessionThread({ runtime, transport: spied, initial: hydrated })
+      const registry = AtomRegistry.make()
+      expect(registry.get(chat.state)).toEqual(hydrated)
+      expect(registry.get(chat.streamId)).toBeNull()
+
+      registry.set(chat.open, { streamId: chatId, after: hydrated.lastSeq })
+      const thread = yield* settledCount(registry, chat.state, 3)
+      expect(yield* Ref.get(opened)).toEqual([hydrated.lastSeq])
+      expect(thread.messages.map((m) => m.role)).toEqual(["user", "assistant", "assistant"])
+    }),
+  )
 })

package/src/Atoms.ts

@@ -234,6 +234,9 @@ type BaseSessionOptions<I, S, E, R, ER, D> = {
 export type SessionOptions<I, S, E, R, ER, D = Envelope> = BaseSessionOptions<I, S, E, R, ER, D> &
   WithDecode<D>
 
+/** What `open` follows: a session from its start, or from `after` (e.g. a hydrated thread's `lastSeq`). */
+export type Open = StreamId | { readonly streamId: StreamId; readonly after: number }
+
 const buildSession = <I, S, E, R, ER, D>(
   options: BaseSessionOptions<I, S, E, R, ER, D> & { readonly decode: Decode<D> },
 ) => {
@@ -249,11 +252,13 @@ const buildSession = <I, S, E, R, ER, D>(
 
   // Non-concurrent: opening another session stops following the previous one.
   const open = options.runtime
-    .fn<StreamId>()((id) =>
-      Atom.set(streamId, id).pipe(
+    .fn<Open>()((target) => {
+      const { streamId: id, after } =
+        typeof target === "string" ? { streamId: target, after: 0 } : target
+      return Atom.set(streamId, id).pipe(
         Effect.andThen(
           options.transport
-            .events(id, 0)
+            .events(id, after)
             .pipe(
               Stream.runForEach((envelope) =>
                 options
@@ -267,8 +272,8 @@ const buildSession = <I, S, E, R, ER, D>(
             ),
         ),
         Effect.onExit(settle),
-      ),
-    )
+      )
+    })
     .pipe(Atom.keepAlive)
 
   const submit = options.runtime
@@ -305,7 +310,9 @@ type BuiltSession<I, S, E, R, ER> = ReturnType<typeof buildSession<I, S, E, R, E
 
 /**
  * State over a session transport. `open(streamId)` follows a session's
- * stream from its start (e.g. a chat id kept across reloads). `submit` sends
+ * stream from its start (e.g. a chat id kept across reloads);
+ * `open({ streamId, after })` from a position, for state hydrated elsewhere
+ * (pass it as `initial`; `initial` never opens anything). `submit` sends
  * an input; without an open session the server starts one, which is then
  * opened. Runs arrive on the followed stream, not as responses to `submit`.
  */
@@ -322,6 +329,8 @@ type SessionThreadOptions<I, E, R, ER, P extends Payloads> = {
   readonly runtime: Runtime<R, ER>
   readonly transport: Transport.Session<Input.Sent<I>, Thread.Thread<P>, E, R>
   readonly isBusy?: (thread: Thread.Thread<P>) => boolean
+  /** A thread hydrated elsewhere (e.g. from a database); follow it with `open({ streamId, after: lastSeq })`. */
+  readonly initial?: Thread.Thread<P>
 }
 
 /**
@@ -345,7 +354,7 @@ export function sessionThread<I extends Input.Input, E, R, ER>(
   return buildSession({
     runtime: options.runtime,
     transport: options.transport,
-    initial: fold.initial,
+    initial: options.initial ?? fold.initial,
     step: fold.step,
     decode: options.contract?.decode ?? identity,
     ...(options.isBusy !== undefined ? { isBusy: options.isBusy } : {}),

package/src/Client.ts

@@ -42,26 +42,27 @@ export const ndjson = (request: HttpClientRequest.HttpClientRequest) =>
  * Keep events flowing across dropped connections: `connect(after)` is
  * re-invoked with the last seen `seq` on failure, per `schedule`; duplicates
  * are dropped. A connection that ends cleanly before the end counts as a
- * failure (`Disconnected`), so it is retried too.
+ * failure (`Disconnected`), so it is retried too. Without `schedule` nothing
+ * is retried: an early end just fails with `Disconnected`.
  *
  * `until: "terminal"` (default) follows one run and completes after its
  * terminal. `until: "never"` follows a session stream that carries many runs
  * (a durable chat) and never completes on its own.
  */
-export const resumable = <E, R, X>(
+export const resumable = <E, R, X = never>(
   connect: (after: number) => Stream.Stream<Envelope, E, R>,
-  options: {
+  options?: {
     readonly from?: number
     readonly until?: "terminal" | "never"
-    readonly schedule: Schedule.Schedule<X, E | Disconnected>
+    readonly schedule?: Schedule.Schedule<X, E | Disconnected>
   },
 ): Stream.Stream<Envelope, E | Disconnected, R> =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const untilTerminal = options.until !== "never"
+      const untilTerminal = options?.until !== "never"
       const ends = (envelope: Envelope) => untilTerminal && isTerminal(envelope.event)
       // The last seen seq, and whether the run's terminal arrived.
-      const position = yield* Ref.make({ seq: options.from ?? 0, done: false })
+      const position = yield* Ref.make({ seq: options?.from ?? 0, done: false })
       const attempt = Stream.unwrap(
         Ref.get(position).pipe(
           Effect.map(({ seq: after }) =>
@@ -87,6 +88,7 @@ export const resumable = <E, R, X>(
           ),
         ),
       )
-      return attempt.pipe(Stream.retry(options.schedule))
+      const schedule = options?.schedule
+      return schedule === undefined ? attempt : attempt.pipe(Stream.retry(schedule))
     }),
   )

package/src/SseEncoding.test.ts

@@ -1,5 +1,6 @@
 import { describe, it } from "@effect/vitest"
-import { Effect, Option, Stream } from "effect"
+import { Effect, Fiber, Option, Schedule, Stream } from "effect"
+import { TestClock } from "effect/testing"
 import { expect } from "vitest"
 import { type Envelope, RunId, StreamId } from "./RunEvent.js"
 import * as SseEncoding from "./SseEncoding.js"
@@ -43,4 +44,22 @@ describe("SseEncoding", () => {
   ])("lastEventId reads $label", ({ headers, seq }) => {
     expect(SseEncoding.lastEventId(headers)).toEqual(seq)
   })
+
+  it.effect("heartbeat interleaves comments, ends with the events, and decodes away", () =>
+    Effect.gen(function* () {
+      const fiber = yield* Stream.fromIterable(envelopes).pipe(
+        Stream.schedule(Schedule.spaced("1 second")),
+        SseEncoding.encode,
+        SseEncoding.heartbeat("400 millis"),
+        Stream.runCollect,
+        Effect.forkChild,
+      )
+      yield* TestClock.adjust("3 seconds")
+      const bytes = yield* Fiber.join(fiber)
+      const text = new TextDecoder().decode(Buffer.concat(bytes))
+      expect(text.split(": heartbeat\n\n").length).toBeGreaterThan(2)
+      const decoded = yield* Stream.fromIterable(bytes).pipe(SseEncoding.decode, Stream.runCollect)
+      expect(decoded).toEqual(envelopes)
+    }),
+  )
 })

package/src/SseEncoding.ts

@@ -6,7 +6,7 @@
  * encoder and parser.
  * For NDJSON use `effect/encoding/Ndjson` with `RunEvent.EnvelopeJson`.
  */
-import { Effect, Option, Schema, SchemaTransformation, Stream } from "effect"
+import { type Duration, Effect, Option, Schema, SchemaTransformation, Stream } from "effect"
 import { Sse } from "effect/encoding"
 import { Envelope, EnvelopeJson } from "./RunEvent.js"
 
@@ -50,6 +50,23 @@ export const decode = <E, R>(
 ): Stream.Stream<Envelope, E | Sse.Retry | Sse.SseError | Schema.SchemaError, R> =>
   self.pipe(Stream.decodeText, Stream.pipeThroughChannelOrFail(Sse.decodeSchema(EnvelopeEvent)))
 
+const comment = new TextEncoder().encode(": heartbeat\n\n")
+
+/**
+ * Interleave an SSE comment every `interval`, so proxies don't close a stream
+ * that sits idle (a session between answers). Pipe after `encode`: each frame
+ * is one chunk, so a comment always lands between whole frames. Parsers
+ * (`EventSource`, `decode`) ignore comments. Ends with the event stream.
+ */
+export const heartbeat =
+  (interval: Duration.Input) =>
+  <E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<Uint8Array, E, R> =>
+    self.pipe(
+      Stream.merge(Stream.tick(interval).pipe(Stream.map(() => comment)), {
+        haltStrategy: "left",
+      }),
+    )
+
 /**
  * Headers an SSE response needs. Behind nginx-style proxies, also send
  * `x-accel-buffering: no` so frames are not buffered.

package/src/Transport.test.ts

@@ -0,0 +1,199 @@
+import { describe, it } from "@effect/vitest"
+import { Data, Duration, Effect, Fiber, Function, Ref, Schedule, Stream } from "effect"
+import { Sse } from "effect/encoding"
+import { HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http"
+import { TestClock } from "effect/testing"
+import { expect, expectTypeOf } from "vitest"
+import * as Client from "./Client.js"
+import { type Envelope, RunId, type RunEvent, StreamId } from "./RunEvent.js"
+import * as Transport from "./Transport.js"
+
+const r1 = RunId.make("r1")
+const chatId = StreamId.make("chat")
+
+class SocketDropped extends Data.TaggedError("SocketDropped")<{}> {}
+
+type Failure = HttpClientError.HttpClientError | Sse.Retry | SocketDropped
+
+const frames: ReadonlyArray<Envelope> = (
+  [
+    { type: "run-started", runId: r1, inputs: [], protocol: 2 },
+    { type: "text-delta", text: "a" },
+    { type: "text-delta", text: "b" },
+    { type: "text-delta", text: "c" },
+    { type: "run-completed" },
+  ] satisfies ReadonlyArray<RunEvent>
+).map((event, i) => ({ streamId: chatId, seq: i + 1, runId: r1, event }))
+
+const status = (code: number, headers: Record<string, string> = {}) => {
+  const request = HttpClientRequest.get("/chats/chat/events")
+  const response = HttpClientResponse.fromWeb(
+    request,
+    new Response(null, { status: code, headers }),
+  )
+  return new HttpClientError.HttpClientError({
+    reason: new HttpClientError.StatusCodeError({ request, response }),
+  })
+}
+
+type Attempt = { readonly upTo: number; readonly error?: Failure }
+
+// A server that replays from `after`; how each connection ends is scripted.
+// Past the script, it sends the rest and then stays open (a live session).
+const server = (attempts: ReadonlyArray<Attempt>) =>
+  Effect.gen(function* () {
+    const calls = yield* Ref.make<ReadonlyArray<number>>([])
+    const submits = yield* Ref.make(0)
+    const events = (_: StreamId, after: number): Stream.Stream<Envelope, Failure> =>
+      Stream.unwrap(
+        Ref.modify(calls, (cs) => [cs.length, [...cs, after]]).pipe(
+          Effect.map((n) => {
+            const attempt = attempts[n]
+            if (attempt === undefined) {
+              return Stream.fromIterable(frames.slice(after)).pipe(Stream.concat(Stream.never))
+            }
+            const sent = Stream.fromIterable(frames.slice(after, attempt.upTo))
+            const error = attempt.error
+            return error === undefined ? sent : sent.pipe(Stream.concat(Stream.fail(error)))
+          }),
+        ),
+      )
+    const send = () => Effect.succeed(chatId)
+    const submit = () => Ref.update(submits, (n) => n + 1).pipe(Effect.as(chatId))
+    const session = Transport.session({ send, events })
+    const durable = Transport.durable({ submit, events })
+    return { calls, submits, session, durable }
+  })
+
+const fast = Schedule.forever
+
+const seqs = (envelopes: ReadonlyArray<Envelope>) => envelopes.map((e) => e.seq)
+
+const follow = (session: Transport.Session<unknown, unknown, unknown, never>, take = 5) =>
+  session.events(chatId, 0).pipe(Stream.take(take), Stream.runCollect)
+
+const failure = (session: Transport.Session<unknown, unknown, unknown, never>) =>
+  session.events(chatId, 0).pipe(Stream.runDrain, Effect.flip)
+
+describe("Transport.session / durable", () => {
+  it.effect("a session stream that completes fails with Disconnected at the last seq", () =>
+    Effect.gen(function* () {
+      const { session } = yield* server([{ upTo: 2 }])
+      expect(yield* failure(session)).toEqual(new Client.Disconnected({ lastSeq: 2 }))
+    }),
+  )
+
+  it.effect("a durable run that completes before its terminal fails with Disconnected", () =>
+    Effect.gen(function* () {
+      const { durable } = yield* server([{ upTo: 3 }])
+      const error = yield* durable.start(undefined, undefined).pipe(Stream.runDrain, Effect.flip)
+      expect(error).toEqual(new Client.Disconnected({ lastSeq: 3 }))
+    }),
+  )
+})
+
+describe("Transport.reconnect", () => {
+  it.effect.each([
+    { label: "a clean close", error: undefined },
+    { label: "a 503", error: status(503) },
+    {
+      label: "an SSE retry: line",
+      error: new Sse.Retry({ duration: Duration.zero, lastEventId: "2" }),
+    },
+  ])("re-opens a session from the last seq after $label", ({ error }) =>
+    Effect.gen(function* () {
+      const { calls, session } = yield* server([
+        error === undefined ? { upTo: 2 } : { upTo: 2, error },
+      ])
+      const received = yield* follow(Transport.reconnect(session, { schedule: fast }))
+      expect(seqs(received)).toEqual([1, 2, 3, 4, 5])
+      expect(yield* Ref.get(calls)).toEqual([0, 2])
+    }),
+  )
+
+  it.effect.each([{ code: 404 }, { code: 401 }])(
+    "ends with a $code, without retrying",
+    ({ code }) =>
+      Effect.gen(function* () {
+        const { calls, session } = yield* server([{ upTo: 1, error: status(code) }])
+        const error = yield* failure(Transport.reconnect(session, { schedule: fast }))
+        expect(error).toEqual(status(code))
+        expect(yield* Ref.get(calls)).toEqual([0])
+      }),
+  )
+
+  it.effect("`while` adds the app's own transient errors, typed by the transport", () =>
+    Effect.gen(function* () {
+      const dropped = { upTo: 2, error: new SocketDropped() }
+      const plain = yield* server([dropped])
+      expect(yield* failure(Transport.reconnect(plain.session, { schedule: fast }))).toEqual(
+        new SocketDropped(),
+      )
+
+      const extended = yield* server([dropped])
+      const reconnected = Transport.reconnect(extended.session, {
+        schedule: fast,
+        while: (error) => {
+          expectTypeOf(error).toEqualTypeOf<Failure | Client.Disconnected>()
+          return error instanceof SocketDropped
+        },
+      })
+      expect(seqs(yield* follow(reconnected))).toEqual([1, 2, 3, 4, 5])
+    }),
+  )
+
+  it.effect("pipes, and keeps the transport's kind and errors", () =>
+    Effect.gen(function* () {
+      const { session, durable } = yield* server([{ upTo: 2, error: status(503) }])
+      const piped = Function.pipe(session, Transport.reconnect({ schedule: fast }))
+      expectTypeOf(piped).toExtend<
+        Transport.Session<unknown, unknown, Failure | Client.Disconnected, never>
+      >()
+      expectTypeOf(Function.pipe(durable, Transport.reconnect())).toExtend<
+        Transport.Durable<unknown, unknown, Failure | Client.Disconnected, never>
+      >()
+      expect(seqs(yield* follow(piped))).toEqual([1, 2, 3, 4, 5])
+    }),
+  )
+
+  it.effect("`times` caps the attempts in a row", () =>
+    Effect.gen(function* () {
+      const { calls, session } = yield* server(
+        Array.from({ length: 5 }, () => ({ upTo: 0, error: status(503) })),
+      )
+      const error = yield* failure(Transport.reconnect(session, { schedule: fast, times: 2 }))
+      expect(error).toEqual(status(503))
+      expect((yield* Ref.get(calls)).length).toBe(3)
+    }),
+  )
+
+  it.effect("waits at least the server's Retry-After", () =>
+    Effect.gen(function* () {
+      const { calls, session } = yield* server([
+        { upTo: 2, error: status(429, { "retry-after": "5" }) },
+      ])
+      const fiber = yield* follow(Transport.reconnect(session, { schedule: fast })).pipe(
+        Effect.forkChild,
+      )
+      yield* TestClock.adjust("4 seconds")
+      expect(yield* Ref.get(calls)).toEqual([0])
+      yield* TestClock.adjust("1 second")
+      expect(seqs(yield* Fiber.join(fiber))).toEqual([1, 2, 3, 4, 5])
+      expect(yield* Ref.get(calls)).toEqual([0, 2])
+    }),
+  )
+
+  it.effect.each([
+    { label: "after the first frames", upTo: 2, resumedFrom: 2 },
+    { label: "before the first frame", upTo: 0, resumedFrom: 0 },
+  ])("durable start submits once and resumes a drop $label", ({ upTo, resumedFrom }) =>
+    Effect.gen(function* () {
+      const { calls, submits, durable } = yield* server([{ upTo, error: status(502) }])
+      const reconnected = Transport.reconnect(durable, { schedule: fast })
+      const received = yield* reconnected.start(undefined, undefined).pipe(Stream.runCollect)
+      expect(seqs(received)).toEqual([1, 2, 3, 4, 5])
+      expect(yield* Ref.get(submits)).toBe(1)
+      expect(yield* Ref.get(calls)).toEqual([0, resumedFrom])
+    }),
+  )
+})