@agentuity/runtime 0.0.99 → 0.0.101

package/src/app.ts

@@ -15,11 +15,6 @@ import type { Email } from './io/email';
 import type { ThreadProvider, SessionProvider, Session, Thread } from './session';
 import type WaitUntilHandler from './_waituntil';
 
-// TODO: This should be imported from workbench package, but causes circular dependency
-export interface WorkbenchInstance {
-	config: { route?: string; headers?: Record<string, string> };
-}
-
 type CorsOptions = Parameters<typeof cors>[0];
 
 export interface AppConfig<TAppState = Record<string, never>> {
@@ -63,10 +58,6 @@ export interface AppConfig<TAppState = Record<string, never>> {
 		 * the EvalRunEventProvider to override instead of the default
 		 */
 		evalRunEvent?: EvalRunEventProvider;
-		/**
-		 * the Workbench to override instead of the default
-		 */
-		workbench?: WorkbenchInstance;
 	};
 	/**
 	 * Optional setup function called before server starts

package/src/devmode.ts

@@ -78,12 +78,23 @@ const overlay = `
 </style>
 `;
 
+// Global controller to avoid registering multiple SIGINT listeners
+let globalController: AbortController | undefined;
+let globalSigintHandler: (() => void) | undefined;
+
 export function registerDevModeRoutes(router: Hono) {
-	const controller = new AbortController();
-	const signal = controller.signal;
-	process.on('SIGINT', () => {
-		controller.abort();
-	});
+	// Reuse existing controller or create new one
+	if (!globalController) {
+		globalController = new AbortController();
+
+		// Only register SIGINT handler once
+		globalSigintHandler = () => {
+			globalController?.abort();
+		};
+		process.on('SIGINT', globalSigintHandler);
+	}
+
+	const signal = globalController.signal;
 	router.get('/__dev__/reload', () => {
 		const stream = new ReadableStream({
 			start(controller): void {

package/src/index.ts

@@ -27,7 +27,6 @@ export {
 
 // app.ts exports (all app-related functionality)
 export {
-	type WorkbenchInstance,
 	type AppConfig,
 	type Variables,
 	type TriggerType,
@@ -193,3 +192,8 @@ export type { RouteSchema, GetRouteSchema } from './_validation';
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface AppState {}
+
+// Re-export bootstrapRuntimeEnv from @agentuity/server for convenience
+// 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';

package/src/middleware.ts

@@ -22,6 +22,8 @@ import {
 } from '@opentelemetry/api';
 import { TraceState } from '@opentelemetry/core';
 import * as runtimeConfig from './_config';
+import { getSessionEventProvider } from './_services';
+import { internal } from './logger/internal';
 
 const SESSION_HEADER = 'x-session-id';
 const THREAD_HEADER = 'x-thread-id';
@@ -74,7 +76,8 @@ export interface MiddlewareConfig {
  * Create base middleware that sets up context variables
  */
 export function createBaseMiddleware(config: MiddlewareConfig) {
-	return createMiddleware<Env>(async (c, next) => {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return createMiddleware<Env<any>>(async (c, next) => {
 		c.set('logger', config.logger);
 		c.set('tracer', config.tracer);
 		c.set('meter', config.meter);
@@ -154,7 +157,8 @@ export function createCorsMiddleware(corsOptions?: Parameters<typeof cors>[0]) {
  * This is the critical middleware that creates AgentContext
  */
 export function createOtelMiddleware() {
-	return createMiddleware<Env>(async (c, next) => {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	return createMiddleware<Env<any>>(async (c, next) => {
 		// Import providers dynamically to avoid circular deps
 		const { getThreadProvider, getSessionProvider } = await import('./_services');
 		const WaitUntilHandler = (await import('./_waituntil')).default;
@@ -188,6 +192,14 @@ export function createOtelMiddleware() {
 					const deploymentId = runtimeConfig.getDeploymentId();
 					const isDevMode = runtimeConfig.isDevMode();
 
+					internal.info(
+						'[session] config: orgId=%s, projectId=%s, deploymentId=%s, isDevMode=%s',
+						orgId ?? 'NOT SET (AGENTUITY_CLOUD_ORG_ID)',
+						projectId ?? 'NOT SET (AGENTUITY_CLOUD_PROJECT_ID)',
+						deploymentId ?? 'none',
+						isDevMode
+					);
+
 					if (projectId) traceState = traceState.set('pid', projectId);
 					if (orgId) traceState = traceState.set('oid', orgId);
 					if (isDevMode) traceState = traceState.set('d', '1');
@@ -211,17 +223,45 @@ export function createOtelMiddleware() {
 					c.set('session', session);
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					(c as any).set('waitUntilHandler', handler);
+					const agentIds = new Set<string>();
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					(c as any).set('agentIds', new Set<string>());
+					(c as any).set('agentIds', agentIds);
 					// eslint-disable-next-line @typescript-eslint/no-explicit-any
 					(c as any).set('trigger', 'api');
 
+					// Send session start event (so evalruns can reference this session)
+					const sessionEventProvider = getSessionEventProvider();
+					const shouldSendSession = !!(orgId && projectId);
+					if (shouldSendSession && 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,
+								deploymentId: deploymentId || undefined,
+								devmode: isDevMode,
+								trigger: 'api',
+								routeId,
+								environment: runtimeConfig.getEnvironment(),
+								url: c.req.path,
+								method: c.req.method,
+							});
+						} catch (_ex) {
+							// Silently ignore session start errors - don't block request
+						}
+					}
+
 					try {
 						await next();
-
 						// Save session/thread and send events
+						internal.info('[session] saving session %s (thread: %s)', sessionId, thread.id);
 						await sessionProvider.save(session);
+						internal.info('[session] session saved, now saving thread');
 						await threadProvider.save(thread);
+						internal.info('[session] thread saved');
 						span.setStatus({ code: SpanStatusCode.OK });
 					} catch (ex) {
 						if (ex instanceof Error) {
@@ -233,6 +273,37 @@ export function createOtelMiddleware() {
 						});
 						throw ex;
 					} finally {
+						// Send session complete event
+						internal.info(
+							'[session] shouldSendSession: %s, hasSessionEventProvider: %s',
+							shouldSendSession,
+							!!sessionEventProvider
+						);
+						if (shouldSendSession && sessionEventProvider) {
+							try {
+								const userData = session.serializeUserData();
+								internal.info(
+									'[session] sending session complete event, userData: %s',
+									userData ? `${userData.length} bytes` : 'none'
+								);
+								// eslint-disable-next-line @typescript-eslint/no-explicit-any
+								const agentIdsSet = (c as any).get('agentIds') as Set<string> | undefined;
+								const agentIds = agentIdsSet ? [...agentIdsSet].filter(Boolean) : undefined;
+								internal.info('[session] agentIds: %o', agentIds);
+								await sessionEventProvider.complete({
+									id: sessionId,
+									threadId: thread.empty() ? null : thread.id,
+									statusCode: c.res?.status ?? 200,
+									agentIds: agentIds?.length ? agentIds : undefined,
+									userData,
+								});
+								internal.info('[session] session complete event sent');
+							} catch (ex) {
+								internal.info('[session] session complete event failed: %s', ex);
+								// Silently ignore session complete errors - don't block response
+							}
+						}
+
 						const headers: Record<string, string> = {};
 						propagation.inject(context.active(), headers);
 						for (const key of Object.keys(headers)) {

package/src/services/evalrun/http.ts

@@ -13,6 +13,7 @@ import {
 	type Logger,
 	StructuredError,
 } from '@agentuity/core';
+import { internal } from '../../logger/internal';
 
 const EvalRunResponseError = StructuredError('EvalRunResponseError');
 
@@ -38,12 +39,22 @@ export class HTTPEvalRunEventProvider implements EvalRunEventProvider {
 	async start(event: EvalRunStartEvent): Promise<void> {
 		const endpoint = '/evalrun/2025-03-17';
 		const fullUrl = `${this.baseUrl}${endpoint}`;
-		this.logger.debug('[EVALRUN HTTP] Sending eval run start event: %s', event.id);
-		this.logger.debug('[EVALRUN HTTP] URL: %s %s', 'POST', fullUrl);
-		this.logger.debug('[EVALRUN HTTP] Base URL: %s', this.baseUrl);
 
 		const payload = { ...event, timestamp: Date.now() };
-		this.logger.debug('[EVALRUN HTTP] Start event payload: %s', JSON.stringify(payload, null, 2));
+
+		// Log full payload using internal logger
+		internal.info('[EVALRUN HTTP] ========== START PAYLOAD ==========');
+		internal.info('[EVALRUN HTTP] id: %s', payload.id);
+		internal.info('[EVALRUN HTTP] evalId: %s', payload.evalId);
+		internal.info('[EVALRUN HTTP] evalIdentifier: %s', payload.evalIdentifier);
+		internal.info('[EVALRUN HTTP] sessionId: %s', payload.sessionId);
+		internal.info('[EVALRUN HTTP] orgId: %s', payload.orgId);
+		internal.info('[EVALRUN HTTP] projectId: %s', payload.projectId);
+		internal.info('[EVALRUN HTTP] devmode: %s', payload.devmode);
+		internal.info('[EVALRUN HTTP] deploymentId: %s', payload.deploymentId);
+		internal.info('[EVALRUN HTTP] spanId: %s', payload.spanId);
+		internal.info('[EVALRUN HTTP] URL: POST %s', fullUrl);
+		internal.info('[EVALRUN HTTP] ============================================');
 
 		try {
 			const resp = await this.apiClient.post(

package/src/services/session/http.ts

@@ -8,6 +8,7 @@ import {
 	type Logger,
 	StructuredError,
 } from '@agentuity/core';
+import { internal } from '../../logger/internal';
 
 const SessionResponseError = StructuredError('SessionResponseError');
 
@@ -29,6 +30,7 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 	 * @param event SessionStartEvent
 	 */
 	async start(event: SessionStartEvent): Promise<void> {
+		internal.info('[session-http] sending start event: %s', event.id);
 		this.logger.debug('Sending session start event: %s', event.id);
 		const resp = await this.apiClient.post(
 			'/session/2025-03-17',
@@ -37,9 +39,11 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 			SessionStartEventDelayedSchema
 		);
 		if (resp.success) {
+			internal.info('[session-http] start event sent successfully: %s', event.id);
 			this.logger.debug('Session start event sent successfully: %s', event.id);
 			return;
 		}
+		internal.info('[session-http] start event failed: %s - %s', event.id, resp.message);
 		throw new SessionResponseError({ message: resp.message });
 	}
 
@@ -49,6 +53,11 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 	 * @param event SessionCompleteEvent
 	 */
 	async complete(event: SessionCompleteEvent): Promise<void> {
+		internal.info(
+			'[session-http] sending complete event: %s, userData: %s',
+			event.id,
+			event.userData ? `${event.userData.length} bytes` : 'none'
+		);
 		this.logger.debug('Sending session complete event: %s', event.id);
 		const resp = await this.apiClient.put(
 			'/session/2025-03-17',
@@ -57,9 +66,11 @@ export class HTTPSessionEventProvider implements SessionEventProvider {
 			SessionCompleteEventDelayedSchema
 		);
 		if (resp.success) {
+			internal.info('[session-http] complete event sent successfully: %s', event.id);
 			this.logger.debug('Session complete event sent successfully: %s', event.id);
 			return;
 		}
+		internal.info('[session-http] complete event failed: %s - %s', event.id, resp.message);
 		throw new SessionResponseError({ message: resp.message });
 	}
 }

package/src/services/session/local.ts

@@ -3,6 +3,7 @@ import {
 	type SessionStartEvent,
 	type SessionCompleteEvent,
 } from '@agentuity/core';
+import { internal } from '../../logger/internal';
 
 /**
  * An implementation of the SessionEventProvider which is no-op
@@ -13,8 +14,8 @@ export class LocalSessionEventProvider implements SessionEventProvider {
 	 *
 	 * @param event SessionStartEvent
 	 */
-	async start(_event: SessionStartEvent): Promise<void> {
-		// no op
+	async start(event: SessionStartEvent): Promise<void> {
+		internal.info('[session-local] start event (no-op): %s', event.id);
 	}
 
 	/**
@@ -22,7 +23,11 @@ export class LocalSessionEventProvider implements SessionEventProvider {
 	 *
 	 * @param event SessionCompleteEvent
 	 */
-	async complete(_event: SessionCompleteEvent): Promise<void> {
-		// no op
+	async complete(event: SessionCompleteEvent): Promise<void> {
+		internal.info(
+			'[session-local] complete event (no-op): %s, userData: %s',
+			event.id,
+			event.userData ? `${event.userData.length} bytes` : 'none'
+		);
 	}
 }

package/src/session.ts

@@ -72,6 +72,19 @@ export interface Thread {
 	 */
 	state: Map<string, unknown>;
 
+	/**
+	 * Unencrypted metadata for filtering and querying threads.
+	 * Unlike state, metadata is stored as-is in the database with GIN indexes
+	 * for efficient filtering. Initialized to empty object, only persisted if non-empty.
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.thread.metadata.userId = 'user123';
+	 * ctx.thread.metadata.department = 'sales';
+	 * ```
+	 */
+	metadata: Record<string, unknown>;
+
 	/**
 	 * Register an event listener for when the thread is destroyed.
 	 * Thread is destroyed when it expires or is manually destroyed.
@@ -182,6 +195,19 @@ export interface Session {
 	 */
 	state: Map<string, unknown>;
 
+	/**
+	 * Unencrypted metadata for filtering and querying sessions.
+	 * Unlike state, metadata is stored as-is in the database with GIN indexes
+	 * for efficient filtering. Initialized to empty object, only persisted if non-empty.
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.session.metadata.userId = 'user123';
+	 * ctx.session.metadata.requestType = 'chat';
+	 * ```
+	 */
+	metadata: Record<string, unknown>;
+
 	/**
 	 * Register an event listener for when the session completes.
 	 * Fired after the agent handler returns and response is sent.
@@ -653,13 +679,20 @@ export class DefaultThread implements Thread {
 	#initialStateJson: string | undefined;
 	readonly id: string;
 	readonly state: Map<string, unknown>;
+	metadata: Record<string, unknown>;
 	private provider: ThreadProvider;
 
-	constructor(provider: ThreadProvider, id: string, initialStateJson?: string) {
+	constructor(
+		provider: ThreadProvider,
+		id: string,
+		initialStateJson?: string,
+		metadata?: Record<string, unknown>
+	) {
 		this.provider = provider;
 		this.id = id;
 		this.state = new Map();
 		this.#initialStateJson = initialStateJson;
+		this.metadata = metadata || {};
 	}
 
 	addEventListener(eventName: ThreadEventName, callback: ThreadEventCallback<any>): void {
@@ -707,10 +740,10 @@ export class DefaultThread implements Thread {
 	}
 
 	/**
-	 * Check if thread has any data
+	 * Check if thread has any data (state or metadata)
 	 */
 	empty(): boolean {
-		return this.state.size === 0;
+		return this.state.size === 0 && Object.keys(this.metadata).length === 0;
 	}
 
 	/**
@@ -718,7 +751,24 @@ export class DefaultThread implements Thread {
 	 * @internal
 	 */
 	getSerializedState(): string {
-		return JSON.stringify(Object.fromEntries(this.state));
+		const hasState = this.state.size > 0;
+		const hasMetadata = Object.keys(this.metadata).length > 0;
+
+		if (!hasState && !hasMetadata) {
+			return '';
+		}
+
+		const data: { state?: Record<string, unknown>; metadata?: Record<string, unknown> } = {};
+
+		if (hasState) {
+			data.state = Object.fromEntries(this.state);
+		}
+
+		if (hasMetadata) {
+			data.metadata = this.metadata;
+		}
+
+		return JSON.stringify(data);
 	}
 }
 
@@ -726,11 +776,13 @@ export class DefaultSession implements Session {
 	readonly id: string;
 	readonly thread: Thread;
 	readonly state: Map<string, unknown>;
+	metadata: Record<string, unknown>;
 
-	constructor(thread: Thread, id: string) {
+	constructor(thread: Thread, id: string, metadata?: Record<string, unknown>) {
 		this.id = id;
 		this.thread = thread;
 		this.state = new Map();
+		this.metadata = metadata || {};
 	}
 
 	addEventListener(eventName: SessionEventName, callback: SessionEventCallback<any>): void {
@@ -1032,7 +1084,11 @@ export class ThreadWebSocketClient {
 		});
 	}
 
-	async save(threadId: string, userData: string): Promise<void> {
+	async save(
+		threadId: string,
+		userData: string,
+		threadMetadata?: Record<string, unknown>
+	): Promise<void> {
 		// Wait for connection/reconnection if in progress
 		if (this.wsConnecting) {
 			await this.wsConnecting;
@@ -1058,10 +1114,20 @@ export class ThreadWebSocketClient {
 				reject,
 			});
 
+			const data: { thread_id: string; user_data: string; metadata?: Record<string, unknown> } =
+				{
+					thread_id: threadId,
+					user_data: userData,
+				};
+
+			if (threadMetadata && Object.keys(threadMetadata).length > 0) {
+				data.metadata = threadMetadata;
+			}
+
 			const message = {
 				id: requestId,
 				action: 'save',
-				data: { thread_id: threadId, user_data: userData },
+				data,
 			};
 
 			this.ws!.send(JSON.stringify(message));
@@ -1174,26 +1240,59 @@ export class DefaultThreadProvider implements ThreadProvider {
 	async restore(ctx: Context<Env>): Promise<Thread> {
 		const threadId = await this.threadIDProvider!.getThreadId(this.appState!, ctx);
 		validateThreadIdOrThrow(threadId);
+		internal.info('[thread] restoring thread %s', threadId);
 
 		// Wait for WebSocket connection if still connecting
 		if (this.wsConnecting) {
+			internal.info('[thread] waiting for WebSocket connection');
 			await this.wsConnecting;
 		}
 
-		// Restore thread state from WebSocket if available
+		// Restore thread state and metadata from WebSocket if available
 		let initialStateJson: string | undefined;
+		let restoredMetadata: Record<string, unknown> | undefined;
 		if (this.wsClient) {
 			try {
+				internal.info('[thread] restoring state from WebSocket');
 				const restoredData = await this.wsClient.restore(threadId);
 				if (restoredData) {
 					initialStateJson = restoredData;
+					internal.info('[thread] restored state: %d bytes', restoredData.length);
+					// Parse to check if it includes metadata
+					try {
+						const parsed = JSON.parse(restoredData);
+						// New format: { state?: {...}, metadata?: {...} }
+						if (
+							parsed &&
+							typeof parsed === 'object' &&
+							('state' in parsed || 'metadata' in parsed)
+						) {
+							if (parsed.metadata) {
+								restoredMetadata = parsed.metadata;
+							}
+							// Update initialStateJson to be just the state part for backwards compatibility
+							if (parsed.state) {
+								initialStateJson = JSON.stringify(parsed.state);
+							} else {
+								initialStateJson = undefined;
+							}
+						}
+						// else: Old format (just state object), keep as-is
+					} catch {
+						// Keep original if parse fails
+					}
+				} else {
+					internal.info('[thread] no existing state found');
 				}
-			} catch {
+			} catch (err) {
+				internal.info('[thread] WebSocket restore failed: %s', err);
 				// Continue with empty state rather than failing
 			}
+		} else {
+			internal.info('[thread] no WebSocket client available');
 		}
 
-		const thread = new DefaultThread(this, threadId, initialStateJson);
+		const thread = new DefaultThread(this, threadId, initialStateJson, restoredMetadata);
 
 		// Populate thread state from restored data
 		if (initialStateJson) {
@@ -1202,7 +1301,9 @@ export class DefaultThreadProvider implements ThreadProvider {
 				for (const [key, value] of Object.entries(data)) {
 					thread.state.set(key, value);
 				}
-			} catch {
+				internal.info('[thread] populated state with %d keys', thread.state.size);
+			} catch (err) {
+				internal.info('[thread] failed to parse state JSON: %s', err);
 				// Continue with empty state if parsing fails
 			}
 		}
@@ -1213,8 +1314,16 @@ export class DefaultThreadProvider implements ThreadProvider {
 
 	async save(thread: Thread): Promise<void> {
 		if (thread instanceof DefaultThread) {
+			internal.info(
+				'[thread] DefaultThreadProvider.save() - thread %s, isDirty: %s, hasWsClient: %s',
+				thread.id,
+				thread.isDirty(),
+				!!this.wsClient
+			);
+
 			// Wait for WebSocket connection if still connecting
 			if (this.wsConnecting) {
+				internal.info('[thread] waiting for WebSocket connection');
 				await this.wsConnecting;
 			}
 
@@ -1222,10 +1331,20 @@ export class DefaultThreadProvider implements ThreadProvider {
 			if (this.wsClient && thread.isDirty()) {
 				try {
 					const serialized = thread.getSerializedState();
-					await this.wsClient.save(thread.id, serialized);
-				} catch {
+					internal.info(
+						'[thread] saving to WebSocket, serialized length: %d',
+						serialized.length
+					);
+					const metadata =
+						Object.keys(thread.metadata).length > 0 ? thread.metadata : undefined;
+					await this.wsClient.save(thread.id, serialized, metadata);
+					internal.info('[thread] WebSocket save completed');
+				} catch (err) {
+					internal.info('[thread] WebSocket save failed: %s', err);
 					// Don't throw - allow request to complete even if save fails
 				}
+			} else {
+				internal.info('[thread] skipping save - no wsClient or thread not dirty');
 			}
 		}
 	}
@@ -1269,20 +1388,30 @@ export class DefaultSessionProvider implements SessionProvider {
 	}
 
 	async restore(thread: Thread, sessionId: string): Promise<Session> {
+		internal.info('[session] restoring session %s for thread %s', sessionId, thread.id);
 		let session = this.sessions.get(sessionId);
 		if (!session) {
 			session = new DefaultSession(thread, sessionId);
 			this.sessions.set(sessionId, session);
+			internal.info('[session] created new session, firing session.started');
 			await fireEvent('session.started', session);
+		} else {
+			internal.info('[session] found existing session');
 		}
 		return session;
 	}
 
 	async save(session: Session): Promise<void> {
 		if (session instanceof DefaultSession) {
+			internal.info(
+				'[session] DefaultSessionProvider.save() - firing completed event for session %s',
+				session.id
+			);
 			try {
 				await session.fireEvent('completed');
+				internal.info('[session] session.fireEvent completed, firing app event');
 				await fireEvent('session.completed', session);
+				internal.info('[session] session.completed app event fired');
 			} finally {
 				this.sessions.delete(session.id);
 				sessionEventListeners.delete(session);