@soleri/core 2.10.0 → 2.12.0

package/src/runtime/admin-extra-ops.ts

@@ -76,21 +76,32 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
     // ─── Permissions ────────────────────────────────────────────────
     {
       name: 'admin_permissions',
-      description: 'Get or set auth enforcement policy (strict, moderate, permissive).',
-      auth: 'write',
+      description:
+        'Get or set auth enforcement policy. Modes: permissive (no checks), warn (log violations), enforce (block violations).',
+      auth: 'admin',
       schema: z.object({
         action: z.enum(['get', 'set']),
-        level: z.enum(['strict', 'moderate', 'permissive']).optional(),
+        mode: z.enum(['permissive', 'warn', 'enforce']).optional(),
+        callerLevel: z.enum(['read', 'write', 'admin']).optional(),
       }),
       handler: async (params) => {
         const action = params.action as string;
         if (action === 'set') {
-          const level = params.level as PermissionLevel | undefined;
-          if (level) {
-            permissionLevel = level;
-          }
+          const mode = params.mode as 'permissive' | 'warn' | 'enforce' | undefined;
+          const callerLevel = params.callerLevel as 'read' | 'write' | 'admin' | undefined;
+          if (mode) runtime.authPolicy.mode = mode;
+          if (callerLevel) runtime.authPolicy.callerLevel = callerLevel;
+          // Keep legacy field in sync
+          permissionLevel =
+            mode === 'enforce' ? 'strict' : mode === 'warn' ? 'moderate' : 'permissive';
         }
-        return { level: permissionLevel };
+        return {
+          level: permissionLevel,
+          authPolicy: {
+            mode: runtime.authPolicy.mode,
+            callerLevel: runtime.authPolicy.callerLevel,
+          },
+        };
       },
     },
 
@@ -649,6 +660,79 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Health Registry (#176) ─────────────────────────────────────
+    {
+      name: 'admin_health_snapshot',
+      description:
+        'Full health snapshot — overall status plus per-subsystem health (status, failure count, last error).',
+      auth: 'read',
+      handler: async () => {
+        return runtime.health.snapshot();
+      },
+    },
+    {
+      name: 'admin_subsystem_health',
+      description: 'Get health status of a specific subsystem.',
+      auth: 'read',
+      schema: z.object({
+        subsystem: z.string().describe('Subsystem name (e.g. "vault", "cognee", "llm")'),
+      }),
+      handler: async (params) => {
+        const sub = runtime.health.get(params.subsystem as string);
+        if (!sub) {
+          const snapshot = runtime.health.snapshot();
+          return {
+            error: `Unknown subsystem: ${params.subsystem}`,
+            available: Object.keys(snapshot.subsystems),
+          };
+        }
+        return sub;
+      },
+    },
+
+    // ─── Feature Flags (#173) ───────────────────────────────────────
+    {
+      name: 'admin_list_flags',
+      description:
+        'List all feature flags with current state, description, and source (default/env/runtime).',
+      auth: 'read',
+      handler: async () => {
+        return runtime.flags.getAll();
+      },
+    },
+    {
+      name: 'admin_get_flag',
+      description: 'Get the current value of a specific feature flag.',
+      auth: 'read',
+      schema: z.object({
+        flag: z.string().describe('Flag name (e.g. "auth-enforcement", "cognee-sync")'),
+      }),
+      handler: async (params) => {
+        const flag = params.flag as string;
+        const all = runtime.flags.getAll();
+        const info = all[flag];
+        if (!info) {
+          return { error: `Unknown flag: ${flag}`, availableFlags: Object.keys(all) };
+        }
+        return { flag, ...info };
+      },
+    },
+    {
+      name: 'admin_set_flag',
+      description: 'Set a feature flag at runtime. Persists to flags.json.',
+      auth: 'admin',
+      schema: z.object({
+        flag: z.string().describe('Flag name'),
+        enabled: z.boolean().describe('Enable (true) or disable (false)'),
+      }),
+      handler: async (params) => {
+        const flag = params.flag as string;
+        const enabled = params.enabled as boolean;
+        runtime.flags.set(flag, enabled);
+        return { flag, enabled, persisted: true };
+      },
+    },
+
     // ─── Persistence ────────────────────────────────────────────────
     {
       name: 'admin_persistence_info',
@@ -681,5 +765,106 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return { backend, tables };
       },
     },
+
+    // ─── Setup Wizard (#182) ─────────────────────────────────────────
+    {
+      name: 'admin_setup_check',
+      description:
+        'Check agent setup status — vault health, brain vocabulary, cognee connection, LLM keys, templates.',
+      auth: 'read',
+      handler: async () => {
+        const checks: Record<string, { ok: boolean; detail: string }> = {};
+
+        // Vault
+        try {
+          const stats = vault.stats();
+          checks.vault = {
+            ok: true,
+            detail: `${stats.totalEntries} entries, ${Object.keys(stats.byDomain).length} domains`,
+          };
+        } catch (err) {
+          checks.vault = { ok: false, detail: err instanceof Error ? err.message : 'Failed' };
+        }
+
+        // Brain vocabulary
+        try {
+          const brainStats = brain.getStats();
+          checks.brain = {
+            ok: brainStats.vocabularySize > 0,
+            detail: `${brainStats.vocabularySize} terms`,
+          };
+        } catch {
+          checks.brain = { ok: false, detail: 'Brain not initialized' };
+        }
+
+        // Cognee
+        const cogneeStatus = cognee.getStatus();
+        checks.cognee = {
+          ok: cogneeStatus?.available ?? false,
+          detail: cogneeStatus?.available ? 'Connected' : 'Not available (optional)',
+        };
+
+        // LLM keys
+        const llmAvail = runtime.llmClient.isAvailable();
+        checks.llm = {
+          ok: llmAvail.openai || llmAvail.anthropic,
+          detail: `OpenAI: ${llmAvail.openai ? 'yes' : 'no'}, Anthropic: ${llmAvail.anthropic ? 'yes' : 'no'}`,
+        };
+
+        // Health registry
+        const healthSnap = runtime.health.snapshot();
+        checks.health = {
+          ok: healthSnap.overall !== 'down',
+          detail: `Overall: ${healthSnap.overall}`,
+        };
+
+        const allOk = Object.values(checks).every((c) => c.ok);
+
+        return {
+          ready: allOk,
+          checks,
+          agentId: runtime.config.agentId,
+        };
+      },
+    },
+    {
+      name: 'admin_setup_run',
+      description:
+        'Run first-time agent setup — rebuild brain vocabulary, validate vault schema, seed defaults if empty.',
+      auth: 'admin',
+      handler: async () => {
+        const actions: string[] = [];
+
+        // Rebuild brain vocabulary
+        try {
+          brain.rebuildVocabulary();
+          actions.push('brain_vocabulary_rebuilt');
+        } catch {
+          // Non-fatal
+        }
+
+        // Rebuild FTS index
+        try {
+          vault.rebuildFtsIndex();
+          actions.push('fts_index_rebuilt');
+        } catch {
+          // Non-fatal
+        }
+
+        // Reload templates
+        try {
+          runtime.templateManager.load();
+          actions.push('templates_reloaded');
+        } catch {
+          // Non-fatal
+        }
+
+        return {
+          setup: true,
+          actions,
+          agentId: runtime.config.agentId,
+        };
+      },
+    },
   ];
 }

package/src/runtime/capture-ops.ts

@@ -8,6 +8,8 @@
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { detectScope } from '../vault/scope-detector.js';
+import type { ScopeTier, ScopeDetectionResult } from '../vault/scope-detector.js';
 
 /**
  * Create the 4 intelligent capture operations for an agent runtime.
@@ -26,6 +28,10 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'write',
       schema: z.object({
         projectPath: z.string().optional().default('.'),
+        tier: z
+          .enum(['agent', 'project', 'team'])
+          .optional()
+          .describe('Manual tier override. If omitted, tier is auto-detected from content.'),
         entries: z.array(
           z.object({
             id: z.string().optional(),
@@ -49,11 +55,16 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
             example: z.string().optional(),
             counterExample: z.string().optional(),
             why: z.string().optional(),
+            tier: z
+              .enum(['agent', 'project', 'team'])
+              .optional()
+              .describe('Per-entry tier override. Falls back to top-level tier, then auto-detect.'),
           }),
         ),
       }),
       handler: async (params) => {
         const projectPath = (params.projectPath as string | undefined) ?? '.';
+        const topTier = params.tier as ScopeTier | undefined;
         const entries = params.entries as Array<{
           id?: string;
           type: string;
@@ -66,12 +77,19 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           example?: string;
           counterExample?: string;
           why?: string;
+          tier?: ScopeTier;
         }>;
 
         let captured = 0;
         let proposed = 0;
         let rejected = 0;
-        const results: Array<{ id: string; action: string; reason?: string }> = [];
+        let duplicated = 0;
+        const results: Array<{
+          id: string;
+          action: string;
+          reason?: string;
+          scope?: { tier: ScopeTier; confidence: string; reason: string };
+        }> = [];
 
         for (const entry of entries) {
           const entryId =
@@ -79,6 +97,22 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           const mappedSeverity = mapSeverity(entry.severity);
           const mappedType = mapType(entry.type);
 
+          // Scope detection: per-entry tier > top-level tier > auto-detect
+          const resolvedTier = entry.tier ?? topTier;
+          let scopeResult: ScopeDetectionResult | undefined;
+          let finalTier: ScopeTier;
+          if (resolvedTier) {
+            finalTier = resolvedTier;
+          } else {
+            scopeResult = detectScope({
+              title: entry.title,
+              description: entry.description,
+              category: entry.domain,
+              tags: entry.tags,
+            });
+            finalTier = scopeResult.tier;
+          }
+
           try {
             const decision = governance.evaluateCapture(projectPath, {
               type: mappedType,
@@ -89,7 +123,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
             switch (decision.action) {
               case 'capture': {
                 try {
-                  brain.enrichAndCapture({
+                  const captureResult = brain.enrichAndCapture({
                     id: entryId,
                     type: mappedType as 'pattern' | 'anti-pattern' | 'rule' | 'playbook',
                     domain: entry.domain,
@@ -101,9 +135,39 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                     example: entry.example,
                     counterExample: entry.counterExample,
                     why: entry.why,
+                    tier: finalTier,
                   });
-                  captured++;
-                  results.push({ id: entryId, action: 'capture' });
+                  const scopeMeta = scopeResult
+                    ? {
+                        tier: scopeResult.tier,
+                        confidence: scopeResult.confidence,
+                        reason: scopeResult.reason,
+                      }
+                    : {
+                        tier: finalTier,
+                        confidence: 'MANUAL' as const,
+                        reason: 'explicit override',
+                      };
+                  if (captureResult.blocked) {
+                    duplicated++;
+                    results.push({
+                      id: captureResult.duplicate?.id ?? entryId,
+                      action: 'duplicate',
+                      scope: scopeMeta,
+                    });
+                  } else {
+                    captured++;
+                    const result: (typeof results)[number] = {
+                      id: entryId,
+                      action: 'capture',
+                      scope: scopeMeta,
+                    };
+                    if (scopeResult?.confidence === 'LOW') {
+                      result.reason =
+                        'Low confidence scope detection — consider reviewing tier assignment';
+                    }
+                    results.push(result);
+                  }
                 } catch (err) {
                   rejected++;
                   results.push({
@@ -163,7 +227,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           }
         }
 
-        return { captured, proposed, rejected, results };
+        return { captured, proposed, rejected, duplicated, results };
       },
     },
 
@@ -189,6 +253,10 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
         title: z.string(),
         description: z.string(),
         tags: z.array(z.string()).optional().default([]),
+        tier: z
+          .enum(['agent', 'project', 'team'])
+          .optional()
+          .describe('Manual tier override. If omitted, tier is auto-detected from content.'),
       }),
       handler: async (params) => {
         const projectPath = (params.projectPath as string | undefined) ?? '.';
@@ -197,11 +265,29 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
         const title = params.title as string;
         const description = params.description as string;
         const tags = (params.tags as string[] | undefined) ?? [];
+        const manualTier = params.tier as ScopeTier | undefined;
 
-        const id = `${domain}-${Date.now()}`;
+        const id = `${domain}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         const mappedSeverity = 'info' as const;
         const mappedType = mapType(entryType);
 
+        // Scope detection
+        let scopeResult: ScopeDetectionResult | undefined;
+        let finalTier: ScopeTier;
+        if (manualTier) {
+          finalTier = manualTier;
+        } else {
+          scopeResult = detectScope({ title, description, category: domain, tags });
+          finalTier = scopeResult.tier;
+        }
+        const scopeMeta = scopeResult
+          ? {
+              tier: scopeResult.tier,
+              confidence: scopeResult.confidence,
+              reason: scopeResult.reason,
+            }
+          : { tier: finalTier, confidence: 'MANUAL' as const, reason: 'explicit override' };
+
         try {
           const decision = governance.evaluateCapture(projectPath, {
             type: mappedType,
@@ -212,7 +298,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           switch (decision.action) {
             case 'capture': {
               try {
-                brain.enrichAndCapture({
+                const captureResult = brain.enrichAndCapture({
                   id,
                   type: mappedType as 'pattern' | 'anti-pattern' | 'rule' | 'playbook',
                   domain,
@@ -220,8 +306,27 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                   severity: mapSeverity(mappedSeverity),
                   description,
                   tags,
+                  tier: finalTier,
                 });
-                return { captured: true, id, governance: { action: 'capture' as const } };
+                if (captureResult.blocked) {
+                  return {
+                    captured: false,
+                    id: captureResult.duplicate?.id ?? id,
+                    governance: { action: 'duplicate' as const },
+                    scope: scopeMeta,
+                  };
+                }
+                const result: Record<string, unknown> = {
+                  captured: true,
+                  id,
+                  governance: { action: 'capture' as const },
+                  scope: scopeMeta,
+                };
+                if (scopeResult?.confidence === 'LOW') {
+                  result.reviewNote =
+                    'Low confidence scope detection — consider reviewing tier assignment';
+                }
+                return result;
               } catch (err) {
                 return {
                   captured: false,

package/src/runtime/deprecation.ts

@@ -0,0 +1,58 @@
+/**
+ * Deprecation utilities — log warnings for deprecated ops with migration paths.
+ *
+ * Follows Soleri's semver policy:
+ * 1. Op marked deprecated → logs warning (minor version)
+ * 2. Warning persists for 2+ minor versions
+ * 3. Op removed (next major version)
+ */
+
+const warned = new Set<string>();
+
+export interface DeprecationInfo {
+  /** The deprecated op/function name */
+  name: string;
+  /** Version when it was deprecated */
+  since: string;
+  /** Version when it will be removed */
+  removeIn?: string;
+  /** What to use instead */
+  replacement?: string;
+  /** Additional migration guidance */
+  message?: string;
+}
+
+/**
+ * Log a deprecation warning (once per op per process lifetime).
+ */
+export function deprecationWarning(info: DeprecationInfo): void {
+  if (warned.has(info.name)) return;
+  warned.add(info.name);
+
+  const parts = [`[DEPRECATED] "${info.name}" is deprecated since v${info.since}.`];
+  if (info.replacement) parts.push(`Use "${info.replacement}" instead.`);
+  if (info.removeIn) parts.push(`Will be removed in v${info.removeIn}.`);
+  if (info.message) parts.push(info.message);
+
+  console.warn(parts.join(' '));
+}
+
+/**
+ * Create a deprecated op handler that wraps the real handler with a warning.
+ */
+export function wrapDeprecated<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  info: DeprecationInfo,
+): T {
+  return ((...args: unknown[]) => {
+    deprecationWarning(info);
+    return fn(...args);
+  }) as T;
+}
+
+/**
+ * Clear warned set (for testing).
+ */
+export function resetDeprecationWarnings(): void {
+  warned.clear();
+}

package/src/runtime/domain-ops.ts

@@ -59,11 +59,30 @@ export function createDomainFacade(
         limit: z.number().optional(),
       }),
       handler: async (params) => {
-        return brain.intelligentSearch(params.query as string, {
+        const limit = (params.limit as number) ?? 10;
+        const results = await brain.intelligentSearch(params.query as string, {
           domain,
           tags: params.tags as string[] | undefined,
-          limit: (params.limit as number) ?? 10,
+          limit,
         });
+        // Fallback: when brain returns empty, try vault FTS directly
+        if (results.length === 0) {
+          const ftsResults = vault.search(params.query as string, { domain, limit });
+          return ftsResults.map((r) => ({
+            entry: r.entry,
+            score: 0,
+            breakdown: {
+              semantic: 0,
+              vector: 0,
+              severity: 0,
+              temporalDecay: 0,
+              tagOverlap: 0,
+              domainMatch: 0,
+              total: 0,
+            },
+          }));
+        }
+        return results;
       },
     },
     {

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

@@ -8,11 +8,14 @@ import type { OpDefinition } from '../../facades/types.js';
 import type { AgentRuntime } from '../types.js';
 import { createAdminOps } from '../admin-ops.js';
 import { createAdminExtraOps } from '../admin-extra-ops.js';
+import { createPluginOps } from '../plugin-ops.js';
+import { createPackOps } from '../pack-ops.js';
+import { createTelemetryOps } from '../telemetry-ops.js';
 
 export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
   const { llmClient, keyPool } = runtime;
 
-  return [
+  const ops: OpDefinition[] = [
     // ─── LLM (inline from core-ops.ts) ──────────────────────────
     {
       name: 'llm_rotate',
@@ -98,4 +101,16 @@ export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     ...createAdminOps(runtime),
     ...createAdminExtraOps(runtime),
   ];
+
+  // Plugin ops must mutate the same live op array that MCP dispatch reads.
+  const pluginOps = createPluginOps(runtime, ops);
+  ops.push(...pluginOps);
+
+  // Pack ops
+  ops.push(...createPackOps(runtime));
+
+  // Telemetry ops
+  ops.push(...createTelemetryOps(runtime));
+
+  return ops;
 }

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

@@ -0,0 +1,111 @@
+/**
+ * Agency facade — proactive file watching, pattern surfacing, warning detection.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+
+export function createAgencyFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { agencyManager } = runtime;
+
+  return [
+    {
+      name: 'agency_enable',
+      description:
+        'Enable agency mode — starts proactive file watching, pattern surfacing, and warning detection.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().describe('Project root to watch. Default: "."'),
+      }),
+      handler: async (params) => {
+        const projectPath = (params.projectPath as string) ?? '.';
+        agencyManager.enable(projectPath);
+        return agencyManager.getStatus();
+      },
+    },
+    {
+      name: 'agency_disable',
+      description: 'Disable agency mode — stops file watching and clears pending state.',
+      auth: 'write',
+      handler: async () => {
+        agencyManager.disable();
+        return agencyManager.getStatus();
+      },
+    },
+    {
+      name: 'agency_status',
+      description: 'Get agency mode status — enabled, watching, detectors, pending warnings.',
+      auth: 'read',
+      handler: async () => {
+        return agencyManager.getStatus();
+      },
+    },
+    {
+      name: 'agency_config',
+      description: 'Update agency configuration — watch paths, extensions, debounce, thresholds.',
+      auth: 'write',
+      schema: z.object({
+        watchPaths: z.array(z.string()).optional(),
+        ignorePatterns: z.array(z.string()).optional(),
+        extensions: z.array(z.string()).optional(),
+        debounceMs: z.number().optional(),
+        minPatternConfidence: z.number().optional(),
+        cooldownMs: z.number().optional(),
+      }),
+      handler: async (params) => {
+        agencyManager.updateConfig(params as Record<string, unknown>);
+        return agencyManager.getStatus();
+      },
+    },
+    {
+      name: 'agency_scan_file',
+      description: 'Manually scan a file for warnings using registered detectors.',
+      auth: 'read',
+      schema: z.object({
+        filePath: z.string().describe('Path to file to scan.'),
+      }),
+      handler: async (params) => {
+        const warnings = agencyManager.scanFile(params.filePath as string);
+        return { warnings, count: warnings.length };
+      },
+    },
+    {
+      name: 'agency_warnings',
+      description: 'Get all pending warnings from recent file scans.',
+      auth: 'read',
+      handler: async () => {
+        const warnings = agencyManager.getPendingWarnings();
+        return { warnings, count: warnings.length };
+      },
+    },
+    {
+      name: 'agency_surface_patterns',
+      description: 'Surface vault patterns relevant to a file change.',
+      auth: 'read',
+      schema: z.object({
+        filePath: z.string().describe('File path that changed.'),
+      }),
+      handler: async (params) => {
+        const patterns = agencyManager.surfacePatterns(params.filePath as string);
+        return { patterns, count: patterns.length };
+      },
+    },
+    {
+      name: 'agency_clarify',
+      description: 'Generate a clarification question when intent is ambiguous (low confidence).',
+      auth: 'read',
+      schema: z.object({
+        prompt: z.string().describe('The user prompt to analyze.'),
+        confidence: z.number().describe('Current intent classification confidence (0-1).'),
+      }),
+      handler: async (params) => {
+        const question = agencyManager.generateClarification(
+          params.prompt as string,
+          params.confidence as number,
+        );
+        return question ?? { clarificationNeeded: false };
+      },
+    },
+  ];
+}