@soleri/core 2.4.0 → 2.5.0

package/src/prompts/parser.ts

@@ -0,0 +1,59 @@
+/**
+ * Template parser — extract variables and resolve includes.
+ */
+
+import type { TemplateVariable } from './types.js';
+
+const VAR_PATTERN = /\{\{(\w+)(?::([^}]*))?\}\}/g;
+const INCLUDE_PATTERN = /@include\(([^)]+)\)/g;
+const MAX_INCLUDE_DEPTH = 10;
+
+/**
+ * Extract unique variables from template content.
+ * Supports {{name}} (required) and {{name:default}} (optional with default).
+ */
+export function parseVariables(content: string): TemplateVariable[] {
+  const seen = new Map<string, TemplateVariable>();
+
+  for (const match of content.matchAll(VAR_PATTERN)) {
+    const name = match[1];
+    const defaultValue = match[2];
+    if (!seen.has(name)) {
+      seen.set(name, {
+        name,
+        required: defaultValue === undefined,
+        defaultValue,
+      });
+    }
+  }
+
+  return Array.from(seen.values());
+}
+
+/**
+ * Resolve @include(partial-name) directives.
+ *
+ * The loader function receives the partial name and returns its content.
+ * Cycle detection prevents infinite recursion.
+ */
+export function resolveIncludes(
+  content: string,
+  loader: (name: string) => string,
+  _stack: Set<string> = new Set(),
+  _depth: number = 0,
+): string {
+  if (_depth > MAX_INCLUDE_DEPTH) {
+    throw new Error(`Include depth exceeded ${MAX_INCLUDE_DEPTH}. Possible circular include.`);
+  }
+
+  return content.replace(INCLUDE_PATTERN, (_match, partialName: string) => {
+    const trimmed = partialName.trim();
+    if (_stack.has(trimmed)) {
+      throw new Error(`Circular include detected: ${trimmed} (stack: ${[..._stack].join(' → ')})`);
+    }
+    const newStack = new Set(_stack);
+    newStack.add(trimmed);
+    const partialContent = loader(trimmed);
+    return resolveIncludes(partialContent, loader, newStack, _depth + 1);
+  });
+}

package/src/prompts/template-manager.ts

@@ -0,0 +1,77 @@
+/**
+ * Template manager — load, render, and list .prompt templates.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import type { PromptTemplate, RenderOptions } from './types.js';
+import { parseVariables, resolveIncludes } from './parser.js';
+
+const VAR_REGEX = /\{\{(\w+)(?::([^}]*))?\}\}/g;
+
+export class TemplateManager {
+  private templates = new Map<string, PromptTemplate>();
+  private templatesDir: string;
+
+  constructor(templatesDir: string) {
+    this.templatesDir = templatesDir;
+  }
+
+  /** Load all .prompt files from templatesDir. */
+  load(): void {
+    if (!existsSync(this.templatesDir)) return;
+
+    const files = readdirSync(this.templatesDir).filter((f) => f.endsWith('.prompt'));
+    for (const file of files) {
+      const fullPath = join(this.templatesDir, file);
+      const content = readFileSync(fullPath, 'utf-8');
+      const name = basename(file, '.prompt');
+      this.templates.set(name, {
+        name,
+        content,
+        variables: parseVariables(content),
+        path: fullPath,
+      });
+    }
+  }
+
+  /**
+   * Render a template by name with variable substitution.
+   *
+   * @param name - Template name (without .prompt extension)
+   * @param vars - Variable values to substitute
+   * @param options - Render options (strict mode)
+   * @throws If template not found, or strict mode and required variable missing
+   */
+  render(name: string, vars: Record<string, string> = {}, options?: RenderOptions): string {
+    const template = this.templates.get(name);
+    if (!template) throw new Error(`Template not found: ${name}`);
+
+    const strict = options?.strict ?? true;
+
+    // Resolve @include() directives
+    const resolved = resolveIncludes(template.content, (partialName) => {
+      const partial = this.templates.get(partialName);
+      if (!partial) throw new Error(`Include not found: ${partialName} (in template: ${name})`);
+      return partial.content;
+    });
+
+    // Replace {{var}} and {{var:default}}
+    return resolved.replace(VAR_REGEX, (_match, varName: string, defaultValue?: string) => {
+      if (vars[varName] !== undefined) return vars[varName];
+      if (defaultValue !== undefined) return defaultValue;
+      if (strict) throw new Error(`Missing required variable: ${varName} (in template: ${name})`);
+      return _match; // Leave placeholder as-is in non-strict mode
+    });
+  }
+
+  /** List all loaded template names. */
+  listTemplates(): string[] {
+    return Array.from(this.templates.keys());
+  }
+
+  /** Get a template by name (raw, unrendered). */
+  getTemplate(name: string): PromptTemplate | null {
+    return this.templates.get(name) ?? null;
+  }
+}

package/src/prompts/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Prompt template types.
+ */
+
+export interface TemplateVariable {
+  /** Variable name, e.g. 'agentName' */
+  name: string;
+  /** Whether the variable must be provided at render time. */
+  required: boolean;
+  /** Default value used when variable is not provided (makes required=false). */
+  defaultValue?: string;
+}
+
+export interface PromptTemplate {
+  /** Template name (filename without .prompt extension). */
+  name: string;
+  /** Raw template content before variable substitution. */
+  content: string;
+  /** Variables extracted from the template. */
+  variables: TemplateVariable[];
+  /** Absolute file path. */
+  path: string;
+}
+
+export interface RenderOptions {
+  /** If true (default), throw on missing required variables. */
+  strict?: boolean;
+}

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

@@ -1,18 +1,39 @@
 /**
- * Extended admin operations — 10 ops for production readiness.
+ * Extended admin operations — 23 ops for production readiness.
  *
  * Groups: telemetry (3), permissions (1), vault analytics (1),
- *         search insights (1), module status (1), env (1), gc (1), export config (1).
+ *         search insights (1), module status (1), env (1), gc (1), export config (1),
+ *         key pool (4), profiles (5), plugins (2), instruction validation (1),
+ *         hot reload (1).
  */
 
 import { z } from 'zod';
+import { readFileSync, existsSync } from 'node:fs';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 
 type PermissionLevel = 'strict' | 'moderate' | 'permissive';
 
+interface ApiToken {
+  name: string;
+  role: string;
+  createdAt: number;
+}
+interface AccountProfile {
+  name: string;
+  provider: string;
+  active: boolean;
+  addedAt: number;
+}
+interface PluginInfo {
+  id: string;
+  name: string;
+  status: 'active' | 'inactive' | 'error';
+  opsCount: number;
+}
+
 /**
- * Create 10 extended admin operations for production observability.
+ * Create 23 extended admin operations for production observability.
  */
 export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
   const { vault, brain, cognee, telemetry } = runtime;
@@ -102,9 +123,9 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
             '90d+': 0,
           };
 
-          const rows = db
-            .prepare('SELECT created_at FROM entries')
-            .all() as Array<{ created_at: number }>;
+          const rows = db.prepare('SELECT created_at FROM entries').all() as Array<{
+            created_at: number;
+          }>;
 
           for (const row of rows) {
             const ageSeconds = now - row.created_at;
@@ -115,9 +136,7 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
           }
 
           // Average tags per entry
-          const tagRows = db
-            .prepare('SELECT tags FROM entries')
-            .all() as Array<{ tags: string }>;
+          const tagRows = db.prepare('SELECT tags FROM entries').all() as Array<{ tags: string }>;
 
           let totalTags = 0;
           let noTags = 0;
@@ -135,7 +154,9 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
 
           // Entries without descriptions
           const noDescResult = db
-            .prepare("SELECT COUNT(*) as count FROM entries WHERE description IS NULL OR description = ''")
+            .prepare(
+              "SELECT COUNT(*) as count FROM entries WHERE description IS NULL OR description = ''",
+            )
             .get() as { count: number } | undefined;
           noDescription = noDescResult?.count ?? 0;
 
@@ -146,12 +167,16 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
             byDomain: Object.fromEntries(byDomain.map((r) => [r.domain, r.count])),
             byType: Object.fromEntries(byType.map((r) => [r.type, r.count])),
             byAge: ageBuckets,
-            avgTagsPerEntry: totalEntries > 0 ? Math.round((totalTags / totalEntries) * 10) / 10 : 0,
+            avgTagsPerEntry:
+              totalEntries > 0 ? Math.round((totalTags / totalEntries) * 10) / 10 : 0,
             entriesWithoutTags: noTags,
             entriesWithoutDescription: noDescription,
           };
         } catch (err) {
-          return { error: 'Failed to compute vault analytics', detail: err instanceof Error ? err.message : String(err) };
+          return {
+            error: 'Failed to compute vault analytics',
+            detail: err instanceof Error ? err.message : String(err),
+          };
         }
       },
     },
@@ -185,7 +210,7 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
             topMissedQueries: missedQueries,
             byAction: feedbackStats.byAction,
           };
-        } catch (err) {
+        } catch {
           return {
             totalFeedback: 0,
             missRate: 0,
@@ -303,5 +328,325 @@ export function createAdminExtraOps(runtime: AgentRuntime): OpDefinition[] {
         };
       },
     },
+
+    // ─── Key Pool (#157) ──────────────────────────────────────────
+    {
+      name: 'admin_key_pool_status',
+      description:
+        'LLM key pool status — pool size, active key index, per-key circuit breaker state (open/closed/half-open).',
+      auth: 'read',
+      handler: async () => {
+        const available = runtime.llmClient.isAvailable();
+        return {
+          openai: {
+            available: available.openai,
+          },
+          anthropic: {
+            available: available.anthropic,
+          },
+        };
+      },
+    },
+    {
+      name: 'admin_create_token',
+      description: 'Create a named API token with role-based access.',
+      auth: 'admin',
+      schema: z.object({
+        name: z.string().describe('Token name (unique identifier)'),
+        role: z.enum(['read', 'write', 'admin']).describe('Access role'),
+      }),
+      handler: async (params) => {
+        const token: ApiToken = {
+          name: params.name as string,
+          role: params.role as string,
+          createdAt: Date.now(),
+        };
+        // Store in vault metadata
+        vault.add({
+          id: `api-token-${token.name}`,
+          type: 'rule',
+          domain: 'admin',
+          title: `API Token: ${token.name}`,
+          severity: 'suggestion',
+          description: `API token with ${token.role} access`,
+          tags: ['api-token', token.role],
+        });
+        return { created: true, name: token.name, role: token.role };
+      },
+    },
+    {
+      name: 'admin_revoke_token',
+      description: 'Revoke (delete) a named API token.',
+      auth: 'admin',
+      schema: z.object({
+        name: z.string().describe('Token name to revoke'),
+      }),
+      handler: async (params) => {
+        const removed = vault.remove(`api-token-${params.name}`);
+        return { revoked: removed, name: params.name };
+      },
+    },
+    {
+      name: 'admin_list_tokens',
+      description: 'List all API tokens (names and roles only, no secrets).',
+      auth: 'read',
+      handler: async () => {
+        const entries = vault.list({ domain: 'admin' });
+        const tokens = entries
+          .filter((e) => e.id.startsWith('api-token-'))
+          .map((e) => ({
+            name: e.id.replace('api-token-', ''),
+            role: e.tags?.find((t) => ['read', 'write', 'admin'].includes(t)) ?? 'unknown',
+          }));
+        return { tokens, count: tokens.length };
+      },
+    },
+
+    // ─── Account Profiles (#158) ─────────────────────────────────
+    {
+      name: 'admin_add_account',
+      description: 'Add an API account profile. Keys are stored in vault, never exposed.',
+      auth: 'admin',
+      schema: z.object({
+        name: z.string().describe('Profile name'),
+        provider: z.enum(['openai', 'anthropic']).describe('API provider'),
+      }),
+      handler: async (params) => {
+        const profile: AccountProfile = {
+          name: params.name as string,
+          provider: params.provider as string,
+          active: false,
+          addedAt: Date.now(),
+        };
+        vault.add({
+          id: `account-profile-${profile.name}`,
+          type: 'rule',
+          domain: 'admin',
+          title: `Account: ${profile.name} (${profile.provider})`,
+          severity: 'suggestion',
+          description: `API account profile for ${profile.provider}`,
+          tags: ['account-profile', profile.provider],
+        });
+        return { added: true, name: profile.name, provider: profile.provider };
+      },
+    },
+    {
+      name: 'admin_remove_account',
+      description: 'Remove an API account profile.',
+      auth: 'admin',
+      schema: z.object({
+        name: z.string().describe('Profile name to remove'),
+      }),
+      handler: async (params) => {
+        const removed = vault.remove(`account-profile-${params.name}`);
+        return { removed, name: params.name };
+      },
+    },
+    {
+      name: 'admin_rotate_account',
+      description: 'Rotate to a different API account profile.',
+      auth: 'admin',
+      schema: z.object({
+        name: z.string().describe('Profile name to activate'),
+      }),
+      handler: async (params) => {
+        const entry = vault.get(`account-profile-${params.name}`);
+        if (!entry) return { error: `Account profile not found: ${params.name}` };
+        return {
+          rotated: true,
+          name: params.name,
+          note: 'Profile activated (key rotation requires restart)',
+        };
+      },
+    },
+    {
+      name: 'admin_list_accounts',
+      description: 'List all account profiles (names and providers only, no keys).',
+      auth: 'read',
+      handler: async () => {
+        const entries = vault.list({ domain: 'admin' });
+        const accounts = entries
+          .filter((e) => e.id.startsWith('account-profile-'))
+          .map((e) => ({
+            name: e.id.replace('account-profile-', ''),
+            provider: e.tags?.find((t) => ['openai', 'anthropic'].includes(t)) ?? 'unknown',
+          }));
+        return { accounts, count: accounts.length };
+      },
+    },
+    {
+      name: 'admin_account_status',
+      description: 'Get current active account profile status.',
+      auth: 'read',
+      handler: async () => {
+        const available = runtime.llmClient.isAvailable();
+        return {
+          openai: { available: available.openai },
+          anthropic: { available: available.anthropic },
+        };
+      },
+    },
+
+    // ─── Plugins (#159) ──────────────────────────────────────────
+    {
+      name: 'admin_list_plugins',
+      description: 'List all registered domain plugins and their status.',
+      auth: 'read',
+      handler: async () => {
+        // Plugins are domain facades — discover via vault domains
+        const domains = vault.getDomains();
+        const plugins: PluginInfo[] = domains
+          .filter((d) => d.domain !== 'admin' && d.domain !== 'planning')
+          .map((d) => ({
+            id: d.domain,
+            name: d.domain,
+            status: 'active' as const,
+            opsCount: 5, // standard domain ops: get_patterns, search, get_entry, capture, remove
+          }));
+        return { plugins, count: plugins.length };
+      },
+    },
+    {
+      name: 'admin_plugin_status',
+      description: 'Get detailed status of a specific plugin (domain facade).',
+      auth: 'read',
+      schema: z.object({
+        pluginId: z.string().describe('Plugin/domain ID'),
+      }),
+      handler: async (params) => {
+        const domainId = params.pluginId as string;
+        const domainEntries = vault.list({ domain: domainId });
+        if (domainEntries.length === 0) {
+          return { error: `Plugin not found or empty: ${domainId}` };
+        }
+        return {
+          id: domainId,
+          status: 'active',
+          entryCount: domainEntries.length,
+          opsCount: 5,
+          ops: ['get_patterns', 'search', 'get_entry', 'capture', 'remove'],
+        };
+      },
+    },
+
+    // ─── Hot Reload (#63) ──────────────────────────────────────
+    {
+      name: 'admin_hot_reload',
+      description:
+        'Hot-reload runtime caches — rebuilds brain vocabulary, vault FTS index, and prompt templates. Use after bulk vault changes.',
+      auth: 'write',
+      handler: async () => {
+        const reloaded: string[] = [];
+        let brainTerms = 0;
+        let templateCount = 0;
+
+        try {
+          brain.rebuildVocabulary();
+          brainTerms = brain.getStats().vocabularySize;
+          reloaded.push('brain');
+        } catch {
+          // Graceful degradation
+        }
+
+        try {
+          vault.rebuildFtsIndex();
+          reloaded.push('vault_fts');
+        } catch {
+          // Graceful degradation
+        }
+
+        try {
+          runtime.templateManager.load();
+          templateCount = runtime.templateManager.listTemplates().length;
+          reloaded.push('templates');
+        } catch {
+          // Graceful degradation
+        }
+
+        return { reloaded, brainTerms, templateCount };
+      },
+    },
+
+    // ─── Instruction Validation (#160) ───────────────────────────
+    {
+      name: 'admin_validate_instructions',
+      description:
+        'Validate instruction files (CLAUDE.md, SKILL.md) for governance and quality — checks structure, required fields, formatting.',
+      auth: 'read',
+      schema: z.object({
+        filePath: z.string().describe('Path to the instruction file to validate'),
+      }),
+      handler: async (params) => {
+        try {
+          const filePath = params.filePath as string;
+          if (!existsSync(filePath)) {
+            return { valid: false, errors: [{ line: 0, issue: 'File not found' }] };
+          }
+
+          const content = readFileSync(filePath, 'utf-8');
+          const errors: Array<{ line: number; issue: string }> = [];
+          const warnings: Array<{ line: number; issue: string }> = [];
+
+          // Check for YAML frontmatter (SKILL.md files)
+          if (filePath.endsWith('SKILL.md') || filePath.includes('/skills/')) {
+            if (!content.startsWith('---')) {
+              errors.push({ line: 1, issue: 'SKILL.md must start with YAML frontmatter (---)' });
+            } else {
+              const fmEnd = content.indexOf('---', 3);
+              if (fmEnd === -1) {
+                errors.push({
+                  line: 1,
+                  issue: 'YAML frontmatter not closed (missing closing ---)',
+                });
+              } else {
+                const fm = new Set(content.slice(3, fmEnd));
+                if (!fm.has('name:'))
+                  errors.push({ line: 1, issue: 'Missing required field: name' });
+                if (!fm.has('description:'))
+                  errors.push({ line: 1, issue: 'Missing required field: description' });
+              }
+            }
+          }
+
+          // General checks for any instruction file
+          const lines = content.split('\n');
+          for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Check for extremely long lines
+            if (line.length > 500) {
+              warnings.push({ line: i + 1, issue: `Line too long (${line.length} chars)` });
+            }
+          }
+
+          // Check for conflicting instructions
+          if (content.includes('ALWAYS') && content.includes('NEVER')) {
+            const alwaysLines = lines.filter((l) => l.includes('ALWAYS'));
+            const neverLines = lines.filter((l) => l.includes('NEVER'));
+            if (alwaysLines.length > 5 && neverLines.length > 5) {
+              warnings.push({
+                line: 0,
+                issue: 'Many ALWAYS/NEVER directives — check for contradictions',
+              });
+            }
+          }
+
+          // Check for empty content
+          if (content.trim().length < 10) {
+            errors.push({ line: 1, issue: 'File is essentially empty' });
+          }
+
+          return {
+            valid: errors.length === 0,
+            filePath,
+            errors,
+            warnings,
+            lineCount: lines.length,
+            charCount: content.length,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
   ];
 }

package/src/runtime/admin-ops.ts

@@ -41,7 +41,7 @@ function getCoreVersion(): string {
  * Groups: health (1), introspection (4), diagnostics (2), mutation (1).
  */
 export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
-  const { vault, brain, brainIntelligence, cognee, llmClient, keyPool, curator } = runtime;
+  const { vault, brain, brainIntelligence, cognee, llmClient, curator } = runtime;
 
   return [
     // ─── Health ──────────────────────────────────────────────────────
@@ -61,7 +61,10 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
           vault: { entries: vaultStats.totalEntries, domains: Object.keys(vaultStats.byDomain) },
           cognee: { available: cogneeStatus?.available ?? false },
           llm: llmAvailable,
-          brain: { vocabularySize: brainStats.vocabularySize, feedbackCount: brainStats.feedbackCount },
+          brain: {
+            vocabularySize: brainStats.vocabularySize,
+            feedbackCount: brainStats.feedbackCount,
+          },
           curator: { initialized: curatorStatus.initialized },
         };
       },
@@ -75,7 +78,9 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
       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;
+        const allOps = params._allOps as
+          | Array<{ name: string; description: string; auth: string }>
+          | undefined;
         if (allOps) {
           return {
             count: allOps.length,
@@ -119,7 +124,8 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
     },
     {
       name: 'admin_vault_size',
-      description: 'Get vault database file size on disk (bytes). Returns null for in-memory vaults.',
+      description:
+        'Get vault database file size on disk (bytes). Returns null for in-memory vaults.',
       auth: 'read',
       handler: async () => {
         const dbPath = runtime.config.vaultPath;
@@ -168,7 +174,8 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
     // ─── Mutation ────────────────────────────────────────────────────
     {
       name: 'admin_reset_cache',
-      description: 'Clear all caches — brain vocabulary and cognee health cache. Forces fresh data on next access.',
+      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)
@@ -247,7 +254,11 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
         try {
           const cogneeStatus = cognee.getStatus();
           if (cogneeStatus?.available) {
-            checks.push({ name: 'cognee', status: 'ok', detail: `Connected to ${cogneeStatus.url}` });
+            checks.push({
+              name: 'cognee',
+              status: 'ok',
+              detail: `Connected to ${cogneeStatus.url}`,
+            });
           } else {
             checks.push({
               name: 'cognee',