@agentuity/runtime 0.0.100 → 0.0.102

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);

package/src/workbench.ts

@@ -6,8 +6,7 @@ import { createRouter } from './router';
 import type { WebSocketConnection } from './router';
 import { privateContext } from './_server';
 import { getThreadProvider } from './_services';
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { loadBuildMetadata, getAgentMetadataByAgentId, hasMetadata } from './_metadata';
 
 export const createWorkbenchExecutionRoute = (): Handler => {
 	const authHeader = process.env.AGENTUITY_WORKBENCH_APIKEY
@@ -49,16 +48,11 @@ export const createWorkbenchExecutionRoute = (): Handler => {
 			}
 
 			// Read metadata to find agent name by agentId
-			const metadataPath = join(process.cwd(), '.agentuity', 'agentuity.metadata.json');
-			if (!existsSync(metadataPath)) {
-				return ctx.json({ error: 'Metadata file not found' }, { status: 500 });
-			}
-
-			const fileContent = readFileSync(metadataPath, 'utf-8');
-			const metadata = JSON.parse(fileContent);
-			const agentMeta = metadata.agents?.find((a: { agentId: string }) => a.agentId === agentId);
-
+			const agentMeta = getAgentMetadataByAgentId(agentId);
 			if (!agentMeta) {
+				if (!hasMetadata()) {
+					return ctx.json({ error: 'Metadata file not found' }, { status: 500 });
+				}
 				return ctx.text('Agent not found', { status: 404 });
 			}
 
@@ -75,6 +69,8 @@ export const createWorkbenchExecutionRoute = (): Handler => {
 			const _ctx = privateContext(ctx);
 			if (agentObj.metadata?.id) {
 				_ctx.var.agentIds.add(agentObj.metadata.id);
+			}
+			if (agentObj.metadata?.agentId) {
 				_ctx.var.agentIds.add(agentObj.metadata.agentId);
 			}
 
@@ -295,16 +291,11 @@ export const createWorkbenchSampleRoute = (): Handler => {
 			}
 
 			// Read metadata to find agent name by agentId
-			const metadataPath = join(process.cwd(), '.agentuity', 'agentuity.metadata.json');
-			if (!existsSync(metadataPath)) {
-				return ctx.json({ error: 'Metadata file not found' }, { status: 500 });
-			}
-
-			const fileContent = readFileSync(metadataPath, 'utf-8');
-			const metadata = JSON.parse(fileContent);
-			const agentMeta = metadata.agents?.find((a: { agentId: string }) => a.agentId === agentId);
-
+			const agentMeta = getAgentMetadataByAgentId(agentId);
 			if (!agentMeta) {
+				if (!hasMetadata()) {
+					return ctx.json({ error: 'Metadata file not found' }, { status: 500 });
+				}
 				return ctx.text('Agent not found', { status: 404 });
 			}
 
@@ -446,9 +437,8 @@ export const createWorkbenchMetadataRoute = (): Handler => {
 		}
 
 		// Read metadata from agentuity.metadata.json file
-		const metadataPath = join(process.cwd(), '.agentuity', 'agentuity.metadata.json');
-
-		if (!existsSync(metadataPath)) {
+		const metadata = loadBuildMetadata();
+		if (!metadata) {
 			return ctx.json(
 				{ error: 'Metadata file not found. Run build to generate metadata.' },
 				{ status: 500 }
@@ -456,9 +446,6 @@ export const createWorkbenchMetadataRoute = (): Handler => {
 		}
 
 		try {
-			const fileContent = readFileSync(metadataPath, 'utf-8');
-			const metadata = JSON.parse(fileContent);
-
 			// Get runtime agents for JSON schema generation
 			const agents = getAgents();
 			const agentsByName = new Map();