agents 0.26.0 → 0.27.0

package/dist/experimental/channels/web/index.d.ts

@@ -0,0 +1,189 @@
+import {
+  d as ChannelUpgradeMatch,
+  m as ParticipantResult,
+  n as Channel,
+  t as Awaitable
+} from "../../../channel-Bak_6zDP.js";
+import {
+  _ as TranscriptMessage,
+  c as InboundEvent,
+  i as ConversationSnapshot,
+  m as ResponseChunk,
+  n as ConversationInfo,
+  p as Participant,
+  r as ConversationOperation,
+  y as TurnStatus
+} from "../../../protocol-CukuI73M.js";
+import { i as WebSockets } from "../../../index-Ib_4dwOo.js";
+import {
+  a as ConversationChannel,
+  o as ConversationUpdate,
+  r as ChannelsHost
+} from "../../../conversations-DH0ut_8n.js";
+
+//#region src/experimental/channels/web/channel.d.ts
+type WebChannelOptions = {
+  /**
+   * The connections to serve conversations on, for an agent sharing its own.
+   * Default: the WebSockets Channels shares, created on first use.
+   */
+  websockets?: WebSockets;
+};
+/**
+ * Serves conversations over the agent's WebSockets connections, to clients
+ * the gateway has resolved. Frames are
+ * namespaced `channels:`, so a connection can carry other protocols too.
+ */
+declare class WebChannel implements ConversationChannel {
+  #private;
+  constructor(options?: WebChannelOptions);
+  mount(host: ChannelsHost): void;
+  publish(conversationId: string, update: ConversationUpdate): void;
+}
+//#endregion
+//#region src/experimental/channels/web/ingress.d.ts
+/** How the gateway takes the Web Channel's WebSocket upgrades. */
+type WebIngressOptions = {
+  /**
+   * Who is connecting, from request data you can verify, such as a session
+   * cookie or an Access JWT. Return null to refuse the upgrade.
+   */
+  participant(request: Request): Awaitable<ParticipantResult>;
+  /**
+   * The agent object the participant reaches, or null to refuse them. That
+   * object is the authorization boundary: whoever reaches it may use every
+   * conversation in it. Default: an agent object of the participant's own.
+   */
+  route?(request: Request, participant: Participant): Awaitable<string | null>;
+  /**
+   * Which upgrades are for the Web Channel, and the conversation each
+   * follows. Return undefined for one that is not. Default: `/channels`,
+   * or `/channels/<conversation>`.
+   */
+  match?(request: Request): ChannelUpgradeMatch | undefined;
+};
+/**
+ * The Web Channel's side in the gateway: it resolves each WebSocket upgrade
+ * and forwards it to the agent, whose `WebChannel` serves the connection.
+ *
+ * ```ts
+ * new ChannelGateway({
+ *   agent: (route) => env.SupportAgent.getByName(route),
+ *   channels: {
+ *     web: web({
+ *       participant: async (request) =>
+ *         (await verifySession(request, env))?.id ?? null
+ *     })
+ *   }
+ * });
+ * ```
+ */
+declare function web(options: WebIngressOptions): Channel;
+//#endregion
+//#region src/experimental/channels/web/protocol.d.ts
+/** Who a connection is: set by the gateway, read by the Web Channel. */
+type WebIdentity = {
+  /** The route that picked the agent. */ route: string /** The conversation to follow. Default: the agent's default for the route. */;
+  conversationId?: string;
+  participant: Participant;
+};
+/**
+ * The header carrying a connection's WebIdentity from the gateway to the
+ * agent. The gateway always sets it, so a client cannot supply its own; an
+ * agent must not take WebSocket upgrades from any other route.
+ */
+declare const WEB_IDENTITY_HEADER = "x-channels-identity";
+type ClientFrame =
+  | {
+      type: "channels:event";
+      event: InboundEvent;
+    }
+  | {
+      type: "channels:subscribe";
+      responseId: string;
+      from?: number;
+    } /** Ask for the agent's conversations; answered by `channels:conversations`. */
+  | {
+      type: "channels:list-conversations";
+      requestId: string;
+    };
+type ServerFrame = {
+  conversationId: string;
+} &
+  /**
+   * On connect, after a reset (empty), and when the connection follows
+   * another conversation. `you` is this connection's participant;
+   * `operations` are the conversation operations it may send.
+   */
+  (
+    | ({
+        type: "channels:snapshot";
+        you: Participant;
+        operations: ConversationOperation[];
+      } & ConversationSnapshot)
+    | {
+        type: "channels:turn";
+        turn: TurnStatus;
+      } /** Upserts by id; an unknown id appends. */
+    | {
+        type: "channels:messages";
+        messages: TranscriptMessage[];
+      }
+    | {
+        type: "channels:chunks";
+        responseId: string /** Seq of the first chunk. */;
+        from: number;
+        chunks: ResponseChunk[];
+      } /** Everything before this was replay; what follows is live. */
+    | {
+        type: "channels:caught-up";
+        responseId: string;
+        cursor: number;
+      }
+    | {
+        type: "channels:end";
+        responseId: string;
+        state: "ended" | "interrupted" | "not-found";
+      }
+    /**
+     * The agent's conversations: the answer to a list request, carrying its
+     * `requestId`, or pushed when one is created or forked.
+     */
+    | {
+        type: "channels:conversations";
+        requestId?: string;
+        conversations?: ConversationInfo[];
+        error?: string;
+      } /** `conversationId` is the one a create or fork started, when it did. */
+    | {
+        type: "channels:ack";
+        eventId: string;
+        error?: string;
+      }
+  );
+/** A frame that names a Channels type but is malformed. */
+type InvalidClientFrame = {
+  invalid: string;
+  eventId?: string;
+};
+/**
+ * Parse a text frame. Returns undefined for anything that is not a Channels
+ * frame, so the socket's other protocols keep working.
+ */
+declare function parseClientFrame(
+  text: string
+): ClientFrame | InvalidClientFrame | undefined;
+//#endregion
+export {
+  ClientFrame,
+  InvalidClientFrame,
+  ServerFrame,
+  WEB_IDENTITY_HEADER,
+  WebChannel,
+  WebChannelOptions,
+  WebIdentity,
+  WebIngressOptions,
+  parseClientFrame,
+  web
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/experimental/channels/web/index.js

@@ -0,0 +1,332 @@
+import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "../../../classPrivateFieldGet2-DZBYAB34.js";
+import { t as _classPrivateMethodInitSpec } from "../../../classPrivateMethodInitSpec-qMjJ6sHQ.js";
+import { a as getConnectionFlag, l as registerInternalConnectionKeys, t as WebSockets, u as setConnectionFlag } from "../../../websockets-CmENGb-Z.js";
+import { i as participantRoute } from "../../../internal-kmw70xwR.js";
+import { n as parseClientFrame, t as WEB_IDENTITY_HEADER } from "../../../protocol-y2sSY584.js";
+//#region src/experimental/channels/web/channel.ts
+/** Where a Channels connection's identity lives in its connection state. */
+const IDENTITY_KEY = "_cf_channels";
+registerInternalConnectionKeys(IDENTITY_KEY);
+var _options = /* @__PURE__ */ new WeakMap();
+var _websockets = /* @__PURE__ */ new WeakMap();
+var _host = /* @__PURE__ */ new WeakMap();
+var _pending = /* @__PURE__ */ new WeakMap();
+var _reads = /* @__PURE__ */ new WeakMap();
+var _WebChannel_brand = /* @__PURE__ */ new WeakSet();
+/**
+* Serves conversations over the agent's WebSockets connections, to clients
+* the gateway has resolved. Frames are
+* namespaced `channels:`, so a connection can carry other protocols too.
+*/
+var WebChannel = class {
+	constructor(options = {}) {
+		_classPrivateMethodInitSpec(this, _WebChannel_brand);
+		_classPrivateFieldInitSpec(this, _options, void 0);
+		_classPrivateFieldInitSpec(this, _websockets, void 0);
+		_classPrivateFieldInitSpec(this, _host, void 0);
+		_classPrivateFieldInitSpec(this, _pending, /* @__PURE__ */ new Map());
+		_classPrivateFieldInitSpec(this, _reads, /* @__PURE__ */ new Map());
+		_classPrivateFieldSet2(_options, this, options);
+	}
+	mount(host) {
+		if (_classPrivateFieldGet2(_host, this)) throw new Error("A WebChannel can be mounted only once");
+		_classPrivateFieldSet2(_host, this, host);
+		_classPrivateFieldSet2(_websockets, this, _classPrivateFieldGet2(_options, this).websockets ?? host.websockets(() => new WebSockets()));
+		_classPrivateFieldGet2(_websockets, this).use({
+			onConnect: (connection, ctx) => _assertClassBrand(_WebChannel_brand, this, _connect).call(this, connection, ctx),
+			onMessage: (connection, message) => _assertClassBrand(_WebChannel_brand, this, _message).call(this, connection, message),
+			onClose: (connection) => _assertClassBrand(_WebChannel_brand, this, _close).call(this, connection)
+		});
+	}
+	publish(conversationId, update) {
+		for (const [connection, identity] of _assertClassBrand(_WebChannel_brand, this, _connections).call(this)) {
+			if (identity.conversationId !== conversationId) continue;
+			if (update.type === "messages" && _assertClassBrand(_WebChannel_brand, this, _sentBy).call(this, update, connection)) continue;
+			if (update.type === "reset") _assertClassBrand(_WebChannel_brand, this, _stopReads).call(this, connection.id);
+			const frame = toFrame(update, conversationId, identity.participant, _assertClassBrand(_WebChannel_brand, this, _mounted).call(this).operations);
+			const pending = _classPrivateFieldGet2(_pending, this).get(connection.id);
+			if (pending) pending.push(frame);
+			else send(connection, frame);
+		}
+	}
+};
+async function _connect(connection, { request }) {
+	const header = request.headers.get(WEB_IDENTITY_HEADER);
+	if (header === null) return;
+	const resolved = JSON.parse(header);
+	const host = _assertClassBrand(_WebChannel_brand, this, _mounted).call(this);
+	const identity = {
+		...resolved,
+		conversationId: resolved.conversationId ?? host.defaultConversation(),
+		channelKey: host.channelKey
+	};
+	setConnectionFlag(connection, IDENTITY_KEY, identity);
+	_classPrivateFieldGet2(_pending, this).set(connection.id, []);
+	await _assertClassBrand(_WebChannel_brand, this, _sendSnapshot).call(this, connection, identity);
+}
+async function _message(connection, message) {
+	const identity = _assertClassBrand(_WebChannel_brand, this, _identityOf).call(this, connection);
+	if (!identity || typeof message !== "string") return false;
+	const frame = parseClientFrame(message);
+	if (!frame) return false;
+	if ("invalid" in frame) {
+		send(connection, {
+			type: "channels:ack",
+			conversationId: identity.conversationId,
+			eventId: frame.eventId ?? "",
+			error: `Invalid frame: ${frame.invalid}`
+		});
+		return true;
+	}
+	if (frame.type === "channels:list-conversations") {
+		await _assertClassBrand(_WebChannel_brand, this, _list).call(this, connection, identity, frame.requestId);
+		return true;
+	}
+	if (frame.type === "channels:subscribe") {
+		_assertClassBrand(_WebChannel_brand, this, _subscribe).call(this, connection, identity, frame.responseId, frame.from);
+		return true;
+	}
+	const { eventId } = frame.event;
+	let result;
+	try {
+		result = await _assertClassBrand(_WebChannel_brand, this, _mounted).call(this).dispatch(frame.event, origin(identity, connection.id));
+	} catch {
+		send(connection, {
+			type: "channels:ack",
+			conversationId: identity.conversationId,
+			eventId,
+			error: "Event rejected"
+		});
+		return true;
+	}
+	const followed = result.conversationId;
+	send(connection, {
+		type: "channels:ack",
+		conversationId: followed ?? identity.conversationId,
+		eventId
+	});
+	if (followed !== void 0 && followed !== identity.conversationId) await _assertClassBrand(_WebChannel_brand, this, _follow).call(this, connection, {
+		...identity,
+		conversationId: followed
+	});
+	if (followed !== void 0) await _assertClassBrand(_WebChannel_brand, this, _pushConversations).call(this);
+	return true;
+}
+async function _list(connection, identity, requestId) {
+	const frame = {
+		type: "channels:conversations",
+		conversationId: identity.conversationId,
+		requestId
+	};
+	try {
+		const conversations = await _assertClassBrand(_WebChannel_brand, this, _mounted).call(this).listConversations();
+		send(connection, {
+			...frame,
+			conversations
+		});
+	} catch (error) {
+		console.error("Failed to list conversations", error);
+		send(connection, {
+			...frame,
+			error: "Failed to list conversations"
+		});
+	}
+}
+/** Tell every connection the agent's conversations changed. */
+async function _pushConversations() {
+	let conversations;
+	try {
+		conversations = await _assertClassBrand(_WebChannel_brand, this, _mounted).call(this).listConversations();
+	} catch (error) {
+		console.error("Failed to list conversations", error);
+		return;
+	}
+	for (const [connection, identity] of _assertClassBrand(_WebChannel_brand, this, _connections).call(this)) {
+		const frame = {
+			type: "channels:conversations",
+			conversationId: identity.conversationId,
+			conversations
+		};
+		const pending = _classPrivateFieldGet2(_pending, this).get(connection.id);
+		if (pending) pending.push(frame);
+		else send(connection, frame);
+	}
+}
+/** Move a connection to another conversation, starting from its snapshot. */
+async function _follow(connection, identity) {
+	_assertClassBrand(_WebChannel_brand, this, _stopReads).call(this, connection.id);
+	setConnectionFlag(connection, IDENTITY_KEY, identity);
+	_classPrivateFieldGet2(_pending, this).set(connection.id, []);
+	await _assertClassBrand(_WebChannel_brand, this, _sendSnapshot).call(this, connection, identity);
+}
+function _close(connection) {
+	_assertClassBrand(_WebChannel_brand, this, _stopReads).call(this, connection.id);
+	_classPrivateFieldGet2(_pending, this).delete(connection.id);
+}
+function _sentBy(update, connection) {
+	const surface = update.origin?.surface;
+	return surface !== void 0 && surface.channelKey === _classPrivateFieldGet2(_host, this)?.channelKey && connectionIdOf(surface.address) === connection.id;
+}
+async function _sendSnapshot(connection, identity) {
+	try {
+		const snapshot = await _assertClassBrand(_WebChannel_brand, this, _mounted).call(this).snapshot(identity.conversationId);
+		send(connection, {
+			type: "channels:snapshot",
+			conversationId: identity.conversationId,
+			you: identity.participant,
+			operations: [..._assertClassBrand(_WebChannel_brand, this, _mounted).call(this).operations],
+			...snapshot
+		});
+		for (const frame of _classPrivateFieldGet2(_pending, this).get(connection.id) ?? []) send(connection, frame);
+		_classPrivateFieldGet2(_pending, this).delete(connection.id);
+	} catch (error) {
+		console.error("Failed to read the conversation snapshot", error);
+		_classPrivateFieldGet2(_pending, this).delete(connection.id);
+		connection.close(1011, "Snapshot failed");
+	}
+}
+/** One read per response per connection; a repeated subscribe joins it. */
+function _subscribe(connection, identity, responseId, from) {
+	let reads = _classPrivateFieldGet2(_reads, this).get(connection.id);
+	if (!reads) _classPrivateFieldGet2(_reads, this).set(connection.id, reads = /* @__PURE__ */ new Map());
+	if (reads.has(responseId)) return;
+	const controller = new AbortController();
+	reads.set(responseId, controller);
+	const { conversationId } = identity;
+	_assertClassBrand(_WebChannel_brand, this, _mounted).call(this).readResponse(conversationId, responseId, {
+		from,
+		signal: controller.signal,
+		onChunks: (first, chunks) => send(connection, {
+			type: "channels:chunks",
+			conversationId,
+			responseId,
+			from: first,
+			chunks
+		}),
+		onCaughtUp: (cursor) => send(connection, {
+			type: "channels:caught-up",
+			conversationId,
+			responseId,
+			cursor
+		})
+	}).then((ending) => send(connection, {
+		type: "channels:end",
+		conversationId,
+		responseId,
+		state: ending
+	}), (error) => {
+		if (controller.signal.aborted) return;
+		console.error(`Failed to read response "${responseId}"`, error);
+		send(connection, {
+			type: "channels:end",
+			conversationId,
+			responseId,
+			state: "interrupted"
+		});
+	}).finally(() => reads.delete(responseId));
+}
+function _stopReads(connectionId) {
+	for (const controller of _classPrivateFieldGet2(_reads, this).get(connectionId)?.values() ?? []) controller.abort();
+	_classPrivateFieldGet2(_reads, this).delete(connectionId);
+}
+function* _connections() {
+	for (const connection of _classPrivateFieldGet2(_websockets, this)?.getConnections() ?? []) {
+		const identity = _assertClassBrand(_WebChannel_brand, this, _identityOf).call(this, connection);
+		if (identity) yield [connection, identity];
+	}
+}
+function _identityOf(connection) {
+	const identity = getConnectionFlag(connection, IDENTITY_KEY);
+	return identity?.channelKey === _classPrivateFieldGet2(_host, this)?.channelKey ? identity : void 0;
+}
+function _mounted() {
+	if (!_classPrivateFieldGet2(_host, this)) throw new Error("WebChannel is not mounted");
+	return _classPrivateFieldGet2(_host, this);
+}
+function origin(identity, connectionId) {
+	return {
+		conversationId: identity.conversationId,
+		participant: identity.participant,
+		surface: {
+			channelKey: identity.channelKey,
+			version: 1,
+			address: {
+				conversationId: identity.conversationId,
+				connectionId
+			},
+			label: "Web"
+		}
+	};
+}
+function connectionIdOf(address) {
+	return typeof address === "object" && address !== null && "connectionId" in address && typeof address.connectionId === "string" ? address.connectionId : void 0;
+}
+function toFrame(update, conversationId, you, operations) {
+	switch (update.type) {
+		case "turn": return {
+			type: "channels:turn",
+			conversationId,
+			turn: update.turn
+		};
+		case "messages": return {
+			type: "channels:messages",
+			conversationId,
+			messages: update.messages
+		};
+		case "reset": return {
+			type: "channels:snapshot",
+			conversationId,
+			you,
+			operations: [...operations],
+			messages: [],
+			turns: []
+		};
+		case "response-end": return {
+			type: "channels:end",
+			conversationId,
+			responseId: update.responseId,
+			state: update.ending
+		};
+	}
+}
+/** A failed send to one stale socket must not stop delivery to the rest. */
+function send(connection, frame) {
+	try {
+		connection.send(JSON.stringify(frame));
+	} catch {}
+}
+//#endregion
+//#region src/experimental/channels/web/ingress.ts
+/**
+* The Web Channel's side in the gateway: it resolves each WebSocket upgrade
+* and forwards it to the agent, whose `WebChannel` serves the connection.
+*
+* ```ts
+* new ChannelGateway({
+*   agent: (route) => env.SupportAgent.getByName(route),
+*   channels: {
+*     web: web({
+*       participant: async (request) =>
+*         (await verifySession(request, env))?.id ?? null
+*     })
+*   }
+* });
+* ```
+*/
+function web(options) {
+	const route = options.route;
+	return { upgrade: {
+		match: options.match ?? matchChannelsPath,
+		participant: (request) => options.participant(request),
+		route: (request, participant) => route ? route(request, participant) : participantRoute(participant)
+	} };
+}
+function matchChannelsPath(request) {
+	const match = /^\/channels(?:\/([^/]+))?$/.exec(new URL(request.url).pathname);
+	if (!match) return void 0;
+	return match[1] === void 0 ? {} : { conversationId: decodeURIComponent(match[1]) };
+}
+//#endregion
+export { WEB_IDENTITY_HEADER, WebChannel, parseClientFrame, web };
+
+//# sourceMappingURL=index.js.map

package/dist/experimental/channels/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/experimental/channels/web/channel.ts","../../../../src/experimental/channels/web/ingress.ts"],"sourcesContent":["import type {\n  Connection,\n  ConnectionContext,\n  WSMessage\n} from \"../../../lifecycle\";\nimport {\n  getConnectionFlag,\n  registerInternalConnectionKeys,\n  setConnectionFlag\n} from \"../../../websockets/connection-flags\";\nimport { WebSockets } from \"../../../websockets\";\nimport type {\n  ChannelsHost,\n  ConversationChannel,\n  ConversationUpdate\n} from \"../conversations\";\nimport type {\n  ConversationOperation,\n  EventOrigin,\n  Participant\n} from \"../protocol\";\nimport {\n  parseClientFrame,\n  WEB_IDENTITY_HEADER,\n  type ServerFrame,\n  type WebIdentity\n} from \"./protocol\";\n\n/** Where a Channels connection's identity lives in its connection state. */\nconst IDENTITY_KEY = \"_cf_channels\";\nregisterInternalConnectionKeys(IDENTITY_KEY);\n\nexport type WebChannelOptions = {\n  /**\n   * The connections to serve conversations on, for an agent sharing its own.\n   * Default: the WebSockets Channels shares, created on first use.\n   */\n  websockets?: WebSockets;\n};\n\ntype Identity = Omit<WebIdentity, \"conversationId\"> & {\n  conversationId: string;\n  channelKey: string;\n};\n\n/**\n * Serves conversations over the agent's WebSockets connections, to clients\n * the gateway has resolved. Frames are\n * namespaced `channels:`, so a connection can carry other protocols too.\n */\nexport class WebChannel implements ConversationChannel {\n  readonly #options: WebChannelOptions;\n  #websockets: WebSockets | undefined;\n  #host: ChannelsHost | undefined;\n  /** Frames held back until a connection has its snapshot. */\n  readonly #pending = new Map<string, ServerFrame[]>();\n  /** Active response reads, by connection, then response. */\n  readonly #reads = new Map<string, Map<string, AbortController>>();\n\n  constructor(options: WebChannelOptions = {}) {\n    this.#options = options;\n  }\n\n  mount(host: ChannelsHost): void {\n    if (this.#host) throw new Error(\"A WebChannel can be mounted only once\");\n    this.#host = host;\n    this.#websockets =\n      this.#options.websockets ?? host.websockets(() => new WebSockets());\n    this.#websockets.use({\n      onConnect: (connection, ctx) => this.#connect(connection, ctx),\n      onMessage: (connection, message) => this.#message(connection, message),\n      onClose: (connection) => this.#close(connection)\n    });\n  }\n\n  publish(conversationId: string, update: ConversationUpdate): void {\n    for (const [connection, identity] of this.#connections()) {\n      if (identity.conversationId !== conversationId) continue;\n      // The sender adds its own message once the agent accepts it.\n      if (update.type === \"messages\" && this.#sentBy(update, connection)) {\n        continue;\n      }\n      if (update.type === \"reset\") this.#stopReads(connection.id);\n      const frame = toFrame(\n        update,\n        conversationId,\n        identity.participant,\n        this.#mounted().operations\n      );\n      const pending = this.#pending.get(connection.id);\n      if (pending) pending.push(frame);\n      else send(connection, frame);\n    }\n  }\n\n  async #connect(\n    connection: Connection,\n    { request }: ConnectionContext\n  ): Promise<void> {\n    const header = request.headers.get(WEB_IDENTITY_HEADER);\n    if (header === null) return;\n    // The gateway is the trust boundary: it resolves who is connecting and\n    // sets this header. The agent must only be reachable through the\n    // gateway, or a caller could forge the header and join as anyone.\n    // There is no further authorization here: the agent object is the\n    // boundary, so a connection may use every conversation in it.\n    // SAFETY: only the gateway sets this header, with a WebIdentity.\n    const resolved = JSON.parse(header) as WebIdentity;\n    const host = this.#mounted();\n    const identity: Identity = {\n      ...resolved,\n      conversationId: resolved.conversationId ?? host.defaultConversation(),\n      channelKey: host.channelKey\n    };\n    setConnectionFlag(connection, IDENTITY_KEY, identity);\n    // Listen for pushes before reading the snapshot, so none are lost.\n    this.#pending.set(connection.id, []);\n    await this.#sendSnapshot(connection, identity);\n  }\n\n  async #message(connection: Connection, message: WSMessage): Promise<boolean> {\n    const identity = this.#identityOf(connection);\n    if (!identity || typeof message !== \"string\") return false;\n    const frame = parseClientFrame(message);\n    if (!frame) return false;\n\n    if (\"invalid\" in frame) {\n      send(connection, {\n        type: \"channels:ack\",\n        conversationId: identity.conversationId,\n        eventId: frame.eventId ?? \"\",\n        error: `Invalid frame: ${frame.invalid}`\n      });\n      return true;\n    }\n    if (frame.type === \"channels:list-conversations\") {\n      await this.#list(connection, identity, frame.requestId);\n      return true;\n    }\n    if (frame.type === \"channels:subscribe\") {\n      this.#subscribe(connection, identity, frame.responseId, frame.from);\n      return true;\n    }\n\n    const { eventId } = frame.event;\n    let result;\n    try {\n      result = await this.#mounted().dispatch(\n        frame.event,\n        origin(identity, connection.id)\n      );\n    } catch {\n      send(connection, {\n        type: \"channels:ack\",\n        conversationId: identity.conversationId,\n        eventId,\n        error: \"Event rejected\"\n      });\n      return true;\n    }\n    // The sender follows a conversation it created or forked; other\n    // connections stay where they are. Acknowledge first: a client resends\n    // unacknowledged events on every snapshot, and the new conversation's\n    // snapshot would otherwise carry the create or fork into it again.\n    const followed = result.conversationId;\n    send(connection, {\n      type: \"channels:ack\",\n      conversationId: followed ?? identity.conversationId,\n      eventId\n    });\n    if (followed !== undefined && followed !== identity.conversationId) {\n      await this.#follow(connection, { ...identity, conversationId: followed });\n    }\n    if (followed !== undefined) await this.#pushConversations();\n    return true;\n  }\n\n  async #list(\n    connection: Connection,\n    identity: Identity,\n    requestId: string\n  ): Promise<void> {\n    // The agent object is the authorization boundary, so every connection\n    // may list every conversation in it.\n    const frame = {\n      type: \"channels:conversations\" as const,\n      conversationId: identity.conversationId,\n      requestId\n    };\n    try {\n      const conversations = await this.#mounted().listConversations();\n      send(connection, { ...frame, conversations });\n    } catch (error) {\n      console.error(\"Failed to list conversations\", error);\n      send(connection, { ...frame, error: \"Failed to list conversations\" });\n    }\n  }\n\n  /** Tell every connection the agent's conversations changed. */\n  async #pushConversations(): Promise<void> {\n    let conversations;\n    try {\n      conversations = await this.#mounted().listConversations();\n    } catch (error) {\n      console.error(\"Failed to list conversations\", error);\n      return;\n    }\n    for (const [connection, identity] of this.#connections()) {\n      const frame: ServerFrame = {\n        type: \"channels:conversations\",\n        conversationId: identity.conversationId,\n        conversations\n      };\n      const pending = this.#pending.get(connection.id);\n      if (pending) pending.push(frame);\n      else send(connection, frame);\n    }\n  }\n\n  /** Move a connection to another conversation, starting from its snapshot. */\n  async #follow(connection: Connection, identity: Identity): Promise<void> {\n    this.#stopReads(connection.id);\n    setConnectionFlag(connection, IDENTITY_KEY, identity);\n    this.#pending.set(connection.id, []);\n    await this.#sendSnapshot(connection, identity);\n  }\n\n  #close(connection: Connection): void {\n    this.#stopReads(connection.id);\n    this.#pending.delete(connection.id);\n  }\n\n  #sentBy(\n    update: Extract<ConversationUpdate, { type: \"messages\" }>,\n    connection: Connection\n  ): boolean {\n    const surface = update.origin?.surface;\n    return (\n      surface !== undefined &&\n      surface.channelKey === this.#host?.channelKey &&\n      connectionIdOf(surface.address) === connection.id\n    );\n  }\n\n  async #sendSnapshot(\n    connection: Connection,\n    identity: Identity\n  ): Promise<void> {\n    try {\n      const snapshot = await this.#mounted().snapshot(identity.conversationId);\n      send(connection, {\n        type: \"channels:snapshot\",\n        conversationId: identity.conversationId,\n        you: identity.participant,\n        operations: [...this.#mounted().operations],\n        ...snapshot\n      });\n      for (const frame of this.#pending.get(connection.id) ?? []) {\n        send(connection, frame);\n      }\n      this.#pending.delete(connection.id);\n    } catch (error) {\n      console.error(\"Failed to read the conversation snapshot\", error);\n      this.#pending.delete(connection.id);\n      connection.close(1011, \"Snapshot failed\");\n    }\n  }\n\n  /** One read per response per connection; a repeated subscribe joins it. */\n  #subscribe(\n    connection: Connection,\n    identity: Identity,\n    responseId: string,\n    from: number | undefined\n  ): void {\n    let reads = this.#reads.get(connection.id);\n    if (!reads) this.#reads.set(connection.id, (reads = new Map()));\n    if (reads.has(responseId)) return;\n    const controller = new AbortController();\n    reads.set(responseId, controller);\n\n    const { conversationId } = identity;\n    this.#mounted()\n      .readResponse(conversationId, responseId, {\n        from,\n        signal: controller.signal,\n        onChunks: (first, chunks) =>\n          send(connection, {\n            type: \"channels:chunks\",\n            conversationId,\n            responseId,\n            from: first,\n            chunks\n          }),\n        onCaughtUp: (cursor) =>\n          send(connection, {\n            type: \"channels:caught-up\",\n            conversationId,\n            responseId,\n            cursor\n          })\n      })\n      .then(\n        (ending) =>\n          send(connection, {\n            type: \"channels:end\",\n            conversationId,\n            responseId,\n            state: ending\n          }),\n        (error) => {\n          if (controller.signal.aborted) return;\n          console.error(`Failed to read response \"${responseId}\"`, error);\n          // Tell the client the read is over, so it does not wait forever.\n          send(connection, {\n            type: \"channels:end\",\n            conversationId,\n            responseId,\n            state: \"interrupted\"\n          });\n        }\n      )\n      .finally(() => reads.delete(responseId));\n  }\n\n  #stopReads(connectionId: string): void {\n    for (const controller of this.#reads.get(connectionId)?.values() ?? []) {\n      controller.abort();\n    }\n    this.#reads.delete(connectionId);\n  }\n\n  *#connections(): Iterable<[Connection, Identity]> {\n    for (const connection of this.#websockets?.getConnections() ?? []) {\n      const identity = this.#identityOf(connection);\n      if (identity) yield [connection, identity];\n    }\n  }\n\n  #identityOf(connection: Connection): Identity | undefined {\n    // SAFETY: only #connect writes this key, with an Identity.\n    const identity = getConnectionFlag(connection, IDENTITY_KEY) as\n      | Identity\n      | undefined;\n    return identity?.channelKey === this.#host?.channelKey\n      ? identity\n      : undefined;\n  }\n\n  #mounted(): ChannelsHost {\n    if (!this.#host) throw new Error(\"WebChannel is not mounted\");\n    return this.#host;\n  }\n}\n\nfunction origin(identity: Identity, connectionId: string): EventOrigin {\n  return {\n    conversationId: identity.conversationId,\n    participant: identity.participant,\n    surface: {\n      channelKey: identity.channelKey,\n      version: 1,\n      address: { conversationId: identity.conversationId, connectionId },\n      label: \"Web\"\n    }\n  };\n}\n\nfunction connectionIdOf(address: unknown): string | undefined {\n  return typeof address === \"object\" &&\n    address !== null &&\n    \"connectionId\" in address &&\n    typeof address.connectionId === \"string\"\n    ? address.connectionId\n    : undefined;\n}\n\nfunction toFrame(\n  update: ConversationUpdate,\n  conversationId: string,\n  you: Participant,\n  operations: readonly ConversationOperation[]\n): ServerFrame {\n  switch (update.type) {\n    case \"turn\":\n      return { type: \"channels:turn\", conversationId, turn: update.turn };\n    case \"messages\":\n      return {\n        type: \"channels:messages\",\n        conversationId,\n        messages: update.messages\n      };\n    case \"reset\":\n      return {\n        type: \"channels:snapshot\",\n        conversationId,\n        you,\n        operations: [...operations],\n        messages: [],\n        turns: []\n      };\n    case \"response-end\":\n      return {\n        type: \"channels:end\",\n        conversationId,\n        responseId: update.responseId,\n        state: update.ending\n      };\n  }\n}\n\n/** A failed send to one stale socket must not stop delivery to the rest. */\nfunction send(connection: Connection, frame: ServerFrame): void {\n  try {\n    connection.send(JSON.stringify(frame));\n  } catch {\n    // The socket is closing; its close handler cleans up.\n  }\n}\n","import type {\n  Awaitable,\n  Channel,\n  ChannelUpgradeMatch,\n  ParticipantResult\n} from \"../channel\";\nimport { participantRoute } from \"../internal\";\nimport type { Participant } from \"../protocol\";\n\n/** How the gateway takes the Web Channel's WebSocket upgrades. */\nexport type WebIngressOptions = {\n  /**\n   * Who is connecting, from request data you can verify, such as a session\n   * cookie or an Access JWT. Return null to refuse the upgrade.\n   */\n  participant(request: Request): Awaitable<ParticipantResult>;\n  /**\n   * The agent object the participant reaches, or null to refuse them. That\n   * object is the authorization boundary: whoever reaches it may use every\n   * conversation in it. Default: an agent object of the participant's own.\n   */\n  route?(request: Request, participant: Participant): Awaitable<string | null>;\n  /**\n   * Which upgrades are for the Web Channel, and the conversation each\n   * follows. Return undefined for one that is not. Default: `/channels`,\n   * or `/channels/<conversation>`.\n   */\n  match?(request: Request): ChannelUpgradeMatch | undefined;\n};\n\n/**\n * The Web Channel's side in the gateway: it resolves each WebSocket upgrade\n * and forwards it to the agent, whose `WebChannel` serves the connection.\n *\n * ```ts\n * new ChannelGateway({\n *   agent: (route) => env.SupportAgent.getByName(route),\n *   channels: {\n *     web: web({\n *       participant: async (request) =>\n *         (await verifySession(request, env))?.id ?? null\n *     })\n *   }\n * });\n * ```\n */\nexport function web(options: WebIngressOptions): Channel {\n  const route = options.route;\n  return {\n    upgrade: {\n      match: options.match ?? matchChannelsPath,\n      participant: (request) => options.participant(request),\n      route: (request, participant) =>\n        route ? route(request, participant) : participantRoute(participant)\n    }\n  };\n}\n\nfunction matchChannelsPath(request: Request): ChannelUpgradeMatch | undefined {\n  const match = /^\\/channels(?:\\/([^/]+))?$/.exec(\n    new URL(request.url).pathname\n  );\n  if (!match) return undefined;\n  return match[1] === undefined\n    ? {}\n    : { conversationId: decodeURIComponent(match[1]) };\n}\n"],"mappings":"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"}

package/dist/gateway-BDC07gYO.d.ts

@@ -0,0 +1,100 @@
+import {
+  N as ChannelIdentity,
+  S as ChannelEmailInput,
+  a as ChannelDeliveryOptions,
+  k as ChannelIngressEvent,
+  l as ChannelStreamOptions,
+  n as Channel,
+  o as ChannelMessage,
+  p as DeliveryResult,
+  r as ChannelChunkSource
+} from "./channel-Bak_6zDP.js";
+import {
+  b as ChannelMessageSurface,
+  p as Participant,
+  s as GatewayOrigin
+} from "./protocol-CukuI73M.js";
+import { c as GatewayEvent } from "./conversations-DH0ut_8n.js";
+
+//#region src/experimental/channels/gateway.d.ts
+type ChannelRouteEvent = {
+  channelKey: string;
+  event: ChannelIngressEvent /** Who the Channel resolved the sender as; null when it refused them. */;
+  participant: Participant | null /** The agent object the event reaches; null when it is ignored or refused. */;
+  route:
+    | string
+    | null /** Stable identity derived only from the configured Channel and eventId. */;
+  dispatchId: string;
+};
+/** The agent object a route names, as the gateway reaches it. */
+type GatewayAgent = {
+  /** Hand the agent an inbound event; Channels' `receive` serves it. */ receive(
+    event: GatewayEvent,
+    origin: GatewayOrigin
+  ): Promise<unknown>;
+  fetch(request: Request): Promise<Response>;
+};
+type ChannelGatewayOptions = {
+  /**
+   * The Channels this Worker serves. Each one that takes ingress says who
+   * its senders are (`participant`) and which agent object they reach
+   * (`route`).
+   */
+  channels: Record<string, Channel> /** The agent object a route names. */;
+  agent(
+    route: string
+  ): GatewayAgent /** Observes every valid route outcome before it is sent to the agent. */;
+  onRoute?(event: ChannelRouteEvent): void | Promise<void>;
+};
+/**
+ * The Worker's entry point for Channels. Authenticates and normalizes
+ * webhooks, resolves WebSocket upgrades, routes each to the agent object
+ * its route names, and sends to surfaces.
+ *
+ * The gateway is the trust boundary. It alone decides who a sender is and
+ * tells the agent, so an agent serving Channels must be reachable only
+ * through it: an app that forwards an upgrade to the agent some other way
+ * (another fetch handler, `routeAgentRequest`, RPC) lets the caller pick
+ * its own participant and conversation.
+ *
+ * The agent object is the authorization boundary. Whoever a Channel routes
+ * to an object may list, join, create, fork and reset every conversation in
+ * it. To keep people apart, route them to different objects; by default
+ * each participant gets an object of their own.
+ */
+declare class ChannelGateway {
+  #private;
+  constructor(options: ChannelGatewayOptions);
+  /** Serve a request if it is for Channels, or return undefined. */
+  fetch(request: Request): Promise<Response | undefined>;
+  handleEmail(email: ChannelEmailInput): Promise<boolean>;
+  /** Deliver through the configured Channel named by the surface. */
+  deliver(
+    surface: ChannelMessageSurface,
+    message: ChannelMessage,
+    options?: ChannelDeliveryOptions
+  ): Promise<DeliveryResult>;
+  /**
+   * Deliver a progressively generated answer to the Channel
+   * named by the surface.
+   *
+   * A Channel that can stream consumes the stream itself. A Channel that
+   * cannot never learns it was a stream, because the Host collects the answer
+   * and calls `deliver` once.
+   */
+  stream(
+    surface: ChannelMessageSurface,
+    chunks: ChannelChunkSource,
+    options?: ChannelStreamOptions
+  ): Promise<DeliveryResult>;
+  /** Return the identity's configured Channel destination, when supported. */
+  contactSurface(identity: ChannelIdentity): ChannelMessageSurface | null;
+}
+//#endregion
+export {
+  GatewayAgent as i,
+  ChannelGatewayOptions as n,
+  ChannelRouteEvent as r,
+  ChannelGateway as t
+};
+//# sourceMappingURL=gateway-BDC07gYO.d.ts.map