@agentuity/runtime 1.0.1 → 1.0.3

package/src/handlers/sse.ts

@@ -1,9 +1,19 @@
 import type { Context, Handler } from 'hono';
 import { stream as honoStream } from 'hono/streaming';
 import { context as otelContext, ROOT_CONTEXT } from '@opentelemetry/api';
+import { StructuredError } from '@agentuity/core';
+import type { Schema } from '@agentuity/schema';
 import { getAgentAsyncLocalStorage } from '../_context';
 import type { Env } from '../app';
 
+/**
+ * Error thrown when sse() is called without a handler function.
+ */
+const SSEHandlerMissingError = StructuredError(
+	'SSEHandlerMissingError',
+	'An SSE handler function is required. Use sse(handler) or sse({ output: schema }, handler).'
+);
+
 /**
  * Context variable key for stream completion promise.
  * Used by middleware to defer session/thread saving until stream completes.
@@ -60,6 +70,43 @@ export type SSEHandler<E extends Env = Env> = (
 	stream: SSEStream
 ) => void | Promise<void>;
 
+/**
+ * Options for configuring SSE middleware.
+ *
+ * @template TOutput - The type of data that will be sent through the SSE stream.
+ *   This is used for type inference in generated route registries and does not
+ *   perform runtime validation (SSE data is serialized via JSON.stringify).
+ */
+export interface SSEOptions<TOutput = unknown> {
+	/**
+	 * Schema defining the output type for SSE events.
+	 *
+	 * This schema is used for:
+	 * - Type inference in generated `routes.ts` registry
+	 * - Automatic typing of `useEventStream` hook's `data` property
+	 *
+	 * The schema is NOT used for runtime validation - SSE messages are sent
+	 * as-is through the stream. Use this for TypeScript type safety only.
+	 *
+	 * @example
+	 * ```typescript
+	 * import { s } from '@agentuity/schema';
+	 *
+	 * const StreamEventSchema = s.object({
+	 *   type: s.enum(['token', 'complete', 'error']),
+	 *   content: s.optional(s.string()),
+	 * });
+	 *
+	 * router.get('/stream', sse({ output: StreamEventSchema }, async (c, stream) => {
+	 *   await stream.writeSSE({ data: JSON.stringify({ type: 'token', content: 'Hello' }) });
+	 *   await stream.writeSSE({ data: JSON.stringify({ type: 'complete' }) });
+	 *   stream.close();
+	 * }));
+	 * ```
+	 */
+	output: Schema<TOutput, TOutput>;
+}
+
 /**
  * Format an SSE message according to the SSE specification.
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
@@ -95,7 +142,7 @@ function formatSSEMessage(message: SSEMessage): string {
  *
  * Use with router.get() to create an SSE endpoint:
  *
- * @example
+ * @example Basic SSE without typed output
  * ```typescript
  * import { createRouter, sse } from '@agentuity/runtime';
  *
@@ -120,11 +167,64 @@ function formatSSEMessage(message: SSEMessage): string {
  * }));
  * ```
  *
+ * @example SSE with typed output schema
+ * ```typescript
+ * import { createRouter, sse } from '@agentuity/runtime';
+ * import { s } from '@agentuity/schema';
+ *
+ * // Define your SSE event schema
+ * export const outputSchema = s.object({
+ *   type: s.enum(['token', 'complete', 'error']),
+ *   content: s.optional(s.string()),
+ * });
+ *
+ * const router = createRouter();
+ *
+ * // Pass schema as first argument for typed SSE routes
+ * router.get('/stream', sse({ output: outputSchema }, async (c, stream) => {
+ *   await stream.writeSSE({ data: JSON.stringify({ type: 'token', content: 'Hello' }) });
+ *   await stream.writeSSE({ data: JSON.stringify({ type: 'complete' }) });
+ *   stream.close();
+ * }));
+ *
+ * // On the frontend, useEventStream will now have typed data:
+ * // const { data } = useEventStream('/api/stream');
+ * // data.type is 'token' | 'complete' | 'error'
+ * ```
+ *
  * @param handler - Handler function receiving context and SSE stream
+ * @param options - Optional configuration with output schema for type inference
  * @returns Hono handler for SSE streaming
  * @see https://github.com/agentuity/sdk/issues/471
+ * @see https://github.com/agentuity/sdk/issues/855
+ */
+export function sse<E extends Env = Env>(handler: SSEHandler<E>): Handler<E>;
+/**
+ * Creates an SSE middleware with typed output schema.
+ *
+ * @param options - Configuration object containing the output schema
+ * @param handler - Handler function receiving context and SSE stream
+ * @returns Hono handler for SSE streaming
  */
-export function sse<E extends Env = Env>(handler: SSEHandler<E>): Handler<E> {
+export function sse<E extends Env = Env, TOutput = unknown>(
+	options: SSEOptions<TOutput>,
+	handler: SSEHandler<E>
+): Handler<E>;
+export function sse<E extends Env = Env, TOutput = unknown>(
+	handlerOrOptions: SSEHandler<E> | SSEOptions<TOutput>,
+	maybeHandler?: SSEHandler<E>
+): Handler<E> {
+	// Determine if first arg is options or handler
+	const handler: SSEHandler<E> | undefined =
+		typeof handlerOrOptions === 'function' ? handlerOrOptions : maybeHandler;
+
+	// Validate handler is provided - catches sse({ output }) without handler
+	if (!handler) {
+		throw new SSEHandlerMissingError();
+	}
+
+	// Note: options.output is captured for type inference but not used at runtime
+	// The CLI extracts this during build to generate typed route registries
 	return (c: Context<E>) => {
 		const asyncLocalStorage = getAgentAsyncLocalStorage();
 		const capturedContext = asyncLocalStorage.getStore();

package/src/handlers/webrtc.ts

@@ -0,0 +1,125 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { upgradeWebSocket } from 'hono/bun';
+import { context as otelContext, ROOT_CONTEXT } from '@opentelemetry/api';
+import { getAgentAsyncLocalStorage } from '../_context';
+import type { Env } from '../app';
+import { WebRTCRoomManager, type WebRTCOptions } from '../webrtc-signaling';
+import type { WebSocketConnection } from './websocket';
+
+export type { WebRTCOptions };
+
+/**
+ * Handler function for WebRTC signaling connections.
+ * Receives the Hono context and WebRTCRoomManager.
+ */
+export type WebRTCHandler<E extends Env = Env> = (
+	c: Context<E>,
+	roomManager: WebRTCRoomManager
+) => void | Promise<void>;
+
+/**
+ * Creates a WebRTC signaling middleware for peer-to-peer communication.
+ *
+ * This middleware sets up a WebSocket-based signaling server that handles:
+ * - Room membership and peer discovery
+ * - SDP offer/answer relay
+ * - ICE candidate relay
+ *
+ * Use with router.get() to create a WebRTC signaling endpoint:
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, webrtc } from '@agentuity/runtime';
+ *
+ * const router = createRouter();
+ *
+ * // Basic signaling endpoint
+ * router.get('/call/signal', webrtc());
+ *
+ * // With options
+ * router.get('/call/signal', webrtc({ maxPeers: 4 }));
+ *
+ * // With callbacks for monitoring
+ * router.get('/call/signal', webrtc({
+ *   maxPeers: 2,
+ *   callbacks: {
+ *     onRoomCreated: (roomId) => console.log(`Room ${roomId} created`),
+ *     onPeerJoin: (peerId, roomId) => console.log(`${peerId} joined ${roomId}`),
+ *     onPeerLeave: (peerId, roomId, reason) => {
+ *       console.log(`${peerId} left ${roomId}: ${reason}`);
+ *     },
+ *   },
+ * }));
+ * ```
+ *
+ * @param options - Configuration options for WebRTC signaling
+ * @returns Hono middleware handler for WebSocket upgrade
+ */
+export function webrtc<E extends Env = Env>(options?: WebRTCOptions): MiddlewareHandler<E> {
+	const roomManager = new WebRTCRoomManager(options);
+
+	const wsHandler = upgradeWebSocket((_c: Context<E>) => {
+		let currentWs: WebSocketConnection | undefined;
+		// we need a Privder interface here with AsyncLocalStorage and KV
+		const asyncLocalStorage = getAgentAsyncLocalStorage();
+		const capturedContext = asyncLocalStorage.getStore();
+
+		return {
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onOpen: (_event: Event, ws: any) => {
+				otelContext.with(ROOT_CONTEXT, () => {
+					if (capturedContext) {
+						asyncLocalStorage.run(capturedContext, () => {
+							currentWs = {
+								onOpen: () => {},
+								onMessage: () => {},
+								onClose: () => {},
+								send: (data) => ws.send(data),
+							};
+						});
+					} else {
+						currentWs = {
+							onOpen: () => {},
+							onMessage: () => {},
+							onClose: () => {},
+							send: (data) => ws.send(data),
+						};
+					}
+				});
+			},
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onMessage: (event: MessageEvent, _ws: any) => {
+				if (currentWs) {
+					otelContext.with(ROOT_CONTEXT, () => {
+						if (capturedContext) {
+							asyncLocalStorage.run(capturedContext, () => {
+								roomManager.handleMessage(currentWs!, String(event.data));
+							});
+						} else {
+							roomManager.handleMessage(currentWs!, String(event.data));
+						}
+					});
+				}
+			},
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onClose: (_event: CloseEvent, _ws: any) => {
+				if (currentWs) {
+					otelContext.with(ROOT_CONTEXT, () => {
+						if (capturedContext) {
+							asyncLocalStorage.run(capturedContext, () => {
+								roomManager.handleDisconnect(currentWs!);
+							});
+						} else {
+							roomManager.handleDisconnect(currentWs!);
+						}
+					});
+				}
+			},
+		};
+	});
+
+	const middleware: MiddlewareHandler<E> = (c, next) =>
+		(wsHandler as unknown as MiddlewareHandler<E>)(c, next);
+
+	return middleware;
+}

package/src/index.ts

@@ -77,7 +77,7 @@ export { registerDevModeRoutes } from './devmode';
 // router.ts exports
 export { type HonoEnv, type WebSocketConnection, createRouter } from './router';
 
-// protocol handler exports (websocket, sse, stream, cron)
+// protocol handler exports (websocket, sse, stream, cron, webrtc)
 export {
 	websocket,
 	type WebSocketHandler,
@@ -85,13 +85,26 @@ export {
 	type SSEMessage,
 	type SSEStream,
 	type SSEHandler,
+	type SSEOptions,
 	stream,
 	type StreamHandler,
 	cron,
 	type CronHandler,
 	type CronMetadata,
+	webrtc,
+	type WebRTCHandler,
 } from './handlers';
 
+// webrtc-signaling.ts exports
+export {
+	type SignalMessage,
+	type SDPDescription,
+	type ICECandidate,
+	type WebRTCOptions,
+	type WebRTCSignalingCallbacks,
+	WebRTCRoomManager,
+} from './webrtc-signaling';
+
 // eval.ts exports
 export {
 	EvalHandlerResultSchema,

package/src/router.ts

@@ -83,6 +83,7 @@ declare module 'hono' {
  * - **sse()** - Server-Sent Events (import { sse } from '@agentuity/runtime')
  * - **stream()** - Streaming responses (import { stream } from '@agentuity/runtime')
  * - **cron()** - Scheduled tasks (import { cron } from '@agentuity/runtime')
+ * - **webrtc()** - WebRTC signaling (import { webrtc } from '@agentuity/runtime')
  *
  * @template E - Environment type (Hono Env)
  * @template S - Schema type for route definitions

package/src/webrtc-signaling.ts

@@ -0,0 +1,288 @@
+import type { WebSocketConnection } from './handlers/websocket';
+import type {
+	SDPDescription,
+	ICECandidate,
+	SignalMessage,
+	WebRTCSignalingCallbacks,
+} from '@agentuity/core';
+
+export type { SDPDescription, ICECandidate, SignalMessage, WebRTCSignalingCallbacks };
+
+/**
+ * Configuration options for WebRTC signaling.
+ */
+export interface WebRTCOptions {
+	/** Maximum number of peers per room (default: 2) */
+	maxPeers?: number;
+	/** Callbacks for signaling events */
+	callbacks?: WebRTCSignalingCallbacks;
+}
+
+interface PeerConnection {
+	ws: WebSocketConnection;
+	roomId: string;
+}
+
+/**
+ * In-memory room manager for WebRTC signaling.
+ * Tracks rooms and their connected peers.
+ *
+ * @example
+ * ```ts
+ * import { createRouter, webrtc } from '@agentuity/runtime';
+ *
+ * const router = createRouter();
+ *
+ * // Basic usage
+ * router.get('/call/signal', webrtc());
+ *
+ * // With callbacks for monitoring
+ * router.get('/call/signal', webrtc({
+ *   maxPeers: 2,
+ *   callbacks: {
+ *     onRoomCreated: (roomId) => console.log(`Room ${roomId} created`),
+ *     onPeerJoin: (peerId, roomId) => console.log(`${peerId} joined ${roomId}`),
+ *     onPeerLeave: (peerId, roomId, reason) => {
+ *       analytics.track('peer_left', { peerId, roomId, reason });
+ *     },
+ *     onMessage: (type, from, to, roomId) => {
+ *       metrics.increment(`webrtc.${type}`);
+ *     },
+ *   },
+ * }));
+ * ```
+ */
+export class WebRTCRoomManager {
+	// roomId -> Map<peerId, PeerConnection>
+	private rooms = new Map<string, Map<string, PeerConnection>>();
+	// ws -> peerId (reverse lookup for cleanup)
+	private wsToPeer = new Map<WebSocketConnection, { peerId: string; roomId: string }>();
+	private maxPeers: number;
+	private peerIdCounter = 0;
+	private callbacks: WebRTCSignalingCallbacks;
+
+	constructor(options?: WebRTCOptions) {
+		this.maxPeers = options?.maxPeers ?? 2;
+		this.callbacks = options?.callbacks ?? {};
+	}
+
+	private generatePeerId(): string {
+		return `peer-${Date.now()}-${++this.peerIdCounter}`;
+	}
+
+	private send(ws: WebSocketConnection, msg: SignalMessage): void {
+		ws.send(JSON.stringify(msg));
+	}
+
+	private broadcast(roomId: string, msg: SignalMessage, excludePeerId?: string): void {
+		const room = this.rooms.get(roomId);
+		if (!room) return;
+
+		for (const [peerId, peer] of room) {
+			if (peerId !== excludePeerId) {
+				this.send(peer.ws, msg);
+			}
+		}
+	}
+
+	/**
+	 * Handle a peer joining a room
+	 */
+	handleJoin(ws: WebSocketConnection, roomId: string): void {
+		let room = this.rooms.get(roomId);
+		const isNewRoom = !room;
+
+		// Create room if it doesn't exist
+		if (!room) {
+			room = new Map();
+			this.rooms.set(roomId, room);
+		}
+
+		// Check room capacity
+		if (room.size >= this.maxPeers) {
+			const error = new Error(`Room is full (max ${this.maxPeers} peers)`);
+			this.callbacks.onError?.(error, undefined, roomId);
+			this.send(ws, { t: 'error', message: error.message });
+			return;
+		}
+
+		const peerId = this.generatePeerId();
+		const existingPeers = Array.from(room.keys());
+
+		// Add peer to room
+		room.set(peerId, { ws, roomId });
+		this.wsToPeer.set(ws, { peerId, roomId });
+
+		// Fire callbacks
+		if (isNewRoom) {
+			this.callbacks.onRoomCreated?.(roomId);
+		}
+		this.callbacks.onPeerJoin?.(peerId, roomId);
+
+		// Send joined confirmation with list of existing peers
+		this.send(ws, { t: 'joined', peerId, roomId, peers: existingPeers });
+
+		// Notify existing peers about new peer
+		this.broadcast(roomId, { t: 'peer-joined', peerId }, peerId);
+	}
+
+	/**
+	 * Handle a peer disconnecting
+	 */
+	handleDisconnect(ws: WebSocketConnection): void {
+		const peerInfo = this.wsToPeer.get(ws);
+		if (!peerInfo) return;
+
+		const { peerId, roomId } = peerInfo;
+		const room = this.rooms.get(roomId);
+
+		if (room) {
+			room.delete(peerId);
+
+			// Fire callback
+			this.callbacks.onPeerLeave?.(peerId, roomId, 'disconnect');
+
+			// Notify remaining peers
+			this.broadcast(roomId, { t: 'peer-left', peerId });
+
+			// Clean up empty room
+			if (room.size === 0) {
+				this.rooms.delete(roomId);
+				this.callbacks.onRoomDestroyed?.(roomId);
+			}
+		}
+
+		this.wsToPeer.delete(ws);
+	}
+
+	/**
+	 * Relay SDP message to target peer(s)
+	 */
+	handleSDP(ws: WebSocketConnection, to: string | undefined, description: SDPDescription): void {
+		const peerInfo = this.wsToPeer.get(ws);
+		if (!peerInfo) {
+			const error = new Error('Not in a room');
+			this.callbacks.onError?.(error);
+			this.send(ws, { t: 'error', message: error.message });
+			return;
+		}
+
+		const { peerId, roomId } = peerInfo;
+		const room = this.rooms.get(roomId);
+		if (!room) return;
+
+		// Fire callback
+		this.callbacks.onMessage?.('sdp', peerId, to, roomId);
+
+		// Server injects 'from' to prevent spoofing
+		const msg: SignalMessage = { t: 'sdp', from: peerId, description };
+
+		if (to) {
+			// Send to specific peer
+			const targetPeer = room.get(to);
+			if (targetPeer) {
+				this.send(targetPeer.ws, msg);
+			}
+		} else {
+			// Broadcast to all peers in room
+			this.broadcast(roomId, msg, peerId);
+		}
+	}
+
+	/**
+	 * Relay ICE candidate to target peer(s)
+	 */
+	handleICE(ws: WebSocketConnection, to: string | undefined, candidate: ICECandidate): void {
+		const peerInfo = this.wsToPeer.get(ws);
+		if (!peerInfo) {
+			const error = new Error('Not in a room');
+			this.callbacks.onError?.(error);
+			this.send(ws, { t: 'error', message: error.message });
+			return;
+		}
+
+		const { peerId, roomId } = peerInfo;
+		const room = this.rooms.get(roomId);
+		if (!room) return;
+
+		// Fire callback
+		this.callbacks.onMessage?.('ice', peerId, to, roomId);
+
+		// Server injects 'from' to prevent spoofing
+		const msg: SignalMessage = { t: 'ice', from: peerId, candidate };
+
+		if (to) {
+			// Send to specific peer
+			const targetPeer = room.get(to);
+			if (targetPeer) {
+				this.send(targetPeer.ws, msg);
+			}
+		} else {
+			// Broadcast to all peers in room
+			this.broadcast(roomId, msg, peerId);
+		}
+	}
+
+	/**
+	 * Handle incoming signaling message
+	 */
+	handleMessage(ws: WebSocketConnection, data: string): void {
+		let msg: SignalMessage;
+		try {
+			msg = JSON.parse(data);
+		} catch {
+			const error = new Error('Invalid JSON');
+			this.callbacks.onError?.(error);
+			this.send(ws, { t: 'error', message: error.message });
+			return;
+		}
+
+		// Validate message format
+		if (!msg || typeof msg.t !== 'string') {
+			const error = new Error('Invalid message format');
+			this.callbacks.onError?.(error);
+			this.send(ws, { t: 'error', message: error.message });
+			return;
+		}
+
+		switch (msg.t) {
+			case 'join':
+				if (!msg.roomId || typeof msg.roomId !== 'string') {
+					this.send(ws, { t: 'error', message: 'Missing or invalid roomId' });
+					return;
+				}
+				this.handleJoin(ws, msg.roomId);
+				break;
+			case 'sdp':
+				if (!msg.description || typeof msg.description !== 'object') {
+					this.send(ws, { t: 'error', message: 'Missing or invalid description' });
+					return;
+				}
+				this.handleSDP(ws, msg.to, msg.description);
+				break;
+			case 'ice':
+				if (!msg.candidate || typeof msg.candidate !== 'object') {
+					this.send(ws, { t: 'error', message: 'Missing or invalid candidate' });
+					return;
+				}
+				this.handleICE(ws, msg.to, msg.candidate);
+				break;
+			default:
+				this.send(ws, {
+					t: 'error',
+					message: `Unknown message type: ${(msg as { t: string }).t}`,
+				});
+		}
+	}
+
+	/**
+	 * Get room stats for debugging
+	 */
+	getRoomStats(): { roomCount: number; totalPeers: number } {
+		let totalPeers = 0;
+		for (const room of this.rooms.values()) {
+			totalPeers += room.size;
+		}
+		return { roomCount: this.rooms.size, totalPeers };
+	}
+}