@agentuity/runtime 0.0.104 → 0.0.106

package/src/handlers/sse.ts

@@ -0,0 +1,118 @@
+import type { Context, Handler } from 'hono';
+import { streamSSE as honoStreamSSE } from 'hono/streaming';
+import { getAgentAsyncLocalStorage } from '../_context';
+import type { Env } from '../app';
+
+/**
+ * SSE message format for Server-Sent Events.
+ */
+export interface SSEMessage {
+	data: string;
+	event?: string;
+	id?: string;
+	retry?: number;
+}
+
+/**
+ * SSE stream interface for writing Server-Sent Events.
+ */
+export interface SSEStream {
+	/**
+	 * Write a simple value as SSE data.
+	 * Strings, numbers, and booleans are converted to string data.
+	 * Objects are passed through as SSE message format.
+	 */
+	write: (data: string | number | boolean | SSEMessage) => Promise<void>;
+	/**
+	 * Write a properly formatted SSE message.
+	 */
+	writeSSE: (message: SSEMessage) => Promise<void>;
+	/**
+	 * Register a callback for when the client aborts the connection.
+	 */
+	onAbort: (callback: () => void) => void;
+	/**
+	 * Close the SSE stream.
+	 */
+	close: () => void;
+}
+
+/**
+ * Handler function for SSE connections.
+ * Receives the Hono context and SSE stream with a flattened signature.
+ */
+export type SSEHandler<E extends Env = Env> = (
+	c: Context<E>,
+	stream: SSEStream
+) => void | Promise<void>;
+
+/**
+ * Creates an SSE (Server-Sent Events) middleware for streaming updates to clients.
+ *
+ * Use with router.get() to create an SSE endpoint:
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, sse } from '@agentuity/runtime';
+ *
+ * const router = createRouter();
+ *
+ * router.get('/events', sse((c, stream) => {
+ *   let count = 0;
+ *   const interval = setInterval(() => {
+ *     stream.writeSSE({
+ *       data: `Event ${++count}`,
+ *       event: 'update'
+ *     });
+ *     if (count >= 10) {
+ *       clearInterval(interval);
+ *       stream.close();
+ *     }
+ *   }, 1000);
+ *
+ *   stream.onAbort(() => {
+ *     clearInterval(interval);
+ *   });
+ * }));
+ * ```
+ *
+ * @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> {
+	return (c: Context<E>) => {
+		const asyncLocalStorage = getAgentAsyncLocalStorage();
+		const capturedContext = asyncLocalStorage.getStore();
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		return honoStreamSSE(c, async (stream: any) => {
+			const wrappedStream: SSEStream = {
+				write: async (data) => {
+					if (
+						typeof data === 'string' ||
+						typeof data === 'number' ||
+						typeof data === 'boolean'
+					) {
+						return stream.writeSSE({ data: String(data) });
+					} else if (typeof data === 'object' && data !== null) {
+						return stream.writeSSE(data);
+					}
+					return stream.writeSSE({ data: String(data) });
+				},
+				writeSSE: stream.writeSSE.bind(stream),
+				onAbort: stream.onAbort.bind(stream),
+				close: stream.close?.bind(stream) ?? (() => {}),
+			};
+
+			const runInContext = async () => {
+				await handler(c, wrappedStream);
+			};
+
+			if (capturedContext) {
+				await asyncLocalStorage.run(capturedContext, runInContext);
+			} else {
+				await runInContext();
+			}
+		});
+	};
+}

package/src/handlers/stream.ts

@@ -0,0 +1,86 @@
+import type { Context, Handler } from 'hono';
+import { stream as honoStream } from 'hono/streaming';
+import { getAgentAsyncLocalStorage } from '../_context';
+import type { Env } from '../app';
+
+/**
+ * Handler function for streaming responses.
+ * Returns a ReadableStream that will be piped to the response.
+ */
+export type StreamHandler<E extends Env = Env> = (
+	c: Context<E>
+) => ReadableStream<Uint8Array | string> | Promise<ReadableStream<Uint8Array | string>>;
+
+/**
+ * Creates a streaming middleware for returning ReadableStream responses.
+ *
+ * Use with router.post() (or any HTTP method) to create a streaming endpoint:
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, stream } from '@agentuity/runtime';
+ *
+ * const router = createRouter();
+ *
+ * router.post('/events', stream((c) => {
+ *   return new ReadableStream({
+ *     start(controller) {
+ *       controller.enqueue('event 1\n');
+ *       controller.enqueue('event 2\n');
+ *       controller.close();
+ *     }
+ *   });
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async stream with data from request body
+ * router.post('/process', stream(async (c) => {
+ *   const body = await c.req.json();
+ *
+ *   return new ReadableStream({
+ *     async start(controller) {
+ *       for (const item of body.items) {
+ *         controller.enqueue(`Processing: ${item}\n`);
+ *         await new Promise(r => setTimeout(r, 100));
+ *       }
+ *       controller.close();
+ *     }
+ *   });
+ * }));
+ * ```
+ *
+ * @param handler - Handler function returning a ReadableStream
+ * @returns Hono handler for streaming response
+ */
+export function stream<E extends Env = Env>(handler: StreamHandler<E>): Handler<E> {
+	return (c: Context<E>) => {
+		const asyncLocalStorage = getAgentAsyncLocalStorage();
+		const capturedContext = asyncLocalStorage.getStore();
+
+		c.header('Content-Type', 'application/octet-stream');
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		return honoStream(c, async (s: any) => {
+			const runInContext = async () => {
+				try {
+					let streamResult = handler(c);
+					if (streamResult instanceof Promise) {
+						streamResult = await streamResult;
+					}
+					await s.pipe(streamResult);
+				} catch (err) {
+					c.var.logger?.error('Stream error:', err);
+					throw err;
+				}
+			};
+
+			if (capturedContext) {
+				await asyncLocalStorage.run(capturedContext, runInContext);
+			} else {
+				await runInContext();
+			}
+		});
+	};
+}

package/src/handlers/websocket.ts

@@ -0,0 +1,153 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { upgradeWebSocket } from 'hono/bun';
+import { getAgentAsyncLocalStorage } from '../_context';
+import type { Env } from '../app';
+
+/**
+ * WebSocket connection interface for handling WebSocket events.
+ */
+export interface WebSocketConnection {
+	onOpen: (handler: (event: Event) => void | Promise<void>) => void;
+	onMessage: (handler: (event: MessageEvent) => void | Promise<void>) => void;
+	onClose: (handler: (event: CloseEvent) => void | Promise<void>) => void;
+	send: (data: string | ArrayBuffer | Uint8Array) => void;
+}
+
+/**
+ * Handler function for WebSocket connections.
+ * Receives the Hono context and WebSocket connection with a flattened signature.
+ */
+export type WebSocketHandler<E extends Env = Env> = (
+	c: Context<E>,
+	ws: WebSocketConnection
+) => void | Promise<void>;
+
+/**
+ * Creates a WebSocket middleware for handling WebSocket connections.
+ *
+ * Use with router.get() to create a WebSocket endpoint:
+ *
+ * @example
+ * ```typescript
+ * import { createRouter, websocket } from '@agentuity/runtime';
+ *
+ * const router = createRouter();
+ *
+ * router.get('/ws', websocket((c, ws) => {
+ *   ws.onOpen(() => {
+ *     c.var.logger.info('WebSocket opened');
+ *     ws.send('Welcome!');
+ *   });
+ *
+ *   ws.onMessage((event) => {
+ *     c.var.logger.info('Received:', event.data);
+ *     ws.send('Echo: ' + event.data);
+ *   });
+ *
+ *   ws.onClose(() => {
+ *     c.var.logger.info('WebSocket closed');
+ *   });
+ * }));
+ * ```
+ *
+ * @param handler - Handler function receiving context and WebSocket connection
+ * @returns Hono middleware handler for WebSocket upgrade
+ */
+export function websocket<E extends Env = Env>(handler: WebSocketHandler<E>): MiddlewareHandler<E> {
+	const wsHandler = upgradeWebSocket((c: Context<E>) => {
+		let openHandler: ((event: Event) => void | Promise<void>) | undefined;
+		let messageHandler: ((event: MessageEvent) => void | Promise<void>) | undefined;
+		let closeHandler: ((event: CloseEvent) => void | Promise<void>) | undefined;
+		let initialized = false;
+
+		const asyncLocalStorage = getAgentAsyncLocalStorage();
+		const capturedContext = asyncLocalStorage.getStore();
+
+		const wsConnection: WebSocketConnection = {
+			onOpen: (h) => {
+				openHandler = h;
+			},
+			onMessage: (h) => {
+				messageHandler = h;
+			},
+			onClose: (h) => {
+				closeHandler = h;
+			},
+			send: (_data: string | ArrayBuffer | Uint8Array) => {
+				// This will be bound to the actual ws in the handlers
+			},
+		};
+
+		const runHandler = () => {
+			if (capturedContext) {
+				asyncLocalStorage.run(capturedContext, () => handler(c, wsConnection));
+			} else {
+				handler(c, wsConnection);
+			}
+			initialized = true;
+		};
+
+		runHandler();
+
+		return {
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onOpen: async (event: Event, ws: any) => {
+				try {
+					wsConnection.send = (data) => ws.send(data);
+
+					if (openHandler) {
+						const h = openHandler;
+						if (capturedContext) {
+							await asyncLocalStorage.run(capturedContext, () => h(event));
+						} else {
+							await h(event);
+						}
+					}
+				} catch (err) {
+					c.var.logger?.error('WebSocket onOpen error:', err);
+					throw err;
+				}
+			},
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onMessage: async (event: MessageEvent, ws: any) => {
+				try {
+					if (!initialized) {
+						wsConnection.send = (data) => ws.send(data);
+						runHandler();
+					}
+					if (messageHandler) {
+						const h = messageHandler;
+						if (capturedContext) {
+							await asyncLocalStorage.run(capturedContext, () => h(event));
+						} else {
+							await h(event);
+						}
+					}
+				} catch (err) {
+					c.var.logger?.error('WebSocket onMessage error:', err);
+					throw err;
+				}
+			},
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			onClose: async (event: CloseEvent, _ws: any) => {
+				try {
+					if (closeHandler) {
+						const h = closeHandler;
+						if (capturedContext) {
+							await asyncLocalStorage.run(capturedContext, () => h(event));
+						} else {
+							await h(event);
+						}
+					}
+				} catch (err) {
+					c.var.logger?.error('WebSocket onClose error:', err);
+				}
+			},
+		};
+	});
+
+	const middleware: MiddlewareHandler<E> = (c, next) =>
+		(wsHandler as unknown as MiddlewareHandler<E>)(c, next);
+
+	return middleware;
+}

package/src/index.ts

@@ -65,6 +65,21 @@ export { registerDevModeRoutes } from './devmode';
 // router.ts exports
 export { type HonoEnv, type WebSocketConnection, createRouter } from './router';
 
+// protocol handler exports (websocket, sse, stream, cron)
+export {
+	websocket,
+	type WebSocketHandler,
+	sse,
+	type SSEMessage,
+	type SSEStream,
+	type SSEHandler,
+	stream,
+	type StreamHandler,
+	cron,
+	type CronHandler,
+	type CronMetadata,
+} from './handlers';
+
 // eval.ts exports
 export {
 	EvalHandlerResultSchema,
@@ -143,9 +158,6 @@ export {
 	type InvokeOptions,
 } from './_standalone';
 
-// io/email exports
-export { Email, parseEmail } from './io/email';
-
 // services/evalrun exports
 export {
 	HTTPEvalRunEventProvider,
@@ -204,3 +216,6 @@ export interface AppState {}
 // This allows generated code to import from @agentuity/runtime instead of having
 // a direct dependency on @agentuity/server
 export { bootstrapRuntimeEnv, type RuntimeBootstrapOptions } from '@agentuity/server';
+
+// bun-s3-patch.ts exports
+export { patchBunS3ForStorageDev, isAgentuityStorageEndpoint } from './bun-s3-patch';

package/src/middleware.ts

@@ -38,6 +38,7 @@ export const AGENT_CONTEXT_PROPERTIES = [
 	'kv',
 	'stream',
 	'vector',
+	'sandbox',
 	'state',
 	'thread',
 	'session',
@@ -94,6 +95,7 @@ export function createBaseMiddleware(config: MiddlewareConfig) {
 		c.set('kv', services.kv);
 		c.set('stream', services.stream);
 		c.set('vector', services.vector);
+		c.set('sandbox', services.sandbox);
 
 		installContextPropertyHelpers(c);
 
@@ -278,17 +280,17 @@ export function createOtelMiddleware() {
 					(c as any).set('trigger', 'api');
 
 					// Send session start event (so evalruns can reference this session)
+					// The provider decides whether to send based on available data (orgId, projectId, etc.)
 					const sessionEventProvider = getSessionEventProvider();
-					const shouldSendSession = !!(orgId && projectId);
-					if (shouldSendSession && sessionEventProvider) {
+					if (sessionEventProvider) {
 						try {
 							// eslint-disable-next-line @typescript-eslint/no-explicit-any
 							const routeId = (c as any).var?.routeId || '';
 							await sessionEventProvider.start({
 								id: sessionId,
 								threadId: thread.id,
-								orgId,
-								projectId,
+								orgId: orgId || '',
+								projectId: projectId || '',
 								deploymentId: deploymentId || undefined,
 								devmode: isDevMode,
 								trigger: 'api',
@@ -322,12 +324,8 @@ export function createOtelMiddleware() {
 						throw ex;
 					} finally {
 						// Send session complete event
-						internal.info(
-							'[session] shouldSendSession: %s, hasSessionEventProvider: %s',
-							shouldSendSession,
-							!!sessionEventProvider
-						);
-						if (shouldSendSession && sessionEventProvider) {
+						// The provider decides whether to actually send based on its requirements
+						if (sessionEventProvider) {
 							try {
 								const userData = session.serializeUserData();
 								internal.info(

package/src/otel/logger.ts

@@ -5,9 +5,20 @@ import type { Logger } from '../logger';
 import ConsoleLogger from '../logger/console';
 
 /**
- * Reference to the original console object before patching
+ * Reference to the original console object before patching.
+ * We use a global symbol to ensure we only capture the original console once,
+ * preventing double-patching on hot reload.
  */
-export const __originalConsole = Object.create(console); // save the original console before we patch it
+const ORIGINAL_CONSOLE_KEY = Symbol.for('agentuity.originalConsole');
+
+// Check if we've already saved the original console (prevents double-patching on reload)
+const existingOriginal = (globalThis as Record<symbol, Console>)[ORIGINAL_CONSOLE_KEY];
+export const __originalConsole: Console = existingOriginal ?? Object.create(console);
+
+// Save to global if not already saved
+if (!existingOriginal) {
+	(globalThis as Record<symbol, Console>)[ORIGINAL_CONSOLE_KEY] = __originalConsole;
+}
 
 export class OtelLogger implements Logger {
 	private readonly delegate: LogsAPI.Logger;