@agentuity/runtime 0.0.60 → 0.0.62

package/src/_server.ts

@@ -45,6 +45,8 @@ let globalRouterInstance: Hono<Env> | null = null;
 
 let globalLogger: Logger | null = null;
 let globalTracer: Tracer | null = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let globalAppState: any = null;
 
 export function getServer() {
 	return globalServerInstance;
@@ -64,6 +66,10 @@ export function getTracer() {
 	return globalTracer;
 }
 
+export function getAppState() {
+	return globalAppState;
+}
+
 function isDevelopment(): boolean {
 	const devmode = runtimeConfig.isDevMode();
 	const environment = runtimeConfig.getEnvironment();
@@ -131,11 +137,27 @@ export function privateContext<E extends Env>(c: HonoContext<E>) {
 	return c as unknown as HonoContext<{ Variables: PrivateVariables }>;
 }
 
-export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig) => {
+let startupPromise: Promise<void> | undefined;
+let startupPromiseResolver: (() => void) | undefined;
+let isShutdown = false;
+
+export const notifyReady = () => {
+	startupPromiseResolver?.();
+};
+
+export const createServer = async <TAppState>(
+	router: Hono<Env<TAppState>>,
+	appStateInitializer: () => Promise<TAppState>,
+	config?: AppConfig<TAppState>
+): Promise<[Bun.Server<BunWebSocketData>, TAppState]> => {
 	if (globalServerInstance) {
-		return globalServerInstance;
+		return [globalServerInstance, globalAppState as TAppState];
 	}
 
+	const { promise, resolve } = Promise.withResolvers<void>();
+	startupPromise = promise;
+	startupPromiseResolver = resolve;
+
 	runtimeConfig.init();
 
 	const logLevel = process.env.AGENTUITY_LOG_LEVEL || 'info';
@@ -153,22 +175,13 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 	// Create services (may return local router)
 	const servicesResult = createServices(otel.logger, config, serverUrl);
 
-	const server = Bun.serve({
-		hostname,
-		development: isDevelopment(),
-		fetch: router.fetch,
-		idleTimeout: 0,
-		port,
-		websocket,
-	});
+	// Create the App State
+	globalAppState = await appStateInitializer();
 
 	globalRouterInstance = router as unknown as Hono<Env>;
-	globalServerInstance = server;
 	globalLogger = otel.logger;
 	globalTracer = otel.tracer;
 
-	let isShutdown = false;
-
 	router.onError((error, _c) => {
 		if (error instanceof HTTPException) {
 			otel.logger.error('HTTP Error: %s (%d)', error.cause, error.status);
@@ -178,42 +191,45 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 			otel.logger.error('Unauthenticated Error: %s', error.message);
 			return new Response(error.message, { status: 501 });
 		}
-		if (
-			error instanceof ServiceException ||
-			('statusCode' in error && typeof error.statusCode === 'number')
-		) {
-			const serviceError = error as ServiceException;
+		if (error instanceof ServiceException) {
+			const serviceError = error as InstanceType<typeof ServiceException>;
 			otel.logger.error(
-				'Service Exception: %s (%s returned HTTP status code: %d)',
+				'Service Exception: %s (%s returned HTTP status code: %d%s)',
 				error.message,
 				serviceError.url,
-				serviceError.statusCode
+				serviceError.statusCode,
+				serviceError.sessionId ? `, session: ${serviceError.sessionId}` : ''
 			);
 			return new Response(error.message, {
 				status: serviceError.statusCode ?? 500,
 			});
 		}
-		otel.logger.error('Unhandled Server Error: %s', JSON.stringify(error));
+		otel.logger.error('Unhandled Server Error: %s', error);
 		return new Response('Internal Server Error', { status: 500 });
 	});
 
-	const threadProvider = getThreadProvider();
-	const sessionProvider = getSessionProvider();
+	const blockOnStartup = async () => {
+		// block until completing the setup if still running
+		if (startupPromise) {
+			await startupPromise;
+			startupPromise = undefined;
+			startupPromiseResolver = undefined;
+		}
+	};
 
-	let initPromise: Promise<void> | undefined = new Promise((resolve, reject) => {
-		Promise.all([threadProvider.initialize(), sessionProvider.initialize()])
-			.then(() => resolve())
-			.catch(reject);
+	router.get('/_health', async (c) => {
+		await blockOnStartup();
+		return c.text('OK');
 	});
 
 	router.use(async (c, next) => {
-		if (initPromise) {
-			await initPromise;
-			initPromise = undefined;
-		}
+		await blockOnStartup();
+
 		c.set('logger', otel.logger);
 		c.set('tracer', otel.tracer);
 		c.set('meter', otel.meter);
+		c.set('app', globalAppState);
+
 		const isWebSocket = c.req.header('upgrade')?.toLowerCase() === 'websocket';
 		const skipLogging = c.req.path.startsWith('/_agentuity/');
 		const started = performance.now();
@@ -255,7 +271,6 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 		})
 	);
 
-	router.get('/_health', (c) => c.text('OK'));
 	router.route('/_agentuity', createAgentuityAPIs());
 
 	// Mount local storage router if using local services
@@ -275,7 +290,7 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 				// in production there is no .agentuity folder
 				routeMappingPath = join(projectRoot, '.routemapping.json');
 			} else {
-				routeMappingPath = join(projectRoot, '.agentuity', '.routemapping.json');
+				routeMappingPath = join(import.meta.dirname, '..', '.routemapping.json');
 			}
 			const file = Bun.file(routeMappingPath);
 			if (!(await file.exists())) {
@@ -337,7 +352,33 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 			process.exit(1);
 		}, 5_000);
 		try {
-			await server.stop();
+			// stop accepting new connections
+			if (globalServerInstance) {
+				await globalServerInstance.stop();
+			}
+
+			// wait for idle
+			const shutdownStarted = Date.now();
+			otel.logger.debug('waiting for pending connections to complete');
+			while (Date.now() - shutdownStarted < 60_000 * 2) {
+				if ((globalServerInstance?.pendingRequests ?? 0) > 0) {
+					await Bun.sleep(1_000);
+				} else {
+					break;
+				}
+			}
+			otel.logger.debug('no more pending connections');
+
+			// Run agent shutdowns first
+			const { runAgentShutdowns } = await import('./agent');
+			await runAgentShutdowns(globalAppState);
+
+			// Run app shutdown if provided
+			if (config?.shutdown && globalAppState) {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				await config.shutdown(globalAppState as any);
+			}
+
 			await otel.shutdown();
 			otel.logger.debug('shutdown completed');
 		} finally {
@@ -373,13 +414,24 @@ export const createServer = <E extends Env>(router: Hono<E>, config?: AppConfig)
 		process.exit(1);
 	});
 
-	return server;
+	const server = Bun.serve({
+		hostname,
+		development: isDevelopment(),
+		fetch: router.fetch,
+		idleTimeout: 0,
+		port,
+		websocket,
+		id: null,
+	});
+	globalServerInstance = server;
+
+	return [server, globalAppState];
 };
 
 const createAgentuityAPIs = () => {
 	const router = new Hono<Env>();
 	router.get('idle', (c) => {
-		if (isIdle()) {
+		if (isIdle() || !isShutdown) {
 			return c.text('OK', { status: 200 });
 		}
 		return c.text('NO', { status: 200 });
@@ -485,11 +537,13 @@ const otelMiddleware = createMiddleware<Env>(async (c, next) => {
 								await threadProvider.save(thread);
 								span.setStatus({ code: SpanStatusCode.OK });
 								if (shouldSendSession && canSendSessionEvents) {
+									const userData = session.serializeUserData();
 									sessionEventProvider
 										.complete({
 											id: sessionId,
 											statusCode: c.res.status,
 											agentIds: Array.from(agentIds),
+											userData,
 										})
 										.then(() => {})
 										.catch((ex) => c.var.logger.error(ex));
@@ -507,12 +561,14 @@ const otelMiddleware = createMiddleware<Env>(async (c, next) => {
 								});
 								c.var.logger.error(message);
 								if (shouldSendSession && canSendSessionEvents) {
+									const userData = session.serializeUserData();
 									sessionEventProvider
 										.complete({
 											id: sessionId,
 											statusCode: c.res.status,
 											error: message,
 											agentIds: Array.from(agentIds),
+											userData,
 										})
 										.then(() => {})
 										.catch((ex) => c.var.logger.error(ex));
@@ -524,11 +580,13 @@ const otelMiddleware = createMiddleware<Env>(async (c, next) => {
 					} else {
 						span.setStatus({ code: SpanStatusCode.OK });
 						if (shouldSendSession && canSendSessionEvents) {
+							const userData = session.serializeUserData();
 							sessionEventProvider
 								.complete({
 									id: sessionId,
 									statusCode: c.res.status,
 									agentIds: Array.from(agentIds),
+									userData,
 								})
 								.then(() => {})
 								.catch((ex) => c.var.logger.error(ex));
@@ -545,12 +603,14 @@ const otelMiddleware = createMiddleware<Env>(async (c, next) => {
 					});
 					c.var.logger.error(message);
 					if (shouldSendSession && canSendSessionEvents) {
+						const userData = session.serializeUserData();
 						sessionEventProvider
 							.complete({
 								id: sessionId,
 								statusCode: c.res.status,
 								error: message,
 								agentIds: Array.from(agentIds),
+								userData,
 							})
 							.then(() => {})
 							.catch((ex) => c.var.logger.error(ex));

package/src/_services.ts

@@ -15,6 +15,7 @@ import {
 	type Logger,
 	type SessionEventProvider,
 	type EvalRunEventProvider,
+	StructuredError,
 } from '@agentuity/core';
 import { APIClient, createServerFetchAdapter, getServiceUrls } from '@agentuity/server';
 import {
@@ -189,7 +190,13 @@ let evalRunEvent: EvalRunEventProvider;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let localRouter: any | null = null;
 
-export function createServices(logger: Logger, config?: AppConfig, serverUrl?: string) {
+const ServerUrlMissingError = StructuredError(
+	'ServerUrlMissingError',
+	'serverUrl is required when using local services'
+);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createServices(logger: Logger, config?: AppConfig<any>, serverUrl?: string) {
 	const authenticated = isAuthenticated();
 	const useLocal = config?.services?.useLocal ?? false;
 	adapter = createFetchAdapter(logger);
@@ -203,7 +210,7 @@ export function createServices(logger: Logger, config?: AppConfig, serverUrl?: s
 		const projectPath = normalizeProjectPath();
 
 		if (!serverUrl) {
-			throw new Error('serverUrl is required when using local services');
+			throw new ServerUrlMissingError();
 		}
 
 		logger.info('Using local services (development only)');

package/src/_waituntil.ts

@@ -1,6 +1,7 @@
 import { context, SpanStatusCode, type Tracer, trace } from '@opentelemetry/api';
 import type { Logger } from './logger';
 import { internal } from './logger/internal';
+import { StructuredError } from '@agentuity/core';
 
 let running = 0;
 
@@ -13,6 +14,16 @@ export function hasWaitUntilPending(): boolean {
 	return running > 0;
 }
 
+const WaitUntilInvalidStateError = StructuredError(
+	'WaitUntilInvalidStateError',
+	'waitUntil cannot be called after waitUntilAll has been called'
+);
+
+const WaitUntilAllInvalidStateError = StructuredError(
+	'WaitUntilAllInvalidStateError',
+	'waitUntilAll can only be called once per instance'
+);
+
 export default class WaitUntilHandler {
 	private promises: Promise<void>[];
 	private tracer: Tracer;
@@ -26,7 +37,7 @@ export default class WaitUntilHandler {
 
 	public waitUntil(promise: Promise<void> | (() => void | Promise<void>)): void {
 		if (this.hasCalledWaitUntilAll) {
-			throw new Error('Cannot call waitUntil after waitUntilAll has been called');
+			throw new WaitUntilInvalidStateError();
 		}
 		running++;
 		internal.debug('wait until called, running: %d', running);
@@ -69,7 +80,7 @@ export default class WaitUntilHandler {
 		internal.debug(`🔍 waitUntilAll() called for session ${sessionId} (count: %d)`, running);
 
 		if (this.hasCalledWaitUntilAll) {
-			throw new Error('waitUntilAll can only be called once per instance');
+			throw new WaitUntilAllInvalidStateError();
 		}
 		this.hasCalledWaitUntilAll = true;