@agentuity/runtime 0.1.0 → 0.1.2

package/src/cors.ts

@@ -0,0 +1,137 @@
+/**
+ * CORS trusted origin helpers for same-origin configuration.
+ *
+ * Provides the same trusted-origin logic as @agentuity/auth,
+ * allowing CORS to be restricted to platform-trusted domains.
+ */
+
+import type { Context } from 'hono';
+
+/**
+ * Safely extract origin from a URL string.
+ * Returns undefined if the URL is invalid.
+ */
+function safeOrigin(url: string | undefined): string | undefined {
+	if (!url) return undefined;
+	try {
+		return new URL(url).origin;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Parse an origin-like value (URL or bare domain) into a normalized origin.
+ *
+ * - Full URLs (http://... or https://...) are parsed as-is
+ * - Bare domains (example.com) are treated as https://
+ * - Invalid values return undefined
+ */
+function parseOriginLike(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+
+	// If it looks like a URL (has a scheme), parse directly
+	if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(trimmed)) {
+		return safeOrigin(trimmed);
+	}
+
+	// Otherwise, treat as host[:port] and assume https
+	return safeOrigin(`https://${trimmed}`);
+}
+
+/**
+ * Build the static trusted origins set from environment variables.
+ *
+ * Reads from:
+ * - AGENTUITY_BASE_URL - The base URL for the deployment
+ * - AGENTUITY_CLOUD_DOMAINS - Platform-set domains (comma-separated)
+ * - AUTH_TRUSTED_DOMAINS - Developer-set additional domains (comma-separated)
+ */
+function buildEnvTrustedOrigins(): Set<string> {
+	const agentuityURL = process.env.AGENTUITY_BASE_URL;
+	const cloudDomains = process.env.AGENTUITY_CLOUD_DOMAINS;
+	const devTrustedDomains = process.env.AUTH_TRUSTED_DOMAINS;
+
+	const origins = new Set<string>();
+
+	const agentuityOrigin = safeOrigin(agentuityURL);
+	if (agentuityOrigin) origins.add(agentuityOrigin);
+
+	// Platform-set cloud domains (deployment, project, PR, custom domains, tunnels)
+	if (cloudDomains) {
+		for (const raw of cloudDomains.split(',')) {
+			const origin = parseOriginLike(raw);
+			if (origin) origins.add(origin);
+		}
+	}
+
+	// Developer-set additional trusted domains
+	if (devTrustedDomains) {
+		for (const raw of devTrustedDomains.split(',')) {
+			const origin = parseOriginLike(raw);
+			if (origin) origins.add(origin);
+		}
+	}
+
+	return origins;
+}
+
+/**
+ * Options for createTrustedCorsOrigin.
+ */
+export interface TrustedCorsOriginOptions {
+	/**
+	 * Additional origins to allow on top of environment-derived ones.
+	 * Can be full URLs (https://example.com) or bare domains (example.com).
+	 */
+	allowedOrigins?: string[];
+}
+
+/**
+ * Create a Hono CORS origin callback that only allows trusted origins.
+ *
+ * Trusted origins are derived from:
+ * - AGENTUITY_BASE_URL environment variable
+ * - AGENTUITY_CLOUD_DOMAINS environment variable (comma-separated)
+ * - AUTH_TRUSTED_DOMAINS environment variable (comma-separated)
+ * - The same-origin of the incoming request URL
+ * - Any additional origins specified in allowedOrigins option
+ *
+ * @example
+ * ```typescript
+ * import { createApp, createTrustedCorsOrigin } from '@agentuity/runtime';
+ *
+ * await createApp({
+ *   cors: {
+ *     origin: createTrustedCorsOrigin({
+ *       allowedOrigins: ['https://admin.myapp.com'],
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export function createTrustedCorsOrigin(
+	options?: TrustedCorsOriginOptions
+): (origin: string, c: Context) => string | undefined {
+	// Build static origins from env vars at creation time
+	const baseOrigins = buildEnvTrustedOrigins();
+
+	// Add any extra origins from options
+	if (options?.allowedOrigins) {
+		for (const raw of options.allowedOrigins) {
+			const origin = parseOriginLike(raw);
+			if (origin) baseOrigins.add(origin);
+		}
+	}
+
+	return (origin: string, c: Context): string | undefined => {
+		// Build allowed set per-request to include same-origin of the server
+		const allowed = new Set(baseOrigins);
+		const requestOrigin = safeOrigin(c.req.url);
+		if (requestOrigin) allowed.add(requestOrigin);
+
+		// Only echo back if trusted; otherwise return undefined (no CORS header)
+		return allowed.has(origin) ? origin : undefined;
+	};
+}

package/src/handlers/index.ts

@@ -1,4 +1,11 @@
 export { websocket, type WebSocketConnection, type WebSocketHandler } from './websocket';
-export { sse, type SSEMessage, type SSEStream, type SSEHandler } from './sse';
+export {
+	sse,
+	type SSEMessage,
+	type SSEStream,
+	type SSEHandler,
+	STREAM_DONE_PROMISE_KEY,
+	IS_STREAMING_RESPONSE_KEY,
+} from './sse';
 export { stream, type StreamHandler } from './stream';
 export { cron, type CronHandler, type CronMetadata } from './cron';

package/src/handlers/sse.ts

@@ -3,6 +3,19 @@ import { streamSSE as honoStreamSSE } from 'hono/streaming';
 import { getAgentAsyncLocalStorage } from '../_context';
 import type { Env } from '../app';
 
+/**
+ * Context variable key for stream completion promise.
+ * Used by middleware to defer session/thread saving until stream completes.
+ * @internal
+ */
+export const STREAM_DONE_PROMISE_KEY = '_streamDonePromise';
+
+/**
+ * Context variable key to indicate this is a streaming response.
+ * @internal
+ */
+export const IS_STREAMING_RESPONSE_KEY = '_isStreamingResponse';
+
 /**
  * SSE message format for Server-Sent Events.
  */
@@ -84,8 +97,38 @@ export function sse<E extends Env = Env>(handler: SSEHandler<E>): Handler<E> {
 		const asyncLocalStorage = getAgentAsyncLocalStorage();
 		const capturedContext = asyncLocalStorage.getStore();
 
+		// Track stream completion for deferred session/thread saving
+		// This promise resolves when the stream closes (normally or via abort)
+		let resolveDone: (() => void) | undefined;
+		let rejectDone: ((reason?: unknown) => void) | undefined;
+		const donePromise = new Promise<void>((resolve, reject) => {
+			resolveDone = resolve;
+			rejectDone = reject;
+		});
+
+		// Idempotent function to mark stream as completed
+		let isDone = false;
+		const markDone = (error?: unknown) => {
+			if (isDone) return;
+			isDone = true;
+			if (error && rejectDone) {
+				rejectDone(error);
+			} else if (resolveDone) {
+				resolveDone();
+			}
+		};
+
+		// Expose completion tracking to middleware
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(c as any).set(STREAM_DONE_PROMISE_KEY, donePromise);
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(c as any).set(IS_STREAMING_RESPONSE_KEY, true);
+
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
 		return honoStreamSSE(c, async (stream: any) => {
+			// Track if user registered an onAbort callback
+			let userAbortCallback: (() => void) | undefined;
+
 			const wrappedStream: SSEStream = {
 				write: async (data) => {
 					if (
@@ -100,12 +143,44 @@ export function sse<E extends Env = Env>(handler: SSEHandler<E>): Handler<E> {
 					return stream.writeSSE({ data: String(data) });
 				},
 				writeSSE: stream.writeSSE.bind(stream),
-				onAbort: stream.onAbort.bind(stream),
-				close: stream.close?.bind(stream) ?? (() => {}),
+				onAbort: (callback: () => void) => {
+					userAbortCallback = callback;
+					stream.onAbort(() => {
+						try {
+							callback();
+						} finally {
+							// Mark stream as done on abort
+							markDone();
+						}
+					});
+				},
+				close: () => {
+					try {
+						stream.close?.();
+					} finally {
+						// Mark stream as done on close
+						markDone();
+					}
+				},
 			};
 
+			// Always register internal abort handler if user doesn't register one
+			// This ensures we track completion even if user doesn't call onAbort
+			stream.onAbort(() => {
+				if (!userAbortCallback) {
+					// Only mark done if user didn't register their own handler
+					// (their handler wrapper already calls markDone)
+					markDone();
+				}
+			});
+
 			const runInContext = async () => {
-				await handler(c, wrappedStream);
+				try {
+					await handler(c, wrappedStream);
+				} catch (err) {
+					markDone(err);
+					throw err;
+				}
 			};
 
 			if (capturedContext) {

package/src/handlers/stream.ts

@@ -2,6 +2,7 @@ import type { Context, Handler } from 'hono';
 import { stream as honoStream } from 'hono/streaming';
 import { getAgentAsyncLocalStorage } from '../_context';
 import type { Env } from '../app';
+import { STREAM_DONE_PROMISE_KEY, IS_STREAMING_RESPONSE_KEY } from './sse';
 
 /**
  * Handler function for streaming responses.
@@ -59,6 +60,33 @@ export function stream<E extends Env = Env>(handler: StreamHandler<E>): Handler<
 		const asyncLocalStorage = getAgentAsyncLocalStorage();
 		const capturedContext = asyncLocalStorage.getStore();
 
+		// Track stream completion for deferred session/thread saving
+		// This promise resolves when the stream completes (pipe finishes or errors)
+		let resolveDone: (() => void) | undefined;
+		let rejectDone: ((reason?: unknown) => void) | undefined;
+		const donePromise = new Promise<void>((resolve, reject) => {
+			resolveDone = resolve;
+			rejectDone = reject;
+		});
+
+		// Idempotent function to mark stream as completed
+		let isDone = false;
+		const markDone = (error?: unknown) => {
+			if (isDone) return;
+			isDone = true;
+			if (error && rejectDone) {
+				rejectDone(error);
+			} else if (resolveDone) {
+				resolveDone();
+			}
+		};
+
+		// Expose completion tracking to middleware
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(c as any).set(STREAM_DONE_PROMISE_KEY, donePromise);
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		(c as any).set(IS_STREAMING_RESPONSE_KEY, true);
+
 		c.header('Content-Type', 'application/octet-stream');
 
 		// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -70,8 +98,11 @@ export function stream<E extends Env = Env>(handler: StreamHandler<E>): Handler<
 						streamResult = await streamResult;
 					}
 					await s.pipe(streamResult);
+					// Stream completed successfully
+					markDone();
 				} catch (err) {
 					c.var.logger?.error('Stream error:', err);
+					markDone(err);
 					throw err;
 				}
 			};

package/src/index.ts

@@ -30,6 +30,7 @@ export {
 export {
 	type AppConfig,
 	type CompressionConfig,
+	type CorsConfig,
 	type Variables,
 	type TriggerType,
 	type PrivateVariables,
@@ -42,6 +43,9 @@ export {
 	runShutdown,
 	fireEvent,
 } from './app';
+
+// cors.ts exports (trusted origin helpers)
+export { createTrustedCorsOrigin, type TrustedCorsOriginOptions } from './cors';
 export { addEventListener, removeEventListener } from './_events';
 
 // middleware.ts exports (Vite-native)

package/src/middleware.ts

@@ -6,8 +6,9 @@
 import { createMiddleware } from 'hono/factory';
 import { cors } from 'hono/cors';
 import { compress } from 'hono/compress';
-import { getSignedCookie, setSignedCookie } from 'hono/cookie';
-import type { Env, CompressionConfig } from './app';
+import { setSignedCookie } from 'hono/cookie';
+import type { Env, CompressionConfig, CorsConfig } from './app';
+import { createTrustedCorsOrigin } from './cors';
 import type { Logger } from './logger';
 import { getAppConfig } from './app';
 import { generateId } from './session';
@@ -27,6 +28,7 @@ import { TraceState } from '@opentelemetry/core';
 import * as runtimeConfig from './_config';
 import { getSessionEventProvider } from './_services';
 import { internal } from './logger/internal';
+import { STREAM_DONE_PROMISE_KEY, IS_STREAMING_RESPONSE_KEY } from './handlers/sse';
 
 const SESSION_HEADER = 'x-session-id';
 const THREAD_HEADER = 'x-thread-id';
@@ -171,38 +173,79 @@ export function createBaseMiddleware(config: MiddlewareConfig) {
  * }));
  * ```
  */
-export function createCorsMiddleware(staticOptions?: Parameters<typeof cors>[0]) {
+export function createCorsMiddleware(staticOptions?: CorsConfig) {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	return createMiddleware<Env<any>>(async (c, next) => {
 		// Lazy resolve: merge app config with static options
 		const appConfig = getAppConfig();
+		const appCors = appConfig?.cors;
 		const corsOptions = {
-			...appConfig?.cors,
+			...appCors,
 			...staticOptions,
 		};
 
+		// Extract Agentuity-specific options
+		const { sameOrigin, allowedOrigins, ...honoCorsOptions } = corsOptions;
+
+		// Determine origin handler based on sameOrigin setting
+		let originHandler: NonNullable<Parameters<typeof cors>[0]>['origin'];
+		if (sameOrigin) {
+			// Use trusted origins (env vars + allowedOrigins + same-origin)
+			originHandler = createTrustedCorsOrigin({ allowedOrigins });
+		} else if (honoCorsOptions.origin !== undefined) {
+			// Use explicitly provided origin
+			originHandler = honoCorsOptions.origin;
+		} else {
+			// Default: reflect any origin (backwards compatible)
+			originHandler = (origin: string) => origin;
+		}
+
+		// Required headers that must always be allowed/exposed for runtime functionality
+		const requiredAllowHeaders = [THREAD_HEADER];
+		const requiredExposeHeaders = [
+			TOKENS_HEADER,
+			DURATION_HEADER,
+			THREAD_HEADER,
+			SESSION_HEADER,
+			DEPLOYMENT_HEADER,
+		];
+
+		// Default headers to allow (used if none specified)
+		const defaultAllowHeaders = [
+			'Content-Type',
+			'Authorization',
+			'Accept',
+			'Origin',
+			'X-Requested-With',
+		];
+
+		// Default headers to expose (used if none specified)
+		const defaultExposeHeaders = ['Content-Length'];
+
 		const corsMiddleware = cors({
-			origin: corsOptions?.origin ?? ((origin: string) => origin),
-			allowHeaders: corsOptions?.allowHeaders ?? [
-				'Content-Type',
-				'Authorization',
-				'Accept',
-				'Origin',
-				'X-Requested-With',
-				THREAD_HEADER,
+			...honoCorsOptions,
+			origin: originHandler,
+			// Always include required headers, merge with user-provided or defaults
+			allowHeaders: [
+				...(honoCorsOptions.allowHeaders ?? defaultAllowHeaders),
+				...requiredAllowHeaders,
 			],
-			allowMethods: ['POST', 'GET', 'OPTIONS', 'HEAD', 'PUT', 'DELETE', 'PATCH'],
+			allowMethods: honoCorsOptions.allowMethods ?? [
+				'POST',
+				'GET',
+				'OPTIONS',
+				'HEAD',
+				'PUT',
+				'DELETE',
+				'PATCH',
+			],
+			// Always include required headers, merge with user-provided or defaults
 			exposeHeaders: [
-				'Content-Length',
-				TOKENS_HEADER,
-				DURATION_HEADER,
-				THREAD_HEADER,
-				SESSION_HEADER,
-				DEPLOYMENT_HEADER,
+				...(honoCorsOptions.exposeHeaders ?? defaultExposeHeaders),
+				...requiredExposeHeaders,
 			],
-			maxAge: 600,
-			credentials: true,
-			...(corsOptions ?? {}),
+			maxAge: honoCorsOptions.maxAge ?? 600,
+			credentials: honoCorsOptions.credentials ?? true,
 		});
 
 		return corsMiddleware(c, next);
@@ -311,27 +354,15 @@ export function createOtelMiddleware() {
 						}
 					}
 
-					try {
-						await next();
-						// Save session/thread and send events
+					// Factor out finalization logic so it can run synchronously or deferred
+					const finalizeSession = async (statusCode?: number) => {
 						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) {
-							span.recordException(ex);
-						}
-						span.setStatus({
-							code: SpanStatusCode.ERROR,
-							message: (ex as Error).message ?? String(ex),
-						});
-						throw ex;
-					} finally {
+
 						// Send session complete event
-						// The provider decides whether to actually send based on its requirements
 						if (sessionEventProvider) {
 							try {
 								const userData = session.serializeUserData();
@@ -347,7 +378,7 @@ export function createOtelMiddleware() {
 								await sessionEventProvider.complete({
 									id: sessionId,
 									threadId: isEmpty ? null : thread.id,
-									statusCode: c.res?.status ?? 200,
+									statusCode: statusCode ?? c.res?.status ?? 200,
 									agentIds: agentIds?.length ? agentIds : undefined,
 									userData,
 								});
@@ -357,7 +388,60 @@ export function createOtelMiddleware() {
 								// Silently ignore session complete errors - don't block response
 							}
 						}
+					};
+
+					try {
+						await next();
+
+						// Check if this is a streaming response that needs deferred finalization
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						const streamDone = (c as any).get(STREAM_DONE_PROMISE_KEY) as
+							| Promise<void>
+							| undefined;
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						const isStreaming = Boolean((c as any).get(IS_STREAMING_RESPONSE_KEY));
+
+						if (isStreaming && streamDone) {
+							// Defer session/thread saving until stream completes
+							// This ensures thread state changes made during streaming are persisted
+							internal.info(
+								'[session] deferring session/thread save until streaming completes (session %s)',
+								sessionId
+							);
+
+							handler.waitUntil(async () => {
+								try {
+									await streamDone;
+									internal.info(
+										'[session] stream completed, now saving session/thread (session %s)',
+										sessionId
+									);
+								} catch (ex) {
+									// Stream ended with an error/abort; still try to persist the latest state
+									internal.info(
+										'[session] stream ended with error, still saving state: %s',
+										ex
+									);
+								}
+								await finalizeSession();
+							});
 
+							span.setStatus({ code: SpanStatusCode.OK });
+						} else {
+							// Non-streaming: save session/thread synchronously (existing behavior)
+							await finalizeSession();
+							span.setStatus({ code: SpanStatusCode.OK });
+						}
+					} catch (ex) {
+						if (ex instanceof Error) {
+							span.recordException(ex);
+						}
+						span.setStatus({
+							code: SpanStatusCode.ERROR,
+							message: (ex as Error).message ?? String(ex),
+						});
+						throw ex;
+					} finally {
 						const headers: Record<string, string> = {};
 						propagation.inject(context.active(), headers);
 						for (const key of Object.keys(headers)) {
@@ -394,11 +478,18 @@ export function createOtelMiddleware() {
  * });
  * ```
  */
-export function createCompressionMiddleware(staticConfig?: CompressionConfig) {
+export function createCompressionMiddleware(
+	staticConfig?: CompressionConfig,
+	/**
+	 * Optional config resolver for testing. When provided, this is used instead of getAppConfig().
+	 * @internal
+	 */
+	configResolver?: () => { compression?: CompressionConfig | false } | undefined
+) {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	return createMiddleware<Env<any>>(async (c, next) => {
 		// Lazy resolve: merge app config with static config
-		const appConfig = getAppConfig();
+		const appConfig = configResolver ? configResolver() : getAppConfig();
 		const appCompressionConfig = appConfig?.compression;
 
 		// Check if compression is explicitly disabled
@@ -447,17 +538,18 @@ export function createCompressionMiddleware(staticConfig?: CompressionConfig) {
 }
 
 /**
- * Create lightweight session middleware for web routes (analytics).
+ * Create lightweight thread middleware for web routes (analytics).
  *
- * Sets session and thread cookies that persist across page views.
- * This is a lighter-weight alternative to createOtelMiddleware for
- * routes that don't need full tracing but need session/thread tracking.
+ * Sets thread cookie that persists across page views for client-side analytics.
+ * This middleware does NOT:
+ * - Create or track sessions (no session ID)
+ * - Set session/thread response headers
+ * - Send events to Catalyst sessions table
  *
- * Uses the existing ThreadIDProvider for thread ID generation to ensure
- * consistency with the OTel middleware.
+ * This is intentionally separate from createOtelMiddleware to avoid
+ * polluting the sessions table with web browsing activity.
  *
- * - Session cookie (asid): Per browser session, 30-minute sliding expiry
- * - Thread cookie (atid): Managed by ThreadIDProvider, 1-week expiry
+ * - Thread cookie (atid_a): Analytics-readable copy, 1-week expiry
  */
 export function createWebSessionMiddleware() {
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -467,44 +559,24 @@ export function createWebSessionMiddleware() {
 
 		const secret = getSessionSecret();
 
-		// Check for existing session cookie
-		let sessionId = await getSignedCookie(c, secret, 'asid');
-		if (!sessionId || typeof sessionId !== 'string') {
-			sessionId = generateId('sess');
-		}
-
 		// Use ThreadProvider.restore() to get/create thread (handles header, cookie, generation)
 		const threadProvider = getThreadProvider();
 		const thread = await threadProvider.restore(c);
 
-		// Set session cookie with sliding expiry
-		// httpOnly: false so beacon script can read it for analytics
+		// Set thread cookie for analytics
+		// httpOnly: false so beacon script can read it
 		const isSecure = c.req.url.startsWith('https://');
-		await setSignedCookie(c, 'asid', sessionId, secret, {
-			httpOnly: false, // Readable by JavaScript for analytics
-			secure: isSecure,
-			sameSite: 'Lax',
-			path: '/',
-			maxAge: 30 * 60, // 30 minutes
-		});
-
-		// Note: Thread cookie is set by ThreadProvider with httpOnly: true
-		// We need a readable copy for analytics
 		await setSignedCookie(c, 'atid_a', thread.id, secret, {
 			httpOnly: false, // Readable by JavaScript for analytics
 			secure: isSecure,
 			sameSite: 'Lax',
 			path: '/',
-			maxAge: 604800, // 1 week (same as thread)
+			maxAge: 604800, // 1 week
 		});
 
-		// Set in context for access by handlers (use existing Variables types)
-		c.set('sessionId', sessionId);
-		c.set('thread', thread);
-
-		// Set response headers for debugging/tracing
-		c.header(SESSION_HEADER, sessionId);
-		c.header(THREAD_HEADER, thread.id);
+		// Store in context for handler to access in same request
+		// (cookies aren't readable until the next request)
+		c.set('_webThreadId', thread.id);
 
 		await next();
 	});