@soleri/core 2.9.0 → 2.11.0

package/src/plugins/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Plugin System — Types & Manifest Schema
+ *
+ * A plugin is a directory containing a `soleri-plugin.json` manifest
+ * and optionally additional intelligence data. Plugins register
+ * OpDefinition[] (facades) dynamically without re-scaffolding.
+ */
+
+import { z } from 'zod';
+import type { FacadeConfig } from '../facades/types.js';
+
+// =============================================================================
+// MANIFEST SCHEMA (validated at load time)
+// =============================================================================
+
+export const pluginManifestSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/, 'Plugin ID must be lowercase alphanumeric with hyphens'),
+  name: z.string().min(1),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver (x.y.z)'),
+  description: z.string().optional().default(''),
+  /** Domain this plugin provides knowledge/ops for */
+  domain: z.string().optional(),
+  /** Plugin IDs this plugin depends on (must be loaded first) */
+  dependencies: z.array(z.string()).optional().default([]),
+  /** Facade definitions — each becomes an MCP tool */
+  facades: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string().optional().default(''),
+        ops: z.array(
+          z.object({
+            name: z.string(),
+            description: z.string().optional().default(''),
+            auth: z.enum(['read', 'write', 'admin']).optional().default('read'),
+          }),
+        ),
+      }),
+    )
+    .optional()
+    .default([]),
+  /** Intelligence entries to seed into the vault */
+  intelligence: z
+    .array(
+      z.object({
+        id: z.string(),
+        type: z.string(),
+        domain: z.string().optional(),
+        title: z.string(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        description: z.string(),
+        tags: z.array(z.string()).optional().default([]),
+      }),
+    )
+    .optional()
+    .default([]),
+});
+
+export type PluginManifest = z.infer<typeof pluginManifestSchema>;
+
+// =============================================================================
+// PLUGIN TYPES
+// =============================================================================
+
+export type PluginStatus = 'registered' | 'active' | 'error' | 'deactivated';
+export type PluginProvenance = 'global' | 'project' | 'custom';
+
+/**
+ * A loaded plugin — manifest validated, ready for activation.
+ */
+export interface LoadedPlugin {
+  manifest: PluginManifest;
+  directory: string;
+  provenance: PluginProvenance;
+}
+
+/**
+ * A registered plugin in the runtime — tracks lifecycle state.
+ */
+export interface RegisteredPlugin {
+  id: string;
+  manifest: PluginManifest;
+  directory: string;
+  provenance: PluginProvenance;
+  status: PluginStatus;
+  error?: string;
+  facades: FacadeConfig[];
+  activatedAt?: number;
+  registeredAt: number;
+}
+
+/**
+ * Plugin facade builder — plugins provide this function to create ops
+ * that have access to the agent runtime.
+ *
+ * Plugin JS modules export: `export function createFacades(ctx): FacadeConfig[]`
+ */
+export type PluginFacadeBuilder = (ctx: PluginContext) => FacadeConfig[];
+
+/**
+ * Context passed to plugin facade builders during activation.
+ */
+export interface PluginContext {
+  /** The agent runtime — full access to vault, brain, planner, etc. */
+  runtime: unknown; // AgentRuntime — kept as unknown to avoid circular deps
+  /** The plugin's own manifest */
+  manifest: PluginManifest;
+  /** The plugin's directory on disk */
+  directory: string;
+}
+
+// =============================================================================
+// LOAD RESULT
+// =============================================================================
+
+export interface LoadResult {
+  loaded: LoadedPlugin[];
+  errors: Array<{ directory: string; error: string }>;
+}

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