@agentuity/runtime 0.0.60 → 0.0.62

package/src/router.ts

@@ -1,6 +1,13 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-empty-object-type */
-import { type Context, Hono, type Input, type MiddlewareHandler, type Schema } from 'hono';
+import {
+	type Context,
+	Hono,
+	type Input,
+	type MiddlewareHandler,
+	type Schema,
+	type Env as HonoEnv,
+} from 'hono';
 import { stream as honoStream, streamSSE as honoStreamSSE } from 'hono/streaming';
 import { upgradeWebSocket as honoUpgradeWebSocket } from 'hono/bun';
 import { hash, returnResponse } from './_util';
@@ -8,6 +15,10 @@ import type { Env } from './app';
 import { getAgentAsyncLocalStorage } from './_context';
 import { parseEmail, type Email } from './io/email';
 
+// Re-export both Env types
+export type { Env };
+export type { HonoEnv };
+
 type AgentHandler<E extends Env = Env, P extends string = string, I extends Input = {}> = (
 	c: Context<E, P, I>
 ) => any | Promise<any>;
@@ -21,7 +32,7 @@ type StreamHandler<E extends Env = Env, P extends string = string, I extends Inp
 	c: Context<E, P, I>
 ) => ReadableStream<any> | Promise<ReadableStream<any>>;
 
-interface WebSocketConnection {
+export interface WebSocketConnection {
 	onOpen: (handler: (event: any) => void | Promise<void>) => void;
 	onMessage: (handler: (event: any) => void | Promise<void>) => void;
 	onClose: (handler: (event: any) => void | Promise<void>) => void;
@@ -36,56 +47,314 @@ type SSEHandler<E extends Env = Env, P extends string = string, I extends Input
 	c: Context<E, P, I>
 ) => (stream: any) => void | Promise<void>;
 
-type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options';
-
-type ExtendedHono<E extends Env = Env, S extends Schema = {}> = {
-	[K in Exclude<keyof Hono<E, S>, HttpMethod>]: Hono<E, S>[K];
-} & {
-	[K in HttpMethod]: {
-		<P extends string = string>(path: P, handler: AgentHandler<E, P>): Hono<E, S>;
-		<P extends string = string, I extends Input = {}>(
-			path: P,
-			middleware: MiddlewareHandler<E, P, I>,
-			handler: AgentHandler<E, P, I>
-		): Hono<E, S>;
-		<P extends string = string, I extends Input = {}>(
-			path: P,
-			middleware: MiddlewareHandler<E, P, I>
-		): Hono<E, S>;
-	};
-} & {
-	email(address: string, handler: EmailHandler): Hono<E, S>;
-	email<I extends Input = {}>(
-		address: string,
-		middleware: MiddlewareHandler<E, string, I>,
-		handler: EmailHandler<E, string, I>
-	): Hono<E, S>;
-	sms(params: { number: string }, handler: AgentHandler): Hono<E, S>;
-	cron(schedule: string, handler: AgentHandler): Hono<E, S>;
-	stream<P extends string = string>(path: P, handler: StreamHandler<E, P>): Hono<E, S>;
-	stream<P extends string = string, I extends Input = {}>(
-		path: P,
-		middleware: MiddlewareHandler<E, P, I>,
-		handler: StreamHandler<E, P, I>
-	): Hono<E, S>;
-	websocket<P extends string = string>(path: P, handler: WebSocketHandler<E, P>): Hono<E, S>;
-	websocket<P extends string = string, I extends Input = {}>(
-		path: P,
-		middleware: MiddlewareHandler<E, P, I>,
-		handler: WebSocketHandler<E, P, I>
-	): Hono<E, S>;
-	sse<P extends string = string>(path: P, handler: SSEHandler<E, P>): Hono<E, S>;
-	sse<P extends string = string, I extends Input = {}>(
-		path: P,
-		middleware: MiddlewareHandler<E, P, I>,
-		handler: SSEHandler<E, P, I>
-	): Hono<E, S>;
-};
+// Module augmentation to add custom methods to Hono
+// This avoids wrapper types and type instantiation depth issues
+// Use simplified signatures to avoid type instantiation depth issues
+declare module 'hono' {
+	interface Hono {
+		/**
+		 * Register a route to handle incoming emails at a specific address.
+		 *
+		 * @param address - The email address to handle (e.g., 'support@example.com')
+		 * @param handler - Handler function receiving parsed email and context
+		 *
+		 * @example
+		 * ```typescript
+		 * router.email('support@example.com', (email, c) => {
+		 *   console.log('From:', email.fromEmail());
+		 *   console.log('Subject:', email.subject());
+		 *   console.log('Body:', email.text());
+		 *   return c.text('Email received');
+		 * });
+		 * ```
+		 */
+		email(address: string, handler: (email: Email, c: Context) => any): this;
+
+		/**
+		 * Register a route to handle incoming emails with middleware.
+		 *
+		 * @param address - The email address to handle
+		 * @param middleware - Middleware to run before the handler
+		 * @param handler - Handler function receiving parsed email and context
+		 *
+		 * @example
+		 * ```typescript
+		 * router.email('support@example.com', authMiddleware, (email, c) => {
+		 *   return c.json({ received: email.subject() });
+		 * });
+		 * ```
+		 */
+		email(
+			address: string,
+			middleware: MiddlewareHandler,
+			handler: (email: Email, c: Context) => any
+		): this;
+
+		/**
+		 * Register a route to handle incoming SMS messages to a phone number.
+		 *
+		 * @param params - Configuration object with phone number
+		 * @param params.number - Phone number to handle (e.g., '+1234567890')
+		 * @param handler - Handler function receiving context
+		 *
+		 * @example
+		 * ```typescript
+		 * router.sms({ number: '+1234567890' }, (c) => {
+		 *   const message = c.req.query('message');
+		 *   console.log('SMS received:', message);
+		 *   return c.text('SMS received');
+		 * });
+		 * ```
+		 */
+		sms(params: { number: string }, handler: (c: Context) => any): this;
+
+		/**
+		 * Schedule a handler to run at specific intervals using cron syntax.
+		 *
+		 * @param schedule - Cron expression (e.g., '0 0 * * *' for daily at midnight)
+		 * @param handler - Handler function to run on schedule
+		 *
+		 * @example
+		 * ```typescript
+		 * // Run daily at midnight
+		 * router.cron('0 0 * * *', (c) => {
+		 *   console.log('Daily cleanup running');
+		 *   return c.text('Cleanup complete');
+		 * });
+		 *
+		 * // Run every hour
+		 * router.cron('0 * * * *', (c) => {
+		 *   console.log('Hourly health check');
+		 *   return c.text('OK');
+		 * });
+		 * ```
+		 */
+		cron(schedule: string, handler: (c: Context) => any): this;
+
+		/**
+		 * Create a streaming route that returns a ReadableStream.
+		 *
+		 * @param path - The route path
+		 * @param handler - Handler returning a ReadableStream
+		 *
+		 * @example
+		 * ```typescript
+		 * router.stream('/events', (c) => {
+		 *   return new ReadableStream({
+		 *     start(controller) {
+		 *       controller.enqueue('event 1\n');
+		 *       controller.enqueue('event 2\n');
+		 *       controller.close();
+		 *     }
+		 *   });
+		 * });
+		 * ```
+		 */
+		stream(
+			path: string,
+			handler: (c: Context) => ReadableStream<any> | Promise<ReadableStream<any>>
+		): this;
+
+		/**
+		 * Create a streaming route with middleware.
+		 *
+		 * @param path - The route path
+		 * @param middleware - Middleware to run before streaming
+		 * @param handler - Handler returning a ReadableStream
+		 *
+		 * @example
+		 * ```typescript
+		 * router.stream('/protected-stream', authMiddleware, (c) => {
+		 *   return new ReadableStream({
+		 *     start(controller) {
+		 *       controller.enqueue('secure data\n');
+		 *       controller.close();
+		 *     }
+		 *   });
+		 * });
+		 * ```
+		 */
+		stream(
+			path: string,
+			middleware: MiddlewareHandler,
+			handler: (c: Context) => ReadableStream<any> | Promise<ReadableStream<any>>
+		): this;
+
+		/**
+		 * Create a WebSocket route for real-time bidirectional communication.
+		 *
+		 * @param path - The route path
+		 * @param handler - Setup function that registers WebSocket event handlers
+		 *
+		 * @example
+		 * ```typescript
+		 * router.websocket('/ws', (c) => (ws) => {
+		 *   ws.onOpen((event) => {
+		 *     console.log('WebSocket opened');
+		 *     ws.send('Welcome!');
+		 *   });
+		 *
+		 *   ws.onMessage((event) => {
+		 *     console.log('Received:', event.data);
+		 *     ws.send('Echo: ' + event.data);
+		 *   });
+		 *
+		 *   ws.onClose((event) => {
+		 *     console.log('WebSocket closed');
+		 *   });
+		 * });
+		 * ```
+		 */
+		websocket(path: string, handler: (c: Context) => (ws: WebSocketConnection) => void): this;
+
+		/**
+		 * Create a WebSocket route with middleware.
+		 *
+		 * @param path - The route path
+		 * @param middleware - Middleware to run before WebSocket upgrade
+		 * @param handler - Setup function that registers WebSocket event handlers
+		 *
+		 * @example
+		 * ```typescript
+		 * router.websocket('/ws', authMiddleware, (c) => (ws) => {
+		 *   ws.onMessage((event) => {
+		 *     ws.send('Authenticated echo: ' + event.data);
+		 *   });
+		 * });
+		 * ```
+		 */
+		websocket(
+			path: string,
+			middleware: MiddlewareHandler,
+			handler: (c: Context) => (ws: WebSocketConnection) => void
+		): this;
+
+		/**
+		 * Create a Server-Sent Events (SSE) route for streaming updates to clients.
+		 *
+		 * @param path - The route path
+		 * @param handler - Handler receiving SSE stream writer
+		 *
+		 * @example
+		 * ```typescript
+		 * router.sse('/notifications', (c) => async (stream) => {
+		 *   let count = 0;
+		 *   const interval = setInterval(() => {
+		 *     stream.writeSSE({
+		 *       data: `Notification ${++count}`,
+		 *       event: 'notification'
+		 *     });
+		 *     if (count >= 10) {
+		 *       clearInterval(interval);
+		 *       stream.close();
+		 *     }
+		 *   }, 1000);
+		 * });
+		 * ```
+		 */
+		sse(path: string, handler: (c: Context) => (stream: any) => void): this;
+
+		/**
+		 * Create an SSE route with middleware.
+		 *
+		 * @param path - The route path
+		 * @param middleware - Middleware to run before SSE streaming
+		 * @param handler - Handler receiving SSE stream writer
+		 *
+		 * @example
+		 * ```typescript
+		 * router.sse('/protected-events', authMiddleware, (c) => async (stream) => {
+		 *   stream.writeSSE({ data: 'Secure event', event: 'update' });
+		 *   stream.close();
+		 * });
+		 * ```
+		 */
+		sse(
+			path: string,
+			middleware: MiddlewareHandler,
+			handler: (c: Context) => (stream: any) => void
+		): this;
+	}
+}
 
-export const createRouter = <E extends Env = Env, S extends Schema = Schema>(): ExtendedHono<
-	E,
-	S
-> => {
+/**
+ * Creates a Hono router with extended methods for Agentuity-specific routing patterns.
+ *
+ * In addition to standard HTTP methods (get, post, put, delete, patch), the router includes:
+ * - **stream()** - Stream responses with ReadableStream
+ * - **websocket()** - WebSocket connections
+ * - **sse()** - Server-Sent Events
+ * - **email()** - Email handler routing
+ * - **sms()** - SMS handler routing
+ * - **cron()** - Scheduled task routing
+ *
+ * @template E - Environment type (Hono Env)
+ * @template S - Schema type for route definitions
+ *
+ * @returns Extended Hono router with custom methods
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter();
+ *
+ * // Standard HTTP routes
+ * router.get('/hello', (c) => c.text('Hello!'));
+ * router.post('/data', async (c) => {
+ *   const body = await c.req.json();
+ *   return c.json({ received: body });
+ * });
+ *
+ * // Streaming response
+ * router.stream('/events', (c) => {
+ *   return new ReadableStream({
+ *     start(controller) {
+ *       controller.enqueue('event 1\n');
+ *       controller.enqueue('event 2\n');
+ *       controller.close();
+ *     }
+ *   });
+ * });
+ *
+ * // WebSocket connection
+ * router.websocket('/ws', (c) => (ws) => {
+ *   ws.onMessage((event) => {
+ *     console.log('Received:', event.data);
+ *     ws.send('Echo: ' + event.data);
+ *   });
+ * });
+ *
+ * // Server-Sent Events
+ * router.sse('/notifications', (c) => async (stream) => {
+ *   let count = 0;
+ *   const interval = setInterval(() => {
+ *     stream.writeSSE({ data: `Message ${++count}` });
+ *     if (count >= 10) {
+ *       clearInterval(interval);
+ *       stream.close();
+ *     }
+ *   }, 1000);
+ * });
+ *
+ * // Email routing
+ * router.email('support@example.com', (email, c) => {
+ *   console.log('From:', email.fromEmail());
+ *   console.log('Subject:', email.subject());
+ *   return c.text('Email received');
+ * });
+ *
+ * // SMS routing
+ * router.sms({ number: '+1234567890' }, (c) => {
+ *   return c.text('SMS received');
+ * });
+ *
+ * // Scheduled cron
+ * router.cron('0 0 * * *', (c) => {
+ *   console.log('Daily task running');
+ *   return c.text('OK');
+ * });
+ * ```
+ */
+export const createRouter = <E extends Env = Env, S extends Schema = Schema>(): Hono<E, S> => {
 	const router = new Hono<E, S>();
 	// tslint:disable-next-line:no-any no-unused-variable
 	// biome-ignore lint:no-any
@@ -94,38 +363,45 @@ export const createRouter = <E extends Env = Env, S extends Schema = Schema>():
 	for (const method of ['get', 'put', 'post', 'delete', 'options', 'patch']) {
 		const _originalInvoker = _router[method].bind(router);
 		_router[method] = (path: string, ...args: any[]) => {
-			if (args.length === 1) {
-				const arg = args[0];
-				// Check if it's a middleware (not our agent handler)
-				if (typeof arg === 'function' && arg.length === 2) {
-					// Middleware only: (path, middleware)
-					return _originalInvoker(path, arg);
-				}
-				// 2-arg: (path, handler)
-				const handler = arg;
-				const wrapper = async (c: Context): Promise<Response> => {
-					let result = handler(c);
-					if (result instanceof Promise) result = await result;
-					// If handler returns a Response (e.g., websocket upgrade), return it unchanged
-					if (result instanceof Response) return result;
-					return returnResponse(c, result);
-				};
-				return _originalInvoker(path, wrapper);
-			} else {
-				// 3-arg: (path, middleware, handler)
-				const middleware = args[0];
-				const handler = args[1];
-				const wrapper = async (c: Context): Promise<Response> => {
-					let result = handler(c);
-					if (result instanceof Promise) result = await result;
-					// If handler returns a Response (e.g., websocket upgrade), return it unchanged
-					if (result instanceof Response) {
-						return result;
-					}
-					return returnResponse(c, result);
-				};
-				return _originalInvoker(path, middleware, wrapper);
+			// Pass through to original Hono - it handles all the complex type inference
+			// We'll only wrap the final handler to add our response handling
+			if (args.length === 0) {
+				return _originalInvoker(path);
+			}
+
+			// Find the last function in args - that's the handler (everything else is middleware)
+			let handlerIndex = args.length - 1;
+			while (handlerIndex >= 0 && typeof args[handlerIndex] !== 'function') {
+				handlerIndex--;
+			}
+
+			if (handlerIndex < 0) {
+				// No handler found, pass through as-is
+				return _originalInvoker(path, ...args);
+			}
+
+			const handler = args[handlerIndex];
+
+			// Check if this is middleware (2 params: c, next) vs handler (1 param: c)
+			if (handler.length === 2) {
+				// This is middleware-only, pass through
+				return _originalInvoker(path, ...args);
 			}
+
+			// Wrap the handler to add our response conversion
+			const wrapper = async (c: Context): Promise<Response> => {
+				let result = handler(c);
+				if (result instanceof Promise) result = await result;
+				// If handler returns a Response, return it unchanged
+				if (result instanceof Response) return result;
+				return returnResponse(c, result);
+			};
+
+			// Replace the handler with our wrapper
+			const newArgs = [...args];
+			newArgs[handlerIndex] = wrapper;
+
+			return _originalInvoker(path, ...newArgs);
 		};
 	}
 
@@ -433,5 +709,5 @@ export const createRouter = <E extends Env = Env, S extends Schema = Schema>():
 		}
 	};
 
-	return router as unknown as ExtendedHono<E, S>;
+	return router;
 };

package/src/services/evalrun/http.ts

@@ -1,4 +1,9 @@
-import { APIClient, APIResponseSchemaNoData, ValidationError } from '@agentuity/server';
+import {
+	APIClient,
+	APIResponseSchemaNoData,
+	ValidationInputError,
+	ValidationOutputError,
+} from '@agentuity/server';
 import {
 	type EvalRunEventProvider,
 	type EvalRunStartEvent,
@@ -6,8 +11,11 @@ import {
 	EvalRunCompleteEventDelayedSchema,
 	type EvalRunCompleteEvent,
 	type Logger,
+	StructuredError,
 } from '@agentuity/core';
 
+const EvalRunResponseError = StructuredError('EvalRunResponseError');
+
 /**
  * An implementation of the EvalRunEventProvider which uses HTTP for delivery
  */
@@ -51,7 +59,7 @@ export class HTTPEvalRunEventProvider implements EvalRunEventProvider {
 			}
 			const errorMsg = resp.message || 'Unknown error';
 			this.logger.error('[EVALRUN HTTP] Start event failed: %s, error: %s', event.id, errorMsg);
-			throw new Error(errorMsg);
+			throw new EvalRunResponseError({ message: errorMsg });
 		} catch (error) {
 			this.logger.error(
 				'[EVALRUN HTTP] Start event exception: %s, error: %s',
@@ -59,7 +67,10 @@ export class HTTPEvalRunEventProvider implements EvalRunEventProvider {
 				error instanceof Error ? error.message : String(error)
 			);
 			// Log validation errors if available
-			if (error instanceof ValidationError) {
+			if (
+				(error instanceof ValidationInputError || error instanceof ValidationOutputError) &&
+				error.issues?.length
+			) {
 				this.logger.error(
 					'[EVALRUN HTTP] Validation issues: %s',
 					JSON.stringify(error.issues, null, 2)
@@ -99,7 +110,7 @@ export class HTTPEvalRunEventProvider implements EvalRunEventProvider {
 				event.id,
 				errorMsg
 			);
-			throw new Error(errorMsg);
+			throw new EvalRunResponseError({ message: errorMsg });
 		} catch (error) {
 			this.logger.error(
 				'[EVALRUN HTTP] Complete event exception: %s, error: %s',

package/src/services/local/_util.ts

@@ -1,3 +1,4 @@
+import { StructuredError } from '@agentuity/core';
 import { resolve } from 'node:path';
 
 /**
@@ -26,12 +27,17 @@ export function simpleEmbedding(text: string, dimensions = 128): number[] {
 	return magnitude > 0 ? vec.map((v) => v / magnitude) : vec;
 }
 
+const InvalidVectorError = StructuredError(
+	'InvalidVectorError',
+	'Vectors must have the same dimension'
+);
+
 /**
  * Calculate cosine similarity between two vectors
  */
 export function cosineSimilarity(a: number[], b: number[]): number {
 	if (a.length !== b.length) {
-		throw new Error('Vectors must have the same dimension');
+		throw new InvalidVectorError();
 	}
 
 	const dot = a.reduce((sum, ai, i) => sum + ai * (b[i] ?? 0), 0);

package/src/services/session/http.ts

@@ -6,8 +6,11 @@ import {
 	SessionCompleteEventDelayedSchema,
 	type SessionCompleteEvent,
 	type Logger,
+	StructuredError,
 } from '@agentuity/core';
 
+const SessionResponseError = StructuredError('SessionResponseError');
+
 /**
  * An implementation of the SessionEventProvider which uses HTTP for delivery
  */
@@ -38,7 +41,7 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 			this.logger.debug('Session start event sent successfully: %s', event.id);
 			return;
 		}
-		throw new Error(resp.message);
+		throw new SessionResponseError({ message: resp.message });
 	}
 
 	/**
@@ -59,6 +62,6 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 			this.logger.debug('Session complete event sent successfully: %s', event.id);
 			return;
 		}
-		throw new Error(resp.message);
+		throw new SessionResponseError({ message: resp.message });
 	}
 }