@danielsimonjr/memory-mcp 11.1.0 → 12.2.3

package/dist/server/toolHandlers.js

@@ -1,15 +1,89 @@
 /**
  * MCP Tool Handlers
  *
- * Contains handler functions for all 59 Knowledge Graph tools.
+ * Contains handler functions for all 137 Knowledge Graph tools.
  * Handlers call managers directly via ManagerContext.
  * All core functionality is imported from @danielsimonjr/memoryjs.
  *
  * @module server/toolHandlers
  */
-import { formatToolResponse, formatTextResponse, formatRawResponse, validateWithSchema, validateFilePath, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, AddObservationsInputSchema, DeleteObservationsInputSchema, ArchiveCriteriaSchema, SavedSearchInputSchema, SavedSearchUpdateSchema, ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, SearchQuerySchema, HybridSearchManager, QueryAnalyzer, QueryPlanner, ReflectionManager, ObservationNormalizer, } from '@danielsimonjr/memoryjs';
+import path from 'node:path';
+import { formatToolResponse, formatTextResponse, formatRawResponse, validateWithSchema, validateFilePath, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, AddObservationsInputSchema, DeleteObservationsInputSchema, ArchiveCriteriaSchema, SavedSearchInputSchema, SavedSearchUpdateSchema, ImportFormatSchema, ExtendedExportFormatSchema, MergeStrategySchema, ExportFilterSchema, SearchQuerySchema, HybridSearchManager, QueryAnalyzer, QueryPlanner, ReflectionManager, ObservationNormalizer, RefIndex, AuditLog, GovernanceManager, FreshnessManager, ArtifactManager, CollaborativeSynthesis, FailureDistillation, CognitiveLoadAnalyzer, ConsolidationScheduler, DreamEngine, DistillationPipeline, DefaultDistillationPolicy, NoOpDistillationPolicy, computeEntropy, passesEntropyFilter, EntropyFilterStage, getRoleProfile, listRoleProfiles, QueryCostEstimator, ContradictionDetector, PiiRedactor, } from '@danielsimonjr/memoryjs';
 import { z } from 'zod';
 import { maybeCompressResponse } from './responseCompressor.js';
+// ==================== SINGLETON INFRASTRUCTURE ====================
+// WeakMap-based singletons keyed on ManagerContext to avoid re-instantiation per request.
+// These managers are not on ManagerContext directly, so we wire them up once per ctx.
+const refIndexMap = new WeakMap();
+const auditLogMap = new WeakMap();
+const governanceMap = new WeakMap();
+const freshnessMap = new WeakMap();
+const artifactManagerMap = new WeakMap();
+const distillationPipelineMap = new WeakMap();
+const failureDistillationMap = new WeakMap();
+const consolidationSchedulerMap = new WeakMap();
+const dreamEngineMap = new WeakMap();
+const queryCostEstimatorMap = new WeakMap();
+function getStorageFilePath(ctx) {
+    // GraphStorage exposes filePath publicly; fall back to cwd-relative default
+    return ctx.storage.filePath ?? 'memory.jsonl';
+}
+function getRefIndex(ctx) {
+    if (!refIndexMap.has(ctx)) {
+        const storagePath = getStorageFilePath(ctx);
+        const dir = path.dirname(storagePath);
+        refIndexMap.set(ctx, new RefIndex(path.join(dir, 'memory-ref-index.jsonl')));
+    }
+    return refIndexMap.get(ctx);
+}
+function getAuditLog(ctx) {
+    if (!auditLogMap.has(ctx)) {
+        const storagePath = getStorageFilePath(ctx);
+        const dir = path.dirname(storagePath);
+        auditLogMap.set(ctx, new AuditLog(path.join(dir, 'memory-audit.jsonl')));
+    }
+    return auditLogMap.get(ctx);
+}
+function getGovernanceManager(ctx) {
+    if (!governanceMap.has(ctx)) {
+        // GovernanceManager constructor accepts GraphStorage; ctx.storage is GraphStorage
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        governanceMap.set(ctx, new GovernanceManager(ctx.storage, getAuditLog(ctx)));
+    }
+    return governanceMap.get(ctx);
+}
+function getFreshnessManager(ctx) {
+    if (!freshnessMap.has(ctx)) {
+        freshnessMap.set(ctx, new FreshnessManager(ctx.storage));
+    }
+    return freshnessMap.get(ctx);
+}
+function getArtifactManager(ctx) {
+    if (!artifactManagerMap.has(ctx)) {
+        const refIndex = getRefIndex(ctx);
+        // EntityManager.registerRef() requires setRefIndex to be called first.
+        ctx.entityManager.setRefIndex(refIndex);
+        artifactManagerMap.set(ctx, new ArtifactManager(ctx.storage, ctx.entityManager, refIndex));
+    }
+    return artifactManagerMap.get(ctx);
+}
+function getDistillationPipeline(ctx) {
+    if (!distillationPipelineMap.has(ctx)) {
+        distillationPipelineMap.set(ctx, new DistillationPipeline());
+    }
+    return distillationPipelineMap.get(ctx);
+}
+function getFailureDistillation(ctx) {
+    if (!failureDistillationMap.has(ctx)) {
+        failureDistillationMap.set(ctx, new FailureDistillation(ctx.storage));
+    }
+    return failureDistillationMap.get(ctx);
+}
+/** Simple token estimator: ~4 chars per token */
+function estimateTokens(entity) {
+    const text = [entity.name, entity.entityType, ...entity.observations].join(' ');
+    return Math.ceil(text.length / 4);
+}
 /**
  * Wrapper to apply automatic response compression for large tool responses.
  *
@@ -69,6 +143,37 @@ export const toolHandlers = {
             : [];
         return withCompression(async () => formatToolResponse(await ctx.searchManager.openNodes(names)));
     },
+    // Phase 13: Project scoping + memory versioning
+    list_projects: async (ctx, _args) => {
+        const projects = await ctx.entityManager.listProjects();
+        return formatToolResponse({ projects, count: projects.length });
+    },
+    get_entity_versions: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const latest = await ctx.entityManager.getLatestVersion(entityName);
+        if (!latest) {
+            return { content: [{ type: 'text', text: `Entity '${entityName}' not found` }], isError: true };
+        }
+        return formatToolResponse(latest);
+    },
+    get_version_chain: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const chain = await ctx.entityManager.getVersionChain(entityName);
+        if (chain.length === 0) {
+            return { content: [{ type: 'text', text: `Entity '${entityName}' not found` }], isError: true };
+        }
+        return formatToolResponse({
+            rootEntity: chain[0]?.name ?? null,
+            latestEntity: chain.find(e => e.isLatest !== false)?.name ?? null,
+            versions: chain.map(e => ({
+                name: e.name,
+                version: e.version ?? 1,
+                isLatest: e.isLatest !== false,
+                observations: e.observations,
+            })),
+            count: chain.length,
+        });
+    },
     // ==================== RELATION HANDLERS ====================
     create_relations: async (ctx, args) => {
         const relations = validateWithSchema(args.relations, BatchCreateRelationsSchema, 'Invalid relations data');
@@ -79,6 +184,49 @@ export const toolHandlers = {
         await ctx.relationManager.deleteRelations(relations);
         return formatTextResponse(`Deleted ${relations.length} relations`);
     },
+    // Phase 13: Temporal knowledge graph
+    invalidate_relation: async (ctx, args) => {
+        try {
+            const from = validateWithSchema(args.from, z.string().min(1), 'Invalid from');
+            const relationType = validateWithSchema(args.relationType, z.string().min(1), 'Invalid relationType');
+            const to = validateWithSchema(args.to, z.string().min(1), 'Invalid to');
+            const ended = args.ended !== undefined ? validateWithSchema(args.ended, z.string(), 'Invalid ended') : undefined;
+            await ctx.relationManager.invalidateRelation(from, relationType, to, ended);
+            return formatTextResponse(`Invalidated: ${from} -[${relationType}]-> ${to} (ended: ${ended ?? 'now'})`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: msg }], isError: true };
+        }
+    },
+    query_as_of: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const asOf = validateWithSchema(args.asOf, z.string().min(1), 'Invalid asOf');
+        const direction = args.direction !== undefined
+            ? validateWithSchema(args.direction, z.enum(['outgoing', 'incoming', 'both']), 'Invalid direction')
+            : undefined;
+        const relations = await ctx.relationManager.queryAsOf(entityName, asOf, { direction });
+        return formatToolResponse({ entity: entityName, asOf, relations, count: relations.length });
+    },
+    timeline: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const direction = args.direction !== undefined
+            ? validateWithSchema(args.direction, z.enum(['outgoing', 'incoming', 'both']), 'Invalid direction')
+            : undefined;
+        const relations = await ctx.relationManager.timeline(entityName, { direction });
+        return formatToolResponse({
+            entity: entityName,
+            timeline: relations.map(r => ({
+                from: r.from,
+                relationType: r.relationType,
+                to: r.to,
+                validFrom: r.properties?.validFrom ?? null,
+                validUntil: r.properties?.validUntil ?? null,
+                current: r.properties?.validUntil === undefined,
+            })),
+            count: relations.length,
+        });
+    },
     // ==================== OBSERVATION HANDLERS ====================
     add_observations: async (ctx, args) => {
         const observations = validateWithSchema(args.observations, AddObservationsInputSchema, 'Invalid observations data');
@@ -187,6 +335,18 @@ export const toolHandlers = {
         const limit = args.limit !== undefined ? validateWithSchema(args.limit, z.number().int().positive().max(200), 'Invalid limit') : undefined;
         return formatToolResponse(await ctx.searchManager.autoSearch(query, limit));
     },
+    // Phase 13: Semantic forget
+    forget_memory: async (ctx, args) => {
+        const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
+        const threshold = args.threshold !== undefined ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold') : undefined;
+        const projectId = args.projectId !== undefined ? validateWithSchema(args.projectId, z.string(), 'Invalid projectId') : undefined;
+        const dryRun = args.dryRun === true;
+        const result = await ctx.semanticForget.forgetByContent(content, { threshold, projectId, dryRun });
+        if (result.method === 'not_found') {
+            return formatTextResponse(`No matching memory found for: "${content}". Try a different search term.`);
+        }
+        return formatToolResponse(result);
+    },
     // Phase 11 Sprint 2: Hybrid search
     hybrid_search: async (ctx, args) => {
         const query = validateWithSchema(args.query, SearchQuerySchema, 'Invalid search query');
@@ -532,6 +692,22 @@ export const toolHandlers = {
         const dryRun = args.dryRun !== undefined ? validateWithSchema(args.dryRun, z.boolean(), 'Invalid dryRun value') : undefined;
         return formatToolResponse(await ctx.ioManager.importGraph(format, data, mergeStrategy, dryRun));
     },
+    // Phase 13: Conversation ingestion
+    ingest: async (ctx, args) => {
+        if (!args.messages || args.messages.length === 0) {
+            return formatTextResponse('No messages provided. At least one message is required.');
+        }
+        const messages = validateWithSchema(args.messages, z.array(z.object({ role: z.enum(['user', 'assistant', 'system']), content: z.string(), timestamp: z.string().optional() })), 'Invalid messages');
+        const source = args.source !== undefined ? validateWithSchema(args.source, z.string(), 'Invalid source') : undefined;
+        const projectId = args.projectId !== undefined ? validateWithSchema(args.projectId, z.string(), 'Invalid projectId') : undefined;
+        const tags = args.tags !== undefined ? validateWithSchema(args.tags, z.array(z.string()), 'Invalid tags') : undefined;
+        const chunkBy = args.chunkBy !== undefined
+            ? validateWithSchema(args.chunkBy, z.enum(['exchange', 'paragraph', 'fixed']), 'Invalid chunkBy')
+            : undefined;
+        const dryRun = args.dryRun === true;
+        const result = await ctx.ioManager.ingest({ messages, source }, { projectId, tags, chunkBy, dryRun });
+        return formatToolResponse(result);
+    },
     export_graph: async (ctx, args) => {
         const format = validateWithSchema(args.format, ExtendedExportFormatSchema, 'Invalid export format');
         const filter = args.filter !== undefined ? validateWithSchema(args.filter, ExportFilterSchema, 'Invalid export filter') : undefined;
@@ -540,6 +716,7 @@ export const toolHandlers = {
             ? validateWithSchema(args.compressionQuality, z.number().int().min(0).max(11), 'Invalid compression quality (must be 0-11)')
             : undefined;
         const streaming = args.streaming !== undefined ? validateWithSchema(args.streaming, z.boolean(), 'Invalid streaming value') : undefined;
+        const redactPii = args.redactPii !== undefined ? validateWithSchema(args.redactPii, z.boolean(), 'Invalid redactPii value') : false;
         const rawOutputPath = args.outputPath !== undefined ? validateWithSchema(args.outputPath, z.string(), 'Invalid outputPath value') : undefined;
         // Validate outputPath to prevent path traversal attacks
         const outputPath = rawOutputPath !== undefined ? validateFilePath(rawOutputPath) : undefined;
@@ -551,6 +728,10 @@ export const toolHandlers = {
         else {
             graph = await ctx.storage.loadGraph();
         }
+        // η.6.3 — apply PII redactor on export when requested
+        if (redactPii) {
+            graph = new PiiRedactor().redactGraph(graph);
+        }
         // Export with optional compression and streaming
         const result = await ctx.ioManager.exportGraphWithCompression(graph, format, {
             filter,
@@ -655,6 +836,1067 @@ export const toolHandlers = {
             stats: semanticSearch.getStats(),
         });
     },
+    // ==================== REF INDEX HANDLERS ====================
+    register_ref: async (ctx, args) => {
+        const ref = validateWithSchema(args.ref, z.string().min(1), 'Invalid ref');
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const description = args.description !== undefined
+            ? validateWithSchema(args.description, z.string(), 'Invalid description')
+            : undefined;
+        const entry = await getRefIndex(ctx).register(ref, entityName, description);
+        return formatToolResponse(entry);
+    },
+    resolve_ref: async (ctx, args) => {
+        const ref = validateWithSchema(args.ref, z.string().min(1), 'Invalid ref');
+        const entityName = await getRefIndex(ctx).resolve(ref);
+        if (entityName === null) {
+            return formatTextResponse(`Ref "${ref}" is not registered`);
+        }
+        return formatToolResponse({ ref, entityName });
+    },
+    deregister_ref: async (ctx, args) => {
+        const ref = validateWithSchema(args.ref, z.string().min(1), 'Invalid ref');
+        await getRefIndex(ctx).deregister(ref);
+        return formatTextResponse(`Ref "${ref}" deregistered`);
+    },
+    list_refs: async (ctx, args) => {
+        const entityName = args.entityName !== undefined
+            ? validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName')
+            : undefined;
+        const refs = await getRefIndex(ctx).listRefs(entityName ? { entityName } : undefined);
+        return formatToolResponse({ refs, count: refs.length });
+    },
+    // ==================== ARTIFACT HANDLERS ====================
+    create_artifact: async (ctx, args) => {
+        const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
+        const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
+        const artifactType = validateWithSchema(args.artifactType, z.enum(['tool_output', 'code_snippet', 'api_response', 'search_result', 'file_content', 'user_input']), 'Invalid artifactType');
+        const description = args.description !== undefined
+            ? validateWithSchema(args.description, z.string(), 'Invalid description')
+            : undefined;
+        const sessionId = args.sessionId !== undefined
+            ? validateWithSchema(args.sessionId, z.string(), 'Invalid sessionId')
+            : undefined;
+        const artifact = await getArtifactManager(ctx).createArtifact({
+            content,
+            toolName,
+            artifactType,
+            description,
+            sessionId,
+        });
+        return formatToolResponse(artifact);
+    },
+    get_artifact: async (ctx, args) => {
+        const ref = validateWithSchema(args.ref, z.string().min(1), 'Invalid ref');
+        const artifact = await getArtifactManager(ctx).getArtifact(ref);
+        if (!artifact) {
+            return formatTextResponse(`Artifact "${ref}" not found`);
+        }
+        return formatToolResponse(artifact);
+    },
+    list_artifacts: async (ctx, args) => {
+        const filter = {};
+        if (args.toolName !== undefined) {
+            filter.toolName = validateWithSchema(args.toolName, z.string(), 'Invalid toolName');
+        }
+        if (args.artifactType !== undefined) {
+            filter.artifactType = validateWithSchema(args.artifactType, z.enum(['tool_output', 'code_snippet', 'api_response', 'search_result', 'file_content', 'user_input']), 'Invalid artifactType');
+        }
+        if (args.since !== undefined) {
+            const sinceStr = validateWithSchema(args.since, z.string().regex(/^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]+)?$/, 'since must be an ISO 8601 date string'), 'Invalid since');
+            const sinceDate = new Date(sinceStr);
+            if (isNaN(sinceDate.getTime())) {
+                throw new Error(`Invalid since date: "${sinceStr}" is not a valid date`);
+            }
+            filter.since = sinceDate;
+        }
+        const artifacts = await getArtifactManager(ctx).listArtifacts(Object.keys(filter).length > 0 ? filter : undefined);
+        return formatToolResponse({ artifacts, count: artifacts.length });
+    },
+    // ==================== TEMPORAL SEARCH HANDLER ====================
+    search_by_time: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const options = {};
+        if (args.field !== undefined) {
+            options.field = validateWithSchema(args.field, z.enum(['createdAt', 'lastModified', 'any']), 'Invalid field');
+        }
+        if (args.includeUndated !== undefined) {
+            options.includeUndated = validateWithSchema(args.includeUndated, z.boolean(), 'Invalid includeUndated');
+        }
+        const entities = await ctx.searchManager.searchByTime(query, options);
+        return formatToolResponse({ query, entities, count: entities.length });
+    },
+    // ==================== DISTILLATION HANDLER ====================
+    configure_distillation: async (ctx, args) => {
+        const policy = validateWithSchema(args.policy, z.enum(['default', 'noop', 'none']), 'Invalid policy');
+        const pipeline = getDistillationPipeline(ctx);
+        pipeline.clearPolicies();
+        if (policy === 'default') {
+            pipeline.addPolicy(new DefaultDistillationPolicy(), 'default');
+        }
+        else if (policy === 'noop') {
+            pipeline.addPolicy(new NoOpDistillationPolicy(), 'noop');
+        }
+        // 'none' clears all policies — passthrough behavior
+        return formatTextResponse(`Distillation pipeline configured with policy: "${policy}" (${pipeline.policyCount} policies active)`);
+    },
+    // ==================== FRESHNESS HANDLERS ====================
+    check_freshness: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const graph = await ctx.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            return formatTextResponse(`Entity "${entityName}" not found`);
+        }
+        const fm = getFreshnessManager(ctx);
+        const annotated = fm.annotateEntity(entity);
+        return formatToolResponse({
+            entityName,
+            freshnessScore: fm.calculateFreshness(entity),
+            expiresAt: fm.computeExpiresAt(entity),
+            isExpired: fm.isExpired(entity),
+            annotated,
+        });
+    },
+    get_stale_entities: async (ctx, args) => {
+        const threshold = args.threshold !== undefined
+            ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold (0-1)')
+            : undefined;
+        const fm = getFreshnessManager(ctx);
+        const stale = await fm.getStaleEntities(ctx.storage, threshold);
+        return formatToolResponse({ entities: stale, count: stale.length });
+    },
+    get_expired_entities: async (ctx) => {
+        const fm = getFreshnessManager(ctx);
+        const expired = await fm.getExpiredEntities(ctx.storage);
+        return formatToolResponse({ entities: expired, count: expired.length });
+    },
+    refresh_entity: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const fm = getFreshnessManager(ctx);
+        const updated = await fm.refreshEntity(entityName, ctx.storage);
+        return formatToolResponse({ updated, freshnessScore: fm.calculateFreshness(updated) });
+    },
+    freshness_report: async (ctx, args) => {
+        const threshold = args.threshold !== undefined
+            ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold (0-1)')
+            : undefined;
+        const fm = getFreshnessManager(ctx);
+        const report = await fm.generateReport(ctx.storage, threshold);
+        return formatToolResponse(report);
+    },
+    // ==================== LLM QUERY PLANNER HANDLER ====================
+    query_natural_language: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const entities = await ctx.queryNaturalLanguage(query);
+        return formatToolResponse({ query, entities, count: entities.length });
+    },
+    // ==================== GOVERNANCE HANDLERS ====================
+    set_governance_policy: async (ctx, args) => {
+        const gm = getGovernanceManager(ctx);
+        // GovernancePolicy uses function callbacks; we translate boolean args into allow/deny functions
+        const allowCreate = args.canCreate !== undefined
+            ? validateWithSchema(args.canCreate, z.boolean(), 'Invalid canCreate')
+            : true;
+        const allowUpdate = args.canUpdate !== undefined
+            ? validateWithSchema(args.canUpdate, z.boolean(), 'Invalid canUpdate')
+            : true;
+        const allowDelete = args.canDelete !== undefined
+            ? validateWithSchema(args.canDelete, z.boolean(), 'Invalid canDelete')
+            : true;
+        gm.setPolicy({
+            canCreate: allowCreate ? undefined : () => false,
+            canUpdate: allowUpdate ? undefined : () => false,
+            canDelete: allowDelete ? undefined : () => false,
+        });
+        return formatTextResponse(`Governance policy set: canCreate=${allowCreate}, canUpdate=${allowUpdate}, canDelete=${allowDelete}`);
+    },
+    audit_query: async (ctx, args) => {
+        const filter = {};
+        if (args.operation !== undefined) {
+            filter.operation = validateWithSchema(args.operation, z.enum(['create', 'update', 'delete', 'merge', 'archive']), 'Invalid operation');
+        }
+        if (args.agentId !== undefined) {
+            filter.agentId = validateWithSchema(args.agentId, z.string(), 'Invalid agentId');
+        }
+        if (args.entityName !== undefined) {
+            filter.entityName = validateWithSchema(args.entityName, z.string(), 'Invalid entityName');
+        }
+        // AuditFilter uses fromTime/toTime (not since/until)
+        if (args.since !== undefined) {
+            filter.fromTime = validateWithSchema(args.since, z.string(), 'Invalid since');
+        }
+        if (args.until !== undefined) {
+            filter.toTime = validateWithSchema(args.until, z.string(), 'Invalid until');
+        }
+        const limit = args.limit !== undefined
+            ? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')
+            : 50;
+        const al = getAuditLog(ctx);
+        let entries = await al.query(filter);
+        entries = entries.slice(0, limit);
+        return formatToolResponse({ entries, count: entries.length });
+    },
+    audit_history: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const al = getAuditLog(ctx);
+        const entries = await al.getHistory(entityName);
+        return formatToolResponse({ entityName, entries, count: entries.length });
+    },
+    rollback_operation: async (ctx, args) => {
+        const auditEntryId = validateWithSchema(args.auditEntryId, z.string().min(1), 'Invalid auditEntryId');
+        const gm = getGovernanceManager(ctx);
+        await gm.rollback(auditEntryId);
+        return formatTextResponse(`Operation "${auditEntryId}" rolled back successfully`);
+    },
+    // ==================== ROLE PROFILE HANDLERS ====================
+    set_agent_role: async (_ctx, args) => {
+        const role = validateWithSchema(args.role, z.enum(['researcher', 'planner', 'executor', 'reviewer', 'default']), 'Invalid role');
+        const profile = getRoleProfile(role);
+        return formatToolResponse({
+            role,
+            label: profile.label,
+            salienceConfig: profile.salienceConfig,
+            contextConfig: profile.contextConfig,
+            message: `Role profile "${role}" retrieved. Apply salienceConfig and contextConfig to your agent memory system.`,
+        });
+    },
+    list_role_profiles: async (_ctx) => {
+        const profiles = listRoleProfiles();
+        return formatToolResponse({ profiles, count: profiles.length });
+    },
+    // ==================== ENTROPY FILTER HANDLERS ====================
+    enable_entropy_filter: async (ctx, args) => {
+        const enabled = validateWithSchema(args.enabled, z.boolean(), 'Invalid enabled');
+        const minEntropy = args.minEntropy !== undefined
+            ? validateWithSchema(args.minEntropy, z.number().min(0), 'Invalid minEntropy')
+            : 1.5;
+        const minLength = args.minLength !== undefined
+            ? validateWithSchema(args.minLength, z.number().int().min(0), 'Invalid minLength')
+            : 10;
+        // Register (or clear) the entropy filter stage on the agent memory facade's pipeline
+        const agentMem = ctx.agentMemory();
+        const pipeline = agentMem.consolidationPipeline;
+        if (enabled) {
+            const stage = new EntropyFilterStage({ minEntropy, minLength });
+            pipeline.registerStage(stage);
+            return formatTextResponse(`Entropy filter enabled (minEntropy=${minEntropy}, minLength=${minLength}). Stage registered on consolidation pipeline.`);
+        }
+        else {
+            return formatTextResponse('Entropy filter disabled. No new entropy-filter stage will be registered on the consolidation pipeline.');
+        }
+    },
+    compute_entropy: async (_ctx, args) => {
+        const text = validateWithSchema(args.text, z.string(), 'Invalid text');
+        const entropy = computeEntropy(text);
+        const result = { text: text.length > 100 ? text.slice(0, 100) + '...' : text, entropy };
+        if (args.minEntropy !== undefined) {
+            const minEntropy = validateWithSchema(args.minEntropy, z.number().min(0), 'Invalid minEntropy');
+            result.minEntropy = minEntropy;
+            result.passes = passesEntropyFilter(text, minEntropy);
+        }
+        return formatToolResponse(result);
+    },
+    // ==================== CONSOLIDATION HANDLERS ====================
+    start_consolidation: async (ctx, args) => {
+        const intervalMs = args.intervalMs !== undefined
+            ? validateWithSchema(args.intervalMs, z.number().int().min(1000), 'Invalid intervalMs')
+            : undefined;
+        const autoMergeDuplicates = args.autoMergeDuplicates !== undefined
+            ? validateWithSchema(args.autoMergeDuplicates, z.boolean(), 'Invalid autoMergeDuplicates')
+            : undefined;
+        // Prefer ctx.consolidationScheduler (set via MEMORY_AUTO_CONSOLIDATION env var).
+        // Otherwise use the per-ctx singleton so stop/run_now can retrieve the same instance.
+        let scheduler = ctx.consolidationScheduler ?? consolidationSchedulerMap.get(ctx);
+        if (!scheduler) {
+            const agentMem = ctx.agentMemory();
+            scheduler = new ConsolidationScheduler(agentMem.consolidationPipeline, ctx.compressionManager, {
+                consolidationIntervalMs: intervalMs,
+                autoMergeDuplicates: autoMergeDuplicates,
+            });
+            consolidationSchedulerMap.set(ctx, scheduler);
+        }
+        scheduler.start();
+        return formatTextResponse(`Consolidation scheduler started (interval: ${scheduler.getInterval()}ms, autoMerge: ${scheduler.getConfig().autoMergeDuplicates})`);
+    },
+    stop_consolidation: async (ctx) => {
+        const scheduler = ctx.consolidationScheduler ?? consolidationSchedulerMap.get(ctx);
+        if (!scheduler) {
+            return formatTextResponse('No active consolidation scheduler found. Start one first with start_consolidation.');
+        }
+        scheduler.stop();
+        return formatTextResponse('Consolidation scheduler stopped');
+    },
+    run_consolidation_now: async (ctx) => {
+        // Use ctx.consolidationScheduler or the per-ctx singleton if available,
+        // otherwise create a temporary scheduler just for this one run.
+        let scheduler = ctx.consolidationScheduler ?? consolidationSchedulerMap.get(ctx);
+        if (!scheduler) {
+            const agentMem = ctx.agentMemory();
+            scheduler = new ConsolidationScheduler(agentMem.consolidationPipeline, ctx.compressionManager);
+        }
+        const result = await scheduler.runNow();
+        return formatToolResponse(result);
+    },
+    // ==================== DREAM ENGINE HANDLERS ====================
+    dream_start: async (ctx, args) => {
+        const intervalMs = args.intervalMs !== undefined
+            ? validateWithSchema(args.intervalMs, z.number().int().min(1000), 'Invalid intervalMs')
+            : undefined;
+        const runOnSessionEnd = args.runOnSessionEnd !== undefined
+            ? validateWithSchema(args.runOnSessionEnd, z.boolean(), 'Invalid runOnSessionEnd')
+            : undefined;
+        const maxDurationMs = args.maxDurationMs !== undefined
+            ? validateWithSchema(args.maxDurationMs, z.number().int().min(1000), 'Invalid maxDurationMs')
+            : undefined;
+        const phases = args.phases !== undefined
+            ? validateWithSchema(args.phases, z.object({
+                temporalAnchoring: z.boolean().optional(),
+                freshnessSweep: z.boolean().optional(),
+                entropyPruning: z.boolean().optional(),
+                consolidation: z.boolean().optional(),
+                compression: z.boolean().optional(),
+                entityEnrichment: z.boolean().optional(),
+                patternPromotion: z.boolean().optional(),
+                graphHygiene: z.boolean().optional(),
+            }), 'Invalid phases')
+            : undefined;
+        let engine = dreamEngineMap.get(ctx);
+        if (!engine) {
+            const agentMem = ctx.agentMemory();
+            const config = {
+                ...(intervalMs !== undefined && { intervalMs }),
+                ...(runOnSessionEnd !== undefined && { runOnSessionEnd }),
+                ...(maxDurationMs !== undefined && { maxDurationMs }),
+                ...(phases !== undefined && { phases }),
+            };
+            engine = new DreamEngine(ctx.storage, agentMem.consolidationPipeline, config);
+            dreamEngineMap.set(ctx, engine);
+        }
+        engine.start();
+        return formatTextResponse('DreamEngine started — background memory maintenance active');
+    },
+    dream_stop: async (ctx) => {
+        const engine = dreamEngineMap.get(ctx);
+        if (!engine) {
+            return formatTextResponse('No active DreamEngine found. Start one first with dream_start.');
+        }
+        engine.stop();
+        return formatTextResponse('DreamEngine stopped');
+    },
+    dream_run_now: async (ctx, args) => {
+        const phases = args.phases !== undefined
+            ? validateWithSchema(args.phases, z.object({
+                temporalAnchoring: z.boolean().optional(),
+                freshnessSweep: z.boolean().optional(),
+                entropyPruning: z.boolean().optional(),
+                consolidation: z.boolean().optional(),
+                compression: z.boolean().optional(),
+                entityEnrichment: z.boolean().optional(),
+                patternPromotion: z.boolean().optional(),
+                graphHygiene: z.boolean().optional(),
+            }), 'Invalid phases')
+            : undefined;
+        // Use the per-ctx singleton if available, otherwise create a one-off engine.
+        let engine = dreamEngineMap.get(ctx);
+        if (!engine) {
+            const agentMem = ctx.agentMemory();
+            const config = {
+                ...(phases !== undefined && { phases }),
+            };
+            engine = new DreamEngine(ctx.storage, agentMem.consolidationPipeline, config);
+        }
+        const result = await engine.runDreamCycle();
+        return formatToolResponse(result);
+    },
+    // ==================== MEMORY FORMATTER HANDLER ====================
+    format_with_salience_budget: async (ctx, args) => {
+        const entityNames = validateWithSchema(args.entityNames, z.array(z.string().min(1)), 'Invalid entityNames');
+        const salienceScoresRaw = validateWithSchema(args.salienceScores, z.record(z.string(), z.number()), 'Invalid salienceScores');
+        const totalTokenBudget = validateWithSchema(args.totalTokenBudget, z.number().int().min(1), 'Invalid totalTokenBudget');
+        const header = args.header !== undefined
+            ? validateWithSchema(args.header, z.string(), 'Invalid header')
+            : undefined;
+        const separator = args.separator !== undefined
+            ? validateWithSchema(args.separator, z.string(), 'Invalid separator')
+            : undefined;
+        const graph = await ctx.storage.loadGraph();
+        const memories = graph.entities.filter(e => entityNames.includes(e.name));
+        const salienceScores = new Map(Object.entries(salienceScoresRaw));
+        const formatted = ctx.memoryFormatter.formatWithSalienceBudget(memories, salienceScores, totalTokenBudget, { header, separator });
+        return formatTextResponse(formatted);
+    },
+    // ==================== COLLABORATIVE SYNTHESIS HANDLER ====================
+    synthesize_collaborative_context: async (ctx, args) => {
+        const seedEntityName = validateWithSchema(args.seedEntityName, z.string().min(1), 'Invalid seedEntityName');
+        const config = {};
+        if (args.maxDepth !== undefined) {
+            config.maxDepth = validateWithSchema(args.maxDepth, z.number().int().min(1).max(10), 'Invalid maxDepth');
+        }
+        if (args.minNeighborSalience !== undefined) {
+            config.minNeighborSalience = validateWithSchema(args.minNeighborSalience, z.number().min(0).max(1), 'Invalid minNeighborSalience');
+        }
+        if (args.maxNeighbors !== undefined) {
+            config.maxNeighbors = validateWithSchema(args.maxNeighbors, z.number().int().min(1).max(100), 'Invalid maxNeighbors');
+        }
+        const salienceContext = {};
+        if (args.queryText !== undefined) {
+            salienceContext.queryText = validateWithSchema(args.queryText, z.string(), 'Invalid queryText');
+        }
+        if (args.currentTask !== undefined) {
+            salienceContext.currentTask = validateWithSchema(args.currentTask, z.string(), 'Invalid currentTask');
+        }
+        const synthesis = new CollaborativeSynthesis(ctx.storage, ctx.graphTraversal, ctx.salienceEngine, config);
+        return withCompression(async () => {
+            const result = await synthesis.synthesize(seedEntityName, Object.keys(salienceContext).length > 0 ? salienceContext : undefined);
+            return formatToolResponse(result);
+        });
+    },
+    // ==================== FAILURE DISTILLATION HANDLERS ====================
+    distill_failure: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const config = {};
+        if (args.minLessonConfidence !== undefined) {
+            config.minLessonConfidence = validateWithSchema(args.minLessonConfidence, z.number().min(0).max(1), 'Invalid minLessonConfidence');
+        }
+        if (args.maxCauseChainLength !== undefined) {
+            config.maxCauseChainLength = validateWithSchema(args.maxCauseChainLength, z.number().int().min(1).max(20), 'Invalid maxCauseChainLength');
+        }
+        const fd = Object.keys(config).length > 0
+            ? new FailureDistillation(ctx.storage, config)
+            : getFailureDistillation(ctx);
+        const result = await fd.distillFromSession(sessionId);
+        return formatToolResponse(result);
+    },
+    end_session: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const outcome = validateWithSchema(args.outcome, z.enum(['success', 'failure', 'partial']), 'Invalid outcome');
+        const distillFailures = args.distillFailures !== undefined
+            ? validateWithSchema(args.distillFailures, z.boolean(), 'Invalid distillFailures')
+            : true;
+        const graph = await ctx.storage.loadGraph();
+        const sessionEntity = graph.entities.find(e => e.name === sessionId);
+        if (!sessionEntity) {
+            return formatTextResponse(`Session "${sessionId}" not found`);
+        }
+        // Update session outcome
+        const updatedEntities = graph.entities.map(e => e.name === sessionId
+            ? { ...e, observations: [...e.observations, `outcome: ${outcome}`], lastModified: new Date().toISOString() }
+            : e);
+        await ctx.storage.saveGraph({ entities: updatedEntities, relations: [...graph.relations] });
+        let distillationResult = null;
+        if (outcome === 'failure' && distillFailures) {
+            const fd = getFailureDistillation(ctx);
+            distillationResult = await fd.distillFromSession(sessionId);
+        }
+        return formatToolResponse({
+            sessionId,
+            outcome,
+            distillationResult,
+            message: `Session "${sessionId}" ended with outcome: ${outcome}`,
+        });
+    },
+    // ==================== COGNITIVE LOAD HANDLERS ====================
+    analyze_cognitive_load: async (ctx, args) => {
+        const entityNames = validateWithSchema(args.entityNames, z.array(z.string().min(1)), 'Invalid entityNames');
+        const loadThreshold = args.loadThreshold !== undefined
+            ? validateWithSchema(args.loadThreshold, z.number().min(0).max(1), 'Invalid loadThreshold')
+            : undefined;
+        const graph = await ctx.storage.loadGraph();
+        const memories = graph.entities.filter((e) => entityNames.includes(e.name));
+        if (memories.length === 0) {
+            return formatTextResponse('No entities found matching the provided names');
+        }
+        const analyzer = new CognitiveLoadAnalyzer(loadThreshold ? { loadThreshold } : undefined);
+        const metrics = analyzer.computeMetrics(memories, estimateTokens);
+        return formatToolResponse({ entityCount: memories.length, metrics });
+    },
+    adaptive_reduce_memories: async (ctx, args) => {
+        const entityNames = validateWithSchema(args.entityNames, z.array(z.string().min(1)), 'Invalid entityNames');
+        const salienceScoresRaw = validateWithSchema(args.salienceScores, z.record(z.string(), z.number()), 'Invalid salienceScores');
+        const loadThreshold = args.loadThreshold !== undefined
+            ? validateWithSchema(args.loadThreshold, z.number().min(0).max(1), 'Invalid loadThreshold')
+            : undefined;
+        const graph = await ctx.storage.loadGraph();
+        const memories = graph.entities.filter((e) => entityNames.includes(e.name));
+        if (memories.length === 0) {
+            return formatTextResponse('No entities found matching the provided names');
+        }
+        const salienceScores = new Map(Object.entries(salienceScoresRaw));
+        const analyzer = new CognitiveLoadAnalyzer(loadThreshold ? { loadThreshold } : undefined);
+        const result = analyzer.adaptiveReduce(memories, salienceScores, estimateTokens);
+        return formatToolResponse({
+            retained: result.retained.map(e => e.name),
+            removed: result.removed.map(e => e.name),
+            retainedCount: result.retained.length,
+            removedCount: result.removed.length,
+            beforeMetrics: result.beforeMetrics,
+            afterMetrics: result.afterMetrics,
+        });
+    },
+    // Phase 13: User profile + agent diary
+    get_profile: async (ctx, args) => {
+        const projectId = args.projectId !== undefined ? validateWithSchema(args.projectId, z.string(), 'Invalid projectId') : undefined;
+        const amm = ctx.agentMemory();
+        const profile = await amm.profileManager.getProfile({ projectId });
+        return formatToolResponse(profile);
+    },
+    update_profile: async (ctx, args) => {
+        const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
+        const type = validateWithSchema(args.type, z.enum(['static', 'dynamic']), 'Invalid type');
+        const projectId = args.projectId !== undefined ? validateWithSchema(args.projectId, z.string(), 'Invalid projectId') : undefined;
+        const amm = ctx.agentMemory();
+        await amm.profileManager.addFact(content, type, { projectId });
+        return formatTextResponse(`Added ${type} profile fact: "${content}"`);
+    },
+    diary_write: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const entry = validateWithSchema(args.entry, z.string().min(1), 'Invalid entry');
+        const topic = args.topic !== undefined ? validateWithSchema(args.topic, z.string(), 'Invalid topic') : undefined;
+        const amm = ctx.agentMemory();
+        await amm.writeDiary(agentId, entry, { topic });
+        return formatTextResponse(`Diary entry written for agent '${agentId}'`);
+    },
+    diary_read: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const lastN = args.lastN !== undefined ? validateWithSchema(args.lastN, z.number().int().positive(), 'Invalid lastN') : undefined;
+        const topic = args.topic !== undefined ? validateWithSchema(args.topic, z.string(), 'Invalid topic') : undefined;
+        const amm = ctx.agentMemory();
+        const entries = await amm.readDiary(agentId, { lastN, topic });
+        return formatToolResponse({ agentId, entries, count: entries.length });
+    },
+    // ==================== SESSION & WORKING MEMORY HANDLERS ====================
+    session_start: async (ctx, args) => {
+        const goalDescription = args.taskDescription !== undefined ? validateWithSchema(args.taskDescription, z.string(), 'Invalid taskDescription') : undefined;
+        const previousSessionId = args.parentSessionId !== undefined ? validateWithSchema(args.parentSessionId, z.string(), 'Invalid parentSessionId') : undefined;
+        const amm = ctx.agentMemory();
+        const session = await amm.startSession({ goalDescription, previousSessionId });
+        return formatToolResponse(session);
+    },
+    session_end: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const status = args.status !== undefined
+            ? validateWithSchema(args.status, z.enum(['completed', 'abandoned']), 'Invalid status')
+            : undefined;
+        const amm = ctx.agentMemory();
+        const result = await amm.endSession(sessionId, status);
+        return formatToolResponse(result);
+    },
+    session_checkpoint: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const name = args.name !== undefined ? validateWithSchema(args.name, z.string(), 'Invalid name') : undefined;
+        const amm = ctx.agentMemory();
+        const checkpoint = await amm.checkpointSession(sessionId, name);
+        return formatToolResponse(checkpoint);
+    },
+    session_restore: async (ctx, args) => {
+        const checkpointId = validateWithSchema(args.checkpointId, z.string().min(1), 'Invalid checkpointId');
+        const amm = ctx.agentMemory();
+        await amm.restoreSession(checkpointId);
+        return formatTextResponse(`Session restored from checkpoint '${checkpointId}'`);
+    },
+    add_working_memory: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
+        const taskId = args.taskId !== undefined ? validateWithSchema(args.taskId, z.string(), 'Invalid taskId') : undefined;
+        const importance = args.importance !== undefined ? validateWithSchema(args.importance, z.number().min(0).max(10), 'Invalid importance') : undefined;
+        const ttlHours = args.ttlHours !== undefined ? validateWithSchema(args.ttlHours, z.number().positive(), 'Invalid ttlHours') : undefined;
+        const amm = ctx.agentMemory();
+        const memory = await amm.addWorkingMemory({ sessionId, content, taskId, importance, ttlHours });
+        return formatToolResponse(memory);
+    },
+    promote_working_memory: async (ctx, args) => {
+        const memoryName = validateWithSchema(args.memoryName, z.string().min(1), 'Invalid memoryName');
+        const targetType = args.targetType !== undefined
+            ? validateWithSchema(args.targetType, z.enum(['episodic', 'semantic']), 'Invalid targetType')
+            : undefined;
+        const amm = ctx.agentMemory();
+        const result = await amm.promoteMemory(memoryName, targetType);
+        return formatToolResponse(result);
+    },
+    confirm_memory: async (ctx, args) => {
+        const memoryName = validateWithSchema(args.memoryName, z.string().min(1), 'Invalid memoryName');
+        const confidenceBoost = args.confidenceBoost !== undefined ? validateWithSchema(args.confidenceBoost, z.number(), 'Invalid confidenceBoost') : undefined;
+        const amm = ctx.agentMemory();
+        const result = await amm.confirmMemory(memoryName, confidenceBoost);
+        return formatToolResponse(result);
+    },
+    clear_expired_memories: async (ctx) => {
+        const amm = ctx.agentMemory();
+        const count = await amm.clearExpiredMemories();
+        return formatTextResponse(`Cleared ${count} expired working memories`);
+    },
+    wake_up: async (ctx, args) => {
+        const compress = args.compress !== undefined ? validateWithSchema(args.compress, z.boolean(), 'Invalid compress') : undefined;
+        const result = await ctx.contextWindowManager.wakeUp({ compress });
+        return formatToolResponse(result);
+    },
+    // ==================== AUTO-ENHANCEMENT HANDLERS ====================
+    auto_link_observations: async (ctx, args) => {
+        const text = validateWithSchema(args.text, z.string().min(1), 'Invalid text');
+        const graph = await ctx.storage.loadGraph();
+        const mentions = ctx.autoLinker.detectMentions(text, graph.entities);
+        return formatToolResponse({ mentions, count: mentions.length });
+    },
+    extract_facts: async (ctx, args) => {
+        const text = validateWithSchema(args.text, z.string().min(1), 'Invalid text');
+        const facts = ctx.factExtractor.extract(text);
+        return formatToolResponse({ facts, count: facts.length });
+    },
+    detect_contradictions: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const threshold = args.threshold !== undefined ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold') : undefined;
+        const graph = await ctx.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            return { content: [{ type: 'text', text: `Entity '${entityName}' not found` }], isError: true };
+        }
+        if (!ctx.semanticSearch) {
+            return formatTextResponse('Contradiction detection requires semantic search (set MEMORY_EMBEDDING_PROVIDER)');
+        }
+        const detector = new ContradictionDetector(ctx.semanticSearch, threshold ?? 0.85);
+        const contradictions = await detector.detect(entity, entity.observations);
+        return formatToolResponse({ entityName, contradictions, count: contradictions.length });
+    },
+    consolidate_session: async (ctx, args) => {
+        const sessionId = validateWithSchema(args.sessionId, z.string().min(1), 'Invalid sessionId');
+        const amm = ctx.agentMemory();
+        const result = await amm.consolidateSession(sessionId);
+        return formatToolResponse(result);
+    },
+    detect_patterns: async (ctx, args) => {
+        const entityType = validateWithSchema(args.entityType, z.string().min(1), 'Invalid entityType');
+        const minOccurrences = args.minOccurrences !== undefined ? validateWithSchema(args.minOccurrences, z.number().int().min(2), 'Invalid minOccurrences') : undefined;
+        const amm = ctx.agentMemory();
+        const patterns = await amm.consolidationPipeline.extractPatterns(entityType, minOccurrences);
+        return formatToolResponse({ patterns, count: patterns.length });
+    },
+    summarize_entity: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const threshold = args.threshold !== undefined ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold') : undefined;
+        const amm = ctx.agentMemory();
+        const result = await amm.consolidationPipeline.applySummarizationToEntity(entityName, threshold);
+        return formatToolResponse(result);
+    },
+    priority_dedup: async (ctx) => {
+        const result = await ctx.compressionManager.priorityDedup();
+        return formatToolResponse(result);
+    },
+    // ==================== CONTEXT COMPRESSION HANDLERS ====================
+    compress_context: async (ctx, args) => {
+        const text = validateWithSchema(args.text, z.string().min(1), 'Invalid text');
+        const level = args.level !== undefined
+            ? validateWithSchema(args.level, z.enum(['light', 'medium', 'aggressive']), 'Invalid level')
+            : undefined;
+        const result = ctx.contextWindowManager.compressForContext(text, { level });
+        return formatToolResponse(result);
+    },
+    // ==================== DECAY & SALIENCE HANDLERS ====================
+    run_decay_cycle: async (ctx) => {
+        const amm = ctx.agentMemory();
+        const result = await amm.runDecayCycle();
+        return formatToolResponse(result);
+    },
+    get_decayed_memories: async (ctx, args) => {
+        const threshold = args.threshold !== undefined ? validateWithSchema(args.threshold, z.number(), 'Invalid threshold') : undefined;
+        const amm = ctx.agentMemory();
+        const memories = await amm.getDecayedMemories(threshold);
+        return formatToolResponse({ memories, count: memories.length });
+    },
+    forget_weak_memories: async (ctx, args) => {
+        const effectiveImportanceThreshold = args.threshold !== undefined
+            ? validateWithSchema(args.threshold, z.number(), 'Invalid threshold')
+            : 0.1;
+        const dryRun = args.dryRun !== undefined ? validateWithSchema(args.dryRun, z.boolean(), 'Invalid dryRun') : undefined;
+        const olderThanHours = args.maxCount !== undefined ? validateWithSchema(args.maxCount, z.number().int().positive(), 'Invalid olderThanHours') : undefined;
+        const options = { effectiveImportanceThreshold, dryRun, olderThanHours };
+        const amm = ctx.agentMemory();
+        const result = await amm.forgetWeakMemories(options);
+        return formatToolResponse(result);
+    },
+    reinforce_memory: async (ctx, args) => {
+        const memoryName = validateWithSchema(args.memoryName, z.string().min(1), 'Invalid memoryName');
+        const confirmationBoost = args.confirmationBoost !== undefined ? validateWithSchema(args.confirmationBoost, z.number(), 'Invalid confirmationBoost') : undefined;
+        const confidenceBoost = args.confidenceBoost !== undefined ? validateWithSchema(args.confidenceBoost, z.number(), 'Invalid confidenceBoost') : undefined;
+        const amm = ctx.agentMemory();
+        await amm.reinforceMemory(memoryName, { confirmationBoost, confidenceBoost });
+        return formatTextResponse(`Memory '${memoryName}' reinforced`);
+    },
+    score_salience: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const queryText = args.queryText !== undefined ? validateWithSchema(args.queryText, z.string(), 'Invalid queryText') : undefined;
+        const taskDescription = args.taskDescription !== undefined ? validateWithSchema(args.taskDescription, z.string(), 'Invalid taskDescription') : undefined;
+        const sessionId = args.sessionId !== undefined ? validateWithSchema(args.sessionId, z.string(), 'Invalid sessionId') : undefined;
+        const graph = await ctx.storage.loadGraph();
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            return { content: [{ type: 'text', text: `Entity '${entityName}' not found` }], isError: true };
+        }
+        const context = { queryText, currentTask: taskDescription, currentSession: sessionId };
+        const scored = await ctx.salienceEngine.calculateSalience(entity, context);
+        return formatToolResponse(scored);
+    },
+    // ==================== MULTI-AGENT HANDLERS ====================
+    register_agent: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const type = args.type !== undefined ? validateWithSchema(args.type, z.string(), 'Invalid type') : 'default';
+        const trustLevel = args.trustLevel !== undefined ? validateWithSchema(args.trustLevel, z.number().min(0).max(1), 'Invalid trustLevel') : 0.5;
+        const capabilities = args.capabilities !== undefined ? validateWithSchema(args.capabilities, z.array(z.string()), 'Invalid capabilities') : [];
+        const amm = ctx.agentMemory();
+        amm.registerAgent(agentId, { name: agentId, type, trustLevel, capabilities });
+        return formatTextResponse(`Agent '${agentId}' registered (type: ${type}, trust: ${trustLevel})`);
+    },
+    search_cross_agent: async (ctx, args) => {
+        const requestingAgentId = validateWithSchema(args.requestingAgentId, z.string().min(1), 'Invalid requestingAgentId');
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const agentIds = args.agentIds !== undefined ? validateWithSchema(args.agentIds, z.array(z.string()), 'Invalid agentIds') : undefined;
+        const amm = ctx.agentMemory();
+        const results = await amm.searchCrossAgent(requestingAgentId, query, { agentIds });
+        return withCompression(async () => formatToolResponse({ results, count: results.length }));
+    },
+    set_memory_visibility: async (ctx, args) => {
+        const memoryName = validateWithSchema(args.memoryName, z.string().min(1), 'Invalid memoryName');
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const visibility = validateWithSchema(args.visibility, z.enum(['private', 'team', 'org', 'shared', 'public']), 'Invalid visibility');
+        // η.5.5.b extensions
+        const allowedRoles = args.allowedRoles !== undefined
+            ? validateWithSchema(args.allowedRoles, z.array(z.string()), 'Invalid allowedRoles')
+            : undefined;
+        const visibleFrom = args.visibleFrom !== undefined ? validateWithSchema(args.visibleFrom, z.string(), 'Invalid visibleFrom') : undefined;
+        const visibleUntil = args.visibleUntil !== undefined ? validateWithSchema(args.visibleUntil, z.string(), 'Invalid visibleUntil') : undefined;
+        const amm = ctx.agentMemory();
+        const result = await amm.multiAgentManager.setMemoryVisibility(memoryName, agentId, visibility);
+        // Bug 3 fix: previously returned null silently when entity wasn't an
+        // AgentEntity. Auto-promote: stamp agentId + memoryType + role/window
+        // fields so the visibility takes effect. Error if the entity doesn't
+        // exist at all.
+        if (result === null) {
+            const graph = await ctx.storage.getGraphForMutation();
+            const entity = graph.entities.find(e => e.name === memoryName);
+            if (!entity) {
+                return {
+                    content: [{ type: 'text', text: `Entity '${memoryName}' not found — cannot set visibility` }],
+                    isError: true,
+                };
+            }
+            // Promote plain Entity → AgentEntity by stamping multi-agent fields
+            entity.agentId = agentId;
+            entity.visibility = visibility;
+            if (entity.memoryType === undefined)
+                entity.memoryType = 'semantic';
+            if (entity.confidence === undefined)
+                entity.confidence = 0.8;
+            if (entity.confirmationCount === undefined)
+                entity.confirmationCount = 0;
+            if (entity.accessCount === undefined)
+                entity.accessCount = 0;
+            // η.5.5.b extension fields
+            if (allowedRoles !== undefined)
+                entity.allowedRoles = allowedRoles;
+            if (visibleFrom !== undefined)
+                entity.visibleFrom = visibleFrom;
+            if (visibleUntil !== undefined)
+                entity.visibleUntil = visibleUntil;
+            await ctx.storage.saveGraph(graph);
+            return formatToolResponse({
+                memoryName,
+                agentId,
+                visibility,
+                allowedRoles,
+                visibleFrom,
+                visibleUntil,
+                promoted: true,
+                message: 'Plain entity auto-promoted to AgentEntity with visibility set',
+            });
+        }
+        // Already an AgentEntity — apply η.5.5.b extension fields if provided
+        if (allowedRoles !== undefined || visibleFrom !== undefined || visibleUntil !== undefined) {
+            const graph = await ctx.storage.getGraphForMutation();
+            const entity = graph.entities.find(e => e.name === memoryName);
+            if (entity) {
+                if (allowedRoles !== undefined)
+                    entity.allowedRoles = allowedRoles;
+                if (visibleFrom !== undefined)
+                    entity.visibleFrom = visibleFrom;
+                if (visibleUntil !== undefined)
+                    entity.visibleUntil = visibleUntil;
+                await ctx.storage.saveGraph(graph);
+            }
+        }
+        return formatToolResponse(result);
+    },
+    get_visible_memories: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const amm = ctx.agentMemory();
+        const memories = await amm.multiAgentManager.getVisibleMemories(agentId);
+        return withCompression(async () => formatToolResponse({ memories, count: memories.length }));
+    },
+    resolve_agent_conflict: async (ctx, args) => {
+        const primaryMemory = validateWithSchema(args.primaryMemory, z.string().min(1), 'Invalid primaryMemory');
+        const conflictingMemory = validateWithSchema(args.conflictingMemory, z.string().min(1), 'Invalid conflictingMemory');
+        const strategy = args.strategy !== undefined
+            ? validateWithSchema(args.strategy, z.enum(['most_recent', 'highest_confidence', 'most_confirmations', 'trusted_agent']), 'Invalid strategy')
+            : undefined;
+        const amm = ctx.agentMemory();
+        // Build a ConflictInfo structure for the two memories
+        const conflictInfo = {
+            primaryMemory,
+            conflictingMemories: [conflictingMemory],
+            detectionMethod: 'manual',
+            suggestedStrategy: strategy ?? 'most_recent',
+            detectedAt: new Date().toISOString(),
+        };
+        const result = await amm.resolveConflict(conflictInfo, strategy);
+        return formatToolResponse(result);
+    },
+    // ==================== OBSERVABILITY HANDLERS ====================
+    visualize_graph: async (ctx, args) => {
+        const maxEntities = args.maxEntities !== undefined ? validateWithSchema(args.maxEntities, z.number().int().positive(), 'Invalid maxEntities') : undefined;
+        const title = args.title !== undefined ? validateWithSchema(args.title, z.string(), 'Invalid title') : undefined;
+        const html = await ctx.ioManager.visualizeGraph({ maxEntities, title });
+        return formatRawResponse(html);
+    },
+    split_transcript: async (ctx, args) => {
+        const text = validateWithSchema(args.text, z.string().min(1), 'Invalid text');
+        const result = ctx.ioManager.splitTranscript(text);
+        return formatToolResponse(result);
+    },
+    estimate_query_cost: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        let estimator = queryCostEstimatorMap.get(ctx);
+        if (!estimator) {
+            estimator = new QueryCostEstimator();
+            queryCostEstimatorMap.set(ctx, estimator);
+        }
+        const graph = await ctx.storage.loadGraph();
+        const estimates = estimator.estimateAllMethods(query, graph.entities.length);
+        return formatToolResponse({ query, entityCount: graph.entities.length, estimates });
+    },
+    get_context_profile: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const profileManager = ctx.contextWindowManager.getContextProfileManager();
+        const profile = profileManager.getProfile(name);
+        return formatToolResponse(profile);
+    },
+    // ==================== η.4.4 BITEMPORAL ENTITY HANDLERS ====================
+    invalidate_entity: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const ended = args.ended !== undefined
+            ? validateWithSchema(args.ended, z.string(), 'Invalid ended')
+            : undefined;
+        await ctx.entityManager.invalidateEntity(name, ended);
+        return formatTextResponse(`Invalidated entity '${name}' (ended: ${ended ?? 'now'})`);
+    },
+    entity_as_of: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const asOf = validateWithSchema(args.asOf, z.string().min(1), 'Invalid asOf');
+        const entity = await ctx.entityManager.entityAsOf(name, asOf);
+        if (!entity)
+            return formatToolResponse({ entity: null, valid: false, asOf });
+        return formatToolResponse({ entity, valid: true, asOf });
+    },
+    entity_timeline: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const versions = await ctx.entityManager.entityTimeline(name);
+        return formatToolResponse({ name, versions, count: versions.length });
+    },
+    invalidate_observation: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
+        const ended = args.ended !== undefined
+            ? validateWithSchema(args.ended, z.string(), 'Invalid ended')
+            : undefined;
+        await ctx.observationManager.invalidateObservation(entityName, content, ended);
+        return formatTextResponse(`Invalidated observation on '${entityName}' (ended: ${ended ?? 'now'})`);
+    },
+    observations_as_of: async (ctx, args) => {
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        const asOf = validateWithSchema(args.asOf, z.string().min(1), 'Invalid asOf');
+        const observations = await ctx.observationManager.observationsAsOf(entityName, asOf);
+        return formatToolResponse({ entityName, asOf, observations, count: observations.length });
+    },
+    // ==================== η.5.5.c OCC HANDLER ====================
+    update_entity: async (ctx, args) => {
+        const name = validateWithSchema(args.name, z.string().min(1), 'Invalid name');
+        const updates = validateWithSchema(args.updates, z.record(z.unknown()), 'Invalid updates');
+        const expectedVersion = args.expectedVersion !== undefined
+            ? validateWithSchema(args.expectedVersion, z.number().int().positive(), 'Invalid expectedVersion')
+            : undefined;
+        const updated = await ctx.entityManager.updateEntity(name, updates, expectedVersion !== undefined ? { expectedVersion } : undefined);
+        return formatToolResponse(updated);
+    },
+    // ==================== η.6.1 RBAC HANDLERS ====================
+    rbac_assign_role: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const role = validateWithSchema(args.role, z.string().min(1), 'Invalid role');
+        const resourceType = args.resourceType !== undefined
+            ? validateWithSchema(args.resourceType, z.enum(['entity', 'relation', 'observation', 'session', 'artifact']), 'Invalid resourceType')
+            : undefined;
+        const scope = args.scope !== undefined ? validateWithSchema(args.scope, z.string(), 'Invalid scope') : undefined;
+        const validFrom = args.validFrom !== undefined ? validateWithSchema(args.validFrom, z.string(), 'Invalid validFrom') : undefined;
+        const validUntil = args.validUntil !== undefined ? validateWithSchema(args.validUntil, z.string(), 'Invalid validUntil') : undefined;
+        const notes = args.notes !== undefined ? validateWithSchema(args.notes, z.string(), 'Invalid notes') : undefined;
+        await ctx.roleAssignmentStore.assign({ agentId, role, resourceType, scope, validFrom, validUntil, notes });
+        return formatTextResponse(`Assigned role '${role}' to agent '${agentId}'${resourceType ? ` (resourceType=${resourceType})` : ''}${scope ? ` (scope=${scope})` : ''}`);
+    },
+    rbac_revoke_role: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const role = validateWithSchema(args.role, z.string().min(1), 'Invalid role');
+        const resourceType = args.resourceType !== undefined
+            ? validateWithSchema(args.resourceType, z.enum(['entity', 'relation', 'observation', 'session', 'artifact']), 'Invalid resourceType')
+            : undefined;
+        await ctx.roleAssignmentStore.revoke(agentId, role, resourceType);
+        return formatTextResponse(`Revoked role '${role}' from agent '${agentId}'`);
+    },
+    rbac_check_permission: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const action = validateWithSchema(args.action, z.enum(['read', 'write', 'delete', 'manage']), 'Invalid action');
+        const resourceType = validateWithSchema(args.resourceType, z.enum(['entity', 'relation', 'observation', 'session', 'artifact']), 'Invalid resourceType');
+        const resourceName = args.resourceName !== undefined ? validateWithSchema(args.resourceName, z.string(), 'Invalid resourceName') : undefined;
+        const now = args.now !== undefined ? validateWithSchema(args.now, z.string(), 'Invalid now') : undefined;
+        const allowed = ctx.rbacMiddleware.checkPermission(agentId, action, resourceType, resourceName, now);
+        return formatToolResponse({ agentId, action, resourceType, resourceName, allowed });
+    },
+    rbac_list_assignments: async (ctx, args) => {
+        const agentId = validateWithSchema(args.agentId, z.string().min(1), 'Invalid agentId');
+        const activeOnly = args.activeOnly !== undefined ? validateWithSchema(args.activeOnly, z.boolean(), 'Invalid activeOnly') : false;
+        const now = args.now !== undefined ? validateWithSchema(args.now, z.string(), 'Invalid now') : undefined;
+        const assignments = activeOnly
+            ? ctx.roleAssignmentStore.listActive(agentId, now)
+            : ctx.roleAssignmentStore.list(agentId);
+        return formatToolResponse({ agentId, activeOnly, assignments, count: assignments.length });
+    },
+    // ==================== 3B.4 PROCEDURAL MEMORY HANDLERS ====================
+    add_procedure: async (ctx, args) => {
+        const procedure = await ctx.procedureManager.addProcedure(args);
+        return formatToolResponse(procedure);
+    },
+    get_procedure: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const procedure = await ctx.procedureManager.getProcedure(id);
+        if (!procedure) {
+            return { content: [{ type: 'text', text: `Procedure '${id}' not found` }], isError: true };
+        }
+        return formatToolResponse(procedure);
+    },
+    match_procedure: async (ctx, args) => {
+        const context = validateWithSchema(args.context, z.string().min(1), 'Invalid context');
+        const threshold = args.threshold !== undefined ? validateWithSchema(args.threshold, z.number().min(0).max(1), 'Invalid threshold') : 0;
+        const candidateIds = args.candidateIds !== undefined ? validateWithSchema(args.candidateIds, z.array(z.string()), 'Invalid candidateIds') : undefined;
+        // If specific candidates passed, load each; otherwise scan all 'procedure' entities.
+        const graph = await ctx.storage.loadGraph();
+        const allProcedureEntities = graph.entities.filter(e => e.entityType === 'procedure');
+        const candidates = await Promise.all((candidateIds ?? allProcedureEntities.map(e => e.name)).map(id => ctx.procedureManager.getProcedure(id)));
+        const valid = candidates.filter((p) => p !== null);
+        const matches = await ctx.procedureManager.matchProcedure(context, valid, threshold);
+        return formatToolResponse({ context, threshold, matches, count: matches.length });
+    },
+    refine_procedure: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const succeeded = validateWithSchema(args.succeeded, z.boolean(), 'Invalid succeeded');
+        const notes = args.notes !== undefined ? validateWithSchema(args.notes, z.string(), 'Invalid notes') : undefined;
+        const recordedAt = args.recordedAt !== undefined ? validateWithSchema(args.recordedAt, z.string(), 'Invalid recordedAt') : undefined;
+        const updated = await ctx.procedureManager.refineProcedure(id, { succeeded, notes, recordedAt });
+        return formatToolResponse(updated);
+    },
+    get_procedure_step: async (ctx, args) => {
+        const id = validateWithSchema(args.id, z.string().min(1), 'Invalid id');
+        const order = validateWithSchema(args.order, z.number().int().positive(), 'Invalid order');
+        const next = args.next !== undefined ? validateWithSchema(args.next, z.boolean(), 'Invalid next') : false;
+        const step = next
+            ? await ctx.procedureManager.getNextStep(id, order)
+            : await ctx.procedureManager.getStep(id, order);
+        if (!step) {
+            return { content: [{ type: 'text', text: `Step ${order} not found in procedure '${id}'` }], isError: true };
+        }
+        return formatToolResponse(step);
+    },
+    // ==================== 3B.5 ACTIVE RETRIEVAL HANDLER ====================
+    adaptive_retrieve: async (ctx, args) => {
+        const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
+        const budgetTokens = args.budgetTokens !== undefined ? validateWithSchema(args.budgetTokens, z.number().int().positive(), 'Invalid budgetTokens') : undefined;
+        const result = await ctx.activeRetrieval.adaptiveRetrieve({ query, budgetTokens });
+        return formatToolResponse(result);
+    },
+    // ==================== 3B.6 CAUSAL REASONING HANDLERS ====================
+    find_causes: async (ctx, args) => {
+        const effect = validateWithSchema(args.effect, z.string().min(1), 'Invalid effect');
+        const candidates = validateWithSchema(args.candidates, z.array(z.string()).min(1), 'Invalid candidates');
+        const maxDepth = args.maxDepth !== undefined ? validateWithSchema(args.maxDepth, z.number().int().positive(), 'Invalid maxDepth') : undefined;
+        const chains = await ctx.causalReasoner.findCauses(effect, candidates, maxDepth);
+        return formatToolResponse({ effect, candidates, chains, count: chains.length });
+    },
+    find_effects: async (ctx, args) => {
+        const cause = validateWithSchema(args.cause, z.string().min(1), 'Invalid cause');
+        const candidates = validateWithSchema(args.candidates, z.array(z.string()).min(1), 'Invalid candidates');
+        const maxDepth = args.maxDepth !== undefined ? validateWithSchema(args.maxDepth, z.number().int().positive(), 'Invalid maxDepth') : undefined;
+        const chains = await ctx.causalReasoner.findEffects(cause, candidates, maxDepth);
+        return formatToolResponse({ cause, candidates, chains, count: chains.length });
+    },
+    counterfactual_query: async (ctx, args) => {
+        const seed = validateWithSchema(args.seed, z.string().min(1), 'Invalid seed');
+        const removeFrom = validateWithSchema(args.removeFrom, z.string().min(1), 'Invalid removeFrom');
+        const removeTo = validateWithSchema(args.removeTo, z.string().min(1), 'Invalid removeTo');
+        const predict = validateWithSchema(args.predict, z.string().min(1), 'Invalid predict');
+        const maxDepth = args.maxDepth !== undefined ? validateWithSchema(args.maxDepth, z.number().int().positive(), 'Invalid maxDepth') : undefined;
+        const chains = await ctx.causalReasoner.counterfactual({ seed, removeFrom, removeTo, predict, maxDepth });
+        return formatToolResponse({ scenario: { seed, removeFrom, removeTo, predict }, chains, count: chains.length });
+    },
+    detect_causal_cycles: async (ctx, args) => {
+        const seed = validateWithSchema(args.seed, z.string().min(1), 'Invalid seed');
+        const maxDepth = args.maxDepth !== undefined ? validateWithSchema(args.maxDepth, z.number().int().positive(), 'Invalid maxDepth') : undefined;
+        const cycles = ctx.causalReasoner.detectCycles(seed, maxDepth);
+        return formatToolResponse({ seed, cycles, count: cycles.length });
+    },
+    // ==================== 3B.7 WORLD MODEL HANDLERS ====================
+    get_world_state: async (ctx) => {
+        const snapshot = await ctx.worldModelManager.getCurrentState();
+        return formatToolResponse(snapshot.toJSON());
+    },
+    validate_fact_against_world: async (ctx, args) => {
+        const observation = validateWithSchema(args.observation, z.string().min(1), 'Invalid observation');
+        const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entityName');
+        try {
+            const result = await ctx.worldModelManager.validateFact(observation, entityName);
+            return formatToolResponse({ observation, entityName, result });
+        }
+        catch (err) {
+            // Graceful path for the documented "Returns null if no validator
+            // is wired" semantics: when memoryjs's local embedding provider is
+            // selected but `@xenova/transformers` isn't installed, the
+            // underlying EmbeddingService throws a raw Node module-resolution
+            // error. Translating to a structured null result keeps the MCP
+            // surface coherent and surfaces the configuration issue instead
+            // of leaking Node internals.
+            const msg = err instanceof Error ? err.message : String(err);
+            // Anchored on memoryjs EmbeddingService.ts:368 prefix and the
+            // package-name signal — narrow enough to avoid swallowing
+            // legitimate "Failed to initialize world model — entity has no
+            // embedding" or similar downstream errors.
+            const isProviderUnavailable = /^Failed to initialize local embedding service:/.test(msg) ||
+                /Cannot find package ['"]@xenova\/transformers['"]/.test(msg);
+            if (isProviderUnavailable) {
+                // Log to stderr (stdout is the MCP JSON-RPC stream — must not
+                // be polluted). Operators piping stderr to a file see this once
+                // per process; LLM clients see only the structured null result.
+                console.warn('[validate_fact_against_world] embedding_provider_unavailable: ' + msg);
+                return formatToolResponse({
+                    observation,
+                    entityName,
+                    result: null,
+                    reason: 'embedding_provider_unavailable',
+                    detail: msg,
+                });
+            }
+            throw err;
+        }
+    },
+    predict_outcome: async (ctx, args) => {
+        const action = validateWithSchema(args.action, z.string().min(1), 'Invalid action');
+        const candidates = validateWithSchema(args.candidates, z.array(z.string()).min(1), 'Invalid candidates');
+        const chains = await ctx.worldModelManager.predictOutcome(action, candidates);
+        return formatToolResponse({ action, candidates, chains, count: chains.length });
+    },
 };
 /**
  * Handle a tool call by dispatching to the appropriate handler.