@agentuity/runtime 0.0.95 → 0.0.96

package/src/session.ts

@@ -1,12 +1,12 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /** biome-ignore-all lint/suspicious/noExplicitAny: anys are great */
 import type { Context } from 'hono';
-import { getCookie, setCookie } from 'hono/cookie';
+import { getSignedCookie, setSignedCookie } from 'hono/cookie';
 import { type Env, fireEvent } from './app';
 import type { AppState } from './index';
 import { getServiceUrls } from '@agentuity/server';
-import { WebSocket } from 'ws';
 import { internal } from './logger/internal';
+import { timingSafeEqual } from 'node:crypto';
 
 export type ThreadEventName = 'destroyed';
 export type SessionEventName = 'completed';
@@ -229,13 +229,13 @@ export interface ThreadIDProvider {
 	 * thrd_ such as `thrd_212c16896b974ffeb21a748f0eeba620`. The max length of the
 	 * string is 64 characters and the min length is 32 characters long
 	 * (including the prefix). The characters after the prefix must match the
-	 * regular expression [a-zA-Z0-9-].
+	 * regular expression [a-zA-Z0-9].
 	 *
 	 * @param appState - The app state from createApp setup function
 	 * @param ctx - Hono request context
-	 * @returns The thread id to use
+	 * @returns The thread id to use (can be async for signed cookies)
 	 */
-	getThreadId(appState: AppState, ctx: Context<Env>): string;
+	getThreadId(appState: AppState, ctx: Context<Env>): string | Promise<string>;
 }
 
 /**
@@ -255,7 +255,7 @@ export interface ThreadIDProvider {
  *   }
  *
  *   async restore(ctx: Context<Env>): Promise<Thread> {
- *     const threadId = getCookie(ctx, 'atid') || generateId('thrd');
+ *     const threadId = ctx.req.header('x-thread-id') || getCookie(ctx, 'atid') || generateId('thrd');
  *     const data = await this.redis.get(`thread:${threadId}`);
  *     const thread = new DefaultThread(this, threadId);
  *     if (data) {
@@ -454,21 +454,197 @@ export function generateId(prefix?: string): string {
 }
 
 /**
- * DefaultThreadIDProvider will look for a cookie named `atid` and use that as
- * the thread id or if not found, generate a new one.
+ * Validates a thread ID against runtime constraints:
+ * - Must start with 'thrd_'
+ * - Must be at least 32 characters long (including prefix)
+ * - Must be less than 64 characters long
+ * - Must contain only [a-zA-Z0-9] after 'thrd_' prefix (no dashes for maximum randomness)
+ */
+export function isValidThreadId(threadId: string): boolean {
+	if (!threadId.startsWith('thrd_')) {
+		return false;
+	}
+	if (threadId.length < 32 || threadId.length > 64) {
+		return false;
+	}
+	const validThreadIdCharacters = /^[a-zA-Z0-9]+$/;
+	if (!validThreadIdCharacters.test(threadId.substring(5))) {
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Validates a thread ID and throws detailed error messages for debugging.
+ * @param threadId The thread ID to validate
+ * @throws Error with detailed message if validation fails
+ */
+export function validateThreadIdOrThrow(threadId: string): void {
+	if (!threadId) {
+		throw new Error(`the ThreadIDProvider returned an empty thread id for getThreadId`);
+	}
+	if (!threadId.startsWith('thrd_')) {
+		throw new Error(
+			`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must start with the prefix 'thrd_'.`
+		);
+	}
+	if (threadId.length > 64) {
+		throw new Error(
+			`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must be less than 64 characters long.`
+		);
+	}
+	if (threadId.length < 32) {
+		throw new Error(
+			`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must be at least 32 characters long.`
+		);
+	}
+	const validThreadIdCharacters = /^[a-zA-Z0-9]+$/;
+	if (!validThreadIdCharacters.test(threadId.substring(5))) {
+		throw new Error(
+			`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must contain only characters that match the regular expression [a-zA-Z0-9].`
+		);
+	}
+}
+
+/**
+ * Determines if the connection is secure (HTTPS) by checking the request protocol
+ * and x-forwarded-proto header (for reverse proxy scenarios).
+ * Defaults to false (HTTP) if unable to determine.
+ */
+export function isSecureConnection(ctx: Context<Env>): boolean {
+	// Check x-forwarded-proto header first (reverse proxy)
+	const forwardedProto = ctx.req.header('x-forwarded-proto');
+	if (forwardedProto) {
+		return forwardedProto === 'https';
+	}
+
+	// Check the request URL protocol if available
+	try {
+		if (ctx.req.url) {
+			const url = new URL(ctx.req.url);
+			return url.protocol === 'https:';
+		}
+	} catch {
+		// Fall through to default
+	}
+
+	// Default to HTTP (e.g., for localhost development)
+	return false;
+}
+
+/**
+ * Signs a thread ID using HMAC SHA-256 and returns it in the format: threadId;signature
+ * Format: thrd_abc123;base64signature
+ */
+export async function signThreadId(threadId: string, secret: string): Promise<string> {
+	const hasher = new Bun.CryptoHasher('sha256', secret);
+	hasher.update(threadId);
+	const signatureBase64 = hasher.digest('base64');
+
+	return `${threadId};${signatureBase64}`;
+}
+
+/**
+ * Verifies a signed thread ID header and returns the thread ID if valid, or undefined if invalid.
+ * Expected format: thrd_abc123;base64signature
+ */
+export async function verifySignedThreadId(
+	signedValue: string,
+	secret: string
+): Promise<string | undefined> {
+	const parts = signedValue.split(';');
+	if (parts.length !== 2) {
+		return undefined;
+	}
+
+	const [threadId, providedSignature] = parts;
+
+	// Validate both parts exist
+	if (!threadId || !providedSignature) {
+		return undefined;
+	}
+
+	// Validate thread ID format before verifying signature
+	if (!isValidThreadId(threadId)) {
+		return undefined;
+	}
+
+	// Re-sign the thread ID and compare signatures
+	const expectedSigned = await signThreadId(threadId, secret);
+	const expectedSignature = expectedSigned.split(';')[1];
+
+	// Validate signature exists
+	if (!expectedSignature) {
+		return undefined;
+	}
+
+	// Constant-time comparison to prevent timing attacks
+	// Check lengths match first (fail fast if different lengths)
+	if (providedSignature.length !== expectedSignature.length) {
+		return undefined;
+	}
+
+	try {
+		// Convert to Buffers for constant-time comparison
+		const providedBuffer = Buffer.from(providedSignature, 'base64');
+		const expectedBuffer = Buffer.from(expectedSignature, 'base64');
+
+		if (timingSafeEqual(providedBuffer, expectedBuffer)) {
+			return threadId;
+		}
+	} catch {
+		// Comparison failed or buffer conversion error
+		return undefined;
+	}
+
+	return undefined;
+}
+
+/**
+ * DefaultThreadIDProvider will look for an HTTP header `x-thread-id` first,
+ * then fall back to a signed cookie named `atid`, and use that as the thread id.
+ * If not found, generate a new one. Validates incoming thread IDs against
+ * runtime constraints. Uses AGENTUITY_SDK_KEY for signing, falls back to 'agentuity'.
  */
 export class DefaultThreadIDProvider implements ThreadIDProvider {
-	getThreadId(_appState: AppState, ctx: Context<Env>): string {
-		const cookie = getCookie(ctx);
+	private getSecret(): string {
+		return process.env.AGENTUITY_SDK_KEY || 'agentuity';
+	}
+
+	async getThreadId(_appState: AppState, ctx: Context<Env>): Promise<string> {
 		let threadId: string | undefined;
+		const secret = this.getSecret();
+
+		// Check signed header first
+		const headerValue = ctx.req.header('x-thread-id');
+		if (headerValue) {
+			const verifiedThreadId = await verifySignedThreadId(headerValue, secret);
+			if (verifiedThreadId) {
+				threadId = verifiedThreadId;
+			}
+		}
 
-		if (cookie.atid?.startsWith('thrd_')) {
-			threadId = cookie.atid;
+		// Fall back to signed cookie
+		if (!threadId) {
+			const cookieValue = await getSignedCookie(ctx, secret, 'atid');
+			if (cookieValue && typeof cookieValue === 'string' && isValidThreadId(cookieValue)) {
+				threadId = cookieValue;
+			}
 		}
 
 		threadId = threadId || generateId('thrd');
 
-		setCookie(ctx, 'atid', threadId);
+		await setSignedCookie(ctx, 'atid', threadId, secret, {
+			httpOnly: true,
+			secure: isSecureConnection(ctx),
+			sameSite: 'Lax',
+			path: '/',
+			maxAge: 604800, // 1 week in seconds
+		});
+
+		// Set signed header in response
+		const signedHeader = await signThreadId(threadId, secret);
+		ctx.header('x-thread-id', signedHeader);
 		return threadId;
 	}
 }
@@ -623,6 +799,22 @@ export class DefaultSession implements Session {
  * @internal
  * @experimental
  */
+/**
+ * Configuration options for ThreadWebSocketClient
+ */
+export interface ThreadWebSocketClientOptions {
+	/** Connection timeout in milliseconds (default: 10000) */
+	connectionTimeoutMs?: number;
+	/** Request timeout in milliseconds (default: 10000) */
+	requestTimeoutMs?: number;
+	/** Base delay for reconnection backoff in milliseconds (default: 1000) */
+	reconnectBaseDelayMs?: number;
+	/** Maximum delay for reconnection backoff in milliseconds (default: 30000) */
+	reconnectMaxDelayMs?: number;
+	/** Maximum number of reconnection attempts (default: 5) */
+	maxReconnectAttempts?: number;
+}
+
 export class ThreadWebSocketClient {
 	private ws: WebSocket | null = null;
 	private authenticated = false;
@@ -631,7 +823,7 @@ export class ThreadWebSocketClient {
 		{ resolve: (data?: string) => void; reject: (err: Error) => void }
 	>();
 	private reconnectAttempts = 0;
-	private maxReconnectAttempts = 5;
+	private maxReconnectAttempts: number;
 	private apiKey: string;
 	private wsUrl: string;
 	private wsConnecting: Promise<void> | null = null;
@@ -639,10 +831,19 @@ export class ThreadWebSocketClient {
 	private isDisposed = false;
 	private initialConnectResolve: (() => void) | null = null;
 	private initialConnectReject: ((err: Error) => void) | null = null;
+	private connectionTimeoutMs: number;
+	private requestTimeoutMs: number;
+	private reconnectBaseDelayMs: number;
+	private reconnectMaxDelayMs: number;
 
-	constructor(apiKey: string, wsUrl: string) {
+	constructor(apiKey: string, wsUrl: string, options: ThreadWebSocketClientOptions = {}) {
 		this.apiKey = apiKey;
 		this.wsUrl = wsUrl;
+		this.connectionTimeoutMs = options.connectionTimeoutMs ?? 10_000;
+		this.requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+		this.reconnectBaseDelayMs = options.reconnectBaseDelayMs ?? 1_000;
+		this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? 30_000;
+		this.maxReconnectAttempts = options.maxReconnectAttempts ?? 5;
 	}
 
 	async connect(): Promise<void> {
@@ -659,20 +860,20 @@ export class ThreadWebSocketClient {
 				const rejectFn = this.initialConnectReject || reject;
 				this.initialConnectResolve = null;
 				this.initialConnectReject = null;
-				rejectFn(new Error('WebSocket connection timeout (10s)'));
-			}, 10_000);
+				rejectFn(new Error(`WebSocket connection timeout (${this.connectionTimeoutMs}ms)`));
+			}, this.connectionTimeoutMs);
 
 			try {
 				this.ws = new WebSocket(this.wsUrl);
 
-				this.ws.on('open', () => {
+				this.ws.addEventListener('open', () => {
 					// Send authentication (do NOT clear timeout yet - wait for auth response)
 					this.ws?.send(JSON.stringify({ authorization: this.apiKey }));
 				});
 
-				this.ws.on('message', (data: any) => {
+				this.ws.addEventListener('message', (event: MessageEvent) => {
 					try {
-						const message = JSON.parse(data.toString());
+						const message = JSON.parse(event.data);
 
 						// Handle auth response
 						if ('success' in message && !this.authenticated) {
@@ -715,7 +916,7 @@ export class ThreadWebSocketClient {
 					}
 				});
 
-				this.ws.on('error', (err: Error) => {
+				this.ws.addEventListener('error', (_event: Event) => {
 					clearTimeout(connectionTimeout);
 					if (!this.authenticated) {
 						// Don't reject immediately if we'll attempt reconnection
@@ -723,12 +924,12 @@ export class ThreadWebSocketClient {
 							const rejectFn = this.initialConnectReject || reject;
 							this.initialConnectResolve = null;
 							this.initialConnectReject = null;
-							rejectFn(new Error(`WebSocket error: ${err.message}`));
+							rejectFn(new Error(`WebSocket error`));
 						}
 					}
 				});
 
-				this.ws.on('close', () => {
+				this.ws.addEventListener('close', () => {
 					clearTimeout(connectionTimeout);
 					const wasAuthenticated = this.authenticated;
 					this.authenticated = false;
@@ -754,7 +955,10 @@ export class ThreadWebSocketClient {
 					// This handles server rollouts where connection closes before auth finishes
 					if (this.reconnectAttempts < this.maxReconnectAttempts) {
 						this.reconnectAttempts++;
-						const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30_000);
+						const delay = Math.min(
+							this.reconnectBaseDelayMs * Math.pow(2, this.reconnectAttempts),
+							this.reconnectMaxDelayMs
+						);
 
 						internal.info(
 							`WebSocket disconnected, attempting reconnection ${this.reconnectAttempts}/${this.maxReconnectAttempts} in ${delay}ms`
@@ -818,13 +1022,13 @@ export class ThreadWebSocketClient {
 
 			this.ws!.send(JSON.stringify(message));
 
-			// Timeout after 10 seconds
+			// Timeout after configured duration
 			setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
 					this.pendingRequests.delete(requestId);
 					reject(new Error('Request timeout'));
 				}
-			}, 10000);
+			}, this.requestTimeoutMs);
 		});
 	}
 
@@ -862,13 +1066,13 @@ export class ThreadWebSocketClient {
 
 			this.ws!.send(JSON.stringify(message));
 
-			// Timeout after 10 seconds
+			// Timeout after configured duration
 			setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
 					this.pendingRequests.delete(requestId);
 					reject(new Error('Request timeout'));
 				}
-			}, 10_000);
+			}, this.requestTimeoutMs);
 		});
 	}
 
@@ -897,13 +1101,13 @@ export class ThreadWebSocketClient {
 
 			this.ws!.send(JSON.stringify(message));
 
-			// Timeout after 10 seconds
+			// Timeout after configured duration
 			setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
 					this.pendingRequests.delete(requestId);
 					reject(new Error('Request timeout'));
 				}
-			}, 10_000);
+			}, this.requestTimeoutMs);
 		});
 	}
 
@@ -930,8 +1134,6 @@ export class ThreadWebSocketClient {
 	}
 }
 
-const validThreadIdCharacters = /^[a-zA-Z0-9-]+$/;
-
 export class DefaultThreadProvider implements ThreadProvider {
 	private appState: AppState | null = null;
 	private wsClient: ThreadWebSocketClient | null = null;
@@ -948,7 +1150,7 @@ export class DefaultThreadProvider implements ThreadProvider {
 			const serviceUrls = getServiceUrls(process.env.AGENTUITY_REGION ?? 'usc');
 			const catalystUrl = serviceUrls.catalyst;
 			const wsUrl = new URL('/thread/ws', catalystUrl.replace(/^http/, 'ws'));
-			console.debug('connecting to %s', wsUrl);
+			internal.debug('connecting to %s', wsUrl);
 
 			this.wsClient = new ThreadWebSocketClient(apiKey, wsUrl.toString());
 			// Connect in background, don't block initialization
@@ -958,7 +1160,7 @@ export class DefaultThreadProvider implements ThreadProvider {
 					this.wsConnecting = null;
 				})
 				.catch((err) => {
-					console.error('Failed to connect to thread WebSocket:', err);
+					internal.error('Failed to connect to thread WebSocket:', err);
 					this.wsClient = null;
 					this.wsConnecting = null;
 				});
@@ -970,31 +1172,8 @@ export class DefaultThreadProvider implements ThreadProvider {
 	}
 
 	async restore(ctx: Context<Env>): Promise<Thread> {
-		const threadId = this.threadIDProvider!.getThreadId(this.appState!, ctx);
-
-		if (!threadId) {
-			throw new Error(`the ThreadIDProvider returned an empty thread id for getThreadId`);
-		}
-		if (!threadId.startsWith('thrd_')) {
-			throw new Error(
-				`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must start with the prefix 'thrd_'.`
-			);
-		}
-		if (threadId.length > 64) {
-			throw new Error(
-				`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must be less than 64 characters long.`
-			);
-		}
-		if (threadId.length < 32) {
-			throw new Error(
-				`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must be at least 32 characters long.`
-			);
-		}
-		if (!validThreadIdCharacters.test(threadId.substring(5))) {
-			throw new Error(
-				`the ThreadIDProvider returned an invalid thread id (${threadId}) for getThreadId. The thread id must contain only characters that match the regular expression [a-zA-Z0-9-].`
-			);
-		}
+		const threadId = await this.threadIDProvider!.getThreadId(this.appState!, ctx);
+		validateThreadIdOrThrow(threadId);
 
 		// Wait for WebSocket connection if still connecting
 		if (this.wsConnecting) {

package/src/web.ts

@@ -0,0 +1,75 @@
+import { Hono } from 'hono';
+import { serveStatic } from 'hono/bun';
+import { join, relative } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Create a router that serves the web application.
+ * In dev mode (DEV=true), serves HTML with Vite HMR scripts (Bun server proxies assets to Vite).
+ * In production, serves static files from .agentuity/client/.
+ */
+export async function createWebRouter(): Promise<Hono> {
+	const router = new Hono();
+	const isDev = process.env.DEV === 'true';
+	const rootDir = process.cwd();
+
+	if (isDev) {
+		// In dev mode, serve HTML with Vite client scripts for HMR
+		// Bun server proxies /src/*, /@vite/*, etc. to Vite asset server
+		router.get('/', (c) => {
+			return c.html(
+				`<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Agentuity App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+
+    <script type="module" src="/@vite/client"></script>
+    <script type="module">
+      import RefreshRuntime from '/@react-refresh';
+      RefreshRuntime.injectIntoGlobalHook(window);
+      window.$RefreshReg$ = () => {};
+      window.$RefreshSig$ = () => (type) => type;
+      window.__vite_plugin_react_preamble_installed__ = true;
+    </script>
+
+    <script type="module" src="/src/web/frontend.tsx"></script>
+  </body>
+</html>`
+			);
+		});
+	} else {
+		// Production: serve static files from .agentuity/client/
+		const clientDir = join(rootDir, '.agentuity', 'client');
+
+		// Verify client build exists
+		const indexHtmlPath = join(clientDir, 'index.html');
+		if (!existsSync(indexHtmlPath)) {
+			throw new Error(
+				`Client build not found. Missing ${indexHtmlPath}. Run build to generate client assets.`
+			);
+		}
+
+		// Compute relative paths for serveStatic (it expects relative paths from cwd)
+		let relClientDir = relative(process.cwd(), clientDir);
+		if (!relClientDir.startsWith('.')) {
+			relClientDir = './' + relClientDir;
+		}
+		let relIndexPath = relative(process.cwd(), indexHtmlPath);
+		if (!relIndexPath.startsWith('.')) {
+			relIndexPath = './' + relIndexPath;
+		}
+
+		// Serve static files from .agentuity/client/
+		router.use('/*', serveStatic({ root: relClientDir }));
+
+		// Fallback to index.html for SPA routing
+		router.get('*', serveStatic({ path: relIndexPath }));
+	}
+
+	return router;
+}