@agentuity/runtime 2.0.11 → 3.0.0-alpha.1

package/src/handlers/websocket.ts

@@ -1,203 +0,0 @@
-import type { Context, MiddlewareHandler } from 'hono';
-import { upgradeWebSocket } from 'hono/bun';
-import { context as otelContext, ROOT_CONTEXT } from '@opentelemetry/api';
-import type { Env } from '../app';
-import { tagRoute } from './_route-meta';
-
-/**
- * Context key for WebSocket close promise.
- * Used by middleware to defer session finalization until WebSocket closes.
- */
-export const WS_DONE_PROMISE_KEY = '_wsDonePromise';
-
-/**
- * WebSocket connection interface for handling WebSocket events.
- */
-export interface WebSocketConnection {
-	onOpen: (handler: (event: Event) => void | Promise<void>) => void;
-	onMessage: (handler: (event: MessageEvent) => void | Promise<void>) => void;
-	onClose: (handler: (event: CloseEvent) => void | Promise<void>) => void;
-	send: (data: string | ArrayBuffer | Uint8Array) => void;
-}
-
-/**
- * Handler function for WebSocket connections.
- * Receives the Hono context and WebSocket connection with a flattened signature.
- *
- * **This handler must be synchronous** (returns `void`, not `Promise<void>`).
- * The handler is called inside Hono's `upgradeWebSocket` factory, which must
- * return event handlers synchronously for the HTTP upgrade to complete. If the
- * handler were async, any `ws.onOpen`/`ws.onMessage`/`ws.onClose` registrations
- * after an `await` would be silently lost because the factory returns before
- * they are registered.
- *
- * To perform async work, place it inside the `onOpen`, `onMessage`, or `onClose`
- * callbacks, which are properly awaited by the runtime.
- */
-export type WebSocketHandler<E extends Env = Env> = (
-	c: Context<E>,
-	ws: WebSocketConnection
-) => void;
-
-/**
- * Creates a WebSocket middleware for handling WebSocket connections.
- *
- * The handler must be **synchronous** — it runs inside Hono's `upgradeWebSocket`
- * factory which must return event handlers synchronously for the HTTP upgrade to
- * complete. Async work should go inside `onOpen`, `onMessage`, or `onClose`
- * callbacks, which are properly awaited by the runtime.
- *
- * Use with router.get() to create a WebSocket endpoint:
- *
- * @example
- * ```typescript
- * // Basic synchronous usage
- * import { createRouter, websocket } from '@agentuity/runtime';
- *
- * const router = createRouter();
- *
- * router.get('/ws', websocket((c, ws) => {
- *   ws.onOpen(() => {
- *     c.var.logger.info('WebSocket opened');
- *     ws.send('Welcome!');
- *   });
- *
- *   ws.onMessage((event) => {
- *     c.var.logger.info('Received:', event.data);
- *     ws.send('Echo: ' + event.data);
- *   });
- *
- *   ws.onClose(() => {
- *     c.var.logger.info('WebSocket closed');
- *   });
- * }));
- * ```
- *
- * @example
- * ```typescript
- * // Async work inside callbacks (correct pattern)
- * router.get('/ws', websocket((c, ws) => {
- *   ws.onOpen(async () => {
- *     const user = await fetchUser(c.var.auth);
- *     ws.send(JSON.stringify({ welcome: user.name }));
- *   });
- *
- *   ws.onMessage(async (event) => {
- *     const result = await processMessage(event.data);
- *     ws.send(JSON.stringify(result));
- *   });
- * }));
- * ```
- *
- * @param handler - Synchronous handler function receiving context and WebSocket connection
- * @returns Hono middleware handler for WebSocket upgrade
- */
-export function websocket<E extends Env = Env>(
-	handler: WebSocketHandler<E>
-): MiddlewareHandler<E, string, { outputFormat: 'ws' }> {
-	const wsHandler = upgradeWebSocket((c: Context<E>) => {
-		let openHandler: ((event: Event) => void | Promise<void>) | undefined;
-		let messageHandler: ((event: MessageEvent) => void | Promise<void>) | undefined;
-		let closeHandler: ((event: CloseEvent) => void | Promise<void>) | undefined;
-		let initialized = false;
-
-		// Create done promise for session lifecycle deferral, but ONLY for actual
-		// WebSocket upgrade requests. The factory runs unconditionally for every
-		// request hitting this route (Hono calls createEvents before attempting
-		// server.upgrade). For non-upgrade HTTP requests, setting the promise would
-		// cause the middleware to hang forever waiting for an onClose that never fires.
-		let resolveDone: (() => void) | undefined;
-		const isUpgrade = c.req.header('upgrade')?.toLowerCase() === 'websocket';
-
-		if (isUpgrade) {
-			const donePromise = new Promise<void>((resolve) => {
-				resolveDone = resolve;
-			});
-
-			// Defensive: guard against future code adding rejection paths
-			donePromise.catch(() => {});
-
-			// Set on context so middleware defers session finalization until WS closes
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			(c as any).set(WS_DONE_PROMISE_KEY, donePromise);
-		}
-
-		const wsConnection: WebSocketConnection = {
-			onOpen: (h) => {
-				openHandler = h;
-			},
-			onMessage: (h) => {
-				messageHandler = h;
-			},
-			onClose: (h) => {
-				closeHandler = h;
-			},
-			send: (_data: string | ArrayBuffer | Uint8Array) => {
-				// This will be bound to the actual ws in the handlers
-			},
-		};
-
-		// IMPORTANT: We run in ROOT_CONTEXT (no active OTEL span) to avoid a Bun bug
-		// where OTEL-instrumented fetch conflicts with streaming responses.
-		// See: https://github.com/agentuity/sdk/issues/471
-		// See: https://github.com/oven-sh/bun/issues/24766
-		const runHandler = () => {
-			otelContext.with(ROOT_CONTEXT, () => {
-				handler(c, wsConnection);
-			});
-			initialized = true;
-		};
-
-		runHandler();
-
-		return {
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			onOpen: async (event: Event, ws: any) => {
-				try {
-					wsConnection.send = (data) => ws.send(data);
-
-					if (openHandler) {
-						await otelContext.with(ROOT_CONTEXT, () => openHandler!(event));
-					}
-				} catch (err) {
-					c.var.logger?.error('WebSocket onOpen error:', err);
-					throw err;
-				}
-			},
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			onMessage: async (event: MessageEvent, ws: any) => {
-				try {
-					if (!initialized) {
-						wsConnection.send = (data) => ws.send(data);
-						runHandler();
-					}
-					if (messageHandler) {
-						await otelContext.with(ROOT_CONTEXT, () => messageHandler!(event));
-					}
-				} catch (err) {
-					c.var.logger?.error('WebSocket onMessage error:', err);
-					throw err;
-				}
-			},
-			// eslint-disable-next-line @typescript-eslint/no-explicit-any
-			onClose: async (event: CloseEvent, _ws: any) => {
-				try {
-					if (closeHandler) {
-						await otelContext.with(ROOT_CONTEXT, () => closeHandler!(event));
-					}
-				} catch (err) {
-					c.var.logger?.error('WebSocket onClose error:', err);
-				} finally {
-					// Resolve the done promise to trigger session finalization
-					// This must fire even if the user's onClose handler throws
-					resolveDone?.();
-				}
-			},
-		};
-	});
-
-	const middleware: MiddlewareHandler<E, string, { outputFormat: 'ws' }> = (c, next) =>
-		(wsHandler as unknown as MiddlewareHandler<E, string, { outputFormat: 'ws' }>)(c, next);
-
-	return tagRoute(middleware, { type: 'websocket' });
-}

package/src/logger/console.ts

@@ -1,323 +0,0 @@
-import type { LogLevel } from '@agentuity/core';
-import { __originalConsole } from '../otel/logger';
-import type { Logger } from './logger';
-import { formatMessage } from './util';
-
-const BOLD = '\x1b[1m';
-const RESET = '\x1b[0m';
-
-// Helper to convert hex color to ANSI 24-bit color code
-function hexToAnsi(hex: string): string {
-	const r = parseInt(hex.slice(1, 3), 16);
-	const g = parseInt(hex.slice(3, 5), 16);
-	const b = parseInt(hex.slice(5, 7), 16);
-	return `\x1b[38;2;${r};${g};${b}m`;
-}
-
-interface LogColors {
-	level: string;
-	message: string;
-}
-
-function shouldUseColors(): boolean {
-	// FORCE_COLOR overrides all checks (used when stdout is piped but we still want colors)
-	if (process.env.FORCE_COLOR === '1') {
-		return true;
-	}
-
-	// Check for NO_COLOR environment variable (any non-empty value disables colors)
-	if (process.env.NO_COLOR) {
-		return false;
-	}
-
-	// Check for TERM=dumb
-	if (process.env.TERM === 'dumb') {
-		return false;
-	}
-
-	// Check if stdout is a TTY
-	if (!process.stdout || typeof process.stdout.isTTY === 'undefined') {
-		return false;
-	}
-
-	if (process.stdout && typeof process.stdout.isTTY !== 'undefined' && !process.stdout.isTTY) {
-		return false;
-	}
-
-	return true;
-}
-
-type ColorScheme = 'light' | 'dark';
-
-function getLogColors(scheme: ColorScheme): Record<LogLevel, LogColors> {
-	if (scheme === 'light') {
-		// Darker, high-contrast colors for light backgrounds
-		return {
-			trace: {
-				level: hexToAnsi('#008B8B') + BOLD, // Dark cyan
-				message: hexToAnsi('#4B4B4B'), // Dark gray
-			},
-			debug: {
-				level: hexToAnsi('#0000CD') + BOLD, // Medium blue
-				message: hexToAnsi('#006400'), // Dark green
-			},
-			info: {
-				level: hexToAnsi('#FF8C00') + BOLD, // Dark orange
-				message: hexToAnsi('#0066CC') + BOLD, // Strong blue
-			},
-			warn: {
-				level: hexToAnsi('#9400D3') + BOLD, // Dark violet
-				message: hexToAnsi('#8B008B'), // Dark magenta
-			},
-			error: {
-				level: hexToAnsi('#DC143C') + BOLD, // Crimson
-				message: hexToAnsi('#8B0000') + BOLD, // Dark red
-			},
-		};
-	}
-
-	// Dark mode colors (brighter for dark backgrounds)
-	return {
-		trace: {
-			level: hexToAnsi('#00FFFF') + BOLD, // Cyan
-			message: hexToAnsi('#A0A0A0'), // Light gray
-		},
-		debug: {
-			level: hexToAnsi('#5C9CFF') + BOLD, // Blue
-			message: hexToAnsi('#90EE90'), // Light green
-		},
-		info: {
-			level: hexToAnsi('#FFD700') + BOLD, // Gold/Yellow
-			message: hexToAnsi('#FFFFFF') + BOLD, // White
-		},
-		warn: {
-			level: hexToAnsi('#FF00FF') + BOLD, // Magenta
-			message: hexToAnsi('#FF00FF'), // Magenta
-		},
-		error: {
-			level: hexToAnsi('#FF4444') + BOLD, // Red
-			message: hexToAnsi('#FF4444'), // Red
-		},
-	};
-}
-
-// Detect color scheme from environment
-function detectColorScheme(): ColorScheme {
-	const scheme = process.env.COLOR_SCHEME?.toLowerCase();
-	if (scheme === 'light' || scheme === 'dark') {
-		return scheme;
-	}
-	if (process.env.CI) {
-		return 'light';
-	}
-	return 'dark'; // Default to dark mode
-}
-
-const NOCOLORS = Object.freeze({ level: '', reset: '', message: '' });
-
-/**
- * Console implementation of the Logger interface
- */
-export default class ConsoleLogger implements Logger {
-	private context: Record<string, unknown>;
-	private formatContext: boolean;
-	private logLevel: LogLevel;
-	private colors: Record<LogLevel, LogColors>;
-	private detectedTraceLoopLog: boolean | undefined;
-	private useColors: boolean;
-
-	/**
-	 * Creates a new console logger
-	 *
-	 * @param context - Initial context for the logger
-	 */
-	constructor(
-		context: Record<string, unknown> = {},
-		formatContext = true,
-		logLevel: LogLevel = 'info'
-	) {
-		this.context = context;
-		this.formatContext = formatContext;
-		this.logLevel = logLevel;
-		this.useColors = shouldUseColors();
-		this.colors = this.useColors
-			? getLogColors(detectColorScheme())
-			: ({} as Record<LogLevel, LogColors>);
-	}
-
-	private shouldLog(level: LogLevel): boolean {
-		switch (this.logLevel) {
-			case 'trace':
-				return true;
-			case 'debug':
-				return level === 'debug' || level === 'info' || level === 'warn' || level === 'error';
-			case 'info':
-				return level === 'info' || level === 'warn' || level === 'error';
-			case 'warn':
-				return level === 'warn' || level === 'error';
-			case 'error':
-				return level === 'error';
-		}
-		return false;
-	}
-
-	/**
-	 * Log a trace message (most verbose)
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	trace(message: unknown, ...args: unknown[]): void {
-		if (!this.shouldLog('trace')) {
-			return;
-		}
-		try {
-			const colors = this.useColors ? this.colors.trace : NOCOLORS;
-			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.debug(
-				`${colors.level}[TRACE]${RESET} ${colors.message}${formattedMessage}${RESET}`
-			);
-		} catch (err) {
-			// Fallback to direct logging if formatting fails
-			const colors = this.colors.trace;
-			__originalConsole.debug(`${colors.level}[TRACE]${RESET} ${message}`, ...args);
-			__originalConsole.error('Error formatting log message:', err);
-		}
-	}
-
-	/**
-	 * Log a debug message
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	debug(message: unknown, ...args: unknown[]): void {
-		if (!this.shouldLog('debug')) {
-			return;
-		}
-		try {
-			const colors = this.useColors ? this.colors.debug : NOCOLORS;
-			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.debug(
-				`${colors.level}[DEBUG]${RESET} ${colors.message}${formattedMessage}${RESET}`
-			);
-		} catch (err) {
-			// Fallback to direct logging if formatting fails
-			const colors = this.colors.debug;
-			__originalConsole.debug(`${colors.level}[DEBUG]${RESET} ${message}`, ...args);
-			__originalConsole.error('Error formatting log message:', err);
-		}
-	}
-
-	/**
-	 * Log an info message
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	info(message: unknown, ...args: unknown[]): void {
-		if (!this.shouldLog('info')) {
-			return;
-		}
-		// suppress the default traceloop message at info level
-		if (
-			!this.detectedTraceLoopLog &&
-			typeof message === 'string' &&
-			message.includes('Traceloop exporting traces to')
-		) {
-			this.detectedTraceLoopLog = true;
-			if (this.shouldLog('debug')) {
-				this.debug(message, ...args);
-			}
-			return;
-		}
-		try {
-			const colors = this.useColors ? this.colors.info : NOCOLORS;
-			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.info(
-				`${colors.level}[INFO]${RESET} ${colors.message}${formattedMessage}${RESET}`
-			);
-		} catch (err) {
-			// Fallback to direct logging if formatting fails
-			const colors = this.colors.info;
-			__originalConsole.info(`${colors.level}[INFO]${RESET} ${message}`, ...args);
-			__originalConsole.error('Error formatting log message:', err);
-		}
-	}
-
-	/**
-	 * Log a warning message
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	warn(message: unknown, ...args: unknown[]): void {
-		if (!this.shouldLog('warn')) {
-			return;
-		}
-		try {
-			const colors = this.useColors ? this.colors.warn : NOCOLORS;
-			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.warn(
-				`${colors.level}[WARN]${RESET}  ${colors.message}${formattedMessage}${RESET}`
-			);
-		} catch (err) {
-			// Fallback to direct logging if formatting fails
-			const colors = this.colors.warn;
-			__originalConsole.warn(`${colors.level}[WARN]${RESET}  ${message}`, ...args);
-			__originalConsole.error('Error formatting log message:', err);
-		}
-	}
-
-	/**
-	 * Log an error message
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	error(message: unknown, ...args: unknown[]): void {
-		if (!this.shouldLog('error')) {
-			return;
-		}
-		try {
-			const colors = this.useColors ? this.colors.error : NOCOLORS;
-			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.error(
-				`${colors.level}[ERROR]${RESET} ${colors.message}${formattedMessage}${RESET}`
-			);
-		} catch (err) {
-			// Fallback to direct logging if formatting fails
-			const colors = this.colors.error;
-			__originalConsole.error(`${colors.level}[ERROR]${RESET} ${message}`, ...args);
-			__originalConsole.error('Error formatting log message:', err);
-		}
-	}
-
-	/**
-	 * Log a fatal error message and exit the process
-	 *
-	 * @param message - The message to log
-	 * @param args - Additional arguments to log
-	 */
-	fatal(message: unknown, ...args: unknown[]): never {
-		this.error(message, ...args);
-		process.exit(1);
-	}
-
-	/**
-	 * Create a child logger with additional context
-	 *
-	 * @param opts - Additional context for the child logger
-	 * @returns A new logger instance with the additional context
-	 */
-	child(opts: Record<string, unknown>): Logger {
-		return new ConsoleLogger(
-			{
-				...this.context,
-				...opts,
-			},
-			this.formatContext,
-			this.logLevel
-		);
-	}
-}

package/src/logger/index.ts

@@ -1,2 +0,0 @@
-export { internal } from './internal';
-export { type Logger, logger } from './user';

package/src/logger/internal.ts

@@ -1,165 +0,0 @@
-import { formatMessage } from './util';
-
-const cyan = '\x1b[1;96m';
-const reset = '\x1b[0m';
-
-/**
- * Log levels for internal SDK logging
- */
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
-
-/**
- * Internal logger configuration
- */
-interface InternalLoggerConfig {
-	level: LogLevel;
-	context?: Record<string, unknown>;
-}
-
-/**
- * Simple internal logger that doesn't depend on other SDK modules
- * This logger is only for SDK internal diagnostics and debugging
- */
-class InternalLogger {
-	private config: InternalLoggerConfig;
-
-	constructor() {
-		this.config = this.loadConfig();
-	}
-
-	/**
-	 * Load configuration from environment variables
-	 */
-	private loadConfig(): InternalLoggerConfig {
-		const envLevel = process.env.AGENTUITY_SDK_LOG_LEVEL?.toLowerCase();
-
-		// Validate log level
-		const validLevels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'silent'];
-		const level = validLevels.includes(envLevel as LogLevel) ? (envLevel as LogLevel) : 'silent';
-
-		return {
-			level,
-			context: {
-				'@agentuity/source': 'sdk-internal',
-				'@agentuity/timestamp': new Date().toISOString(),
-			},
-		};
-	}
-
-	/**
-	 * Check if a log level should be output based on current configuration
-	 */
-	private shouldLog(level: LogLevel): boolean {
-		if (this.config.level === 'silent') return false;
-
-		const levelPriority = {
-			debug: 0,
-			info: 1,
-			warn: 2,
-			error: 3,
-			silent: 4,
-		};
-
-		return levelPriority[level] >= levelPriority[this.config.level];
-	}
-
-	/**
-	 * Format a log message with context
-	 */
-	private formatMessage(message: unknown, ...args: unknown[]): string {
-		const formattedMessage = formatMessage(false, this.config.context, message, args);
-		return `${cyan}[INTERNAL]${reset} ${formattedMessage}`;
-	}
-
-	/**
-	 * Log a debug message
-	 */
-	debug(message: unknown, ...args: unknown[]): void {
-		if (this.shouldLog('debug')) {
-			console.debug(this.formatMessage(message, ...args));
-		}
-	}
-
-	/**
-	 * Log an info message
-	 */
-	info(message: unknown, ...args: unknown[]): void {
-		if (this.shouldLog('info')) {
-			console.info(this.formatMessage(message, ...args));
-		}
-	}
-
-	/**
-	 * Log a warning message
-	 */
-	warn(message: unknown, ...args: unknown[]): void {
-		if (this.shouldLog('warn')) {
-			console.warn(this.formatMessage(message, ...args));
-		}
-	}
-
-	/**
-	 * Log an error message
-	 */
-	error(message: unknown, ...args: unknown[]): void {
-		if (this.shouldLog('error')) {
-			console.error(this.formatMessage(message, ...args));
-		}
-	}
-
-	/**
-	 * Update configuration at runtime
-	 */
-	updateConfig(config: Partial<InternalLoggerConfig>): void {
-		this.config = { ...this.config, ...config };
-	}
-
-	/**
-	 * Get current configuration
-	 */
-	getConfig(): InternalLoggerConfig {
-		return { ...this.config };
-	}
-
-	/**
-	 * Check if logging is enabled
-	 */
-	isEnabled(): boolean {
-		return this.config.level !== 'silent';
-	}
-
-	/**
-	 * Create a child logger with additional context
-	 */
-	child(context: Record<string, unknown>): InternalLogger {
-		const childLogger = new InternalLogger();
-		childLogger.updateConfig({
-			...this.config,
-			context: {
-				...this.config.context,
-				...context,
-			},
-		});
-		return childLogger;
-	}
-}
-
-// Singleton instance - not exported
-const internalLogger = new InternalLogger();
-
-/**
- * Internal logger for SDK use only
- * This is NOT exported from the main SDK index
- */
-export const internal = {
-	debug: (message: unknown, ...args: unknown[]) => internalLogger.debug(message, ...args),
-	info: (message: unknown, ...args: unknown[]) => internalLogger.info(message, ...args),
-	warn: (message: unknown, ...args: unknown[]) => internalLogger.warn(message, ...args),
-	error: (message: unknown, ...args: unknown[]) => internalLogger.error(message, ...args),
-
-	// Utility methods
-	updateConfig: (config: Partial<InternalLoggerConfig>) => internalLogger.updateConfig(config),
-	getConfig: () => internalLogger.getConfig(),
-	isEnabled: () => internalLogger.isEnabled(),
-	child: (context: Record<string, unknown>) => internalLogger.child(context),
-};