@agentuity/runtime 0.0.59 → 0.0.61

package/src/session.ts

@@ -3,6 +3,7 @@
 import type { Context } from 'hono';
 import { getCookie, setCookie } from 'hono/cookie';
 import { type Env, fireEvent } from './app';
+import type { AppState } from './index';
 
 export type ThreadEventName = 'destroyed';
 export type SessionEventName = 'completed';
@@ -17,44 +18,336 @@ type SessionEventCallback<T extends Session> = (
 	session: T
 ) => Promise<void> | void;
 
+/**
+ * Represents a conversation thread that persists across multiple sessions.
+ * Threads maintain state and can contain multiple request-response sessions.
+ *
+ * Threads are automatically managed by the runtime and stored in cookies.
+ * They expire after 1 hour of inactivity by default.
+ *
+ * @example
+ * ```typescript
+ * // Access thread in agent handler
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     // Get thread ID
+ *     console.log('Thread:', ctx.thread.id);
+ *
+ *     // Store data in thread state (persists across sessions)
+ *     ctx.thread.state.set('conversationCount',
+ *       (ctx.thread.state.get('conversationCount') as number || 0) + 1
+ *     );
+ *
+ *     // Listen for thread destruction
+ *     ctx.thread.addEventListener('destroyed', (eventName, thread) => {
+ *       console.log('Thread destroyed:', thread.id);
+ *     });
+ *
+ *     return 'Response';
+ *   }
+ * });
+ * ```
+ */
 export interface Thread {
+	/**
+	 * Unique thread identifier (e.g., "thrd_a1b2c3d4...").
+	 * Stored in cookie and persists across requests.
+	 */
 	id: string;
+
+	/**
+	 * Thread-scoped state storage that persists across multiple sessions.
+	 * Use this to maintain conversation history or user preferences.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Store conversation count
+	 * ctx.thread.state.set('messageCount',
+	 *   (ctx.thread.state.get('messageCount') as number || 0) + 1
+	 * );
+	 * ```
+	 */
 	state: Map<string, unknown>;
+
+	/**
+	 * Register an event listener for when the thread is destroyed.
+	 * Thread is destroyed when it expires or is manually destroyed.
+	 *
+	 * @param eventName - Must be 'destroyed'
+	 * @param callback - Function called when thread is destroyed
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.thread.addEventListener('destroyed', (eventName, thread) => {
+	 *   console.log('Cleaning up thread:', thread.id);
+	 * });
+	 * ```
+	 */
 	addEventListener(
 		eventName: 'destroyed',
 		callback: (eventName: 'destroyed', thread: Thread) => Promise<void> | void
 	): void;
+
+	/**
+	 * Remove a previously registered 'destroyed' event listener.
+	 *
+	 * @param eventName - Must be 'destroyed'
+	 * @param callback - The callback function to remove
+	 */
 	removeEventListener(
 		eventName: 'destroyed',
 		callback: (eventName: 'destroyed', thread: Thread) => Promise<void> | void
 	): void;
+
+	/**
+	 * Manually destroy the thread and clean up resources.
+	 * Fires the 'destroyed' event and removes thread from storage.
+	 *
+	 * @example
+	 * ```typescript
+	 * // End conversation
+	 * await ctx.thread.destroy();
+	 * ```
+	 */
 	destroy(): Promise<void>;
 }
 
+/**
+ * Represents a single request-response session within a thread.
+ * Sessions are scoped to a single agent execution and its sub-agent calls.
+ *
+ * Each HTTP request creates a new session with a unique ID, but shares the same thread.
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent({
+ *   handler: async (ctx, input) => {
+ *     // Get session ID (unique per request)
+ *     console.log('Session:', ctx.session.id);
+ *
+ *     // Store data in session state (only for this request)
+ *     ctx.session.state.set('startTime', Date.now());
+ *
+ *     // Access parent thread
+ *     console.log('Thread:', ctx.session.thread.id);
+ *
+ *     // Listen for session completion
+ *     ctx.session.addEventListener('completed', (eventName, session) => {
+ *       const duration = Date.now() - (session.state.get('startTime') as number);
+ *       console.log(`Session completed in ${duration}ms`);
+ *     });
+ *
+ *     return 'Response';
+ *   }
+ * });
+ * ```
+ */
 export interface Session {
+	/**
+	 * Unique session identifier for this request.
+	 * Changes with each HTTP request, even within the same thread.
+	 */
 	id: string;
+
+	/**
+	 * The parent thread this session belongs to.
+	 * Multiple sessions can share the same thread.
+	 */
 	thread: Thread;
+
+	/**
+	 * Session-scoped state storage that only exists for this request.
+	 * Use this for temporary data that shouldn't persist across requests.
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.session.state.set('requestStartTime', Date.now());
+	 * ```
+	 */
 	state: Map<string, unknown>;
+
+	/**
+	 * Register an event listener for when the session completes.
+	 * Fired after the agent handler returns and response is sent.
+	 *
+	 * @param eventName - Must be 'completed'
+	 * @param callback - Function called when session completes
+	 *
+	 * @example
+	 * ```typescript
+	 * ctx.session.addEventListener('completed', (eventName, session) => {
+	 *   console.log('Session finished:', session.id);
+	 * });
+	 * ```
+	 */
 	addEventListener(
 		eventName: 'completed',
 		callback: (eventName: 'completed', session: Session) => Promise<void> | void
 	): void;
+
+	/**
+	 * Remove a previously registered 'completed' event listener.
+	 *
+	 * @param eventName - Must be 'completed'
+	 * @param callback - The callback function to remove
+	 */
 	removeEventListener(
 		eventName: 'completed',
 		callback: (eventName: 'completed', session: Session) => Promise<void> | void
 	): void;
 }
 
+/**
+ * Provider interface for managing thread lifecycle and persistence.
+ * Implement this to customize how threads are stored and retrieved.
+ *
+ * The default implementation (DefaultThreadProvider) stores threads in-memory
+ * with cookie-based identification and 1-hour expiration.
+ *
+ * @example
+ * ```typescript
+ * class RedisThreadProvider implements ThreadProvider {
+ *   private redis: Redis;
+ *
+ *   async initialize(appState: AppState): Promise<void> {
+ *     this.redis = await connectRedis();
+ *   }
+ *
+ *   async restore(ctx: Context<Env>): Promise<Thread> {
+ *     const threadId = getCookie(ctx, 'atid') || generateId('thrd');
+ *     const data = await this.redis.get(`thread:${threadId}`);
+ *     const thread = new DefaultThread(this, threadId);
+ *     if (data) {
+ *       thread.state = new Map(JSON.parse(data));
+ *     }
+ *     return thread;
+ *   }
+ *
+ *   async save(thread: Thread): Promise<void> {
+ *     await this.redis.setex(
+ *       `thread:${thread.id}`,
+ *       3600,
+ *       JSON.stringify([...thread.state])
+ *     );
+ *   }
+ *
+ *   async destroy(thread: Thread): Promise<void> {
+ *     await this.redis.del(`thread:${thread.id}`);
+ *   }
+ * }
+ *
+ * // Use custom provider
+ * const app = await createApp({
+ *   services: {
+ *     thread: new RedisThreadProvider()
+ *   }
+ * });
+ * ```
+ */
 export interface ThreadProvider {
-	initialize(): Promise<void>;
+	/**
+	 * Initialize the provider when the app starts.
+	 * Use this to set up connections, start cleanup intervals, etc.
+	 *
+	 * @param appState - The app state from createApp setup function
+	 */
+	initialize(appState: AppState): Promise<void>;
+
+	/**
+	 * Restore or create a thread from the HTTP request context.
+	 * Should check cookies for existing thread ID or create a new one.
+	 *
+	 * @param ctx - Hono request context
+	 * @returns The restored or newly created thread
+	 */
 	restore(ctx: Context<Env>): Promise<Thread>;
+
+	/**
+	 * Persist thread state to storage.
+	 * Called periodically to save thread data.
+	 *
+	 * @param thread - The thread to save
+	 */
 	save(thread: Thread): Promise<void>;
+
+	/**
+	 * Destroy a thread and clean up resources.
+	 * Should fire the 'destroyed' event and remove from storage.
+	 *
+	 * @param thread - The thread to destroy
+	 */
 	destroy(thread: Thread): Promise<void>;
 }
 
+/**
+ * Provider interface for managing session lifecycle and persistence.
+ * Implement this to customize how sessions are stored and retrieved.
+ *
+ * The default implementation (DefaultSessionProvider) stores sessions in-memory
+ * and automatically cleans them up after completion.
+ *
+ * @example
+ * ```typescript
+ * class PostgresSessionProvider implements SessionProvider {
+ *   private db: Database;
+ *
+ *   async initialize(appState: AppState): Promise<void> {
+ *     this.db = appState.db;
+ *   }
+ *
+ *   async restore(thread: Thread, sessionId: string): Promise<Session> {
+ *     const row = await this.db.query(
+ *       'SELECT state FROM sessions WHERE id = $1',
+ *       [sessionId]
+ *     );
+ *     const session = new DefaultSession(thread, sessionId);
+ *     if (row) {
+ *       session.state = new Map(JSON.parse(row.state));
+ *     }
+ *     return session;
+ *   }
+ *
+ *   async save(session: Session): Promise<void> {
+ *     await this.db.query(
+ *       'INSERT INTO sessions (id, thread_id, state) VALUES ($1, $2, $3)',
+ *       [session.id, session.thread.id, JSON.stringify([...session.state])]
+ *     );
+ *   }
+ * }
+ *
+ * // Use custom provider
+ * const app = await createApp({
+ *   services: {
+ *     session: new PostgresSessionProvider()
+ *   }
+ * });
+ * ```
+ */
 export interface SessionProvider {
-	initialize(): Promise<void>;
+	/**
+	 * Initialize the provider when the app starts.
+	 * Use this to set up database connections or other resources.
+	 *
+	 * @param appState - The app state from createApp setup function
+	 */
+	initialize(appState: AppState): Promise<void>;
+
+	/**
+	 * Restore or create a session for the given thread and session ID.
+	 * Should load existing session data or create a new session.
+	 *
+	 * @param thread - The parent thread for this session
+	 * @param sessionId - The unique session identifier
+	 * @returns The restored or newly created session
+	 */
 	restore(thread: Thread, sessionId: string): Promise<Session>;
+
+	/**
+	 * Persist session state and fire completion events.
+	 * Called after the agent handler completes.
+	 *
+	 * @param session - The session to save
+	 */
 	save(session: Session): Promise<void>;
 }
 
@@ -194,7 +487,7 @@ export class DefaultSession implements Session {
 export class DefaultThreadProvider implements ThreadProvider {
 	private threads = new Map<string, DefaultThread>();
 
-	async initialize(): Promise<void> {
+	async initialize(_appState: AppState): Promise<void> {
 		setInterval(() => {
 			for (const [, thread] of this.threads) {
 				if (thread.expired()) {
@@ -256,7 +549,7 @@ export class DefaultThreadProvider implements ThreadProvider {
 export class DefaultSessionProvider implements SessionProvider {
 	private sessions = new Map<string, DefaultSession>();
 
-	async initialize(): Promise<void> {
+	async initialize(_appState: AppState): Promise<void> {
 		// No initialization needed for in-memory provider
 	}