@agi-cli/server 0.1.67 → 0.1.68

package/src/routes/session-messages.ts

@@ -9,6 +9,8 @@ import {
 	ensureProviderEnv,
 } from '@agi-cli/sdk';
 import { dispatchAssistantMessage } from '../runtime/message-service.ts';
+import { logger } from '../runtime/logger.ts';
+import { serializeError } from '../runtime/api-error.ts';
 
 type MessagePartRow = typeof messageParts.$inferSelect;
 type SessionRow = typeof sessions.$inferSelect;
@@ -16,108 +18,125 @@ type SessionRow = typeof sessions.$inferSelect;
 export function registerSessionMessagesRoutes(app: Hono) {
 	// List messages for a session
 	app.get('/v1/sessions/:id/messages', async (c) => {
-		const projectRoot = c.req.query('project') || process.cwd();
-		const cfg = await loadConfig(projectRoot);
-		const db = await getDb(cfg.projectRoot);
-		const id = c.req.param('id');
-		const rows = await db
-			.select()
-			.from(messages)
-			.where(eq(messages.sessionId, id))
-			.orderBy(messages.createdAt);
-		const without = c.req.query('without');
-		if (without !== 'parts') {
-			const ids = rows.map((m) => m.id);
-			const parts = ids.length
-				? await db
-						.select()
-						.from(messageParts)
-						.where(inArray(messageParts.messageId, ids))
-				: [];
-			const partsByMsg = new Map<string, MessagePartRow[]>();
-			for (const p of parts) {
-				const existing = partsByMsg.get(p.messageId);
-				if (existing) existing.push(p);
-				else partsByMsg.set(p.messageId, [p]);
-			}
-			const wantParsed = (() => {
-				const q = (c.req.query('parsed') || '').toLowerCase();
-				return q === '1' || q === 'true' || q === 'yes';
-			})();
-			function parseContent(raw: string): Record<string, unknown> | string {
-				try {
-					const v = JSON.parse(String(raw ?? ''));
-					if (v && typeof v === 'object' && !Array.isArray(v))
-						return v as Record<string, unknown>;
-				} catch {}
-				return raw;
-			}
-			const enriched = rows.map((m) => {
-				const parts = (partsByMsg.get(m.id) ?? []).sort(
-					(a, b) => a.index - b.index,
-				);
-				const mapped = parts.map((p) => {
-					const parsed = parseContent(p.content);
-					return wantParsed
-						? { ...p, content: parsed }
-						: { ...p, contentJson: parsed };
+		try {
+			const projectRoot = c.req.query('project') || process.cwd();
+			const cfg = await loadConfig(projectRoot);
+			const db = await getDb(cfg.projectRoot);
+			const id = c.req.param('id');
+			const rows = await db
+				.select()
+				.from(messages)
+				.where(eq(messages.sessionId, id))
+				.orderBy(messages.createdAt);
+			const without = c.req.query('without');
+			if (without !== 'parts') {
+				const ids = rows.map((m) => m.id);
+				const parts = ids.length
+					? await db
+							.select()
+							.from(messageParts)
+							.where(inArray(messageParts.messageId, ids))
+					: [];
+				const partsByMsg = new Map<string, MessagePartRow[]>();
+				for (const p of parts) {
+					const existing = partsByMsg.get(p.messageId);
+					if (existing) existing.push(p);
+					else partsByMsg.set(p.messageId, [p]);
+				}
+				const wantParsed = (() => {
+					const q = (c.req.query('parsed') || '').toLowerCase();
+					return q === '1' || q === 'true' || q === 'yes';
+				})();
+				function parseContent(raw: string): Record<string, unknown> | string {
+					try {
+						const v = JSON.parse(String(raw ?? ''));
+						if (v && typeof v === 'object' && !Array.isArray(v))
+							return v as Record<string, unknown>;
+					} catch {}
+					return raw;
+				}
+				const enriched = rows.map((m) => {
+					const parts = (partsByMsg.get(m.id) ?? []).sort(
+						(a, b) => a.index - b.index,
+					);
+					const mapped = parts.map((p) => {
+						const parsed = parseContent(p.content);
+						return wantParsed
+							? { ...p, content: parsed }
+							: { ...p, contentJson: parsed };
+					});
+					return { ...m, parts: mapped };
 				});
-				return { ...m, parts: mapped };
-			});
-			return c.json(enriched);
+				return c.json(enriched);
+			}
+			return c.json(rows);
+		} catch (error) {
+			logger.error('Failed to list session messages', error);
+			const errorResponse = serializeError(error);
+			return c.json(errorResponse, errorResponse.error.status || 500);
 		}
-		return c.json(rows);
 	});
 
 	// Post a user message and get assistant reply (non-streaming for v0)
 	app.post('/v1/sessions/:id/messages', async (c) => {
-		const projectRoot = c.req.query('project') || process.cwd();
-		const cfg = await loadConfig(projectRoot);
-		const db = await getDb(cfg.projectRoot);
-		const sessionId = c.req.param('id');
-		const body = await c.req.json().catch(() => ({}));
-		// Load session to inherit its provider/model/agent by default
-		const sessionRows = await db
-			.select()
-			.from(sessions)
-			.where(eq(sessions.id, sessionId));
-		if (!sessionRows.length) return c.json({ error: 'Session not found' }, 404);
-		const sess: SessionRow = sessionRows[0];
-		const provider = body?.provider ?? sess.provider ?? cfg.defaults.provider;
-		const modelName = body?.model ?? sess.model ?? cfg.defaults.model;
-		const agent = body?.agent ?? sess.agent ?? cfg.defaults.agent;
-		const content = body?.content ?? '';
-
-		// Validate model capabilities if tools are allowed for this agent
-		const wantsToolCalls = true; // agent toolset may be non-empty
 		try {
-			validateProviderModel(provider, modelName, { wantsToolCalls });
-		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			return c.json({ error: message }, 400);
-		}
-		// Enforce provider auth: only allow providers/models the user authenticated for
-		const authorized = await isProviderAuthorized(cfg, provider);
-		if (!authorized) {
-			return c.json(
-				{
-					error: `Provider ${provider} is not configured. Run \`agi auth login\` to add credentials.`,
-				},
-				400,
-			);
-		}
-		await ensureProviderEnv(cfg, provider);
+			const projectRoot = c.req.query('project') || process.cwd();
+			const cfg = await loadConfig(projectRoot);
+			const db = await getDb(cfg.projectRoot);
+			const sessionId = c.req.param('id');
+			const body = await c.req.json().catch(() => ({}));
+			// Load session to inherit its provider/model/agent by default
+			const sessionRows = await db
+				.select()
+				.from(sessions)
+				.where(eq(sessions.id, sessionId));
+			if (!sessionRows.length) {
+				logger.warn('Session not found', { sessionId });
+				return c.json({ error: 'Session not found' }, 404);
+			}
+			const sess: SessionRow = sessionRows[0];
+			const provider = body?.provider ?? sess.provider ?? cfg.defaults.provider;
+			const modelName = body?.model ?? sess.model ?? cfg.defaults.model;
+			const agent = body?.agent ?? sess.agent ?? cfg.defaults.agent;
+			const content = body?.content ?? '';
+
+			// Validate model capabilities if tools are allowed for this agent
+			const wantsToolCalls = true; // agent toolset may be non-empty
+			try {
+				validateProviderModel(provider, modelName, { wantsToolCalls });
+			} catch (err) {
+				logger.error('Model validation failed', err, { provider, modelName });
+				const message = err instanceof Error ? err.message : String(err);
+				return c.json({ error: message }, 400);
+			}
+			// Enforce provider auth: only allow providers/models the user authenticated for
+			const authorized = await isProviderAuthorized(cfg, provider);
+			if (!authorized) {
+				logger.warn('Provider not authorized', { provider });
+				return c.json(
+					{
+						error: `Provider ${provider} is not configured. Run \`agi auth login\` to add credentials.`,
+					},
+					400,
+				);
+			}
+			await ensureProviderEnv(cfg, provider);
 
-		const { assistantMessageId } = await dispatchAssistantMessage({
-			cfg,
-			db,
-			session: sess,
-			agent,
-			provider,
-			model: modelName,
-			content,
-			oneShot: Boolean(body?.oneShot),
-		});
-		return c.json({ messageId: assistantMessageId }, 202);
+			const { assistantMessageId } = await dispatchAssistantMessage({
+				cfg,
+				db,
+				session: sess,
+				agent,
+				provider,
+				model: modelName,
+				content,
+				oneShot: Boolean(body?.oneShot),
+			});
+			return c.json({ messageId: assistantMessageId }, 202);
+		} catch (error) {
+			logger.error('Failed to create session message', error);
+			const errorResponse = serializeError(error);
+			return c.json(errorResponse, errorResponse.error.status || 500);
+		}
 	});
 }

package/src/routes/sessions.ts

@@ -7,6 +7,8 @@ import type { ProviderId } from '@agi-cli/sdk';
 import { isProviderId } from '@agi-cli/sdk';
 import { resolveAgentConfig } from '../runtime/agent-registry.ts';
 import { createSession as createSessionRow } from '../runtime/session-manager.ts';
+import { serializeError } from '../runtime/api-error.ts';
+import { logger } from '../runtime/logger.ts';
 
 export function registerSessionsRoutes(app: Hono) {
 	// List sessions
@@ -72,8 +74,9 @@ export function registerSessionsRoutes(app: Hono) {
 			});
 			return c.json(row, 201);
 		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
-			return c.json({ error: message }, 400);
+			logger.error('Failed to create session', err);
+			const errorResponse = serializeError(err);
+			return c.json(errorResponse, errorResponse.error.status || 400);
 		}
 	});
 

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);
 }