@agi-cli/server 0.1.66 → 0.1.68

package/src/runtime/api-error.ts

@@ -0,0 +1,191 @@
+/**
+ * Unified API error handling
+ *
+ * Provides consistent error serialization and response formatting
+ * across all API endpoints.
+ */
+
+import { isDebugEnabled } from './debug-state';
+import { toErrorPayload } from './error-handling';
+
+/**
+ * Standard API error response format
+ */
+export type APIErrorResponse = {
+	error: {
+		message: string;
+		type: string;
+		code?: string;
+		status?: number;
+		details?: Record<string, unknown>;
+		stack?: string;
+	};
+};
+
+/**
+ * Custom API Error class
+ */
+export class APIError extends Error {
+	public readonly code?: string;
+	public readonly status: number;
+	public readonly type: string;
+	public readonly details?: Record<string, unknown>;
+
+	constructor(
+		message: string,
+		options?: {
+			code?: string;
+			status?: number;
+			type?: string;
+			details?: Record<string, unknown>;
+			cause?: unknown;
+		},
+	) {
+		super(message);
+		this.name = 'APIError';
+		this.code = options?.code;
+		this.status = options?.status ?? 500;
+		this.type = options?.type ?? 'api_error';
+		this.details = options?.details;
+
+		if (options?.cause) {
+			this.cause = options.cause;
+		}
+
+		// Maintain proper stack trace
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, APIError);
+		}
+	}
+}
+
+/**
+ * Serialize any error into a consistent API error response
+ *
+ * @param err - The error to serialize
+ * @returns A properly formatted API error response
+ */
+export function serializeError(err: unknown): APIErrorResponse {
+	// Use existing error payload logic
+	const payload = toErrorPayload(err);
+
+	// Determine HTTP status code
+	let status = 500;
+	if (err && typeof err === 'object') {
+		const errObj = err as Record<string, unknown>;
+		if (typeof errObj.status === 'number') {
+			status = errObj.status;
+		} else if (typeof errObj.statusCode === 'number') {
+			status = errObj.statusCode;
+		} else if (
+			errObj.details &&
+			typeof errObj.details === 'object' &&
+			typeof (errObj.details as Record<string, unknown>).statusCode === 'number'
+		) {
+			status = (errObj.details as Record<string, unknown>).statusCode as number;
+		}
+	}
+
+	// Handle APIError instances
+	if (err instanceof APIError) {
+		status = err.status;
+	}
+
+	// Extract code if available
+	let code: string | undefined;
+	if (err && typeof err === 'object') {
+		const errObj = err as Record<string, unknown>;
+		if (typeof errObj.code === 'string') {
+			code = errObj.code;
+		}
+	}
+
+	if (err instanceof APIError && err.code) {
+		code = err.code;
+	}
+
+	// Build response
+	const response: APIErrorResponse = {
+		error: {
+			message: payload.message || 'An error occurred',
+			type: payload.type || 'unknown',
+			status,
+			...(code ? { code } : {}),
+			...(payload.details ? { details: payload.details } : {}),
+		},
+	};
+
+	// Include stack trace in debug mode
+	if (isDebugEnabled() && err instanceof Error && err.stack) {
+		response.error.stack = err.stack;
+	}
+
+	return response;
+}
+
+/**
+ * Create an error response with proper HTTP status code
+ *
+ * @param err - The error to convert
+ * @returns Tuple of [APIErrorResponse, HTTP status code]
+ */
+export function createErrorResponse(err: unknown): [APIErrorResponse, number] {
+	const response = serializeError(err);
+	return [response, response.error.status ?? 500];
+}
+
+/**
+ * Normalize error to ensure it's an Error instance
+ *
+ * @param err - The error to normalize
+ * @returns An Error instance
+ */
+export function normalizeError(err: unknown): Error {
+	if (err instanceof Error) {
+		return err;
+	}
+
+	if (typeof err === 'string') {
+		return new Error(err);
+	}
+
+	if (err && typeof err === 'object') {
+		const errObj = err as Record<string, unknown>;
+		if (typeof errObj.message === 'string') {
+			return new Error(errObj.message);
+		}
+	}
+
+	return new Error('An unknown error occurred');
+}
+
+/**
+ * Extract error message from any error type
+ *
+ * @param err - The error to extract message from
+ * @returns The error message string
+ */
+export function getErrorMessage(err: unknown): string {
+	if (typeof err === 'string') {
+		return err;
+	}
+
+	if (err instanceof Error) {
+		return err.message;
+	}
+
+	if (err && typeof err === 'object') {
+		const errObj = err as Record<string, unknown>;
+		if (typeof errObj.message === 'string') {
+			return errObj.message;
+		}
+		if (typeof errObj.error === 'string') {
+			return errObj.error;
+		}
+	}
+
+	return 'An unknown error occurred';
+}
+
+// Legacy compatibility - AskServiceError alias
+export { APIError as AskServiceError };

package/src/runtime/debug-state.ts

@@ -0,0 +1,124 @@
+/**
+ * Runtime debug state management
+ *
+ * Centralizes debug flag state that can be set either via:
+ * - Environment variables (AGI_DEBUG, DEBUG_AGI)
+ * - Runtime configuration (CLI --debug flag)
+ */
+
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+type DebugState = {
+	enabled: boolean;
+	traceEnabled: boolean;
+	runtimeOverride: boolean | null;
+	runtimeTraceOverride: boolean | null;
+};
+
+// Global state
+const state: DebugState = {
+	enabled: false,
+	traceEnabled: false,
+	runtimeOverride: null,
+	runtimeTraceOverride: null,
+};
+
+/**
+ * Check if environment variables indicate debug mode
+ */
+function checkEnvDebug(): boolean {
+	const sources = [process.env.AGI_DEBUG, process.env.DEBUG_AGI];
+	for (const value of sources) {
+		if (!value) continue;
+		const trimmed = value.trim().toLowerCase();
+		if (TRUTHY.has(trimmed) || trimmed === 'all') {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Check if environment variables indicate trace mode
+ */
+function checkEnvTrace(): boolean {
+	const sources = [process.env.AGI_TRACE, process.env.TRACE_AGI];
+	for (const value of sources) {
+		if (!value) continue;
+		const trimmed = value.trim().toLowerCase();
+		if (TRUTHY.has(trimmed)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Initialize debug state from environment
+ */
+function initialize() {
+	if (state.runtimeOverride === null) {
+		state.enabled = checkEnvDebug();
+	}
+	if (state.runtimeTraceOverride === null) {
+		state.traceEnabled = checkEnvTrace();
+	}
+}
+
+/**
+ * Check if debug mode is enabled
+ * Considers both runtime override and environment variables
+ */
+export function isDebugEnabled(): boolean {
+	initialize();
+	return state.enabled;
+}
+
+/**
+ * Check if trace mode is enabled (shows stack traces)
+ * Trace mode requires debug mode to be enabled
+ */
+export function isTraceEnabled(): boolean {
+	initialize();
+	return state.enabled && state.traceEnabled;
+}
+
+/**
+ * Enable or disable debug mode at runtime
+ * Overrides environment variable settings
+ *
+ * @param enabled - true to enable debug mode, false to disable
+ */
+export function setDebugEnabled(enabled: boolean): void {
+	state.enabled = enabled;
+	state.runtimeOverride = enabled;
+}
+
+/**
+ * Enable or disable trace mode at runtime
+ * Trace mode shows full stack traces in error logs
+ *
+ * @param enabled - true to enable trace mode, false to disable
+ */
+export function setTraceEnabled(enabled: boolean): void {
+	state.traceEnabled = enabled;
+	state.runtimeTraceOverride = enabled;
+}
+
+/**
+ * Reset debug state to environment defaults
+ */
+export function resetDebugState(): void {
+	state.runtimeOverride = null;
+	state.runtimeTraceOverride = null;
+	state.enabled = checkEnvDebug();
+	state.traceEnabled = checkEnvTrace();
+}
+
+/**
+ * Get current debug state (for testing/diagnostics)
+ */
+export function getDebugState(): Readonly<DebugState> {
+	initialize();
+	return { ...state };
+}

package/src/runtime/debug.ts

@@ -1,3 +1,13 @@
+/**
+ * Legacy debug utilities - now integrated with new logger
+ *
+ * This file maintains backward compatibility while using the new
+ * centralized debug-state and logger modules.
+ */
+
+import { isDebugEnabled as isDebugEnabledNew } from './debug-state';
+import { time as timeNew, debug as debugNew } from './logger';
+
 const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
 
 const SYNONYMS: Record<string, string> = {
@@ -60,45 +70,48 @@ function getDebugConfig(): DebugConfig {
 	return cachedConfig;
 }
 
+/**
+ * Check if debug mode is enabled for a specific flag
+ * Now uses the centralized debug state
+ *
+ * @deprecated Use isDebugEnabled from debug-state.ts instead
+ */
 export function isDebugEnabled(flag?: string): boolean {
+	// Use new centralized debug state for general debug
+	if (!flag || flag === 'log') {
+		return isDebugEnabledNew();
+	}
+
+	// For specific flags like 'timing', check both new state and legacy env vars
+	if (flag === 'timing') {
+		// If new debug state is enabled OR timing flag is set
+		if (isDebugEnabledNew()) return true;
+	}
+
+	// Legacy flag checking
 	const config = getDebugConfig();
 	if (config.flags.has('all')) return true;
 	if (flag) return config.flags.has(flag);
 	return config.flags.has('log');
 }
 
+/**
+ * Log debug message
+ * Now uses the centralized logger
+ *
+ * @deprecated Use logger.debug from logger.ts instead
+ */
 export function debugLog(...args: unknown[]) {
 	if (!isDebugEnabled('log')) return;
-	try {
-		console.log('[debug]', ...args);
-	} catch {}
-}
-
-function nowMs(): number {
-	const perf = (globalThis as { performance?: { now?: () => number } })
-		.performance;
-	if (perf && typeof perf.now === 'function') return perf.now();
-	return Date.now();
+	debugNew(args.map((arg) => String(arg)).join(' '));
 }
 
-type Timer = { end(meta?: Record<string, unknown>): void };
-
-export function time(label: string): Timer {
-	if (!isDebugEnabled('timing')) {
-		return { end() {} };
-	}
-	const start = nowMs();
-	let finished = false;
-	return {
-		end(meta?: Record<string, unknown>) {
-			if (finished) return;
-			finished = true;
-			const duration = nowMs() - start;
-			try {
-				const line = `[timing] ${label} ${duration.toFixed(1)}ms`;
-				if (meta && Object.keys(meta).length) console.log(line, meta);
-				else console.log(line);
-			} catch {}
-		},
-	};
+/**
+ * Create a timer for performance measurement
+ * Integrated with centralized logger
+ */
+export function time(label: string): {
+	end(meta?: Record<string, unknown>): void;
+} {
+	return timeNew(label);
 }

package/src/runtime/logger.ts

@@ -0,0 +1,204 @@
+/**
+ * Centralized logging utility
+ *
+ * Provides structured logging with debug mode awareness.
+ * Replaces scattered console.log calls throughout the codebase.
+ */
+
+import { isDebugEnabled, isTraceEnabled } from './debug-state';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Format a log message with optional metadata
+ */
+function _formatMessage(
+	level: LogLevel,
+	message: string,
+	meta?: Record<string, unknown>,
+): string {
+	const timestamp = new Date().toISOString();
+	const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+
+	if (meta && Object.keys(meta).length > 0) {
+		return `${prefix} ${message} ${JSON.stringify(meta)}`;
+	}
+
+	return `${prefix} ${message}`;
+}
+
+/**
+ * Log at debug level (only when debug mode is enabled)
+ */
+export function debug(message: string, meta?: Record<string, unknown>): void {
+	if (!isDebugEnabled()) return;
+
+	try {
+		if (meta && Object.keys(meta).length > 0) {
+			console.log(`[debug] ${message}`, meta);
+		} else {
+			console.log(`[debug] ${message}`);
+		}
+	} catch {
+		// Silently fail
+	}
+}
+
+/**
+ * Log informational messages
+ */
+export function info(message: string, meta?: Record<string, unknown>): void {
+	try {
+		if (meta && Object.keys(meta).length > 0) {
+			console.log(`[info] ${message}`, meta);
+		} else {
+			console.log(`[info] ${message}`);
+		}
+	} catch {
+		// Silently fail
+	}
+}
+
+/**
+ * Log warning messages
+ */
+export function warn(message: string, meta?: Record<string, unknown>): void {
+	try {
+		if (meta && Object.keys(meta).length > 0) {
+			console.warn(`[warn] ${message}`, meta);
+		} else {
+			console.warn(`[warn] ${message}`);
+		}
+	} catch {
+		// Silently fail
+	}
+}
+
+/**
+ * Log error messages (only in debug mode, stack trace only with --trace)
+ */
+export function error(
+	message: string,
+	err?: unknown,
+	meta?: Record<string, unknown>,
+): void {
+	// Only log errors when debug mode is enabled
+	if (!isDebugEnabled()) return;
+
+	try {
+		const logMeta: Record<string, unknown> = { ...meta };
+
+		if (err) {
+			if (err instanceof Error) {
+				// Always show error name and message in debug mode
+				logMeta.error = {
+					name: err.name,
+					message: err.message,
+				};
+
+				// Show full stack trace only with --trace flag
+				if (isTraceEnabled() && err.stack) {
+					logMeta.error.stack = err.stack;
+				}
+			} else if (typeof err === 'string') {
+				logMeta.error = err;
+			} else if (err && typeof err === 'object') {
+				// For other error objects, try to extract useful info
+				const errObj = err as Record<string, unknown>;
+				logMeta.error = {
+					...(typeof errObj.name === 'string' ? { name: errObj.name } : {}),
+					...(typeof errObj.message === 'string'
+						? { message: errObj.message }
+						: {}),
+					...(typeof errObj.code === 'string' ? { code: errObj.code } : {}),
+					...(typeof errObj.status === 'number'
+						? { status: errObj.status }
+						: {}),
+					...(typeof errObj.statusCode === 'number'
+						? { statusCode: errObj.statusCode }
+						: {}),
+				};
+
+				// Include stack in trace mode
+				if (isTraceEnabled() && typeof errObj.stack === 'string') {
+					logMeta.error.stack = errObj.stack;
+				}
+			} else {
+				// Fallback for primitive types
+				logMeta.error = String(err);
+			}
+		}
+
+		if (Object.keys(logMeta).length > 0) {
+			console.error(`[error] ${message}`, logMeta);
+		} else {
+			console.error(`[error] ${message}`);
+		}
+	} catch (logErr) {
+		// Last resort: at least try to log something
+		try {
+			console.error(`[error] ${message} (logging failed:`, logErr, ')');
+		} catch {
+			// Give up silently
+		}
+	}
+}
+
+/**
+ * Logger object with all methods
+ */
+export const logger = {
+	debug,
+	info,
+	warn,
+	error,
+};
+
+/**
+ * Timing utilities (integrates with existing debug.ts timing)
+ */
+function nowMs(): number {
+	const perf = (globalThis as { performance?: { now?: () => number } })
+		.performance;
+	if (perf && typeof perf.now === 'function') return perf.now();
+	return Date.now();
+}
+
+type Timer = {
+	end(meta?: Record<string, unknown>): void;
+};
+
+/**
+ * Create a timer for performance measurement
+ * Only active when debug mode is enabled
+ */
+export function time(label: string): Timer {
+	if (!isDebugEnabled()) {
+		return { end() {} };
+	}
+
+	const start = nowMs();
+	let finished = false;
+
+	return {
+		end(meta?: Record<string, unknown>) {
+			if (finished) return;
+			finished = true;
+			const duration = nowMs() - start;
+
+			try {
+				const line = `[timing] ${label} ${duration.toFixed(1)}ms`;
+				if (meta && Object.keys(meta).length) {
+					console.log(line, meta);
+				} else {
+					console.log(line);
+				}
+			} catch {
+				// Silently fail
+			}
+		},
+	};
+}
+
+// Export legacy compatibility
+export { isDebugEnabled, isTraceEnabled };