@effect-uai/core 0.15.0 → 0.16.0

package/dist/streaming/WebSocketSession.test.mjs

@@ -0,0 +1,51 @@
+import { describe } from "../domain/AiError.mjs";
+import { toAiError } from "./WebSocketSession.mjs";
+import { o as describe$1 } from "../utils-CiH_DjFW.mjs";
+import { n as globalExpect } from "../test.DNmyFkvJ-YPzDR0Co.mjs";
+import { t as it } from "../dist-nohcnkD6.mjs";
+import * as Socket from "effect/unstable/socket/Socket";
+//#region src/streaming/WebSocketSession.test.ts
+const KEY = "AIzaSyEXAMPLEKEY";
+const URL = `wss://generativelanguage.googleapis.com/ws/BidiGenerateContent?key=${KEY}`;
+/**
+* What Bun hands the `error` listener when the upgrade is rejected: the whole
+* socket URL, in prose, on a prototype getter. Node and Deno say less, but the
+* adapter cannot know which runtime it is on.
+*/
+var BunErrorEvent = class {
+	get message() {
+		return `WebSocket connection to '${URL}' failed: Connection ended`;
+	}
+};
+/** Deno names the status but not the URL, also on a prototype getter. */
+var DenoErrorEvent = class {
+	detail;
+	constructor(detail) {
+		this.detail = detail;
+	}
+	get message() {
+		return `NetworkError: failed to connect to WebSocket: ${this.detail}`;
+	}
+};
+const openFailure = (cause) => new Socket.SocketError({ reason: new Socket.SocketOpenError({
+	kind: "Unknown",
+	cause
+}) });
+describe$1("WebSocketSession errors", () => {
+	it("keeps the key out of the error a rejected upgrade produces", () => {
+		const error = toAiError("google")(openFailure(new BunErrorEvent()));
+		globalExpect(JSON.stringify(error)).not.toContain(KEY);
+		globalExpect(describe(error)).not.toContain(KEY);
+		globalExpect(JSON.stringify(error)).toContain("generativelanguage.googleapis.com");
+	});
+	it("reads the rejected status out of the prose, wherever the runtime put it", () => {
+		const forbidden = toAiError("google")(openFailure(new DenoErrorEvent("Invalid status code: 403")));
+		const ended = toAiError("google")(openFailure(new BunErrorEvent()));
+		globalExpect(forbidden._tag).toBe("AuthFailed");
+		globalExpect(ended._tag).toBe("Unavailable");
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=WebSocketSession.test.mjs.map

package/dist/streaming/WebSocketSession.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketSession.test.mjs","names":["describe","AiError.describe"],"sources":["../../src/streaming/WebSocketSession.test.ts"],"sourcesContent":["import { describe, it } from \"@effect/vitest\"\nimport * as Socket from \"effect/unstable/socket/Socket\"\nimport { expect } from \"vitest\"\nimport * as AiError from \"../domain/AiError.js\"\nimport { toAiError } from \"./WebSocketSession.js\"\n\nconst KEY = \"AIzaSyEXAMPLEKEY\"\nconst URL = `wss://generativelanguage.googleapis.com/ws/BidiGenerateContent?key=${KEY}`\n\n/**\n * What Bun hands the `error` listener when the upgrade is rejected: the whole\n * socket URL, in prose, on a prototype getter. Node and Deno say less, but the\n * adapter cannot know which runtime it is on.\n */\nclass BunErrorEvent {\n  get message(): string {\n    return `WebSocket connection to '${URL}' failed: Connection ended`\n  }\n}\n\n/** Deno names the status but not the URL, also on a prototype getter. */\nclass DenoErrorEvent {\n  constructor(private readonly detail: string) {}\n  get message(): string {\n    return `NetworkError: failed to connect to WebSocket: ${this.detail}`\n  }\n}\n\nconst openFailure = (cause: unknown) =>\n  new Socket.SocketError({ reason: new Socket.SocketOpenError({ kind: \"Unknown\", cause }) })\n\ndescribe(\"WebSocketSession errors\", () => {\n  it(\"keeps the key out of the error a rejected upgrade produces\", () => {\n    const error = toAiError(\"google\")(openFailure(new BunErrorEvent()))\n\n    expect(JSON.stringify(error)).not.toContain(KEY)\n    expect(AiError.describe(error)).not.toContain(KEY)\n    // The host is still there: an error that says nothing is its own problem.\n    expect(JSON.stringify(error)).toContain(\"generativelanguage.googleapis.com\")\n  })\n\n  it(\"reads the rejected status out of the prose, wherever the runtime put it\", () => {\n    // Deno's wording. The status is the only hint a rejected upgrade gives.\n    const forbidden = toAiError(\"google\")(\n      openFailure(new DenoErrorEvent(\"Invalid status code: 403\")),\n    )\n    const ended = toAiError(\"google\")(openFailure(new BunErrorEvent()))\n\n    expect(forbidden._tag).toBe(\"AuthFailed\")\n    expect(ended._tag).toBe(\"Unavailable\")\n  })\n})\n"],"mappings":";;;;;;;AAMA,MAAM,MAAM;AACZ,MAAM,MAAM,sEAAsE;;;;;;AAOlF,IAAM,gBAAN,MAAoB;CAClB,IAAI,UAAkB;EACpB,OAAO,4BAA4B,IAAI;CACzC;AACF;;AAGA,IAAM,iBAAN,MAAqB;CACU;CAA7B,YAAY,QAAiC;EAAhB,KAAA,SAAA;CAAiB;CAC9C,IAAI,UAAkB;EACpB,OAAO,iDAAiD,KAAK;CAC/D;AACF;AAEA,MAAM,eAAe,UACnB,IAAI,OAAO,YAAY,EAAE,QAAQ,IAAI,OAAO,gBAAgB;CAAE,MAAM;CAAW;AAAM,CAAC,EAAE,CAAC;AAE3FA,WAAS,iCAAiC;CACxC,GAAG,oEAAoE;EACrE,MAAM,QAAQ,UAAU,QAAQ,CAAC,CAAC,YAAY,IAAI,cAAc,CAAC,CAAC;EAElE,aAAO,KAAK,UAAU,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,GAAG;EAC/C,aAAOC,SAAiB,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,GAAG;EAEjD,aAAO,KAAK,UAAU,KAAK,CAAC,CAAC,CAAC,UAAU,mCAAmC;CAC7E,CAAC;CAED,GAAG,iFAAiF;EAElF,MAAM,YAAY,UAAU,QAAQ,CAAC,CACnC,YAAY,IAAI,eAAe,0BAA0B,CAAC,CAC5D;EACA,MAAM,QAAQ,UAAU,QAAQ,CAAC,CAAC,YAAY,IAAI,cAAc,CAAC,CAAC;EAElE,aAAO,UAAU,IAAI,CAAC,CAAC,KAAK,YAAY;EACxC,aAAO,MAAM,IAAI,CAAC,CAAC,KAAK,aAAa;CACvC,CAAC;AACH,CAAC"}

package/dist/testing/FakeWebSocket.d.mts

@@ -0,0 +1,25 @@
+import { Effect, Layer, Scope } from "effect";
+import * as Socket from "effect/unstable/socket/Socket";
+//#region src/testing/FakeWebSocket.d.ts
+type FakeWebSocketServer = {
+  /** Every frame the client has sent, JSON-parsed, oldest first. */
+  readonly sent: Effect.Effect<ReadonlyArray<unknown>>;
+  /** Deliver one frame to the client. */
+  readonly push: (frame: unknown) => Effect.Effect<void>;
+  /** Close the socket. 1000, 1001 and 1005 are the clean codes. */
+  readonly close: (code?: number) => Effect.Effect<void>;
+  /** Hand this to an adapter that takes a socket constructor directly. */
+  readonly connect: Socket.WebSocketConstructor["Service"];
+  /** Provide this in place of the real constructor. */
+  readonly layer: Layer.Layer<Socket.WebSocketConstructor>;
+};
+type FakeWebSocketOptions = {
+  /** Pushed once the client subscribes, for a protocol whose server speaks first. */
+  readonly greeting?: ReadonlyArray<unknown>;
+  /** How the server answers each client frame. */
+  readonly reply?: (frame: unknown) => Effect.Effect<ReadonlyArray<unknown>>;
+};
+declare const make: (options?: FakeWebSocketOptions) => Effect.Effect<FakeWebSocketServer, never, Scope.Scope>;
+//#endregion
+export { FakeWebSocketOptions, FakeWebSocketServer, make };
+//# sourceMappingURL=FakeWebSocket.d.mts.map

package/dist/testing/FakeWebSocket.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeWebSocket.d.mts","names":[],"sources":["../../src/testing/FakeWebSocket.ts"],"mappings":";;;KAeY;;WAED,MAAM,OAAO,OAAO;;WAEpB,OAAO,mBAAmB,OAAO;;WAEjC,QAAQ,kBAAkB,OAAO;;WAEjC,SAAS,OAAO;;WAEhB,OAAO,MAAM,MAAM,OAAO;;KAGzB;;WAED,WAAW;;WAEX,SAAS,mBAAmB,OAAO,OAAO;;cAWxC,OAAI,UACL,yBACT,OAAO,OAAO,4BAA4B,MAAM"}

package/dist/testing/FakeWebSocket.mjs

@@ -0,0 +1,79 @@
+import { Effect, Layer, Queue, Ref, Stream } from "effect";
+import * as Socket from "effect/unstable/socket/Socket";
+//#region src/testing/FakeWebSocket.ts
+/**
+* An in-memory WebSocket for testing socket adapters without a server.
+*
+* Provide `layer` in place of the real `Socket.WebSocketConstructor` and the
+* adapter runs end to end: its own connect, handshake, decode and teardown.
+* The test plays the other end with `reply`, `push`, `close` and `sent`.
+*
+* Client frames land on a queue, so the scripted server is a forked fiber and
+* `reply` is a real Effect. What stays imperative is the listener table the
+* shim registers, since `Socket.makeWebSocket` drives it with plain callbacks.
+* The shim is a plain object, so nothing here touches a platform global.
+*/
+const OPEN = 1;
+const CLOSED = 3;
+/** Run after the current call unwinds, so the client is never re-entered. */
+const soon = (run) => void Promise.resolve().then(run);
+const make = (options) => Effect.gen(function* () {
+	const inbound = yield* Queue.unbounded();
+	const sent = yield* Ref.make([]);
+	const wiring = {
+		listeners: {},
+		readyState: OPEN,
+		greeted: false
+	};
+	const emit = (type, event) => (wiring.listeners[type] ?? []).forEach((listener) => listener(event));
+	const deliverSync = (frames) => frames.forEach((f) => emit("message", { data: JSON.stringify(f) }));
+	const deliver = (frames) => Effect.sync(() => deliverSync(frames));
+	const shutdown = (code) => {
+		if (wiring.readyState === CLOSED) return;
+		wiring.readyState = CLOSED;
+		emit("close", {
+			code,
+			reason: ""
+		});
+	};
+	yield* Stream.fromQueue(inbound).pipe(Stream.runForEach((frame) => Effect.gen(function* () {
+		yield* Ref.update(sent, (frames) => [...frames, frame]);
+		const answer = yield* options?.reply?.(frame) ?? Effect.succeed([]);
+		yield* deliver(answer);
+	})), Effect.forkScoped);
+	const socket = {
+		get readyState() {
+			return wiring.readyState;
+		},
+		addEventListener: (type, fn) => {
+			wiring.listeners = {
+				...wiring.listeners,
+				[type]: [...wiring.listeners[type] ?? [], fn]
+			};
+			if (type === "message" && !wiring.greeted) {
+				wiring.greeted = true;
+				soon(() => deliverSync(options?.greeting ?? []));
+			}
+		},
+		removeEventListener: (type, fn) => {
+			wiring.listeners = {
+				...wiring.listeners,
+				[type]: (wiring.listeners[type] ?? []).filter((l) => l !== fn)
+			};
+		},
+		send: (data) => void Queue.offerUnsafe(inbound, JSON.parse(data)),
+		close: (code = 1e3) => shutdown(code)
+	};
+	const connect = () => socket;
+	return {
+		sent: Ref.get(sent),
+		push: (frame) => deliver([frame]),
+		close: (code = 1e3) => Effect.sync(() => shutdown(code)),
+		connect,
+		layer: Layer.succeed(Socket.WebSocketConstructor, connect)
+	};
+});
+//#endregion
+export { make };
+
+//# sourceMappingURL=FakeWebSocket.mjs.map

package/dist/testing/FakeWebSocket.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeWebSocket.mjs","names":[],"sources":["../../src/testing/FakeWebSocket.ts"],"sourcesContent":["/**\n * An in-memory WebSocket for testing socket adapters without a server.\n *\n * Provide `layer` in place of the real `Socket.WebSocketConstructor` and the\n * adapter runs end to end: its own connect, handshake, decode and teardown.\n * The test plays the other end with `reply`, `push`, `close` and `sent`.\n *\n * Client frames land on a queue, so the scripted server is a forked fiber and\n * `reply` is a real Effect. What stays imperative is the listener table the\n * shim registers, since `Socket.makeWebSocket` drives it with plain callbacks.\n * The shim is a plain object, so nothing here touches a platform global.\n */\nimport { Effect, Layer, Queue, Ref, type Scope, Stream } from \"effect\"\nimport * as Socket from \"effect/unstable/socket/Socket\"\n\nexport type FakeWebSocketServer = {\n  /** Every frame the client has sent, JSON-parsed, oldest first. */\n  readonly sent: Effect.Effect<ReadonlyArray<unknown>>\n  /** Deliver one frame to the client. */\n  readonly push: (frame: unknown) => Effect.Effect<void>\n  /** Close the socket. 1000, 1001 and 1005 are the clean codes. */\n  readonly close: (code?: number) => Effect.Effect<void>\n  /** Hand this to an adapter that takes a socket constructor directly. */\n  readonly connect: Socket.WebSocketConstructor[\"Service\"]\n  /** Provide this in place of the real constructor. */\n  readonly layer: Layer.Layer<Socket.WebSocketConstructor>\n}\n\nexport type FakeWebSocketOptions = {\n  /** Pushed once the client subscribes, for a protocol whose server speaks first. */\n  readonly greeting?: ReadonlyArray<unknown>\n  /** How the server answers each client frame. */\n  readonly reply?: (frame: unknown) => Effect.Effect<ReadonlyArray<unknown>>\n}\n\ntype Listener = (event: any) => void\n\nconst OPEN = 1\nconst CLOSED = 3\n\n/** Run after the current call unwinds, so the client is never re-entered. */\nconst soon = (run: () => void): void => void Promise.resolve().then(run)\n\nexport const make = (\n  options?: FakeWebSocketOptions,\n): Effect.Effect<FakeWebSocketServer, never, Scope.Scope> =>\n  Effect.gen(function* () {\n    const inbound = yield* Queue.unbounded<unknown>()\n    const sent = yield* Ref.make<ReadonlyArray<unknown>>([])\n\n    const wiring = {\n      listeners: {} as Record<string, ReadonlyArray<Listener>>,\n      readyState: OPEN,\n      greeted: false,\n    }\n\n    const emit = (type: string, event: unknown): void =>\n      (wiring.listeners[type] ?? []).forEach((listener) => listener(event))\n\n    const deliverSync = (frames: ReadonlyArray<unknown>): void =>\n      frames.forEach((f) => emit(\"message\", { data: JSON.stringify(f) }))\n\n    const deliver = (frames: ReadonlyArray<unknown>): Effect.Effect<void> =>\n      Effect.sync(() => deliverSync(frames))\n\n    const shutdown = (code: number): void => {\n      if (wiring.readyState === CLOSED) return\n      wiring.readyState = CLOSED\n      emit(\"close\", { code, reason: \"\" })\n    }\n\n    // The scripted server. Answers land on their own turn, like a real one.\n    yield* Stream.fromQueue(inbound).pipe(\n      Stream.runForEach((frame) =>\n        Effect.gen(function* () {\n          yield* Ref.update(sent, (frames) => [...frames, frame])\n          const answer = yield* options?.reply?.(frame) ?? Effect.succeed([])\n          yield* deliver(answer)\n        }),\n      ),\n      Effect.forkScoped,\n    )\n\n    const socket = {\n      get readyState() {\n        return wiring.readyState\n      },\n      addEventListener: (type: string, fn: Listener): void => {\n        wiring.listeners = {\n          ...wiring.listeners,\n          [type]: [...(wiring.listeners[type] ?? []), fn],\n        }\n        // The greeting waits for a subscriber before it lands.\n        if (type === \"message\" && !wiring.greeted) {\n          wiring.greeted = true\n          soon(() => deliverSync(options?.greeting ?? []))\n        }\n      },\n      removeEventListener: (type: string, fn: Listener): void => {\n        wiring.listeners = {\n          ...wiring.listeners,\n          [type]: (wiring.listeners[type] ?? []).filter((l) => l !== fn),\n        }\n      },\n      // Safe from a synchronous callback, and no runtime needed.\n      send: (data: string): void => void Queue.offerUnsafe(inbound, JSON.parse(data)),\n      close: (code = 1000): void => shutdown(code),\n    }\n\n    const connect: Socket.WebSocketConstructor[\"Service\"] = () =>\n      socket as unknown as globalThis.WebSocket\n\n    return {\n      sent: Ref.get(sent),\n      push: (frame) => deliver([frame]),\n      close: (code = 1000) => Effect.sync(() => shutdown(code)),\n      connect,\n      layer: Layer.succeed(Socket.WebSocketConstructor, connect),\n    }\n  })\n"],"mappings":";;;;;;;;;;;;;;;AAqCA,MAAM,OAAO;AACb,MAAM,SAAS;;AAGf,MAAM,QAAQ,QAA0B,KAAK,QAAQ,QAAQ,CAAC,CAAC,KAAK,GAAG;AAEvE,MAAa,QACX,YAEA,OAAO,IAAI,aAAa;CACtB,MAAM,UAAU,OAAO,MAAM,UAAmB;CAChD,MAAM,OAAO,OAAO,IAAI,KAA6B,CAAC,CAAC;CAEvD,MAAM,SAAS;EACb,WAAW,CAAC;EACZ,YAAY;EACZ,SAAS;CACX;CAEA,MAAM,QAAQ,MAAc,WACzB,OAAO,UAAU,SAAS,CAAC,EAAA,CAAG,SAAS,aAAa,SAAS,KAAK,CAAC;CAEtE,MAAM,eAAe,WACnB,OAAO,SAAS,MAAM,KAAK,WAAW,EAAE,MAAM,KAAK,UAAU,CAAC,EAAE,CAAC,CAAC;CAEpE,MAAM,WAAW,WACf,OAAO,WAAW,YAAY,MAAM,CAAC;CAEvC,MAAM,YAAY,SAAuB;EACvC,IAAI,OAAO,eAAe,QAAQ;EAClC,OAAO,aAAa;EACpB,KAAK,SAAS;GAAE;GAAM,QAAQ;EAAG,CAAC;CACpC;CAGA,OAAO,OAAO,UAAU,OAAO,CAAC,CAAC,KAC/B,OAAO,YAAY,UACjB,OAAO,IAAI,aAAa;EACtB,OAAO,IAAI,OAAO,OAAO,WAAW,CAAC,GAAG,QAAQ,KAAK,CAAC;EACtD,MAAM,SAAS,OAAO,SAAS,QAAQ,KAAK,KAAK,OAAO,QAAQ,CAAC,CAAC;EAClE,OAAO,QAAQ,MAAM;CACvB,CAAC,CACH,GACA,OAAO,UACT;CAEA,MAAM,SAAS;EACb,IAAI,aAAa;GACf,OAAO,OAAO;EAChB;EACA,mBAAmB,MAAc,OAAuB;GACtD,OAAO,YAAY;IACjB,GAAG,OAAO;KACT,OAAO,CAAC,GAAI,OAAO,UAAU,SAAS,CAAC,GAAI,EAAE;GAChD;GAEA,IAAI,SAAS,aAAa,CAAC,OAAO,SAAS;IACzC,OAAO,UAAU;IACjB,WAAW,YAAY,SAAS,YAAY,CAAC,CAAC,CAAC;GACjD;EACF;EACA,sBAAsB,MAAc,OAAuB;GACzD,OAAO,YAAY;IACjB,GAAG,OAAO;KACT,QAAQ,OAAO,UAAU,SAAS,CAAC,EAAA,CAAG,QAAQ,MAAM,MAAM,EAAE;GAC/D;EACF;EAEA,OAAO,SAAuB,KAAK,MAAM,YAAY,SAAS,KAAK,MAAM,IAAI,CAAC;EAC9E,QAAQ,OAAO,QAAe,SAAS,IAAI;CAC7C;CAEA,MAAM,gBACJ;CAEF,OAAO;EACL,MAAM,IAAI,IAAI,IAAI;EAClB,OAAO,UAAU,QAAQ,CAAC,KAAK,CAAC;EAChC,QAAQ,OAAO,QAAS,OAAO,WAAW,SAAS,IAAI,CAAC;EACxD;EACA,OAAO,MAAM,QAAQ,OAAO,sBAAsB,OAAO;CAC3D;AACF,CAAC"}

package/dist/testing/MockRealtimeSession.d.mts

@@ -0,0 +1,30 @@
+import { CommonSessionRequest, RealtimeEvent, RealtimeInput } from "../domain/Realtime.mjs";
+import { RealtimeSession, RealtimeVideoInput } from "../realtime/RealtimeSession.mjs";
+import { Effect, Layer } from "effect";
+//#region src/testing/MockRealtimeSession.d.ts
+type MockRealtimeSessionRecorder = {
+  readonly openCalls: ReadonlyArray<CommonSessionRequest>;
+  readonly sent: ReadonlyArray<RealtimeInput>;
+};
+type MockRealtimeSessionScript = {
+  /** Emitted as soon as the session opens. */
+  readonly initial?: ReadonlyArray<RealtimeEvent>;
+  /** The server's answer to each input. */
+  readonly onInput?: (input: RealtimeInput) => ReadonlyArray<RealtimeEvent>;
+};
+/** Scripted session that also ships the `RealtimeVideoInput` marker. */
+declare const layer: (script: MockRealtimeSessionScript) => {
+  readonly layer: Layer.Layer<RealtimeSession | RealtimeVideoInput>;
+  readonly recorder: Effect.Effect<MockRealtimeSessionRecorder>;
+};
+/**
+ * The same without the marker, to test that a caller sending video against an
+ * audio-only provider fails to compile.
+ */
+declare const layerAudioOnly: (script: MockRealtimeSessionScript) => {
+  readonly layer: Layer.Layer<RealtimeSession>;
+  readonly recorder: Effect.Effect<MockRealtimeSessionRecorder>;
+};
+//#endregion
+export { MockRealtimeSessionRecorder, MockRealtimeSessionScript, layer, layerAudioOnly };
+//# sourceMappingURL=MockRealtimeSession.d.mts.map

package/dist/testing/MockRealtimeSession.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockRealtimeSession.d.mts","names":[],"sources":["../../src/testing/MockRealtimeSession.ts"],"mappings":";;;;KASY;WACD,WAAW,cAAc;WACzB,MAAM,cAAc;;KAGnB;;WAED,UAAU,cAAc;;WAExB,WAAW,OAAO,kBAAkB,cAAc;;;cAgDhD,QAAK,QACR;WAEC,OAAO,MAAM,MAAM,kBAAkB;WACrC,UAAU,OAAO,OAAO;;;;;;cAatB,iBAAc,QACjB;WAEC,OAAO,MAAM,MAAM;WACnB,UAAU,OAAO,OAAO"}

package/dist/testing/MockRealtimeSession.mjs

@@ -0,0 +1,52 @@
+import { RealtimeSession, RealtimeVideoInput } from "../realtime/RealtimeSession.mjs";
+import { Effect, Layer, Queue, Ref, Stream } from "effect";
+//#region src/testing/MockRealtimeSession.ts
+const makeService = (script, record) => ({ open: (request) => Effect.gen(function* () {
+	yield* record.open(request);
+	const queue = yield* Queue.unbounded();
+	yield* Effect.addFinalizer(() => Queue.end(queue));
+	yield* Queue.offerAll(queue, script.initial ?? []);
+	return {
+		send: (input) => Effect.andThen(record.send(input), Queue.offerAll(queue, script.onInput?.(input) ?? [])).pipe(Effect.asVoid),
+		events: Stream.fromQueue(queue)
+	};
+}) });
+const build = (script) => {
+	const openCalls = Ref.makeUnsafe([]);
+	const sent = Ref.makeUnsafe([]);
+	return {
+		sessionLayer: Layer.succeed(RealtimeSession, makeService(script, {
+			open: (request) => Ref.update(openCalls, (xs) => [...xs, request]),
+			send: (input) => Ref.update(sent, (xs) => [...xs, input])
+		})),
+		recorder: Effect.gen(function* () {
+			return {
+				openCalls: yield* Ref.get(openCalls),
+				sent: yield* Ref.get(sent)
+			};
+		})
+	};
+};
+/** Scripted session that also ships the `RealtimeVideoInput` marker. */
+const layer = (script) => {
+	const { sessionLayer, recorder } = build(script);
+	return {
+		layer: Layer.merge(sessionLayer, Layer.succeed(RealtimeVideoInput, void 0)),
+		recorder
+	};
+};
+/**
+* The same without the marker, to test that a caller sending video against an
+* audio-only provider fails to compile.
+*/
+const layerAudioOnly = (script) => {
+	const { sessionLayer, recorder } = build(script);
+	return {
+		layer: sessionLayer,
+		recorder
+	};
+};
+//#endregion
+export { layer, layerAudioOnly };
+
+//# sourceMappingURL=MockRealtimeSession.mjs.map

package/dist/testing/MockRealtimeSession.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockRealtimeSession.mjs","names":[],"sources":["../../src/testing/MockRealtimeSession.ts"],"sourcesContent":["import { Cause, Effect, Layer, Queue, Ref, Stream } from \"effect\"\nimport type { CommonSessionRequest, RealtimeEvent, RealtimeInput } from \"../domain/Realtime.js\"\nimport {\n  RealtimeSession,\n  RealtimeVideoInput,\n  type RealtimeSessionHandle,\n  type RealtimeSessionService,\n} from \"../realtime/RealtimeSession.js\"\n\nexport type MockRealtimeSessionRecorder = {\n  readonly openCalls: ReadonlyArray<CommonSessionRequest>\n  readonly sent: ReadonlyArray<RealtimeInput>\n}\n\nexport type MockRealtimeSessionScript = {\n  /** Emitted as soon as the session opens. */\n  readonly initial?: ReadonlyArray<RealtimeEvent>\n  /** The server's answer to each input. */\n  readonly onInput?: (input: RealtimeInput) => ReadonlyArray<RealtimeEvent>\n}\n\ntype Recorders = {\n  readonly open: (request: CommonSessionRequest) => Effect.Effect<void>\n  readonly send: (input: RealtimeInput) => Effect.Effect<void>\n}\n\nconst makeService = (\n  script: MockRealtimeSessionScript,\n  record: Recorders,\n): RealtimeSessionService => ({\n  open: (request) =>\n    Effect.gen(function* () {\n      yield* record.open(request)\n      const queue = yield* Queue.unbounded<RealtimeEvent, Cause.Done>()\n      // Closing the scope ends `events`, leaving anything already queued to drain.\n      yield* Effect.addFinalizer(() => Queue.end(queue))\n      yield* Queue.offerAll(queue, script.initial ?? [])\n      const handle: RealtimeSessionHandle = {\n        send: (input) =>\n          Effect.andThen(\n            record.send(input),\n            Queue.offerAll(queue, script.onInput?.(input) ?? []),\n          ).pipe(Effect.asVoid),\n        events: Stream.fromQueue(queue),\n      }\n      return handle\n    }),\n})\n\nconst build = (script: MockRealtimeSessionScript) => {\n  const openCalls = Ref.makeUnsafe<ReadonlyArray<CommonSessionRequest>>([])\n  const sent = Ref.makeUnsafe<ReadonlyArray<RealtimeInput>>([])\n  const sessionLayer = Layer.succeed(\n    RealtimeSession,\n    makeService(script, {\n      open: (request) => Ref.update(openCalls, (xs) => [...xs, request]),\n      send: (input) => Ref.update(sent, (xs) => [...xs, input]),\n    }),\n  )\n  const recorder: Effect.Effect<MockRealtimeSessionRecorder> = Effect.gen(function* () {\n    return { openCalls: yield* Ref.get(openCalls), sent: yield* Ref.get(sent) }\n  })\n  return { sessionLayer, recorder }\n}\n\n/** Scripted session that also ships the `RealtimeVideoInput` marker. */\nexport const layer = (\n  script: MockRealtimeSessionScript,\n): {\n  readonly layer: Layer.Layer<RealtimeSession | RealtimeVideoInput>\n  readonly recorder: Effect.Effect<MockRealtimeSessionRecorder>\n} => {\n  const { sessionLayer, recorder } = build(script)\n  return {\n    layer: Layer.merge(sessionLayer, Layer.succeed(RealtimeVideoInput, undefined)),\n    recorder,\n  }\n}\n\n/**\n * The same without the marker, to test that a caller sending video against an\n * audio-only provider fails to compile.\n */\nexport const layerAudioOnly = (\n  script: MockRealtimeSessionScript,\n): {\n  readonly layer: Layer.Layer<RealtimeSession>\n  readonly recorder: Effect.Effect<MockRealtimeSessionRecorder>\n} => {\n  const { sessionLayer, recorder } = build(script)\n  return { layer: sessionLayer, recorder }\n}\n"],"mappings":";;;AA0BA,MAAM,eACJ,QACA,YAC4B,EAC5B,OAAO,YACL,OAAO,IAAI,aAAa;CACtB,OAAO,OAAO,KAAK,OAAO;CAC1B,MAAM,QAAQ,OAAO,MAAM,UAAqC;CAEhE,OAAO,OAAO,mBAAmB,MAAM,IAAI,KAAK,CAAC;CACjD,OAAO,MAAM,SAAS,OAAO,OAAO,WAAW,CAAC,CAAC;CASjD,OAAO;EAPL,OAAO,UACL,OAAO,QACL,OAAO,KAAK,KAAK,GACjB,MAAM,SAAS,OAAO,OAAO,UAAU,KAAK,KAAK,CAAC,CAAC,CACrD,CAAC,CAAC,KAAK,OAAO,MAAM;EACtB,QAAQ,OAAO,UAAU,KAAK;CAEpB;AACd,CAAC,EACL;AAEA,MAAM,SAAS,WAAsC;CACnD,MAAM,YAAY,IAAI,WAAgD,CAAC,CAAC;CACxE,MAAM,OAAO,IAAI,WAAyC,CAAC,CAAC;CAW5D,OAAO;EAAE,cAVY,MAAM,QACzB,iBACA,YAAY,QAAQ;GAClB,OAAO,YAAY,IAAI,OAAO,YAAY,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC;GACjE,OAAO,UAAU,IAAI,OAAO,OAAO,OAAO,CAAC,GAAG,IAAI,KAAK,CAAC;EAC1D,CAAC,CAKiB;EAAG,UAHsC,OAAO,IAAI,aAAa;GACnF,OAAO;IAAE,WAAW,OAAO,IAAI,IAAI,SAAS;IAAG,MAAM,OAAO,IAAI,IAAI,IAAI;GAAE;EAC5E,CAC8B;CAAE;AAClC;;AAGA,MAAa,SACX,WAIG;CACH,MAAM,EAAE,cAAc,aAAa,MAAM,MAAM;CAC/C,OAAO;EACL,OAAO,MAAM,MAAM,cAAc,MAAM,QAAQ,oBAAoB,KAAA,CAAS,CAAC;EAC7E;CACF;AACF;;;;;AAMA,MAAa,kBACX,WAIG;CACH,MAAM,EAAE,cAAc,aAAa,MAAM,MAAM;CAC/C,OAAO;EAAE,OAAO;EAAc;CAAS;AACzC"}

package/dist/tool/Toolkit.d.mts

@@ -1,2 +1,2 @@
-import { S as wrap, _ as fromArray, a as ToolMap, b as namespace, c as ToolkitR, d as appendToolResults, f as collectResults, g as descriptors, h as describeFailures, i as NoDuplicateNames, m as continueWithResults, n as ExecuteOptions, o as Toolkit, p as compose, r as Middleware, s as ToolkitE, t as DuplicateToolName, u as UniqueTools, v as make, x as run, y as makeNamespaced } from "../Toolkit-DAjJ9Tvl.mjs";
+import { S as wrap, _ as fromArray, a as ToolMap, b as namespace, c as ToolkitR, d as appendToolResults, f as collectResults, g as descriptors, h as describeFailures, i as NoDuplicateNames, m as continueWithResults, n as ExecuteOptions, o as Toolkit, p as compose, r as Middleware, s as ToolkitE, t as DuplicateToolName, u as UniqueTools, v as make, x as run, y as makeNamespaced } from "../Toolkit-tlL0F2YR.mjs";
 export { DuplicateToolName, ExecuteOptions, Middleware, NoDuplicateNames, ToolMap, Toolkit, ToolkitE, ToolkitR, UniqueTools, appendToolResults, collectResults, compose, continueWithResults, describeFailures, descriptors, fromArray, make, makeNamespaced, namespace, run, wrap };

package/dist/transcriber/Transcriber.d.mts

@@ -1,4 +1,4 @@
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { a as AudioSource, r as AudioFormat } from "../Audio-_nGR4V0X.mjs";
 import { TranscriptEvent, TranscriptResult } from "../domain/Transcript.mjs";
 import { Context, Effect, Stream } from "effect";

package/dist/web-read/WebRead.d.mts

@@ -1,4 +1,4 @@
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { Context, Duration, Effect } from "effect";
 declare namespace WebRead_d_exports {
   export { CommonReadRequest, ReadFormat, ReadResponse, WebRead, WebReadService, read };

package/dist/web-read/WebReadTool.d.mts

@@ -1,5 +1,5 @@
 import { l as Tool } from "../Tool-BF78QWtn.mjs";
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { ReadFormat, ReadResponse, WebRead } from "./WebRead.mjs";
 import { Schema } from "effect";
 declare namespace WebReadTool_d_exports {

package/dist/web-search/WebSearch.d.mts

@@ -1,4 +1,4 @@
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { Context, DateTime, Effect, Schema } from "effect";
 declare namespace WebSearch_d_exports {
   export { CommonSearchRequest, SearchRecency, SearchResponse, SearchResult, WebSearch, WebSearchService, search };

package/dist/web-search/WebSearchTool.d.mts

@@ -1,5 +1,5 @@
 import { l as Tool } from "../Tool-BF78QWtn.mjs";
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { SearchResult, WebSearch } from "./WebSearch.mjs";
 import { Schema } from "effect";
 declare namespace WebSearchTool_d_exports {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -90,6 +90,14 @@
       "types": "./dist/domain/Music.d.mts",
       "import": "./dist/domain/Music.mjs"
     },
+    "./Realtime": {
+      "types": "./dist/domain/Realtime.d.mts",
+      "import": "./dist/domain/Realtime.mjs"
+    },
+    "./RealtimeSession": {
+      "types": "./dist/realtime/RealtimeSession.d.mts",
+      "import": "./dist/realtime/RealtimeSession.mjs"
+    },
     "./Transcript": {
       "types": "./dist/domain/Transcript.d.mts",
       "import": "./dist/domain/Transcript.mjs"
@@ -178,9 +186,13 @@
       "types": "./dist/web-search/WebSearchTool.d.mts",
       "import": "./dist/web-search/WebSearchTool.mjs"
     },
-    "./Inbox": {
-      "types": "./dist/inbox/Inbox.d.mts",
-      "import": "./dist/inbox/Inbox.mjs"
+    "./WebSocketSession": {
+      "types": "./dist/streaming/WebSocketSession.d.mts",
+      "import": "./dist/streaming/WebSocketSession.mjs"
+    },
+    "./Settle": {
+      "types": "./dist/streaming/Settle.d.mts",
+      "import": "./dist/streaming/Settle.mjs"
     },
     "./Loop": {
       "types": "./dist/loop/Loop.d.mts",
@@ -270,6 +282,14 @@
       "types": "./dist/testing/MockSandbox.d.mts",
       "import": "./dist/testing/MockSandbox.mjs"
     },
+    "./testing/FakeWebSocket": {
+      "types": "./dist/testing/FakeWebSocket.d.mts",
+      "import": "./dist/testing/FakeWebSocket.mjs"
+    },
+    "./testing/MockRealtimeSession": {
+      "types": "./dist/testing/MockRealtimeSession.d.mts",
+      "import": "./dist/testing/MockRealtimeSession.mjs"
+    },
     "./testing/MockTranscriber": {
       "types": "./dist/testing/MockTranscriber.d.mts",
       "import": "./dist/testing/MockTranscriber.mjs"

package/src/domain/AiError.ts

@@ -100,6 +100,15 @@ export class Unsupported extends Data.TaggedError("Unsupported")<{
   reason?: string
 }> {}
 
+/**
+ * A long-lived session hit the provider's lifetime cap. Distinct from
+ * `Unavailable`: reconnecting works, retrying the same session does not.
+ */
+export class SessionExpired extends Data.TaggedError("SessionExpired")<{
+  provider: string
+  raw?: unknown
+}> {}
+
 export type AiError =
   | RateLimited
   | Unavailable
@@ -112,6 +121,7 @@ export type AiError =
   | IncompleteTurn
   | GenerationFailed
   | Unsupported
+  | SessionExpired
 
 const withReason = (base: string, reason: string | undefined): string =>
   reason === undefined ? base : `${base}: ${reason}`
@@ -136,5 +146,6 @@ export const describe: (e: AiError) => string = Match.type<AiError>().pipe(
     IncompleteTurn: () => "the provider stream ended without completing",
     GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,
     Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason),
+    SessionExpired: (e) => `the ${e.provider} session reached its lifetime limit`,
   }),
 )

package/src/domain/Realtime.ts

@@ -0,0 +1,101 @@
+/**
+ * Types for a duplex speech-to-speech session: one long-lived connection the
+ * server drives, rather than a caller-driven turn.
+ *
+ * Only what both OpenAI Realtime and Gemini Live do natively lives here. VAD
+ * knobs, truncation, resumption, thinking, grounding and noise reduction are
+ * provider-typed on each adapter's request.
+ */
+import { Data, type Duration } from "effect"
+import type { AudioFormat } from "./Audio.js"
+import type { ImageSource } from "./Image.js"
+import type { HistoryItem, ToolCall, ToolCallOutput, Usage } from "./Items.js"
+import type { ToolDescriptor } from "../tool/Tool.js"
+
+/**
+ * What the caller pushes into a live session.
+ *
+ * - `Audio`: encoded per `request.inputFormat`. The adapter neither paces nor
+ *   buffers; send at real time.
+ * - `Text`: role `system` maps to a system item where the provider has one and
+ *   fails `Unsupported` where it does not.
+ * - `Interrupt`: cancel the response in flight.
+ * - `VideoFrame`: gated by the `RealtimeVideoInput` marker.
+ * - `ActivityStart` / `ActivityEnd`: manual turn detection only; `ActivityEnd`
+ *   also asks for a response. Dropped with a warning on a `"server"` session.
+ * - `PlaybackPosition`: how much of a response the user actually heard, so the
+ *   adapter can trim the rest from context. A no-op where the wire has no
+ *   truncate.
+ */
+export type RealtimeInput = Data.TaggedEnum<{
+  Audio: { readonly bytes: Uint8Array }
+  Text: { readonly text: string; readonly role?: "user" | "system" }
+  ToolResult: { readonly output: ToolCallOutput }
+  Interrupt: {}
+  VideoFrame: { readonly frame: ImageSource }
+  ActivityStart: {}
+  ActivityEnd: {}
+  PlaybackPosition: { readonly responseId: string; readonly playedMs: number }
+}>
+
+export const RealtimeInput = Data.taggedEnum<RealtimeInput>()
+
+/**
+ * What the session emits. Every `AudioDelta` and `OutputTranscriptDelta` is
+ * bracketed by `ResponseStarted` and `ResponseDone` carrying the same
+ * `responseId`.
+ *
+ * - `InputTranscript`: transcription of the user's own speech.
+ * - `SpeechStarted` / `SpeechStopped`: sparse. OpenAI emits them, Gemini
+ *   does not.
+ * - `Interrupted`: stop and flush playback now. Always precedes the
+ *   `ResponseDone { reason: "interrupted" }` for that response.
+ * - `ToolCallCancelled`: calls of an interrupted response that will never be
+ *   answered.
+ * - `ResumptionHandle`: Gemini only; pass it back as `request.resume`.
+ * - `SessionEnding`: the connection is about to close on the server's terms.
+ * - `Error`: non-fatal. A fatal error fails the stream instead.
+ */
+export type RealtimeEvent = Data.TaggedEnum<{
+  ResponseStarted: { readonly responseId: string }
+  AudioDelta: { readonly responseId: string; readonly bytes: Uint8Array }
+  OutputTranscriptDelta: { readonly responseId: string; readonly text: string }
+  InputTranscript: { readonly text: string; readonly final: boolean }
+  SpeechStarted: {}
+  SpeechStopped: {}
+  ToolCall: { readonly responseId: string; readonly call: ToolCall }
+  ToolCallCancelled: { readonly callIds: ReadonlyArray<string> }
+  Interrupted: { readonly responseId: string }
+  ResponseDone: {
+    readonly responseId: string
+    readonly reason: "complete" | "interrupted" | "cancelled" | "error"
+    readonly usage?: Usage
+  }
+  ResumptionHandle: { readonly handle: string }
+  SessionEnding: { readonly timeLeft?: Duration.Duration }
+  Error: { readonly code?: string; readonly message: string }
+}>
+
+export const RealtimeEvent = Data.taggedEnum<RealtimeEvent>()
+
+/**
+ * Cross-provider session setup. Each adapter extends this, narrowing `model`
+ * and adding its own knobs.
+ */
+export type CommonSessionRequest = {
+  readonly model: string
+  readonly instructions?: string
+  readonly voiceId?: string
+  /** `Toolkit.descriptors(toolkit)`. Immutable for the connection on Gemini. */
+  readonly tools?: ReadonlyArray<ToolDescriptor>
+  readonly inputFormat: AudioFormat
+  readonly outputFormat: AudioFormat
+  /** Who decides a turn ended. Defaults to `"server"`. */
+  readonly turnDetection?: "server" | "manual"
+  /** Transcribe the user's own audio. Defaults to `true`. */
+  readonly transcribeInput?: boolean
+  /** Text-only conversation seed. */
+  readonly history?: ReadonlyArray<HistoryItem>
+  /** A `ResumptionHandle` from a previous session. `Unsupported` off Gemini. */
+  readonly resume?: string
+}

package/src/domain/Transcript.test.ts

@@ -0,0 +1,98 @@
+import { describe, it } from "@effect/vitest"
+import { Cause, Effect, Queue, Ref, Stream } from "effect"
+import { TestClock } from "effect/testing"
+import { expect } from "vitest"
+import { accumulatePartials, type TranscriptEvent } from "./Transcript.js"
+
+const collecting = (stream: Stream.Stream<TranscriptEvent, never>) =>
+  Effect.gen(function* () {
+    const seen = yield* Ref.make<ReadonlyArray<TranscriptEvent>>([])
+    yield* Effect.forkChild(Stream.runForEach(stream, (e) => Ref.update(seen, (xs) => [...xs, e])))
+    return seen
+  })
+
+/** Deltas arriving faster than any settle window. */
+const speak = (
+  queue: Queue.Queue<TranscriptEvent, Cause.Done>,
+  tokens: ReadonlyArray<string>,
+): Effect.Effect<void> =>
+  Effect.forEach(
+    tokens,
+    (text) =>
+      Effect.andThen(Queue.offer(queue, { _tag: "partial", text }), TestClock.adjust("100 millis")),
+    { discard: true },
+  )
+
+const opened = Effect.gen(function* () {
+  const queue = yield* Queue.unbounded<TranscriptEvent, Cause.Done>()
+  const seen = yield* collecting(
+    Stream.fromQueue(queue).pipe(accumulatePartials({ silence: "1 second" })),
+  )
+  return { queue, seen }
+})
+
+describe("accumulatePartials", () => {
+  it.effect("joins deltas into the running hypothesis, forwarding each as it arrives", () =>
+    Effect.gen(function* () {
+      const { queue, seen } = yield* opened
+
+      yield* speak(queue, [" Hi", ",", " how"])
+
+      // Three in, three out, each the whole sentence so far, none delayed.
+      expect(yield* Ref.get(seen)).toEqual([
+        { _tag: "partial", text: "Hi" },
+        { _tag: "partial", text: "Hi," },
+        { _tag: "partial", text: "Hi, how" },
+      ])
+    }),
+  )
+
+  it.effect("commits on silence and starts the next utterance from empty", () =>
+    Effect.gen(function* () {
+      const { queue, seen } = yield* opened
+
+      yield* speak(queue, [" Hi", " there"])
+      yield* TestClock.adjust("3 seconds")
+      yield* speak(queue, [" Bye"])
+      yield* TestClock.adjust("3 seconds")
+
+      expect(yield* Ref.get(seen)).toEqual([
+        { _tag: "partial", text: "Hi" },
+        { _tag: "partial", text: "Hi there" },
+        { _tag: "final", text: "Hi there" },
+        { _tag: "partial", text: "Bye" },
+        { _tag: "final", text: "Bye" },
+      ])
+    }),
+  )
+
+  it.effect("a provider's own final resets the accumulator, so silence adds no duplicate", () =>
+    Effect.gen(function* () {
+      const { queue, seen } = yield* opened
+
+      yield* speak(queue, [" Hi"])
+      yield* Queue.offer(queue, { _tag: "final", text: "Hi." })
+      yield* TestClock.adjust("3 seconds")
+
+      expect(yield* Ref.get(seen)).toEqual([
+        { _tag: "partial", text: "Hi" },
+        { _tag: "final", text: "Hi." },
+      ])
+    }),
+  )
+
+  it.effect("commits the pending text when the stream ends mid-utterance", () =>
+    Effect.gen(function* () {
+      const { queue, seen } = yield* opened
+
+      yield* speak(queue, [" Half a sen"])
+      yield* Queue.end(queue)
+      yield* TestClock.adjust("10 millis")
+
+      expect(yield* Ref.get(seen)).toEqual([
+        { _tag: "partial", text: "Half a sen" },
+        { _tag: "final", text: "Half a sen" },
+      ])
+    }),
+  )
+})