@agentuity/runtime 0.0.60 → 0.0.61

package/src/app.ts

@@ -2,6 +2,7 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: any are ok */
 import { type Env as HonoEnv, Hono } from 'hono';
 import type { cors } from 'hono/cors';
+import type { BunWebSocketData } from 'hono/bun';
 import type { Logger } from './logger';
 import { createServer, getLogger } from './_server';
 import type { Meter, Tracer } from '@opentelemetry/api';
@@ -26,7 +27,7 @@ export interface WorkbenchInstance {
 
 type CorsOptions = Parameters<typeof cors>[0];
 
-export interface AppConfig {
+export interface AppConfig<TAppState = Record<string, never>> {
 	/**
 	 * Override the default cors settings
 	 */
@@ -76,9 +77,19 @@ export interface AppConfig {
 		 */
 		workbench?: WorkbenchInstance;
 	};
+	/**
+	 * Optional setup function called before server starts
+	 * Returns app state that will be available in all agents and routes
+	 */
+	setup?: () => Promise<TAppState> | TAppState;
+	/**
+	 * Optional shutdown function called when server is stopping
+	 * Receives the app state returned from setup
+	 */
+	shutdown?: (state: TAppState) => Promise<void> | void;
 }
 
-export interface Variables {
+export interface Variables<TAppState = Record<string, never>> {
 	logger: Logger;
 	meter: Meter;
 	tracer: Tracer;
@@ -91,6 +102,7 @@ export interface Variables {
 	objectstore: ObjectStorage;
 	stream: StreamStorage;
 	vector: VectorStorage;
+	app: TAppState;
 }
 
 export type TriggerType = SessionStartEvent['trigger'];
@@ -102,51 +114,128 @@ export interface PrivateVariables {
 	trigger: TriggerType;
 }
 
-export interface Env extends HonoEnv {
-	Variables: Variables;
+export interface Env<TAppState = Record<string, never>> extends HonoEnv {
+	Variables: Variables<TAppState>;
 }
 
-type AppEventMap = {
-	'agent.started': [Agent<any, any, any>, AgentContext];
-	'agent.completed': [Agent<any, any, any>, AgentContext];
-	'agent.errored': [Agent<any, any, any>, AgentContext, Error];
+type AppEventMap<TAppState = Record<string, never>> = {
+	'agent.started': [
+		Agent<any, any, any, any, TAppState>,
+		AgentContext<any, any, any, any, TAppState>,
+	];
+	'agent.completed': [
+		Agent<any, any, any, any, TAppState>,
+		AgentContext<any, any, any, any, TAppState>,
+	];
+	'agent.errored': [
+		Agent<any, any, any, any, TAppState>,
+		AgentContext<any, any, any, any, TAppState>,
+		Error,
+	];
 	'session.started': [Session];
 	'session.completed': [Session];
 	'thread.created': [Thread];
 	'thread.destroyed': [Thread];
 };
 
-type AppEventCallback<K extends keyof AppEventMap> = (
+type AppEventCallback<K extends keyof AppEventMap<any>, TAppState = Record<string, never>> = (
 	eventName: K,
-	...args: AppEventMap[K]
+	...args: AppEventMap<TAppState>[K]
 ) => void | Promise<void>;
 
-export class App {
+/**
+ * Main application instance created by createApp().
+ * Provides access to the router, server, logger, and app state.
+ *
+ * @template TAppState - The type of application state returned from setup function
+ *
+ * @example
+ * ```typescript
+ * const app = await createApp({
+ *   setup: async () => ({ db: await connectDB() })
+ * });
+ *
+ * // Access state
+ * console.log(app.state.db);
+ *
+ * // Add routes
+ * app.router.get('/health', (c) => c.text('OK'));
+ *
+ * // Listen to events
+ * app.addEventListener('agent.started', (eventName, agent, ctx) => {
+ *   console.log(`Agent ${agent.metadata.name} started`);
+ * });
+ * ```
+ */
+export class App<TAppState = Record<string, never>> {
 	/**
-	 * the router instance
+	 * The Hono router instance for defining routes.
 	 */
-	readonly router: Hono<Env>;
+	readonly router: Hono<Env<TAppState>>;
 	/**
-	 * the server instance
+	 * The Bun server instance.
 	 */
-	readonly server: ReturnType<typeof createServer>;
+	readonly server: Bun.Server<BunWebSocketData>;
 	/**
-	 * the logger instance
+	 * The application logger instance.
 	 */
 	readonly logger: Logger;
+	/**
+	 * The application state returned from the setup function.
+	 * Available in all agents via ctx.app.
+	 */
+	readonly state: TAppState;
 
-	private eventListeners = new Map<keyof AppEventMap, Set<AppEventCallback<any>>>();
+	private eventListeners = new Map<
+		keyof AppEventMap<TAppState>,
+		Set<AppEventCallback<any, TAppState>>
+	>();
 
-	constructor(config?: AppConfig) {
-		this.router = new Hono<Env>();
-		this.server = createServer(this.router, config);
+	constructor(
+		state: TAppState,
+		router: Hono<Env<TAppState>>,
+		server: Bun.Server<BunWebSocketData>
+	) {
+		this.state = state;
+		this.router = router;
+		this.server = server;
 		this.logger = getLogger() as Logger;
 		setGlobalApp(this);
 	}
 
-	addEventListener<K extends keyof AppEventMap>(
+	/**
+	 * Register an event listener for application lifecycle events.
+	 *
+	 * Available events:
+	 * - `agent.started` - Fired when an agent begins execution
+	 * - `agent.completed` - Fired when an agent completes successfully
+	 * - `agent.errored` - Fired when an agent throws an error
+	 * - `session.started` - Fired when a new session starts
+	 * - `session.completed` - Fired when a session completes
+	 * - `thread.created` - Fired when a thread is created
+	 * - `thread.destroyed` - Fired when a thread is destroyed
+	 *
+	 * @param eventName - The event name to listen for
+	 * @param callback - The callback function to execute when the event fires
+	 *
+	 * @example
+	 * ```typescript
+	 * app.addEventListener('agent.started', (eventName, agent, ctx) => {
+	 *   console.log(`${agent.metadata.name} started for session ${ctx.sessionId}`);
+	 * });
+	 *
+	 * app.addEventListener('agent.errored', (eventName, agent, ctx, error) => {
+	 *   console.error(`${agent.metadata.name} failed:`, error.message);
+	 * });
+	 *
+	 * app.addEventListener('session.started', (eventName, session) => {
+	 *   console.log(`New session: ${session.id}`);
+	 * });
+	 * ```
+	 */
+	addEventListener<K extends keyof AppEventMap<TAppState>>(
 		eventName: K,
-		callback: AppEventCallback<K>
+		callback: AppEventCallback<K, TAppState>
 	): void {
 		let callbacks = this.eventListeners.get(eventName);
 		if (!callbacks) {
@@ -156,18 +245,48 @@ export class App {
 		callbacks.add(callback);
 	}
 
-	removeEventListener<K extends keyof AppEventMap>(
+	/**
+	 * Remove a previously registered event listener.
+	 *
+	 * @param eventName - The event name to stop listening for
+	 * @param callback - The callback function to remove
+	 *
+	 * @example
+	 * ```typescript
+	 * const handler = (eventName, agent, ctx) => {
+	 *   console.log('Agent started:', agent.metadata.name);
+	 * };
+	 *
+	 * app.addEventListener('agent.started', handler);
+	 * // Later...
+	 * app.removeEventListener('agent.started', handler);
+	 * ```
+	 */
+	removeEventListener<K extends keyof AppEventMap<TAppState>>(
 		eventName: K,
-		callback: AppEventCallback<K>
+		callback: AppEventCallback<K, TAppState>
 	): void {
 		const callbacks = this.eventListeners.get(eventName);
 		if (!callbacks) return;
 		callbacks.delete(callback);
 	}
 
-	async fireEvent<K extends keyof AppEventMap>(
+	/**
+	 * Manually fire an application event.
+	 * Typically used internally by the runtime, but can be used for custom events.
+	 *
+	 * @param eventName - The event name to fire
+	 * @param args - The arguments to pass to event listeners
+	 *
+	 * @example
+	 * ```typescript
+	 * // Fire a session completed event
+	 * await app.fireEvent('session.completed', session);
+	 * ```
+	 */
+	async fireEvent<K extends keyof AppEventMap<TAppState>>(
 		eventName: K,
-		...args: AppEventMap[K]
+		...args: AppEventMap<TAppState>[K]
 	): Promise<void> {
 		const callbacks = this.eventListeners.get(eventName);
 		if (!callbacks || callbacks.size === 0) return;
@@ -178,34 +297,115 @@ export class App {
 	}
 }
 
-let globalApp: App | null = null;
+let globalApp: App<any> | null = null;
 
-function setGlobalApp(app: App): void {
+function setGlobalApp(app: App<any>): void {
 	globalApp = app;
 }
 
-export function getApp(): App | null {
+/**
+ * Get the global app instance.
+ * Returns null if createApp() has not been called yet.
+ *
+ * @returns The global App instance or null
+ *
+ * @example
+ * ```typescript
+ * const app = getApp();
+ * if (app) {
+ *   console.log('Server running on port:', app.server.port);
+ * }
+ * ```
+ */
+export function getApp(): App<any> | null {
 	return globalApp;
 }
 
 /**
- * create a new app instance
+ * Creates a new Agentuity application with optional lifecycle hooks and service configuration.
+ *
+ * This is the main entry point for creating an Agentuity app. The app will:
+ * 1. Run the setup function (if provided) to initialize app state
+ * 2. Start the Bun server
+ * 3. Make the app state available in all agents via ctx.app
+ *
+ * @template TAppState - The type of application state returned from setup function
+ *
+ * @param config - Optional application configuration
+ * @param config.setup - Function to initialize app state, runs before server starts
+ * @param config.shutdown - Function to clean up resources when server stops
+ * @param config.cors - CORS configuration for HTTP routes
+ * @param config.services - Override default storage and service providers
+ *
+ * @returns Promise resolving to App instance with running server
  *
- * @returns App instance
+ * @example
+ * ```typescript
+ * // Simple app with no state
+ * const app = await createApp();
+ *
+ * // App with database connection
+ * const app = await createApp({
+ *   setup: async () => {
+ *     const db = await connectDatabase();
+ *     return { db };
+ *   },
+ *   shutdown: async (state) => {
+ *     await state.db.close();
+ *   }
+ * });
+ *
+ * // Access state in agents
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     const db = ctx.app.db; // Strongly typed!
+ *     return db.query('SELECT * FROM users');
+ *   }
+ * });
+ *
+ * // App with custom services
+ * const app = await createApp({
+ *   services: {
+ *     useLocal: true, // Use local in-memory storage for development
+ *   }
+ * });
+ * ```
  */
-export function createApp(config?: AppConfig): App {
-	return new App(config);
+export async function createApp<TAppState = Record<string, never>>(
+	config?: AppConfig<TAppState>
+): Promise<App<TAppState>> {
+	const initializer = async (): Promise<TAppState> => {
+		// Run setup if provided
+		if (config?.setup) {
+			return config.setup();
+		} else {
+			return {} as TAppState;
+		}
+	};
+
+	const router = new Hono<Env<TAppState>>();
+	const [server, state] = await createServer<TAppState>(router, initializer, config);
+
+	return new App(state, router, server);
 }
 
 /**
- * fire a global event
+ * Fire a global application event.
+ * Convenience function that calls fireEvent on the global app instance.
+ *
+ * @param eventName - The event name to fire
+ * @param args - The arguments to pass to event listeners
  *
- * @param eventName
- * @param args
+ * @example
+ * ```typescript
+ * // Fire from anywhere in your app
+ * await fireEvent('session.started', session);
+ * await fireEvent('agent.completed', agent, ctx);
+ * ```
  */
-export async function fireEvent<K extends keyof AppEventMap>(
+export async function fireEvent<K extends keyof AppEventMap<any>>(
 	eventName: K,
-	...args: AppEventMap[K]
+	...args: AppEventMap<any>[K]
 ) {
 	await globalApp?.fireEvent(eventName, ...args);
 }

package/src/index.ts

@@ -6,7 +6,47 @@ export * from './eval';
 export * from './session';
 export * from './workbench';
 export type { Logger } from './logger';
-export { getRouter } from './_server';
+export { getRouter, getAppState } from './_server';
 export { Email, parseEmail } from './io/email';
 export * from './services/evalrun';
-export { getEvalRunEventProvider } from './_services';
+export { getEvalRunEventProvider, getThreadProvider, getSessionProvider } from './_services';
+
+/**
+ * Application state interface that gets automatically augmented based on your createApp setup function.
+ *
+ * This interface is empty by default but gets populated with strongly-typed properties
+ * when you define a setup function in createApp(). The Agentuity build tool automatically
+ * generates type augmentations in `.agentuity/.agentuity_runtime.ts`.
+ *
+ * **How it works:**
+ * 1. You define setup() in createApp() that returns an object
+ * 2. The build tool generates module augmentation for this interface
+ * 3. All agents get strongly-typed access to app state via `ctx.app`
+ *
+ * @example
+ * ```typescript
+ * // In your app.ts:
+ * const app = await createApp({
+ *   setup: async () => {
+ *     const db = await connectDatabase();
+ *     const redis = await connectRedis();
+ *     return { db, redis };
+ *   }
+ * });
+ *
+ * // In your agent:
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     // ctx.app is strongly typed with { db, redis }!
+ *     const user = await ctx.app.db.query('SELECT * FROM users');
+ *     await ctx.app.redis.set('key', 'value');
+ *     return user;
+ *   }
+ * });
+ * ```
+ *
+ * **Note:** If you're not seeing type hints for `ctx.app`, make sure you've run `bun run build`
+ * to generate the type augmentations.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AppState {}

package/src/io/email.ts

@@ -1,3 +1,4 @@
+import { StructuredError } from '@agentuity/core';
 import { type ParsedMail, type Headers, simpleParser, type AddressObject } from 'mailparser';
 
 /**
@@ -143,6 +144,21 @@ export class Email {
 	}
 }
 
+const InvalidEmailEmptyError = StructuredError(
+	'InvalidEmailEmptyError',
+	'Failed to parse email: empty buffer'
+);
+
+const InvalidEmailHeadersError = StructuredError(
+	'InvalidEmailHeadersError',
+	'Failed to parse email: missing headers'
+);
+
+const InvalidEmailParseError = StructuredError(
+	'InvalidEmailParseError',
+	'Failed to parse email: body was invalid'
+)<{ bufferSize: number; preview?: string }>();
+
 /**
  * Parse an email from a buffer and return an Email object.
  *
@@ -152,22 +168,24 @@ export class Email {
  */
 export async function parseEmail(data: Buffer): Promise<Email> {
 	if (data.length === 0) {
-		throw new Error('Failed to parse email: empty buffer');
+		throw new InvalidEmailEmptyError();
 	}
 
 	const first16KB = data.slice(0, 16384).toString('utf-8', 0, Math.min(data.length, 16384));
 	const hasHeaders = /(^|\r?\n)[!-9;-~]+:\s/.test(first16KB);
 
 	if (!hasHeaders) {
-		throw new Error('Failed to parse email: missing headers');
+		throw new InvalidEmailHeadersError();
 	}
 
 	try {
 		const message = await simpleParser(data);
 		return new Email(message);
 	} catch (error) {
-		throw new Error(
-			`Failed to parse email: ${error instanceof Error ? error.message : 'Unknown error'}`
-		);
+		throw new InvalidEmailParseError({
+			bufferSize: data.length,
+			preview: data.subarray(0, 50).toString('hex'),
+			cause: error,
+		});
 	}
 }