@resolveio/server-lib 22.3.17 → 22.3.19

package/src/methods/mongo-explorer.ts

@@ -0,0 +1,1880 @@
+import SimpleSchema from 'simpl-schema';
+import { Db } from 'mongodb';
+import { Users } from '../collections/user.collection';
+import { MethodManager } from '../managers/method.manager';
+import { recordOpenAIUsage } from '../managers/openai-usage-ledger.manager';
+import { ResolveIOServer } from '../resolveio-server-app';
+import { CodexClient } from '../services/codex-client';
+import { objectIdHexString, round } from '../util/common';
+import { countChatTokens, countTokens } from '../util/tokenizer';
+
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 2000;
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const MAX_REVIEW_STRING_LENGTH = 500;
+const MAX_REVIEW_ARRAY_ITEMS = 10;
+const MAX_REVIEW_OBJECT_KEYS = 40;
+const MAX_REVIEW_DEPTH = 4;
+const MAX_REVIEW_LIST_ITEMS = 6;
+const MAX_REVIEW_CHANGED_FIELDS = 60;
+const DEFAULT_RISK_REVIEW_TIMEOUT_MS = 30000;
+const DEFAULT_RISK_REVIEW_MAX_TOKENS = 700;
+const SENSITIVE_REVIEW_FIELD_REGEX = /(password|secret|token|api[_-]?key|salt|hash|email|phone|address|ssn|services|roles)/i;
+const DEFAULT_AI_SUGGEST_TIMEOUT_MS = 60000;
+const DEFAULT_AI_SUGGEST_MAX_TOKENS = 1000;
+const MAX_AI_SUGGEST_FIELDS = 700;
+const MAX_AI_SUGGEST_COLLECTIONS = 800;
+const MAX_AI_SUGGEST_RESULTS = 500;
+const RESTRICTED_AGGREGATE_STAGES = new Set(['$out', '$merge']);
+
+type ExplorerFindOptions = {
+	projection?: Record<string, number>;
+	sort?: Record<string, any>;
+	limit?: number;
+	skip?: number;
+	includeTotal?: boolean;
+};
+
+type ExplorerMode = 'resolveio' | 'aicoder';
+
+type MongoExplorerDeleteImpactCollection = {
+	collection: string;
+	references: number;
+	sample_ids: string[];
+};
+
+type MongoExplorerDeleteImpact = {
+	has_references: boolean;
+	unresolved: boolean;
+	collections: MongoExplorerDeleteImpactCollection[];
+};
+
+type MongoExplorerRiskOperation = 'insert' | 'replace' | 'delete' | 'command';
+type MongoExplorerRiskLevel = 'low' | 'medium' | 'high' | 'critical';
+type MongoExplorerRiskReviewStatus = 'ok' | 'fallback' | 'disabled';
+
+type MongoExplorerRiskReview = {
+	operation: MongoExplorerRiskOperation;
+	risk_level: MongoExplorerRiskLevel;
+	should_block: boolean;
+	summary: string;
+	reasons: string[];
+	suggested_checks: string[];
+	confidence: number;
+	model: string;
+	request_id: string;
+	review_status: MongoExplorerRiskReviewStatus;
+	reviewed_at: string;
+};
+
+type MongoExplorerRiskReviewInput = {
+	database: string;
+	collection: string;
+	operation: MongoExplorerRiskOperation;
+	mode: ExplorerMode;
+	before_document?: any;
+	after_document?: any;
+	delete_impact?: MongoExplorerDeleteImpact;
+};
+
+type MongoExplorerAiAction = 'find' | 'aggregate';
+
+type MongoExplorerAiPayload = {
+	prompt?: string;
+	database?: string;
+	selected_collection?: string;
+	available_collections?: Array<{ name?: string; collection?: string; type?: string }>;
+	available_fields?: Array<{ path?: string; label?: string; type?: string; collection?: string }>;
+	permission_view?: string;
+	mode?: string;
+	id_client?: string;
+	max_results?: number;
+};
+
+type MongoExplorerAiField = {
+	path: string;
+	label: string;
+	type: string;
+	collection: string;
+};
+
+type MongoExplorerAiPlan = {
+	action: MongoExplorerAiAction;
+	collection: string;
+	query?: Record<string, any>;
+	pipeline?: any[];
+	options?: Record<string, any>;
+	documents?: any[];
+	total?: number | null;
+	notes?: string;
+};
+
+function parseMongoExplorerWriteUsers(): string[] {
+	const raw = typeof process.env.MONGO_EXPLORER_WRITE_USERS === 'string' ? process.env.MONGO_EXPLORER_WRITE_USERS.trim() : '';
+	if (!raw) {
+		return [];
+	}
+
+	try {
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed)) {
+			return parsed.map(value => String(value)).filter(value => value.trim().length);
+		}
+		if (typeof parsed === 'string') {
+			return [parsed.trim()].filter(Boolean);
+		}
+	}
+	catch {
+		// Fall back to comma-separated list.
+	}
+
+	return raw
+		.split(',')
+		.map(value => value.trim())
+		.filter(Boolean);
+}
+
+function normalizeExplorerMode(mode?: string): ExplorerMode {
+	const normalizedMode = String(mode || '').trim().toLowerCase();
+	if (normalizedMode === 'resolveio') {
+		return 'resolveio';
+	}
+	return 'aicoder';
+}
+
+function allowUnschemaizedWrites(): boolean {
+	return process.env.MONGO_EXPLORER_ALLOW_UNSCHEMATIZED_WRITE === 'true';
+}
+
+function resolveDatabaseName(database?: string): string {
+	const defaultDb = ResolveIOServer.getServerConfig()?.DATABASE || '';
+	const dbName = typeof database === 'string' && database.trim().length ? database.trim() : defaultDb;
+
+	if (!dbName) {
+		throw new Error('Mongo Explorer: Database is required');
+	}
+
+	const allowedDatabases = ResolveIOServer.getMongoManager()?.getWatchedDatabases() || [];
+	if (allowedDatabases.length && !allowedDatabases.includes(dbName)) {
+		throw new Error('Mongo Explorer: Database access denied');
+	}
+
+	return dbName;
+}
+
+function resolveDatabase(database?: string): Db {
+	const dbName = resolveDatabaseName(database);
+	return ResolveIOServer.getMongoConnection().db(dbName);
+}
+
+function resolveCollectionHandle(database: string, collection: string) {
+	const mainDb = ResolveIOServer.getServerConfig()?.DATABASE || '';
+	const isMainDb = database === mainDb;
+	const managerCollection = isMainDb ? ResolveIOServer.getMongoManager()?.collection(collection) : null;
+	const db = ResolveIOServer.getMongoConnection().db(database);
+
+	return {
+		managerCollection,
+		dbCollection: db.collection(collection)
+	};
+}
+
+function getSchemaDefinition(collectionRef: any): Record<string, any> {
+	if (!collectionRef || !collectionRef.simplschema || typeof collectionRef.simplschema.schema !== 'function') {
+		return {};
+	}
+
+	const schema = collectionRef.simplschema.schema();
+	return schema && typeof schema === 'object' ? schema : {};
+}
+
+function getSchemaTypeName(definition: any): string {
+	const typeDefs = definition?.type?.definitions;
+	if (!Array.isArray(typeDefs) || !typeDefs.length) {
+		return 'Any';
+	}
+
+	const firstType = typeDefs[0]?.type;
+	if (!firstType) {
+		return 'Any';
+	}
+
+	if (firstType === String) {
+		return 'String';
+	}
+	if (firstType === Number) {
+		return 'Number';
+	}
+	if (firstType === Boolean) {
+		return 'Boolean';
+	}
+	if (firstType === Date) {
+		return 'Date';
+	}
+	if (firstType === Object) {
+		return 'Object';
+	}
+	if (firstType === Array) {
+		return 'Array';
+	}
+
+	const typeName = firstType.name || String(firstType);
+	if (typeName === 'Integer') {
+		return 'Number';
+	}
+	return typeName;
+}
+
+function toLabel(path: string): string {
+	const last = path.split('.').pop() || path;
+	return last
+		.replace(/\$/g, '')
+		.replace(/_/g, ' ')
+		.replace(/\s+/g, ' ')
+		.trim();
+}
+
+function isProtectedFieldSegment(segment: string): boolean {
+	if (!segment) {
+		return false;
+	}
+
+	if (segment === '_id') {
+		return true;
+	}
+
+	const normalizedSegment = segment.replace(/\[\d+\]/g, '');
+	return normalizedSegment.toLowerCase().startsWith('id_');
+}
+
+function isProtectedFieldPath(path: string): boolean {
+	const segments = String(path || '').split('.').filter(Boolean);
+	return segments.some(segment => isProtectedFieldSegment(segment));
+}
+
+function safeStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value);
+	}
+	catch {
+		return String(value);
+	}
+}
+
+function collectProtectedFieldPaths(value: any, prefix = '', out: Record<string, any> = {}): Record<string, any> {
+	if (Array.isArray(value)) {
+		value.forEach((item, index) => {
+			const nextPrefix = prefix ? `${prefix}[${index}]` : `[${index}]`;
+			collectProtectedFieldPaths(item, nextPrefix, out);
+		});
+		return out;
+	}
+
+	if (!value || typeof value !== 'object') {
+		return out;
+	}
+
+	Object.keys(value).forEach((key) => {
+		const nextPrefix = prefix ? `${prefix}.${key}` : key;
+		if (isProtectedFieldSegment(key)) {
+			out[nextPrefix] = value[key];
+		}
+		collectProtectedFieldPaths(value[key], nextPrefix, out);
+	});
+
+	return out;
+}
+
+function ensureProtectedFieldsUnchanged(originalDoc: any, updatedDoc: any) {
+	const originalProtected = collectProtectedFieldPaths(originalDoc || {});
+	const updatedProtected = collectProtectedFieldPaths(updatedDoc || {});
+	const violations: string[] = [];
+
+	Object.keys(originalProtected).forEach((path) => {
+		if (!Object.prototype.hasOwnProperty.call(updatedProtected, path)) {
+			violations.push(path);
+			return;
+		}
+
+		const originalValue = safeStringify(originalProtected[path]);
+		const updatedValue = safeStringify(updatedProtected[path]);
+		if (originalValue !== updatedValue) {
+			violations.push(path);
+		}
+	});
+
+	Object.keys(updatedProtected).forEach((path) => {
+		if (!Object.prototype.hasOwnProperty.call(originalProtected, path)) {
+			violations.push(path);
+		}
+	});
+
+	if (violations.length) {
+		const preview = violations.slice(0, 4).join(', ');
+		throw new Error(`Mongo Explorer: Protected fields cannot be edited (${preview}${violations.length > 4 ? ', ...' : ''})`);
+	}
+}
+
+function coerceDateValue(value: unknown): unknown {
+	if (value instanceof Date) {
+		return value;
+	}
+
+	if (typeof value !== 'string' || !ISO_DATE_REGEX.test(value)) {
+		return value;
+	}
+
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? value : parsed;
+}
+
+function coerceDatePath(target: any, segments: string[]) {
+	if (!target || !segments.length) {
+		return;
+	}
+
+	const [segment, ...rest] = segments;
+
+	if (segment === '$') {
+		if (Array.isArray(target)) {
+			target.forEach(item => coerceDatePath(item, rest));
+		}
+		return;
+	}
+
+	if (!Object.prototype.hasOwnProperty.call(target, segment)) {
+		return;
+	}
+
+	if (rest.length === 0) {
+		const updatedValue = coerceDateValue(target[segment]);
+		if (updatedValue !== target[segment]) {
+			target[segment] = updatedValue;
+		}
+		return;
+	}
+
+	coerceDatePath(target[segment], rest);
+}
+
+function coerceDateFields(collectionRef: any, doc: any) {
+	if (!collectionRef || !collectionRef.simplschema || !doc) {
+		return;
+	}
+
+	const schema = getSchemaDefinition(collectionRef);
+	Object.keys(schema).forEach((schemaKey) => {
+		const definition = schema[schemaKey];
+		const typeDefs = definition?.type?.definitions;
+		if (!Array.isArray(typeDefs) || !typeDefs.some(typeDef => typeDef.type === Date)) {
+			return;
+		}
+
+		coerceDatePath(doc, schemaKey.split('.'));
+	});
+}
+
+function normalizeFindOptions(options?: ExplorerFindOptions) {
+	const normalized = options || {};
+	const projection = normalized.projection && Object.keys(normalized.projection).length ? normalized.projection : undefined;
+	const sort = normalized.sort && Object.keys(normalized.sort).length ? normalized.sort : undefined;
+	const limit = typeof normalized.limit === 'number' ? Math.min(Math.max(normalized.limit, 0), MAX_LIMIT) : DEFAULT_LIMIT;
+	const skip = typeof normalized.skip === 'number' ? Math.max(normalized.skip, 0) : 0;
+
+	return {
+		findOptions: {
+			projection,
+			sort,
+			limit,
+			skip
+		},
+		includeTotal: normalized.includeTotal === true
+	};
+}
+
+function userHasView(user, view: string): boolean {
+	if (!user || !view) {
+		return false;
+	}
+
+	if (user.roles?.super_admin) {
+		return true;
+	}
+
+	const groups = Array.isArray(user.roles?.groups) ? user.roles.groups : [];
+	const miscs = Array.isArray(user.roles?.miscs) ? user.roles.miscs : [];
+
+	if (groups.some(group => Array.isArray(group.views) && group.views.some(v => v.startsWith(view)))) {
+		return true;
+	}
+
+	if (miscs.some(v => v.startsWith(view))) {
+		return true;
+	}
+
+	if (groups.some(group => group.name === view)) {
+		return true;
+	}
+
+	return false;
+}
+
+async function ensureWriteAccess(context: any, permissionView?: string, mode?: string) {
+	const idUser = context?.id_user;
+	if (!idUser) {
+		throw new Error('Mongo Explorer: Unauthorized');
+	}
+
+	const user = await Users.findOne({_id: idUser});
+	if (!user) {
+		throw new Error('Mongo Explorer: Unauthorized');
+	}
+
+	if (user.readonly) {
+		throw new Error('Mongo Explorer: Readonly user');
+	}
+
+	const normalizedMode = normalizeExplorerMode(mode);
+	if (normalizedMode === 'resolveio') {
+		throw new Error('Mongo Explorer: ResolveIO mode is read only');
+	}
+
+	const allowedUsers = parseMongoExplorerWriteUsers();
+	if (allowedUsers.length) {
+		const username = String(user.username || '').trim().toLowerCase();
+		const email = String(user.email || '').trim().toLowerCase();
+		const id = String(user._id || '').trim();
+		const isAllowed = allowedUsers.some(entry => {
+			const normalized = String(entry || '').trim().toLowerCase();
+			if (!normalized) {
+				return false;
+			}
+			return normalized === username || (email && normalized === email) || (id && entry === id);
+		});
+
+		if (!isAllowed) {
+			throw new Error('Mongo Explorer: Write access denied');
+		}
+	}
+
+	if (user.roles?.super_admin) {
+		return;
+	}
+
+	const normalizedPermission = typeof permissionView === 'string' ? permissionView.trim() : '';
+
+	if (!normalizedPermission) {
+		return;
+	}
+
+	if (userHasView(user, normalizedPermission)) {
+		return;
+	}
+
+	throw new Error('Mongo Explorer: Write access denied');
+}
+
+function buildDeleteSafetyCollections(collectionRef: any): string[] {
+	const schema = getSchemaDefinition(collectionRef);
+	return Object.keys(schema).filter(path => isProtectedFieldPath(path) && path !== '_id');
+}
+
+async function buildDeleteImpact(database: string, sourceCollection: string, docId: string): Promise<MongoExplorerDeleteImpact> {
+	const mainDb = ResolveIOServer.getServerConfig()?.DATABASE || '';
+	if (database !== mainDb) {
+		return {
+			has_references: false,
+			unresolved: true,
+			collections: []
+		};
+	}
+
+	const mongoManager = ResolveIOServer.getMongoManager();
+	const collections = mongoManager?.collections ? mongoManager.collections() : [];
+	const impacts: MongoExplorerDeleteImpactCollection[] = [];
+	let unresolved = false;
+
+	for (const collectionRef of collections) {
+		const collectionName = collectionRef?.collectionName;
+		if (!collectionName) {
+			continue;
+		}
+		if (collectionName === `${sourceCollection}.versions`) {
+			continue;
+		}
+
+		const referencePaths = buildDeleteSafetyCollections(collectionRef);
+		if (!referencePaths.length) {
+			continue;
+		}
+
+		const query = {
+			$or: referencePaths.map(path => ({ [path]: docId }))
+		};
+
+		try {
+			const docs = await collectionRef.find(query, { projection: { _id: 1 }, limit: 3 });
+			if (Array.isArray(docs) && docs.length) {
+				impacts.push({
+					collection: collectionName,
+					references: docs.length,
+					sample_ids: docs.map(doc => String(doc?._id || '')).filter(Boolean)
+				});
+			}
+		}
+		catch {
+			unresolved = true;
+		}
+	}
+
+	return {
+		has_references: impacts.length > 0,
+		unresolved,
+		collections: impacts.sort((a, b) => a.collection.localeCompare(b.collection))
+	};
+}
+
+function normalizeOptionalString(value: any): string | undefined {
+	if (typeof value === 'string') {
+		const trimmed = value.trim();
+		return trimmed.length ? trimmed : undefined;
+	}
+	if (value === null || value === undefined) {
+		return undefined;
+	}
+	const normalized = String(value).trim();
+	return normalized.length ? normalized : undefined;
+}
+
+function normalizePositiveNumber(value: any, fallback: number): number {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		return fallback;
+	}
+	return parsed;
+}
+
+function parseBooleanValue(value: any, fallback: boolean): boolean {
+	if (typeof value === 'boolean') {
+		return value;
+	}
+	const normalized = String(value || '').trim().toLowerCase();
+	if (!normalized.length) {
+		return fallback;
+	}
+	if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+		return true;
+	}
+	if (['0', 'false', 'no', 'off'].includes(normalized)) {
+		return false;
+	}
+	return fallback;
+}
+
+function truncateForRiskReview(value: string, maxLength = MAX_REVIEW_STRING_LENGTH): string {
+	const normalized = String(value || '');
+	if (normalized.length <= maxLength) {
+		return normalized;
+	}
+	const diff = normalized.length - maxLength;
+	return `${normalized.slice(0, maxLength)}...[+${diff} chars]`;
+}
+
+function sanitizeForRiskReview(value: any, depth = 0): any {
+	if (value === null || value === undefined) {
+		return value;
+	}
+
+	if (depth > MAX_REVIEW_DEPTH) {
+		return '[Truncated depth]';
+	}
+
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+
+	if (typeof value === 'string') {
+		return truncateForRiskReview(value);
+	}
+
+	if (typeof value === 'number' || typeof value === 'boolean') {
+		return value;
+	}
+
+	if (Array.isArray(value)) {
+		const sanitized = value
+			.slice(0, MAX_REVIEW_ARRAY_ITEMS)
+			.map(item => sanitizeForRiskReview(item, depth + 1));
+		if (value.length > MAX_REVIEW_ARRAY_ITEMS) {
+			sanitized.push(`[${value.length - MAX_REVIEW_ARRAY_ITEMS} more item(s)]`);
+		}
+		return sanitized;
+	}
+
+	if (typeof value === 'object') {
+		const output: Record<string, any> = {};
+		const keys = Object.keys(value);
+		const limitedKeys = keys.slice(0, MAX_REVIEW_OBJECT_KEYS);
+		limitedKeys.forEach((key) => {
+			if (SENSITIVE_REVIEW_FIELD_REGEX.test(key)) {
+				output[key] = '[REDACTED]';
+				return;
+			}
+			output[key] = sanitizeForRiskReview(value[key], depth + 1);
+		});
+		if (keys.length > MAX_REVIEW_OBJECT_KEYS) {
+			output.__truncated_keys = keys.length - MAX_REVIEW_OBJECT_KEYS;
+		}
+		return output;
+	}
+
+	return truncateForRiskReview(String(value));
+}
+
+function pickChangedFields(beforeDocument: any, afterDocument: any): string[] {
+	if (!beforeDocument || typeof beforeDocument !== 'object' || !afterDocument || typeof afterDocument !== 'object') {
+		return [];
+	}
+
+	const changed: string[] = [];
+	const fieldNames = new Set<string>([
+		...Object.keys(beforeDocument),
+		...Object.keys(afterDocument)
+	]);
+
+	for (const field of fieldNames) {
+		if (changed.length >= MAX_REVIEW_CHANGED_FIELDS) {
+			break;
+		}
+		const beforeValue = safeStringify(beforeDocument[field]);
+		const afterValue = safeStringify(afterDocument[field]);
+		if (beforeValue !== afterValue) {
+			changed.push(field);
+		}
+	}
+
+	return changed;
+}
+
+function normalizeRiskLevel(value: any): MongoExplorerRiskLevel {
+	const normalized = String(value || '').trim().toLowerCase();
+	if (normalized === 'low') {
+		return 'low';
+	}
+	if (normalized === 'medium') {
+		return 'medium';
+	}
+	if (normalized === 'high') {
+		return 'high';
+	}
+	if (normalized === 'critical') {
+		return 'critical';
+	}
+	return 'high';
+}
+
+function normalizeRiskList(value: any): string[] {
+	if (!Array.isArray(value)) {
+		return [];
+	}
+	return value
+		.map(item => normalizeOptionalString(item))
+		.filter((item): item is string => !!item)
+		.slice(0, MAX_REVIEW_LIST_ITEMS)
+		.map(item => truncateForRiskReview(item, 220));
+}
+
+function buildFallbackRiskReview(operation: MongoExplorerRiskOperation, summary: string, model = ''): MongoExplorerRiskReview {
+	return {
+		operation,
+		risk_level: 'high',
+		should_block: true,
+		summary: truncateForRiskReview(summary, 220),
+		reasons: [
+			'AI review could not produce a reliable result.',
+			'Proceed only with explicit approval and manual dependency checks.'
+		],
+		suggested_checks: [
+			'Confirm related records and id_* references before writing.',
+			'Validate that schema-required fields and date values remain valid.'
+		],
+		confidence: 0,
+		model: model || '',
+		request_id: '',
+		review_status: 'fallback',
+		reviewed_at: new Date().toISOString()
+	};
+}
+
+function buildDisabledRiskReview(operation: MongoExplorerRiskOperation): MongoExplorerRiskReview {
+	return {
+		operation,
+		risk_level: 'low',
+		should_block: false,
+		summary: 'AI risk review is disabled by configuration.',
+		reasons: [],
+		suggested_checks: [],
+		confidence: 1,
+		model: '',
+		request_id: '',
+		review_status: 'disabled',
+		reviewed_at: new Date().toISOString()
+	};
+}
+
+function parseRiskReviewPayload(content: string): any {
+	const normalized = String(content || '').trim();
+	if (!normalized.length) {
+		return {};
+	}
+
+	try {
+		return JSON.parse(normalized);
+	}
+	catch {
+		// Fall through and try to parse a JSON object embedded in plain text.
+	}
+
+	const start = normalized.indexOf('{');
+	const end = normalized.lastIndexOf('}');
+	if (start !== -1 && end > start) {
+		const candidate = normalized.slice(start, end + 1);
+		try {
+			return JSON.parse(candidate);
+		}
+		catch {
+			return {};
+		}
+	}
+
+	return {};
+}
+
+function normalizeRiskReview(
+	operation: MongoExplorerRiskOperation,
+	payload: any,
+	model: string,
+	requestId: string
+): MongoExplorerRiskReview {
+	const riskLevel = normalizeRiskLevel(payload?.risk_level);
+	const normalizedConfidence = Number(payload?.confidence);
+	const confidence = Number.isFinite(normalizedConfidence)
+		? Math.max(0, Math.min(1, normalizedConfidence))
+		: 0.6;
+	const summary = normalizeOptionalString(payload?.summary)
+		|| `AI review marked this operation as ${riskLevel} risk.`;
+	const reasons = normalizeRiskList(payload?.reasons);
+	const suggestedChecks = normalizeRiskList(payload?.suggested_checks);
+	const shouldBlock = payload?.should_block === true || riskLevel === 'critical';
+
+	return {
+		operation,
+		risk_level: riskLevel,
+		should_block: !!shouldBlock,
+		summary: truncateForRiskReview(summary, 220),
+		reasons,
+		suggested_checks: suggestedChecks,
+		confidence,
+		model: model || '',
+		request_id: requestId || '',
+		review_status: 'ok',
+		reviewed_at: new Date().toISOString()
+	};
+}
+
+function resolveRiskReviewSettings() {
+	const serverConfig = ResolveIOServer.getServerConfig() || {};
+
+	const enabled = parseBooleanValue(
+		serverConfig['MONGO_EXPLORER_ENABLE_AI_RISK_REVIEW'] ?? process.env.MONGO_EXPLORER_ENABLE_AI_RISK_REVIEW,
+		true
+	);
+
+	const model = normalizeOptionalString(
+		serverConfig['MONGO_EXPLORER_RISK_REVIEW_MODEL']
+		|| process.env.MONGO_EXPLORER_RISK_REVIEW_MODEL
+		|| serverConfig['AI_ASSISTANT_CODEX_MODEL']
+		|| process.env.AI_ASSISTANT_CODEX_MODEL
+		|| serverConfig['AI_DASHBOARD_CODEX_MODEL']
+		|| process.env.AI_DASHBOARD_CODEX_MODEL
+	);
+
+	const fallbackModel = normalizeOptionalString(
+		serverConfig['MONGO_EXPLORER_RISK_REVIEW_FALLBACK_MODEL']
+		|| process.env.MONGO_EXPLORER_RISK_REVIEW_FALLBACK_MODEL
+		|| serverConfig['AI_ASSISTANT_CODEX_FALLBACK_MODEL']
+		|| process.env.AI_ASSISTANT_CODEX_FALLBACK_MODEL
+		|| serverConfig['AI_DASHBOARD_CODEX_FALLBACK_MODEL']
+		|| process.env.AI_DASHBOARD_CODEX_FALLBACK_MODEL
+	);
+
+	const timeoutMs = normalizePositiveNumber(
+		serverConfig['MONGO_EXPLORER_RISK_REVIEW_TIMEOUT_MS'] ?? process.env.MONGO_EXPLORER_RISK_REVIEW_TIMEOUT_MS,
+		DEFAULT_RISK_REVIEW_TIMEOUT_MS
+	);
+
+	const maxTokens = normalizePositiveNumber(
+		serverConfig['MONGO_EXPLORER_RISK_REVIEW_MAX_TOKENS'] ?? process.env.MONGO_EXPLORER_RISK_REVIEW_MAX_TOKENS,
+		DEFAULT_RISK_REVIEW_MAX_TOKENS
+	);
+
+	const maxRetries = normalizePositiveNumber(
+		serverConfig['OPENAI_MAX_RETRIES'] ?? process.env.OPENAI_MAX_RETRIES,
+		1
+	);
+
+	const retryDelayMs = normalizePositiveNumber(
+		serverConfig['OPENAI_RETRY_DELAY_MS'] ?? process.env.OPENAI_RETRY_DELAY_MS,
+		750
+	);
+
+	const apiKey = normalizeOptionalString(serverConfig['OPENAI_API_KEY'] || process.env.OPENAI_API_KEY) || '';
+	const baseUrl = normalizeOptionalString(serverConfig['OPENAI_BASE_URL'] || process.env.OPENAI_BASE_URL);
+
+	return {
+		enabled,
+		apiKey,
+		baseUrl,
+		model,
+		fallbackModel,
+		timeoutMs,
+		maxTokens,
+		maxRetries,
+		retryDelayMs
+	};
+}
+
+function buildCodexPrompt(systemPrompt: string, userPrompt: string): string {
+	return `System:\n${systemPrompt}\n\nUser:\n${userPrompt}`.trim();
+}
+
+function buildCodexClient(settings: {
+	apiKey: string;
+	baseUrl?: string;
+	model?: string;
+	fallbackModel?: string;
+	maxRetries?: number;
+	retryDelayMs?: number;
+}): CodexClient {
+	const fallbackModels: string[] = [];
+	const fallback = normalizeOptionalString(settings.fallbackModel);
+	if (fallback && fallback !== settings.model) {
+		fallbackModels.push(fallback);
+	}
+	return new CodexClient({
+		apiKey: settings.apiKey,
+		baseUrl: settings.baseUrl,
+		...(settings.model ? { model: settings.model } : {}),
+		...(fallbackModels.length ? { fallbackModel: fallbackModels[0], fallbackModels } : {}),
+		maxRetries: round(settings.maxRetries || 0),
+		retryDelayMs: round(settings.retryDelayMs || 0)
+	});
+}
+
+function estimateCodexUsage(messages: Array<{ role: string; content: string }>, responseText: string, model: string) {
+	const inputTokens = countChatTokens(messages, model);
+	const outputTokens = countTokens(responseText || '', model);
+	return {
+		inputTokens,
+		outputTokens,
+		totalTokens: inputTokens + outputTokens
+	};
+}
+
+function buildRiskReviewPrompt(input: MongoExplorerRiskReviewInput): string {
+	const payload = {
+		database: input.database,
+		collection: input.collection,
+		operation: input.operation,
+		mode: input.mode,
+		changed_fields: pickChangedFields(input.before_document, input.after_document),
+		delete_impact: sanitizeForRiskReview(input.delete_impact || null),
+		before_document: sanitizeForRiskReview(input.before_document || null),
+		after_document: sanitizeForRiskReview(input.after_document || null)
+	};
+
+	return [
+		'Review this MongoDB write operation for runtime and data integrity risk.',
+		'Focus on foreign-key style id_* dependencies, schema compatibility, destructive impact, and financial/operational record safety.',
+		'Return JSON only.',
+		JSON.stringify(payload, null, 2)
+	].join('\n');
+}
+
+async function reviewOperationRisk(input: MongoExplorerRiskReviewInput): Promise<MongoExplorerRiskReview> {
+	const settings = resolveRiskReviewSettings();
+	if (!settings.enabled) {
+		return buildDisabledRiskReview(input.operation);
+	}
+
+	if (!settings.apiKey) {
+		return buildFallbackRiskReview(input.operation, 'AI risk review unavailable: AI API key is missing.');
+	}
+
+	const client = buildCodexClient(settings);
+
+	const systemPrompt = [
+		'You are a MongoDB operation safety reviewer for a production SaaS application.',
+		'Respond with a single JSON object only.',
+		'Required keys:',
+		'risk_level ("low" | "medium" | "high" | "critical"),',
+		'should_block (boolean),',
+		'summary (string),',
+		'reasons (string[]),',
+		'suggested_checks (string[]),',
+		'confidence (number between 0 and 1).',
+		'Keep summary concise (<= 220 chars).'
+	].join(' ');
+	const userPrompt = buildRiskReviewPrompt(input);
+	const prompt = buildCodexPrompt(systemPrompt, userPrompt);
+
+	try {
+		const responseText = await client.run(prompt, {
+			timeoutMs: round(settings.timeoutMs),
+			threadOptions: {
+				model: settings.model,
+				sandboxMode: 'read-only',
+				skipGitRepoCheck: true,
+				networkAccessEnabled: false,
+				webSearchMode: 'disabled',
+				webSearchEnabled: false,
+				approvalPolicy: 'never'
+			}
+		});
+
+		const payload = parseRiskReviewPayload(responseText);
+		return normalizeRiskReview(input.operation, payload, settings.model, '');
+	}
+	catch (err) {
+		const detail = err?.message ? String(err.message) : 'Unknown AI review error';
+		return buildFallbackRiskReview(input.operation, `AI risk review failed: ${truncateForRiskReview(detail, 160)}`, settings.model);
+	}
+}
+
+function normalizeAiAction(value: any): MongoExplorerAiAction {
+	const normalized = normalizeOptionalString(value) || '';
+	return normalized.toLowerCase() === 'aggregate' ? 'aggregate' : 'find';
+}
+
+function sanitizeAiCollections(raw: any[]): string[] {
+	const values: string[] = [];
+	const seen = new Set<string>();
+	(raw || []).forEach((entry) => {
+		const normalized = normalizeOptionalString((entry as any)?.collection || (entry as any)?.name || entry);
+		if (!normalized) {
+			return;
+		}
+		const key = normalized.toLowerCase();
+		if (seen.has(key)) {
+			return;
+		}
+		seen.add(key);
+		values.push(normalized);
+	});
+	return values.slice(0, MAX_AI_SUGGEST_COLLECTIONS);
+}
+
+function sanitizeAiFields(raw: any[], fallbackCollection: string): MongoExplorerAiField[] {
+	const fields: MongoExplorerAiField[] = [];
+	const seen = new Set<string>();
+	(raw || []).forEach((entry) => {
+		const path = normalizeOptionalString(entry?.path || entry?.field_path || entry?.fieldPath);
+		if (!path) {
+			return;
+		}
+		const collection = normalizeOptionalString(
+			entry?.collection || entry?.collection_name || entry?.collectionName
+		) || fallbackCollection || '';
+		const key = `${collection.toLowerCase()}::${path.toLowerCase()}`;
+		if (seen.has(key)) {
+			return;
+		}
+		seen.add(key);
+		fields.push({
+			path,
+			label: normalizeOptionalString(entry?.label || entry?.field_path_name || entry?.fieldPathName) || path,
+			type: normalizeOptionalString(entry?.type || entry?.field_type || entry?.fieldType) || 'Any',
+			collection
+		});
+	});
+	return fields.slice(0, MAX_AI_SUGGEST_FIELDS);
+}
+
+function deriveAiFieldsFromCollection(database: string, collection: string): MongoExplorerAiField[] {
+	if (!collection) {
+		return [];
+	}
+	const { managerCollection } = resolveCollectionHandle(database, collection);
+	if (!managerCollection) {
+		return [];
+	}
+	const schema = getSchemaDefinition(managerCollection);
+	return Object.keys(schema)
+		.sort((a, b) => a.localeCompare(b))
+		.slice(0, MAX_AI_SUGGEST_FIELDS)
+		.map((path) => {
+			const definition = schema[path];
+			return {
+				path,
+				label: toLabel(path),
+				type: getSchemaTypeName(definition),
+				collection
+			};
+		});
+}
+
+function resolveCollectionFromList(value: any, collections: string[], fallback = ''): string {
+	const normalized = normalizeOptionalString(value);
+	if (normalized) {
+		const matched = (collections || []).find(entry => entry.toLowerCase() === normalized.toLowerCase());
+		if (matched) {
+			return matched;
+		}
+	}
+	if (fallback) {
+		return fallback;
+	}
+	return collections?.[0] || '';
+}
+
+function normalizeAiResultLimit(value: any, fallback = 100): number {
+	const fallbackValue = Math.min(Math.max(fallback, 1), MAX_AI_SUGGEST_RESULTS);
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) {
+		return fallbackValue;
+	}
+	return Math.min(Math.max(round(parsed), 1), MAX_AI_SUGGEST_RESULTS);
+}
+
+function normalizeAiSkip(value: any): number {
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed < 0) {
+		return 0;
+	}
+	return Math.max(0, round(parsed));
+}
+
+function normalizeAiObject(value: any): Record<string, any> {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) {
+		return {};
+	}
+	return value;
+}
+
+function hasObjectKeys(value: any): boolean {
+	return !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+
+function parseAiPlanPayload(content: string): any {
+	const normalized = String(content || '').trim();
+	if (!normalized.length) {
+		return {};
+	}
+
+	try {
+		return JSON.parse(normalized);
+	}
+	catch {
+		// Fall through and parse embedded JSON object.
+	}
+
+	const start = normalized.indexOf('{');
+	const end = normalized.lastIndexOf('}');
+	if (start !== -1 && end > start) {
+		try {
+			return JSON.parse(normalized.slice(start, end + 1));
+		}
+		catch {
+			return {};
+		}
+	}
+
+	return {};
+}
+
+function resolveMongoExplorerAiSettings() {
+	const serverConfig = ResolveIOServer.getServerConfig() || {};
+	const apiKey = normalizeOptionalString(serverConfig['OPENAI_API_KEY'] || process.env.OPENAI_API_KEY) || '';
+	const baseUrl = normalizeOptionalString(serverConfig['OPENAI_BASE_URL'] || process.env.OPENAI_BASE_URL);
+
+	const model = normalizeOptionalString(
+		serverConfig['MONGO_EXPLORER_AI_MODEL']
+		|| process.env.MONGO_EXPLORER_AI_MODEL
+		|| serverConfig['AI_ASSISTANT_CODEX_MODEL']
+		|| process.env.AI_ASSISTANT_CODEX_MODEL
+	);
+
+	const fallbackModel = normalizeOptionalString(
+		serverConfig['MONGO_EXPLORER_AI_FALLBACK_MODEL']
+		|| process.env.MONGO_EXPLORER_AI_FALLBACK_MODEL
+		|| serverConfig['AI_ASSISTANT_CODEX_FALLBACK_MODEL']
+		|| process.env.AI_ASSISTANT_CODEX_FALLBACK_MODEL
+	);
+
+	const timeoutMs = normalizePositiveNumber(
+		serverConfig['MONGO_EXPLORER_AI_TIMEOUT_MS'] ?? process.env.MONGO_EXPLORER_AI_TIMEOUT_MS,
+		DEFAULT_AI_SUGGEST_TIMEOUT_MS
+	);
+
+	const maxTokens = normalizePositiveNumber(
+		serverConfig['MONGO_EXPLORER_AI_MAX_TOKENS'] ?? process.env.MONGO_EXPLORER_AI_MAX_TOKENS,
+		DEFAULT_AI_SUGGEST_MAX_TOKENS
+	);
+
+	const maxRetries = normalizePositiveNumber(
+		serverConfig['OPENAI_MAX_RETRIES'] ?? process.env.OPENAI_MAX_RETRIES,
+		1
+	);
+
+	const retryDelayMs = normalizePositiveNumber(
+		serverConfig['OPENAI_RETRY_DELAY_MS'] ?? process.env.OPENAI_RETRY_DELAY_MS,
+		750
+	);
+
+	return {
+		apiKey,
+		baseUrl,
+		model,
+		fallbackModel,
+		timeoutMs,
+		maxTokens,
+		maxRetries,
+		retryDelayMs
+	};
+}
+
+function buildMongoExplorerAiSystemPrompt(): string {
+	return [
+		'You are a MongoDB query planner for a read-only Mongo Explorer UI.',
+		'Return a single JSON object and nothing else.',
+		'Supported schema:',
+		'{',
+		'  "action": "find|aggregate",',
+		'  "collection": "string",',
+		'  "query": { ... },',
+		'  "pipeline": [{ ... }],',
+		'  "options": {',
+		'    "projection": { "field": 1 },',
+		'    "sort": { "field": -1 },',
+		'    "limit": 100,',
+		'    "skip": 0,',
+		'    "includeTotal": true,',
+		'    "allowDiskUse": true',
+		'  },',
+		'  "notes": "short summary"',
+		'}',
+		'Rules:',
+		'- Use only provided collection names and field paths.',
+		'- Read-only only. Never output write operations, update/delete commands, or aggregation stages $out/$merge.',
+		'- Prefer action=find for direct lookups and simple filters.',
+		'- Use action=aggregate for grouped totals, rankings, or trend buckets.',
+		'- Keep options.limit between 1 and 500.',
+		'- If request is ambiguous, use selected_collection and a conservative limit.'
+	].join('\n');
+}
+
+function buildMongoExplorerAiUserPrompt(input: {
+	prompt: string;
+	selectedCollection: string;
+	availableCollections: string[];
+	availableFields: MongoExplorerAiField[];
+	maxResults: number;
+}): string {
+	const payload = {
+		request: input.prompt,
+		selected_collection: input.selectedCollection || '',
+		max_results: input.maxResults,
+		available_collections: input.availableCollections || [],
+		available_fields: input.availableFields || []
+	};
+	return JSON.stringify(payload);
+}
+
+function sanitizeAggregatePipeline(rawPipeline: any, limit: number): { pipeline: any[]; removedRestricted: boolean } {
+	const source = Array.isArray(rawPipeline) ? rawPipeline : [];
+	const sanitized: any[] = [];
+	let removedRestricted = false;
+
+	source.forEach((stage) => {
+		if (!stage || typeof stage !== 'object' || Array.isArray(stage)) {
+			return;
+		}
+
+		const keys = Object.keys(stage);
+		if (!keys.length) {
+			return;
+		}
+
+		const stageName = keys[0];
+		if (RESTRICTED_AGGREGATE_STAGES.has(String(stageName).toLowerCase())) {
+			removedRestricted = true;
+			return;
+		}
+
+		if (stageName === '$limit') {
+			sanitized.push({ $limit: normalizeAiResultLimit((stage as any).$limit, limit) });
+			return;
+		}
+
+		sanitized.push(stage);
+	});
+
+	if (!sanitized.some(stage => Object.keys(stage || {})[0] === '$limit')) {
+		sanitized.push({ $limit: limit });
+	}
+
+	return {
+		pipeline: sanitized,
+		removedRestricted
+	};
+}
+
+function sanitizeFindOptions(raw: any, fallbackLimit: number): {
+	projection?: Record<string, any>;
+	sort?: Record<string, any>;
+	limit: number;
+	skip: number;
+	includeTotal: boolean;
+} {
+	const options = normalizeAiObject(raw);
+	return {
+		projection: hasObjectKeys(options.projection) ? options.projection : undefined,
+		sort: hasObjectKeys(options.sort) ? options.sort : undefined,
+		limit: normalizeAiResultLimit(options.limit, fallbackLimit),
+		skip: normalizeAiSkip(options.skip),
+		includeTotal: options.includeTotal === true
+	};
+}
+
+function buildMongoExplorerAiNotes(
+	rawNotes: any,
+	action: MongoExplorerAiAction,
+	collection: string,
+	rowCount: number,
+	total: number | null,
+	removedRestricted: boolean
+): string {
+	const notes: string[] = [];
+	const base = normalizeOptionalString(rawNotes);
+	if (base) {
+		notes.push(base);
+	}
+
+	const actionLabel = action === 'aggregate' ? 'aggregate pipeline' : 'query';
+	if (typeof total === 'number' && total >= 0) {
+		notes.push(`Applied ${actionLabel} on ${collection}. Loaded ${rowCount} of ${total} rows.`);
+	}
+	else {
+		notes.push(`Applied ${actionLabel} on ${collection}. Loaded ${rowCount} rows.`);
+	}
+
+	if (removedRestricted) {
+		notes.push('Removed restricted write stages from the generated pipeline.');
+	}
+
+	return notes.join(' ').trim();
+}
+
+async function resolveUsageClientId(idClientInput?: string, idUser?: string): Promise<string> {
+	const normalized = normalizeOptionalString(idClientInput);
+	if (normalized) {
+		return normalized;
+	}
+	if (!idUser) {
+		return '';
+	}
+	try {
+		const user = await Users.findById(idUser);
+		return normalizeOptionalString(user?.other?.id_client || user?.other?.idClient) || '';
+	}
+	catch {
+		return '';
+	}
+}
+
+async function executeMongoExplorerAi(payload: MongoExplorerAiPayload, context: any) {
+	const input = payload || {};
+	const prompt = normalizeOptionalString(input.prompt);
+	if (!prompt) {
+		throw new Error('Prompt is required.');
+	}
+
+	const database = resolveDatabaseName(input.database);
+	const db = resolveDatabase(database);
+
+	let availableCollections = sanitizeAiCollections(input.available_collections || []);
+	if (!availableCollections.length) {
+		const listed = await db.listCollections().toArray();
+		availableCollections = listed
+			.map(collection => normalizeOptionalString(collection?.name))
+			.filter((collection): collection is string => !!collection)
+			.slice(0, MAX_AI_SUGGEST_COLLECTIONS);
+	}
+
+	if (!availableCollections.length) {
+		throw new Error('Mongo Explorer AI assistant: no collections available.');
+	}
+
+	const selectedCollection = resolveCollectionFromList(
+		input.selected_collection,
+		availableCollections,
+		availableCollections[0]
+	);
+
+	let availableFields = sanitizeAiFields(input.available_fields || [], selectedCollection);
+	if (!availableFields.length && selectedCollection) {
+		availableFields = deriveAiFieldsFromCollection(database, selectedCollection);
+	}
+
+	const settings = resolveMongoExplorerAiSettings();
+	if (!settings.apiKey) {
+		throw new Error('AI API key missing. Add an AI API key to server config.');
+	}
+
+	const maxResults = normalizeAiResultLimit(input.max_results, 100);
+	const client = buildCodexClient(settings);
+	const messages: Array<{ role: 'system' | 'user'; content: string }> = [
+		{ role: 'system', content: buildMongoExplorerAiSystemPrompt() },
+		{
+			role: 'user',
+			content: buildMongoExplorerAiUserPrompt({
+				prompt,
+				selectedCollection,
+				availableCollections,
+				availableFields,
+				maxResults
+			})
+		}
+	];
+	const responseText = await client.run(
+		buildCodexPrompt(messages[0].content, messages[1].content),
+		{
+			timeoutMs: round(settings.timeoutMs),
+			threadOptions: {
+				model: settings.model,
+				sandboxMode: 'read-only',
+				skipGitRepoCheck: true,
+				networkAccessEnabled: false,
+				webSearchMode: 'disabled',
+				webSearchEnabled: false,
+				approvalPolicy: 'never'
+			}
+		}
+	);
+
+	const parsed = parseAiPlanPayload(responseText);
+	const action = normalizeAiAction(parsed?.action || (Array.isArray(parsed?.pipeline) ? 'aggregate' : 'find'));
+	const collection = resolveCollectionFromList(
+		parsed?.collection || parsed?.collection_name,
+		availableCollections,
+		selectedCollection || availableCollections[0]
+	);
+
+	if (!collection) {
+		throw new Error('Mongo Explorer AI assistant could not resolve a collection.');
+	}
+
+	let plan: MongoExplorerAiPlan = {
+		action,
+		collection,
+		options: {}
+	};
+	let removedRestrictedStages = false;
+
+	if (action === 'aggregate') {
+		const optionsRaw = normalizeAiObject(parsed?.options);
+		const aggregateLimit = normalizeAiResultLimit(optionsRaw.limit ?? parsed?.limit, maxResults);
+		const pipelineResult = sanitizeAggregatePipeline(parsed?.pipeline, aggregateLimit);
+		removedRestrictedStages = pipelineResult.removedRestricted;
+
+		const aggregateOptions = {
+			allowDiskUse: optionsRaw.allowDiskUse === true
+		};
+
+		const aggregateRows = await db.collection(collection).aggregate(pipelineResult.pipeline, aggregateOptions).toArray();
+		const rows = (aggregateRows || []).slice(0, aggregateLimit);
+
+		plan = {
+			action,
+			collection,
+			pipeline: pipelineResult.pipeline,
+			options: {
+				allowDiskUse: aggregateOptions.allowDiskUse,
+				limit: aggregateLimit
+			},
+			documents: rows,
+			total: null
+		};
+	}
+	else {
+		const query = normalizeAiObject(parsed?.query);
+		const options = sanitizeFindOptions(parsed?.options, maxResults);
+		const findOptions: any = {
+			limit: options.limit,
+			skip: options.skip
+		};
+		if (options.projection) {
+			findOptions.projection = options.projection;
+		}
+		if (options.sort) {
+			findOptions.sort = options.sort;
+		}
+
+		const rows = await db.collection(collection).find(query, findOptions).toArray();
+		const total = options.includeTotal ? await db.collection(collection).countDocuments(query) : null;
+
+		plan = {
+			action,
+			collection,
+			query,
+			options: {
+				...(options.projection ? { projection: options.projection } : {}),
+				...(options.sort ? { sort: options.sort } : {}),
+				limit: options.limit,
+				skip: options.skip,
+				includeTotal: options.includeTotal
+			},
+			documents: rows,
+			total
+		};
+	}
+
+	plan.notes = buildMongoExplorerAiNotes(
+		parsed?.notes,
+		plan.action,
+		plan.collection,
+		Array.isArray(plan.documents) ? plan.documents.length : 0,
+		typeof plan.total === 'number' ? plan.total : null,
+		removedRestrictedStages
+	);
+
+	const usage = estimateCodexUsage(messages, responseText, settings.model);
+	const idClient = await resolveUsageClientId(input.id_client, context?.id_user);
+	if (usage.totalTokens) {
+		await recordOpenAIUsage({
+			id_client: idClient || '',
+			model: settings.model || 'unknown',
+			input_tokens: usage.inputTokens || 0,
+			output_tokens: usage.outputTokens || 0,
+			total_tokens: usage.totalTokens || 0,
+			category: 'mongo-explorer-ai',
+			id_request: ''
+		});
+	}
+
+	return {
+		notes: plan.notes,
+		plan,
+		model: settings.model,
+		usage: {
+			input_tokens: usage.inputTokens || 0,
+			output_tokens: usage.outputTokens || 0,
+			total_tokens: usage.totalTokens || 0
+		}
+	};
+}
+
+export function loadMongoExplorerMethods(methodManager: MethodManager) {
+	methodManager.methods({
+		mongoExplorerAiSuggest: {
+			check: new SimpleSchema({
+				payload: {
+					type: Object,
+					blackbox: true
+				}
+			}),
+			function: async function(payload: any) {
+				return executeMongoExplorerAi(payload || {}, this);
+			}
+		},
+		mongoExplorerListCollections: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				}
+			}),
+			function: async function(database?: string) {
+				const db = resolveDatabase(database);
+				const collections = await db.listCollections().toArray();
+				return collections
+					.map(col => ({
+						name: col.name,
+						type: col.type || 'collection'
+					}))
+					.sort((a, b) => a.name.localeCompare(b.name));
+			}
+		},
+		mongoExplorerFind: {
+			bypassSession: true,
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				query: {
+					type: Object,
+					blackbox: true,
+					optional: true
+				},
+				options: {
+					type: Object,
+					blackbox: true,
+					optional: true
+				}
+			}),
+			function: async function(database: string, collection: string, query: any = {}, options?) {
+				const db = resolveDatabase(database);
+				const normalized = normalizeFindOptions(options);
+				const documents = await db.collection(collection).find(query || {}, normalized.findOptions).toArray();
+				let total = null;
+
+				if (normalized.includeTotal) {
+					total = await db.collection(collection).countDocuments(query || {});
+				}
+
+				return {
+					documents,
+					total
+				};
+			}
+		},
+		mongoExplorerGetCollectionSchema: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				}
+			}),
+			function: function(database: string, collection: string) {
+				const dbName = resolveDatabaseName(database);
+				const { managerCollection } = resolveCollectionHandle(dbName, collection);
+				if (!managerCollection) {
+					return Promise.resolve({
+						collection,
+						has_schema: false,
+						fields: []
+					});
+				}
+
+				const schema = getSchemaDefinition(managerCollection);
+				const fields = Object.keys(schema)
+					.sort((a, b) => a.localeCompare(b))
+					.map((path) => {
+						const definition = schema[path];
+						return {
+							path,
+							label: toLabel(path),
+							type: getSchemaTypeName(definition),
+							optional: definition?.optional === true,
+							protected: isProtectedFieldPath(path),
+							depth: path.split('.').filter((segment: string) => segment !== '$').length - 1
+						};
+					});
+
+				return Promise.resolve({
+					collection,
+					has_schema: true,
+					fields
+				});
+			}
+		},
+		mongoExplorerAggregate: {
+			bypassSession: true,
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				pipeline: {
+					type: Array
+				},
+				'pipeline.$': {
+					type: Object,
+					blackbox: true
+				},
+				options: {
+					type: Object,
+					optional: true,
+					blackbox: true
+				}
+			}),
+			function: async function(database: string, collection: string, pipeline: any[], options: any = {}) {
+				const db = resolveDatabase(database);
+				return db.collection(collection).aggregate(pipeline || [], options || undefined).toArray();
+			}
+		},
+		mongoExplorerCommand: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				command: {
+					type: Object,
+					blackbox: true
+				},
+				permissionView: {
+					type: String,
+					optional: true
+				},
+				mode: {
+					type: String,
+					optional: true
+				}
+			}),
+			function: async function(database: string, command: any, permissionView?: string, mode?: string) {
+				await ensureWriteAccess(this, permissionView, mode);
+				const db = resolveDatabase(database);
+				return db.command(command);
+			}
+		},
+		mongoExplorerInsertDocument: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				document: {
+					type: Object,
+					blackbox: true
+				},
+				permissionView: {
+					type: String,
+					optional: true
+				},
+				mode: {
+					type: String,
+					optional: true
+				}
+			}),
+			function: async function(database: string, collection: string, document: any, permissionView?: string, mode?: string) {
+				await ensureWriteAccess(this, permissionView, mode);
+				const dbName = resolveDatabaseName(database);
+				const { managerCollection, dbCollection } = resolveCollectionHandle(dbName, collection);
+
+				if (!document || typeof document !== 'object') {
+					throw new Error('Mongo Explorer: Document is required');
+				}
+
+				if (!managerCollection && !allowUnschemaizedWrites()) {
+					throw new Error('Mongo Explorer: Writes require schema-backed collections. Set MONGO_EXPLORER_ALLOW_UNSCHEMATIZED_WRITE=true to bypass.');
+				}
+
+				if (!document._id) {
+					document._id = objectIdHexString();
+				}
+
+				if (document.__v === undefined) {
+					document.__v = 0;
+				}
+
+				if (managerCollection) {
+					coerceDateFields(managerCollection, document);
+					await managerCollection.insertOne(document);
+				}
+				else {
+					await dbCollection.insertOne(document);
+				}
+
+				return document._id;
+			}
+		},
+			mongoExplorerReplaceDocument: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				document: {
+					type: Object,
+					blackbox: true
+				},
+				permissionView: {
+					type: String,
+					optional: true
+				},
+				mode: {
+					type: String,
+					optional: true
+				}
+			}),
+			function: async function(database: string, collection: string, document: any, permissionView?: string, mode?: string) {
+				await ensureWriteAccess(this, permissionView, mode);
+				const dbName = resolveDatabaseName(database);
+				const { managerCollection, dbCollection } = resolveCollectionHandle(dbName, collection);
+
+				if (!document || typeof document !== 'object' || !document._id) {
+					throw new Error('Mongo Explorer: Document with _id is required');
+				}
+
+				const currentDoc = managerCollection
+					? await managerCollection.findOne({_id: document._id})
+					: await dbCollection.findOne({_id: document._id});
+				if (!currentDoc) {
+					throw new Error('Mongo Explorer: Document not found');
+				}
+
+				ensureProtectedFieldsUnchanged(currentDoc, document);
+
+				if (!managerCollection && !allowUnschemaizedWrites()) {
+					throw new Error('Mongo Explorer: Writes require schema-backed collections. Set MONGO_EXPLORER_ALLOW_UNSCHEMATIZED_WRITE=true to bypass.');
+				}
+
+				if (managerCollection) {
+					coerceDateFields(managerCollection, document);
+					await managerCollection.replaceOne({_id: document._id}, document);
+				}
+				else {
+					await dbCollection.replaceOne({_id: document._id}, document);
+				}
+
+					return true;
+				}
+			},
+			mongoExplorerReviewOperationRisk: {
+				check: new SimpleSchema({
+					database: {
+						type: String,
+						optional: true
+					},
+					collection: {
+						type: String
+					},
+					operation: {
+						type: String,
+						allowedValues: ['insert', 'replace', 'delete', 'command']
+					},
+					before_document: {
+						type: Object,
+						blackbox: true,
+						optional: true
+					},
+					after_document: {
+						type: Object,
+						blackbox: true,
+						optional: true
+					},
+					delete_impact: {
+						type: Object,
+						blackbox: true,
+						optional: true
+					},
+					permissionView: {
+						type: String,
+						optional: true
+					},
+					mode: {
+						type: String,
+						optional: true
+					}
+				}),
+				function: async function(
+					database: string,
+					collection: string,
+					operation: MongoExplorerRiskOperation,
+					before_document?: any,
+					after_document?: any,
+					delete_impact?: MongoExplorerDeleteImpact,
+					permissionView?: string,
+					mode?: string
+				) {
+					await ensureWriteAccess(this, permissionView, mode);
+					const dbName = resolveDatabaseName(database);
+
+					return reviewOperationRisk({
+						database: dbName,
+						collection,
+						operation,
+						mode: normalizeExplorerMode(mode),
+						before_document,
+						after_document,
+						delete_impact
+					});
+				}
+			},
+			mongoExplorerDeleteDocument: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				doc_id: {
+					type: String
+				},
+				permissionView: {
+					type: String,
+					optional: true
+				},
+				force: {
+					type: Boolean,
+					optional: true
+				},
+				mode: {
+					type: String,
+					optional: true
+				}
+			}),
+			function: async function(database: string, collection: string, doc_id: string, permissionView?: string, force = false, mode?: string) {
+				await ensureWriteAccess(this, permissionView, mode);
+				const dbName = resolveDatabaseName(database);
+				const impact = await buildDeleteImpact(dbName, collection, doc_id);
+				if (!force && (impact.unresolved || impact.has_references)) {
+					const collectionPreview = impact.collections.slice(0, 3).map(item => item.collection).join(', ');
+					if (impact.unresolved) {
+						throw new Error('Mongo Explorer: Delete blocked because dependency checks could not complete. Use force delete after review.');
+					}
+					throw new Error(`Mongo Explorer: Delete blocked. Document is referenced by ${collectionPreview}${impact.collections.length > 3 ? ', ...' : ''}`);
+				}
+
+				const { managerCollection, dbCollection } = resolveCollectionHandle(dbName, collection);
+				const deleteFilter = { _id: doc_id } as any;
+
+				if (managerCollection) {
+					await managerCollection.deleteOne(deleteFilter);
+				}
+				else {
+					await dbCollection.deleteOne(deleteFilter);
+				}
+
+				return true;
+			}
+		},
+		mongoExplorerDeleteImpact: {
+			check: new SimpleSchema({
+				database: {
+					type: String,
+					optional: true
+				},
+				collection: {
+					type: String
+				},
+				doc_id: {
+					type: String
+				}
+			}),
+			function: async function(database: string, collection: string, doc_id: string) {
+				const dbName = resolveDatabaseName(database);
+				return buildDeleteImpact(dbName, collection, doc_id);
+			}
+		}
+	});
+}