@soleri/core 2.1.0 → 2.5.0

package/src/runtime/admin-ops.ts

@@ -0,0 +1,340 @@
+/**
+ * Admin / infrastructure operations — 8 ops for agent self-management.
+ *
+ * These ops let agents introspect their own health, configuration, and
+ * runtime state. No new modules needed — uses existing runtime parts.
+ */
+
+import { readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+/**
+ * Resolve the @soleri/core package.json version.
+ * Walks up from this file's directory to find the closest package.json.
+ */
+function getCoreVersion(): string {
+  try {
+    // __dirname equivalent for ESM
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    // Walk up until we find package.json
+    let dir = thisDir;
+    for (let i = 0; i < 5; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        return pkg.version ?? 'unknown';
+      } catch {
+        dir = dirname(dir);
+      }
+    }
+  } catch {
+    // Fallback — import.meta.url may not be available in some test envs
+  }
+  return 'unknown';
+}
+
+/**
+ * Create the 8 admin/infrastructure operations for an agent runtime.
+ *
+ * Groups: health (1), introspection (4), diagnostics (2), mutation (1).
+ */
+export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, brain, brainIntelligence, cognee, llmClient, curator } = runtime;
+
+  return [
+    // ─── Health ──────────────────────────────────────────────────────
+    {
+      name: 'admin_health',
+      description: 'Comprehensive agent health check — vault, cognee, LLM, brain status.',
+      auth: 'read',
+      handler: async () => {
+        const vaultStats = vault.stats();
+        const cogneeStatus = cognee.getStatus();
+        const llmAvailable = llmClient.isAvailable();
+        const brainStats = brain.getStats();
+        const curatorStatus = curator.getStatus();
+
+        return {
+          status: 'ok',
+          vault: { entries: vaultStats.totalEntries, domains: Object.keys(vaultStats.byDomain) },
+          cognee: { available: cogneeStatus?.available ?? false },
+          llm: llmAvailable,
+          brain: {
+            vocabularySize: brainStats.vocabularySize,
+            feedbackCount: brainStats.feedbackCount,
+          },
+          curator: { initialized: curatorStatus.initialized },
+        };
+      },
+    },
+
+    // ─── Introspection ───────────────────────────────────────────────
+    {
+      name: 'admin_tool_list',
+      description: 'List all available ops with descriptions and auth levels.',
+      auth: 'read',
+      handler: async (params) => {
+        // The caller can pass in the full ops list via `_allOps` (injected by
+        // the facade builder). If not provided, we return only admin ops.
+        const allOps = params._allOps as
+          | Array<{ name: string; description: string; auth: string }>
+          | undefined;
+        if (allOps) {
+          return {
+            count: allOps.length,
+            ops: allOps.map((op) => ({
+              name: op.name,
+              description: op.description,
+              auth: op.auth,
+            })),
+          };
+        }
+        // Fallback — just describe admin ops
+        return {
+          count: 8,
+          ops: [
+            { name: 'admin_health', auth: 'read' },
+            { name: 'admin_tool_list', auth: 'read' },
+            { name: 'admin_config', auth: 'read' },
+            { name: 'admin_vault_size', auth: 'read' },
+            { name: 'admin_uptime', auth: 'read' },
+            { name: 'admin_version', auth: 'read' },
+            { name: 'admin_reset_cache', auth: 'write' },
+            { name: 'admin_diagnostic', auth: 'read' },
+          ],
+        };
+      },
+    },
+    {
+      name: 'admin_config',
+      description: 'Get current runtime configuration — agentId, paths, log level.',
+      auth: 'read',
+      handler: async () => {
+        const { agentId, vaultPath, plansPath, dataDir, logLevel } = runtime.config;
+        return {
+          agentId,
+          vaultPath: vaultPath ?? null,
+          plansPath: plansPath ?? null,
+          dataDir: dataDir ?? null,
+          logLevel: logLevel ?? 'info',
+        };
+      },
+    },
+    {
+      name: 'admin_vault_size',
+      description:
+        'Get vault database file size on disk (bytes). Returns null for in-memory vaults.',
+      auth: 'read',
+      handler: async () => {
+        const dbPath = runtime.config.vaultPath;
+        if (!dbPath || dbPath === ':memory:') {
+          return { path: ':memory:', sizeBytes: null, sizeHuman: 'in-memory' };
+        }
+        try {
+          const stat = statSync(dbPath);
+          const sizeBytes = stat.size;
+          const sizeHuman = formatBytes(sizeBytes);
+          return { path: dbPath, sizeBytes, sizeHuman };
+        } catch {
+          return { path: dbPath, sizeBytes: null, sizeHuman: 'file not found' };
+        }
+      },
+    },
+    {
+      name: 'admin_uptime',
+      description: 'Time since runtime creation — seconds and human-readable.',
+      auth: 'read',
+      handler: async () => {
+        const uptimeMs = Date.now() - runtime.createdAt;
+        const uptimeSec = Math.floor(uptimeMs / 1000);
+        return {
+          createdAt: new Date(runtime.createdAt).toISOString(),
+          uptimeMs,
+          uptimeSec,
+          uptimeHuman: formatUptime(uptimeSec),
+        };
+      },
+    },
+    {
+      name: 'admin_version',
+      description: 'Package version info for @soleri/core and Node.js.',
+      auth: 'read',
+      handler: async () => {
+        return {
+          core: getCoreVersion(),
+          node: process.version,
+          platform: process.platform,
+          arch: process.arch,
+        };
+      },
+    },
+
+    // ─── Mutation ────────────────────────────────────────────────────
+    {
+      name: 'admin_reset_cache',
+      description:
+        'Clear all caches — brain vocabulary and cognee health cache. Forces fresh data on next access.',
+      auth: 'write',
+      handler: async () => {
+        // Rebuild brain vocabulary (clears old TF-IDF state, rebuilds from vault)
+        brain.rebuildVocabulary();
+
+        // Reset cognee health cache by checking health again (no direct reset method)
+        // The next isAvailable check will need a fresh health probe
+        const cogneeHealth = await cognee.healthCheck().catch(() => null);
+
+        return {
+          cleared: ['brain_vocabulary', 'cognee_health_cache'],
+          brainVocabularySize: brain.getStats().vocabularySize,
+          cogneeAvailable: cogneeHealth?.available ?? false,
+        };
+      },
+    },
+
+    // ─── Diagnostics ─────────────────────────────────────────────────
+    {
+      name: 'admin_diagnostic',
+      description: 'Run diagnostic checks and return a comprehensive report.',
+      auth: 'read',
+      handler: async () => {
+        const checks: Array<{ name: string; status: 'ok' | 'warn' | 'error'; detail: string }> = [];
+
+        // 1. Vault connectivity
+        try {
+          const stats = vault.stats();
+          checks.push({
+            name: 'vault',
+            status: 'ok',
+            detail: `${stats.totalEntries} entries across ${Object.keys(stats.byDomain).length} domains`,
+          });
+        } catch (err) {
+          checks.push({
+            name: 'vault',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        // 2. Brain vocabulary
+        try {
+          const brainStats = brain.getStats();
+          const status = brainStats.vocabularySize > 0 ? 'ok' : 'warn';
+          checks.push({
+            name: 'brain_vocabulary',
+            status,
+            detail: `${brainStats.vocabularySize} terms, ${brainStats.feedbackCount} feedback entries`,
+          });
+        } catch (err) {
+          checks.push({
+            name: 'brain_vocabulary',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        // 3. Brain intelligence
+        try {
+          const intStats = brainIntelligence.getStats();
+          checks.push({
+            name: 'brain_intelligence',
+            status: 'ok',
+            detail: `${intStats.strengths} strengths, ${intStats.sessions} sessions`,
+          });
+        } catch (err) {
+          checks.push({
+            name: 'brain_intelligence',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        // 4. Cognee availability
+        try {
+          const cogneeStatus = cognee.getStatus();
+          if (cogneeStatus?.available) {
+            checks.push({
+              name: 'cognee',
+              status: 'ok',
+              detail: `Connected to ${cogneeStatus.url}`,
+            });
+          } else {
+            checks.push({
+              name: 'cognee',
+              status: 'warn',
+              detail: cogneeStatus?.error ?? 'Not connected (no health check yet)',
+            });
+          }
+        } catch (err) {
+          checks.push({
+            name: 'cognee',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        // 5. LLM key pools
+        const llmStatus = llmClient.isAvailable();
+        checks.push({
+          name: 'llm_openai',
+          status: llmStatus.openai ? 'ok' : 'warn',
+          detail: llmStatus.openai ? 'Keys available' : 'No keys configured',
+        });
+        checks.push({
+          name: 'llm_anthropic',
+          status: llmStatus.anthropic ? 'ok' : 'warn',
+          detail: llmStatus.anthropic ? 'Keys available' : 'No keys configured',
+        });
+
+        // 6. Curator
+        try {
+          const curatorStatus = curator.getStatus();
+          checks.push({
+            name: 'curator',
+            status: curatorStatus.initialized ? 'ok' : 'error',
+            detail: curatorStatus.initialized ? 'Initialized' : 'Not initialized',
+          });
+        } catch (err) {
+          checks.push({
+            name: 'curator',
+            status: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+          });
+        }
+
+        const errorCount = checks.filter((c) => c.status === 'error').length;
+        const warnCount = checks.filter((c) => c.status === 'warn').length;
+        const overall = errorCount > 0 ? 'unhealthy' : warnCount > 0 ? 'degraded' : 'healthy';
+
+        return {
+          overall,
+          checks,
+          summary: `${checks.length} checks: ${checks.length - errorCount - warnCount} ok, ${warnCount} warn, ${errorCount} error`,
+        };
+      },
+    },
+  ];
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+function formatUptime(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${secs}s`;
+  const hours = Math.floor(minutes / 60);
+  const mins = minutes % 60;
+  if (hours < 24) return `${hours}h ${mins}m`;
+  const days = Math.floor(hours / 24);
+  const hrs = hours % 24;
+  return `${days}d ${hrs}h`;
+}