@soleri/core 2.7.0 → 2.9.0

package/src/runtime/facades/control-facade.ts

@@ -0,0 +1,279 @@
+/**
+ * Control facade — agent behavior ops.
+ * identity, intent routing, morphing, guidelines, governance.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import type { GuidelineCategory, OperationalMode } from '../../control/types.js';
+import type { PolicyType, PolicyPreset } from '../../governance/types.js';
+
+export function createControlFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { identityManager, intentRouter, governance } = runtime;
+
+  return [
+    // ─── Control (inline from core-ops.ts) ──────────────────────
+    {
+      name: 'get_identity',
+      description: 'Get current agent identity with guidelines.',
+      auth: 'read',
+      schema: z.object({
+        agentId: z.string().describe('Agent identifier.'),
+      }),
+      handler: async (params) => {
+        const identity = identityManager.getIdentity(params.agentId as string);
+        if (!identity) return { found: false, agentId: params.agentId };
+        return identity;
+      },
+    },
+    {
+      name: 'update_identity',
+      description: 'Update identity fields. Auto-versions and snapshots previous state.',
+      auth: 'write',
+      schema: z.object({
+        agentId: z.string(),
+        name: z.string().optional(),
+        role: z.string().optional(),
+        description: z.string().optional(),
+        personality: z.array(z.string()).optional(),
+        changedBy: z.string().optional(),
+        changeReason: z.string().optional(),
+      }),
+      handler: async (params) => {
+        const identity = identityManager.setIdentity(params.agentId as string, {
+          name: params.name as string | undefined,
+          role: params.role as string | undefined,
+          description: params.description as string | undefined,
+          personality: params.personality as string[] | undefined,
+          changedBy: params.changedBy as string | undefined,
+          changeReason: params.changeReason as string | undefined,
+        });
+        return { updated: true, identity };
+      },
+    },
+    {
+      name: 'add_guideline',
+      description: 'Add a behavioral guideline (behavior/preference/restriction/style).',
+      auth: 'write',
+      schema: z.object({
+        agentId: z.string(),
+        category: z.enum(['behavior', 'preference', 'restriction', 'style']),
+        text: z.string(),
+        priority: z.number().optional(),
+      }),
+      handler: async (params) => {
+        const guideline = identityManager.addGuideline(params.agentId as string, {
+          category: params.category as GuidelineCategory,
+          text: params.text as string,
+          priority: params.priority as number | undefined,
+        });
+        return { added: true, guideline };
+      },
+    },
+    {
+      name: 'remove_guideline',
+      description: 'Remove a guideline by ID.',
+      auth: 'write',
+      schema: z.object({
+        guidelineId: z.string(),
+      }),
+      handler: async (params) => {
+        const removed = identityManager.removeGuideline(params.guidelineId as string);
+        return { removed };
+      },
+    },
+    {
+      name: 'rollback_identity',
+      description: 'Restore a previous identity version. Creates a new version with the old data.',
+      auth: 'write',
+      schema: z.object({
+        agentId: z.string(),
+        version: z.number().describe('Version number to roll back to.'),
+      }),
+      handler: async (params) => {
+        const identity = identityManager.rollback(
+          params.agentId as string,
+          params.version as number,
+        );
+        return { rolledBack: true, identity };
+      },
+    },
+    {
+      name: 'route_intent',
+      description: 'Classify a prompt into intent + operational mode via keyword matching.',
+      auth: 'read',
+      schema: z.object({
+        prompt: z.string().describe('The user prompt to classify.'),
+      }),
+      handler: async (params) => {
+        return intentRouter.routeIntent(params.prompt as string);
+      },
+    },
+    {
+      name: 'morph',
+      description: 'Switch operational mode manually.',
+      auth: 'write',
+      schema: z.object({
+        mode: z
+          .string()
+          .describe('The operational mode to switch to (e.g., BUILD-MODE, FIX-MODE).'),
+      }),
+      handler: async (params) => {
+        return intentRouter.morph(params.mode as OperationalMode);
+      },
+    },
+    {
+      name: 'get_behavior_rules',
+      description: 'Get behavior rules for current or specified mode.',
+      auth: 'read',
+      schema: z.object({
+        mode: z.string().optional().describe('Mode to get rules for. Defaults to current mode.'),
+      }),
+      handler: async (params) => {
+        const mode = params.mode as OperationalMode | undefined;
+        const rules = intentRouter.getBehaviorRules(mode);
+        const currentMode = intentRouter.getCurrentMode();
+        return { mode: mode ?? currentMode, rules };
+      },
+    },
+
+    // ─── Governance (inline from core-ops.ts) ───────────────────
+    {
+      name: 'governance_policy',
+      description:
+        'Get, set, or apply a preset to vault governance policies (quota, retention, auto-capture).',
+      auth: 'write',
+      schema: z.object({
+        action: z.enum(['get', 'set', 'applyPreset']),
+        projectPath: z.string(),
+        policyType: z.enum(['quota', 'retention', 'auto-capture']).optional(),
+        config: z.record(z.unknown()).optional(),
+        preset: z.enum(['strict', 'moderate', 'permissive']).optional(),
+        changedBy: z.string().optional(),
+      }),
+      handler: async (params) => {
+        const action = params.action as string;
+        const projectPath = params.projectPath as string;
+        if (action === 'get') {
+          return governance.getPolicy(projectPath);
+        }
+        if (action === 'set') {
+          governance.setPolicy(
+            projectPath,
+            params.policyType as PolicyType,
+            params.config as Record<string, unknown>,
+            params.changedBy as string | undefined,
+          );
+          return { updated: true, policy: governance.getPolicy(projectPath) };
+        }
+        if (action === 'applyPreset') {
+          governance.applyPreset(
+            projectPath,
+            params.preset as PolicyPreset,
+            params.changedBy as string | undefined,
+          );
+          return {
+            applied: true,
+            preset: params.preset,
+            policy: governance.getPolicy(projectPath),
+          };
+        }
+        return { error: 'Unknown action: ' + action };
+      },
+    },
+    {
+      name: 'governance_proposals',
+      description:
+        'Manage knowledge capture proposals — list, approve, reject, modify, get stats, or expire stale.',
+      auth: 'write',
+      schema: z.object({
+        action: z.enum(['list', 'approve', 'reject', 'modify', 'stats', 'expire']),
+        projectPath: z.string().optional(),
+        proposalId: z.number().optional(),
+        decidedBy: z.string().optional(),
+        note: z.string().optional(),
+        modifications: z.record(z.unknown()).optional(),
+        maxAgeDays: z.number().optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        const action = params.action as string;
+        if (action === 'list') {
+          return governance.listPendingProposals(
+            params.projectPath as string | undefined,
+            params.limit as number | undefined,
+          );
+        }
+        if (action === 'approve') {
+          return governance.approveProposal(
+            params.proposalId as number,
+            params.decidedBy as string | undefined,
+          );
+        }
+        if (action === 'reject') {
+          return governance.rejectProposal(
+            params.proposalId as number,
+            params.decidedBy as string | undefined,
+            params.note as string | undefined,
+          );
+        }
+        if (action === 'modify') {
+          return governance.modifyProposal(
+            params.proposalId as number,
+            params.modifications as Record<string, unknown>,
+            params.decidedBy as string | undefined,
+          );
+        }
+        if (action === 'stats') {
+          return governance.getProposalStats(params.projectPath as string | undefined);
+        }
+        if (action === 'expire') {
+          const expired = governance.expireStaleProposals(params.maxAgeDays as number | undefined);
+          return { expired };
+        }
+        return { error: 'Unknown action: ' + action };
+      },
+    },
+    {
+      name: 'governance_stats',
+      description: 'Get governance statistics — quota status and proposal stats for a project.',
+      auth: 'read',
+      schema: z.object({
+        projectPath: z.string(),
+      }),
+      handler: async (params) => {
+        const projectPath = params.projectPath as string;
+        return {
+          quotaStatus: governance.getQuotaStatus(projectPath),
+          proposalStats: governance.getProposalStats(projectPath),
+        };
+      },
+    },
+    {
+      name: 'governance_expire',
+      description: 'Expire stale pending proposals older than a threshold.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional(),
+        maxAgeDays: z.number().optional().describe('Days threshold. Default 14.'),
+      }),
+      handler: async (params) => {
+        const expired = governance.expireStaleProposals(params.maxAgeDays as number | undefined);
+        return { expired };
+      },
+    },
+    {
+      name: 'governance_dashboard',
+      description:
+        'Get governance dashboard — vault size, quota usage, pending proposals, acceptance rate, evaluation trend.',
+      auth: 'read',
+      schema: z.object({
+        projectPath: z.string(),
+      }),
+      handler: async (params) => {
+        return governance.getDashboard(params.projectPath as string);
+      },
+    },
+  ];
+}

package/src/runtime/facades/curator-facade.ts

@@ -0,0 +1,132 @@
+/**
+ * Curator facade — quality ops.
+ * duplicate detection, contradictions, grooming, health audit.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createCuratorExtraOps } from '../curator-extra-ops.js';
+
+export function createCuratorFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { curator } = runtime;
+
+  return [
+    // ─── Curator (inline from core-ops.ts) ──────────────────────
+    {
+      name: 'curator_status',
+      description: 'Curator status — table row counts, last groomed timestamp.',
+      auth: 'read',
+      handler: async () => {
+        return curator.getStatus();
+      },
+    },
+    {
+      name: 'curator_detect_duplicates',
+      description: 'Detect duplicate entries using TF-IDF cosine similarity.',
+      auth: 'read',
+      schema: z.object({
+        entryId: z.string().optional().describe('Check a specific entry. Omit to scan all.'),
+        threshold: z.number().optional().describe('Similarity threshold (0-1). Default 0.45.'),
+      }),
+      handler: async (params) => {
+        return curator.detectDuplicates(
+          params.entryId as string | undefined,
+          params.threshold as number | undefined,
+        );
+      },
+    },
+    {
+      name: 'curator_contradictions',
+      description: 'List or detect contradictions between patterns and anti-patterns.',
+      auth: 'read',
+      schema: z.object({
+        status: z.enum(['open', 'resolved', 'dismissed']).optional().describe('Filter by status.'),
+        detect: z.boolean().optional().describe('If true, run detection before listing.'),
+      }),
+      handler: async (params) => {
+        if (params.detect) {
+          curator.detectContradictions();
+        }
+        return curator.getContradictions(
+          params.status as 'open' | 'resolved' | 'dismissed' | undefined,
+        );
+      },
+    },
+    {
+      name: 'curator_resolve_contradiction',
+      description: 'Resolve or dismiss a contradiction.',
+      auth: 'write',
+      schema: z.object({
+        id: z.number().describe('Contradiction ID.'),
+        resolution: z.enum(['resolved', 'dismissed']),
+      }),
+      handler: async (params) => {
+        return curator.resolveContradiction(
+          params.id as number,
+          params.resolution as 'resolved' | 'dismissed',
+        );
+      },
+    },
+    {
+      name: 'curator_groom',
+      description: 'Groom a single entry — normalize tags, check staleness.',
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string().describe('Entry ID to groom.'),
+      }),
+      handler: async (params) => {
+        return curator.groomEntry(params.entryId as string);
+      },
+    },
+    {
+      name: 'curator_groom_all',
+      description: 'Groom all vault entries — normalize tags, detect staleness.',
+      auth: 'write',
+      handler: async () => {
+        return curator.groomAll();
+      },
+    },
+    {
+      name: 'curator_consolidate',
+      description:
+        'Consolidate vault — find duplicates, stale entries, contradictions. Dry-run by default.',
+      auth: 'write',
+      schema: z.object({
+        dryRun: z.boolean().optional().describe('Default true. Set false to apply mutations.'),
+        staleDaysThreshold: z
+          .number()
+          .optional()
+          .describe('Days before entry is stale. Default 90.'),
+        duplicateThreshold: z
+          .number()
+          .optional()
+          .describe('Cosine similarity threshold. Default 0.45.'),
+        contradictionThreshold: z
+          .number()
+          .optional()
+          .describe('Contradiction threshold. Default 0.4.'),
+      }),
+      handler: async (params) => {
+        return curator.consolidate({
+          dryRun: params.dryRun as boolean | undefined,
+          staleDaysThreshold: params.staleDaysThreshold as number | undefined,
+          duplicateThreshold: params.duplicateThreshold as number | undefined,
+          contradictionThreshold: params.contradictionThreshold as number | undefined,
+        });
+      },
+    },
+    {
+      name: 'curator_health_audit',
+      description:
+        'Audit vault health — score (0-100), coverage, freshness, quality, tag health, recommendations.',
+      auth: 'read',
+      handler: async () => {
+        return curator.healthAudit();
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createCuratorExtraOps(runtime),
+  ];
+}

package/src/runtime/facades/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Semantic facade assembler — creates 10 domain-specific facades
+ * matching Salvador's engine-level architecture.
+ *
+ * Each facade becomes its own MCP tool with op dispatch.
+ */
+
+import type { FacadeConfig } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createVaultFacadeOps } from './vault-facade.js';
+import { createPlanFacadeOps } from './plan-facade.js';
+import { createBrainFacadeOps } from './brain-facade.js';
+import { createMemoryFacadeOps } from './memory-facade.js';
+import { createAdminFacadeOps } from './admin-facade.js';
+import { createCuratorFacadeOps } from './curator-facade.js';
+import { createLoopFacadeOps } from './loop-facade.js';
+import { createOrchestrateFacadeOps } from './orchestrate-facade.js';
+import { createControlFacadeOps } from './control-facade.js';
+import { createCogneeFacadeOps } from './cognee-facade.js';
+
+export function createSemanticFacades(runtime: AgentRuntime, agentId: string): FacadeConfig[] {
+  return [
+    {
+      name: `${agentId}_vault`,
+      description: 'Knowledge management — search, CRUD, import/export, intake, archival.',
+      ops: createVaultFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_plan`,
+      description: 'Plan lifecycle — create, approve, execute, reconcile, complete, grading.',
+      ops: createPlanFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_brain`,
+      description: 'Learning system — intelligence pipeline, strengths, feedback, sessions.',
+      ops: createBrainFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_memory`,
+      description: 'Session & cross-project memory — capture, search, dedup, promote.',
+      ops: createMemoryFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_admin`,
+      description: 'Infrastructure — health, config, telemetry, tokens, LLM, prompts.',
+      ops: createAdminFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_curator`,
+      description: 'Quality — duplicate detection, contradictions, grooming, health audit.',
+      ops: createCuratorFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_loop`,
+      description: 'Iterative validation loops — start, iterate, cancel, complete, history.',
+      ops: createLoopFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_orchestrate`,
+      description: 'Execution orchestration — project registration, playbooks, plan/execute/complete.',
+      ops: createOrchestrateFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_control`,
+      description: 'Agent behavior — identity, intent routing, morphing, guidelines, governance.',
+      ops: createControlFacadeOps(runtime),
+    },
+    {
+      name: `${agentId}_cognee`,
+      description: 'Knowledge graph — Cognee search, sync, export, graph stats.',
+      ops: createCogneeFacadeOps(runtime),
+    },
+  ];
+}

package/src/runtime/facades/loop-facade.ts

@@ -0,0 +1,12 @@
+/**
+ * Loop facade — iterative validation loops.
+ * start, iterate, cancel, complete, history.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createLoopOps } from '../loop-ops.js';
+
+export function createLoopFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return createLoopOps(runtime);
+}

package/src/runtime/facades/memory-facade.ts

@@ -0,0 +1,114 @@
+/**
+ * Memory facade — session & cross-project memory ops.
+ * capture, search, dedup, promote.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createMemoryExtraOps } from '../memory-extra-ops.js';
+import { createMemoryCrossProjectOps } from '../memory-cross-project-ops.js';
+
+export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault } = runtime;
+
+  return [
+    // ─── Memory (inline from core-ops.ts) ───────────────────────
+    {
+      name: 'memory_search',
+      description: 'Search memories using full-text search.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string(),
+        type: z.enum(['session', 'lesson', 'preference']).optional(),
+        projectPath: z.string().optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return vault.searchMemories(params.query as string, {
+          type: params.type as string | undefined,
+          projectPath: params.projectPath as string | undefined,
+          limit: (params.limit as number) ?? 10,
+        });
+      },
+    },
+    {
+      name: 'memory_capture',
+      description: 'Capture a memory — session summary, lesson learned, or preference.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string(),
+        type: z.enum(['session', 'lesson', 'preference']),
+        context: z.string(),
+        summary: z.string(),
+        topics: z.array(z.string()).optional().default([]),
+        filesModified: z.array(z.string()).optional().default([]),
+        toolsUsed: z.array(z.string()).optional().default([]),
+      }),
+      handler: async (params) => {
+        const memory = vault.captureMemory({
+          projectPath: params.projectPath as string,
+          type: params.type as 'session' | 'lesson' | 'preference',
+          context: params.context as string,
+          summary: params.summary as string,
+          topics: (params.topics as string[]) ?? [],
+          filesModified: (params.filesModified as string[]) ?? [],
+          toolsUsed: (params.toolsUsed as string[]) ?? [],
+        });
+        return { captured: true, memory };
+      },
+    },
+    {
+      name: 'memory_list',
+      description: 'List memories with optional filters.',
+      auth: 'read',
+      schema: z.object({
+        type: z.enum(['session', 'lesson', 'preference']).optional(),
+        projectPath: z.string().optional(),
+        limit: z.number().optional(),
+        offset: z.number().optional(),
+      }),
+      handler: async (params) => {
+        const memories = vault.listMemories({
+          type: params.type as string | undefined,
+          projectPath: params.projectPath as string | undefined,
+          limit: (params.limit as number) ?? 50,
+          offset: (params.offset as number) ?? 0,
+        });
+        const stats = vault.memoryStats();
+        return { memories, stats };
+      },
+    },
+    {
+      name: 'session_capture',
+      description:
+        'Capture a session summary before context compaction. Called automatically by PreCompact hook.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().default('.'),
+        summary: z.string().describe('Brief summary of what was accomplished in this session'),
+        topics: z.array(z.string()).optional().default([]),
+        filesModified: z.array(z.string()).optional().default([]),
+        toolsUsed: z.array(z.string()).optional().default([]),
+      }),
+      handler: async (params) => {
+        const { resolve } = await import('node:path');
+        const projectPath = resolve((params.projectPath as string) ?? '.');
+        const memory = vault.captureMemory({
+          projectPath,
+          type: 'session',
+          context: 'Auto-captured before context compaction',
+          summary: params.summary as string,
+          topics: (params.topics as string[]) ?? [],
+          filesModified: (params.filesModified as string[]) ?? [],
+          toolsUsed: (params.toolsUsed as string[]) ?? [],
+        });
+        return { captured: true, memory, message: 'Session summary saved to memory.' };
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createMemoryExtraOps(runtime),
+    ...createMemoryCrossProjectOps(runtime),
+  ];
+}

package/src/runtime/facades/orchestrate-facade.ts

@@ -0,0 +1,68 @@
+/**
+ * Orchestrate facade — execution orchestration ops.
+ * project registration, playbooks, plan/execute/complete.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createOrchestrateOps } from '../orchestrate-ops.js';
+import { createProjectOps } from '../project-ops.js';
+import { createPlaybookOps } from '../playbook-ops.js';
+
+export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, governance, projectRegistry } = runtime;
+
+  return [
+    // ─── Register (inline from core-ops.ts) ─────────────────────
+    {
+      name: 'register',
+      description:
+        'Register a project for this session. Call on every new session to track usage and get context.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().default('.'),
+        name: z.string().optional().describe('Project display name (derived from path if omitted)'),
+      }),
+      handler: async (params) => {
+        const { resolve } = await import('node:path');
+        const projectPath = resolve((params.projectPath as string) ?? '.');
+        const project = vault.registerProject(projectPath, params.name as string | undefined);
+        // Also track in project registry for cross-project features
+        projectRegistry.register(projectPath, params.name as string | undefined);
+        const stats = vault.stats();
+        const isNew = project.sessionCount === 1;
+
+        // Expire stale proposals on session start (fire-and-forget)
+        const policy = governance.getPolicy(projectPath);
+        const expired = governance.expireStaleProposals(policy.autoCapture.autoExpireDays);
+
+        const proposalStats = governance.getProposalStats(projectPath);
+        const quotaStatus = governance.getQuotaStatus(projectPath);
+
+        return {
+          project,
+          is_new: isNew,
+          message: isNew
+            ? 'Welcome! New project registered.'
+            : 'Welcome back! Session #' + project.sessionCount + ' for ' + project.name + '.',
+          vault: { entries: stats.totalEntries, domains: Object.keys(stats.byDomain) },
+          governance: {
+            pendingProposals: proposalStats.pending,
+            quotaPercent:
+              quotaStatus.maxTotal > 0
+                ? Math.round((quotaStatus.total / quotaStatus.maxTotal) * 100)
+                : 0,
+            isQuotaWarning: quotaStatus.isWarning,
+            expiredThisSession: expired,
+          },
+        };
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createOrchestrateOps(runtime),
+    ...createProjectOps(runtime),
+    ...createPlaybookOps(runtime),
+  ];
+}