@soleri/core 2.8.0 → 2.9.0

package/src/index.ts

@@ -29,8 +29,6 @@ export type {
   MergedPlaybook,
   PlaybookMatchResult,
 } from './playbooks/index.js';
-export { createPlaybookOps } from './runtime/playbook-ops.js';
-
 // ─── Text Utilities ─────────────────────────────────────────────────
 export {
   tokenize,
@@ -239,6 +237,10 @@ export {
 export { KeyPool, loadKeyPoolConfig } from './llm/key-pool.js';
 export type { KeyPoolFiles } from './llm/key-pool.js';
 
+// ─── Extensions ──────────────────────────────────────────────────────
+export type { AgentExtensions, OpMiddleware, MiddlewareContext } from './extensions/index.js';
+export { wrapWithMiddleware } from './extensions/index.js';
+
 // ─── Facades ─────────────────────────────────────────────────────────
 export { registerFacade, registerAllFacades } from './facades/facade-factory.js';
 export { facadeInputSchema } from './facades/types.js';
@@ -285,22 +287,8 @@ export type { LogLevel, LogEntry, LogContext, LoggerConfig } from './logging/typ
 
 // ─── Runtime Factory ────────────────────────────────────────────────
 export { createAgentRuntime } from './runtime/runtime.js';
-export { createCoreOps } from './runtime/core-ops.js';
+export { createSemanticFacades } from './runtime/facades/index.js';
 export { createDomainFacade, createDomainFacades } from './runtime/domain-ops.js';
-export { createPlanningExtraOps } from './runtime/planning-extra-ops.js';
-export { createMemoryExtraOps } from './runtime/memory-extra-ops.js';
-export { createVaultExtraOps } from './runtime/vault-extra-ops.js';
-export { createAdminOps } from './runtime/admin-ops.js';
-export { createAdminExtraOps } from './runtime/admin-extra-ops.js';
-export { createLoopOps } from './runtime/loop-ops.js';
-export { createOrchestrateOps } from './runtime/orchestrate-ops.js';
-export { createGradingOps } from './runtime/grading-ops.js';
-export { createCaptureOps } from './runtime/capture-ops.js';
-export { createCuratorExtraOps } from './runtime/curator-extra-ops.js';
-export { createProjectOps } from './runtime/project-ops.js';
-export { createMemoryCrossProjectOps } from './runtime/memory-cross-project-ops.js';
-export { createCogneeSyncOps } from './runtime/cognee-sync-ops.js';
-export { createIntakeOps } from './runtime/intake-ops.js';
 export type { AgentRuntimeConfig, AgentRuntime } from './runtime/types.js';
 
 // ─── Errors ────────────────────────────────────────────────────────────
@@ -337,6 +325,15 @@ export type {
   FtsSearchOptions,
 } from './persistence/index.js';
 
+// ─── Streams ──────────────────────────────────────────────────────────
+export { ReplayableStream } from './streams/index.js';
+export { normalize, collect } from './streams/index.js';
+export type { NestableInput } from './streams/index.js';
+
+// ─── Content Hashing ──────────────────────────────────────────────────
+export { computeContentHash } from './vault/content-hash.js';
+export type { HashableEntry } from './vault/content-hash.js';
+
 // ─── Prompts ───────────────────────────────────────────────────────────
 export { TemplateManager, parseVariables, resolveIncludes } from './prompts/index.js';
 export type { PromptTemplate, TemplateVariable, RenderOptions } from './prompts/index.js';

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

@@ -0,0 +1,101 @@
+/**
+ * Admin facade — infrastructure ops.
+ * health, config, telemetry, tokens, LLM, prompts.
+ */
+
+import { z } from 'zod';
+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';
+
+export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { llmClient, keyPool } = runtime;
+
+  return [
+    // ─── LLM (inline from core-ops.ts) ──────────────────────────
+    {
+      name: 'llm_rotate',
+      description:
+        'Force rotate the active API key for a provider. Useful when rate-limited or key is failing.',
+      auth: 'write',
+      schema: z.object({
+        provider: z.enum(['openai', 'anthropic']),
+      }),
+      handler: async (params) => {
+        const provider = params.provider as 'openai' | 'anthropic';
+        const pool = keyPool[provider];
+        if (!pool.hasKeys) return { rotated: false, error: `No ${provider} keys configured` };
+        const newKey = pool.rotateOnError();
+        return {
+          rotated: newKey !== null,
+          activeKeyIndex: pool.activeKeyIndex,
+          poolSize: pool.poolSize,
+          exhausted: pool.exhausted,
+        };
+      },
+    },
+    {
+      name: 'llm_call',
+      description: 'Make an LLM completion call. Uses model routing config and key pool rotation.',
+      auth: 'write',
+      schema: z.object({
+        systemPrompt: z.string().describe('System prompt for the LLM.'),
+        userPrompt: z.string().describe('User prompt / task input.'),
+        model: z
+          .string()
+          .optional()
+          .describe('Model name. Routed via model-routing.json if omitted.'),
+        temperature: z.number().optional().describe('Sampling temperature (0-2). Default 0.3.'),
+        maxTokens: z.number().optional().describe('Max output tokens. Default 500.'),
+        caller: z.string().optional().describe('Caller name for routing. Default "core-ops".'),
+        task: z.string().optional().describe('Task name for routing.'),
+      }),
+      handler: async (params) => {
+        return llmClient.complete({
+          provider: 'openai',
+          model: (params.model as string) ?? '',
+          systemPrompt: params.systemPrompt as string,
+          userPrompt: params.userPrompt as string,
+          temperature: params.temperature as number | undefined,
+          maxTokens: params.maxTokens as number | undefined,
+          caller: (params.caller as string) ?? 'core-ops',
+          task: params.task as string | undefined,
+        });
+      },
+    },
+
+    // ─── Prompt Templates (inline from core-ops.ts) ─────────────
+    {
+      name: 'render_prompt',
+      description:
+        'Render a prompt template with variable substitution. Templates are .prompt files loaded from the templates directory.',
+      auth: 'read' as const,
+      schema: z.object({
+        template: z.string().describe('Template name (without .prompt extension)'),
+        variables: z.record(z.string()).optional().default({}),
+        strict: z.boolean().optional().default(true),
+      }),
+      handler: async (params) => {
+        const rendered = runtime.templateManager.render(
+          params.template as string,
+          (params.variables ?? {}) as Record<string, string>,
+          { strict: params.strict as boolean },
+        );
+        return { rendered };
+      },
+    },
+    {
+      name: 'list_templates',
+      description: 'List all loaded prompt templates.',
+      auth: 'read' as const,
+      handler: async () => ({
+        templates: runtime.templateManager.listTemplates(),
+      }),
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createAdminOps(runtime),
+    ...createAdminExtraOps(runtime),
+  ];
+}

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

@@ -0,0 +1,331 @@
+/**
+ * Brain facade — learning system ops.
+ * intelligence pipeline, strengths, feedback, sessions.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+
+export function createBrainFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { brain, brainIntelligence, llmClient, keyPool, governance } = runtime;
+
+  return [
+    // ─── Brain (inline from core-ops.ts) ────────────────────────
+    {
+      name: 'record_feedback',
+      description:
+        'Record feedback on a search result — accepted or dismissed. Used for adaptive weight tuning.',
+      auth: 'write',
+      schema: z.object({
+        query: z.string().describe('The original search query'),
+        entryId: z.string().describe('The entry ID that was accepted or dismissed'),
+        action: z.enum(['accepted', 'dismissed']),
+      }),
+      handler: async (params) => {
+        brain.recordFeedback(
+          params.query as string,
+          params.entryId as string,
+          params.action as 'accepted' | 'dismissed',
+        );
+        return {
+          recorded: true,
+          query: params.query,
+          entryId: params.entryId,
+          action: params.action,
+        };
+      },
+    },
+    {
+      name: 'brain_feedback',
+      description:
+        'Enhanced feedback with typed actions (accepted/dismissed/modified/failed), source tracking, confidence, duration, and reason.',
+      auth: 'write',
+      schema: z.object({
+        query: z.string().describe('The original search query'),
+        entryId: z.string().describe('The entry ID'),
+        action: z.enum(['accepted', 'dismissed', 'modified', 'failed']),
+        source: z
+          .enum(['search', 'recommendation', 'tool-execution', 'explicit'])
+          .optional()
+          .describe("Feedback source. Default 'search'."),
+        confidence: z.number().optional().describe('Confidence 0-1. Default 0.6.'),
+        duration: z.number().optional().describe('Duration in ms.'),
+        context: z.string().optional().describe("JSON context string. Default '{}'."),
+        reason: z.string().optional().describe('Human-readable reason.'),
+      }),
+      handler: async (params) => {
+        const entry = brain.recordFeedback({
+          query: params.query as string,
+          entryId: params.entryId as string,
+          action: params.action as 'accepted' | 'dismissed' | 'modified' | 'failed',
+          source: params.source as
+            | 'search'
+            | 'recommendation'
+            | 'tool-execution'
+            | 'explicit'
+            | undefined,
+          confidence: params.confidence as number | undefined,
+          duration: params.duration as number | undefined,
+          context: params.context as string | undefined,
+          reason: params.reason as string | undefined,
+        });
+        return entry;
+      },
+    },
+    {
+      name: 'brain_feedback_stats',
+      description:
+        'Feedback statistics — counts by action and source, acceptance rate, average confidence.',
+      auth: 'read',
+      handler: async () => {
+        return brain.getFeedbackStats();
+      },
+    },
+    {
+      name: 'rebuild_vocabulary',
+      description: 'Force rebuild the TF-IDF vocabulary from all vault entries.',
+      auth: 'write',
+      handler: async () => {
+        brain.rebuildVocabulary();
+        return { rebuilt: true, vocabularySize: brain.getVocabularySize() };
+      },
+    },
+    {
+      name: 'brain_stats',
+      description:
+        'Get brain intelligence stats — vocabulary size, feedback count, current scoring weights, intelligence pipeline stats.',
+      auth: 'read',
+      handler: async () => {
+        const base = brain.getStats();
+        const intelligence = brainIntelligence.getStats();
+        return { ...base, intelligence };
+      },
+    },
+    {
+      name: 'brain_decay_report',
+      description:
+        'Show temporal decay scores for entries matching a query — reveals which entries are expiring, active, or expired.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string().describe('Search query to find entries'),
+        limit: z.number().optional().describe('Max results (default 10)'),
+      }),
+      handler: async (params) => {
+        const results = await brain.getDecayReport(
+          params.query as string,
+          (params.limit as number | undefined) ?? 10,
+        );
+        return { results, count: results.length };
+      },
+    },
+    {
+      name: 'llm_status',
+      description:
+        'LLM client status — provider availability, key pool status, model routing config.',
+      auth: 'read',
+      handler: async () => {
+        const available = llmClient.isAvailable();
+        return {
+          providers: {
+            openai: {
+              available: available.openai,
+              keyPool: keyPool.openai.hasKeys ? keyPool.openai.getStatus() : null,
+            },
+            anthropic: {
+              available: available.anthropic,
+              keyPool: keyPool.anthropic.hasKeys ? keyPool.anthropic.getStatus() : null,
+            },
+          },
+          routes: llmClient.getRoutes(),
+        };
+      },
+    },
+
+    // ─── Brain Intelligence ──────────────────────────────────────
+    {
+      name: 'brain_session_context',
+      description:
+        'Get recent session context — sessions, tool usage frequency, file change frequency.',
+      auth: 'read',
+      schema: z.object({
+        limit: z.number().optional().describe('Number of recent sessions. Default 10.'),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.getSessionContext((params.limit as number) ?? 10);
+      },
+    },
+    {
+      name: 'brain_strengths',
+      description:
+        'Get pattern strength scores. 4-signal scoring: usage (0-25) + spread (0-25) + success (0-25) + recency (0-25).',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional(),
+        minStrength: z.number().optional().describe('Minimum strength score (0-100).'),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.getStrengths({
+          domain: params.domain as string | undefined,
+          minStrength: params.minStrength as number | undefined,
+          limit: (params.limit as number) ?? 50,
+        });
+      },
+    },
+    {
+      name: 'brain_global_patterns',
+      description:
+        'Get cross-domain pattern registry — patterns that appear across multiple domains.',
+      auth: 'read',
+      schema: z.object({
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.getGlobalPatterns((params.limit as number) ?? 20);
+      },
+    },
+    {
+      name: 'brain_recommend',
+      description:
+        'Get pattern recommendations for a task context. Matches domain, task terms, and source-specific acceptance rates against known strengths.',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional(),
+        task: z.string().optional().describe('Task description for contextual matching.'),
+        source: z
+          .string()
+          .optional()
+          .describe(
+            'Feedback source to boost by (search, recommendation, tool-execution, explicit).',
+          ),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.recommend({
+          domain: params.domain as string | undefined,
+          task: params.task as string | undefined,
+          source: params.source as string | undefined,
+          limit: (params.limit as number) ?? 5,
+        });
+      },
+    },
+    {
+      name: 'brain_build_intelligence',
+      description:
+        'Run the full intelligence pipeline: compute strengths → build global registry → build domain profiles.',
+      auth: 'write',
+      handler: async () => {
+        return brainIntelligence.buildIntelligence();
+      },
+    },
+    {
+      name: 'brain_export',
+      description:
+        'Export all brain intelligence data — strengths, sessions, proposals, global patterns, domain profiles.',
+      auth: 'read',
+      handler: async () => {
+        return brainIntelligence.exportData();
+      },
+    },
+    {
+      name: 'brain_import',
+      description: 'Import brain intelligence data from a previous export.',
+      auth: 'write',
+      schema: z.object({
+        data: z.any().describe('BrainExportData object from brain_export.'),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.importData(
+          params.data as import('../../brain/types.js').BrainExportData,
+        );
+      },
+    },
+    {
+      name: 'brain_extract_knowledge',
+      description:
+        'Extract knowledge proposals from a session using 6 heuristic rules (repeated tools, multi-file edits, long sessions, plan outcomes, feedback ratios).',
+      auth: 'write',
+      schema: z.object({
+        sessionId: z.string().describe('Session ID to extract knowledge from.'),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.extractKnowledge(params.sessionId as string);
+      },
+    },
+    {
+      name: 'brain_archive_sessions',
+      description: 'Archive (delete) completed sessions older than N days.',
+      auth: 'write',
+      schema: z.object({
+        olderThanDays: z.number().optional().describe('Days threshold. Default 30.'),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.archiveSessions((params.olderThanDays as number) ?? 30);
+      },
+    },
+    {
+      name: 'brain_promote_proposals',
+      description:
+        'Promote knowledge proposals to vault entries. Creates intelligence entries from auto-extracted patterns. Gated by governance policies.',
+      auth: 'write',
+      schema: z.object({
+        proposalIds: z.array(z.string()).describe('IDs of proposals to promote.'),
+        projectPath: z.string().optional().default('.'),
+      }),
+      handler: async (params) => {
+        const pp = (params.projectPath as string | undefined) ?? '.';
+        return brainIntelligence.promoteProposals(params.proposalIds as string[], governance, pp);
+      },
+    },
+    {
+      name: 'brain_lifecycle',
+      description:
+        'Start or end a brain session. Sessions track tool usage, file changes, and plan context.',
+      auth: 'write',
+      schema: z.object({
+        action: z.enum(['start', 'end']),
+        sessionId: z
+          .string()
+          .optional()
+          .describe('Required for end. Auto-generated for start if omitted.'),
+        domain: z.string().optional(),
+        context: z.string().optional(),
+        toolsUsed: z.array(z.string()).optional(),
+        filesModified: z.array(z.string()).optional(),
+        planId: z.string().optional(),
+        planOutcome: z.string().optional(),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.lifecycle({
+          action: params.action as 'start' | 'end',
+          sessionId: params.sessionId as string | undefined,
+          domain: params.domain as string | undefined,
+          context: params.context as string | undefined,
+          toolsUsed: params.toolsUsed as string[] | undefined,
+          filesModified: params.filesModified as string[] | undefined,
+          planId: params.planId as string | undefined,
+          planOutcome: params.planOutcome as string | undefined,
+        });
+      },
+    },
+    {
+      name: 'brain_reset_extracted',
+      description:
+        'Reset extraction status on brain sessions, allowing re-extraction. Filter by sessionId, since date, or all.',
+      auth: 'write',
+      schema: z.object({
+        sessionId: z.string().optional().describe('Reset a specific session.'),
+        since: z.string().optional().describe('Reset sessions extracted since this ISO date.'),
+        all: z.boolean().optional().describe('Reset all extracted sessions.'),
+      }),
+      handler: async (params) => {
+        return brainIntelligence.resetExtracted({
+          sessionId: params.sessionId as string | undefined,
+          since: params.since as string | undefined,
+          all: params.all as boolean | undefined,
+        });
+      },
+    },
+  ];
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Cognee facade — knowledge graph ops.
+ * Cognee search, sync, export, graph stats.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { IntelligenceEntry } from '../../intelligence/types.js';
+import type { AgentRuntime } from '../types.js';
+import type { CogneeSearchType } from '../../cognee/types.js';
+import { createCogneeSyncOps } from '../cognee-sync-ops.js';
+
+export function createCogneeFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { cognee, vault, syncManager } = runtime;
+
+  return [
+    // ─── Cognee (inline from core-ops.ts) ───────────────────────
+    {
+      name: 'cognee_status',
+      description:
+        'Cognee vector search health — availability, URL, latency. Checks the Cognee API endpoint.',
+      auth: 'read',
+      handler: async () => {
+        return cognee.healthCheck();
+      },
+    },
+    {
+      name: 'cognee_search',
+      description:
+        'Vector similarity search via Cognee. Complements TF-IDF vault search with semantic understanding.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string(),
+        searchType: z
+          .enum([
+            'SUMMARIES',
+            'CHUNKS',
+            'RAG_COMPLETION',
+            'TRIPLET_COMPLETION',
+            'GRAPH_COMPLETION',
+            'GRAPH_SUMMARY_COMPLETION',
+            'NATURAL_LANGUAGE',
+            'GRAPH_COMPLETION_COT',
+            'FEELING_LUCKY',
+            'CHUNKS_LEXICAL',
+          ])
+          .optional()
+          .describe('Cognee search type. Default CHUNKS (pure vector similarity).'),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return cognee.search(params.query as string, {
+          searchType: params.searchType as CogneeSearchType | undefined,
+          limit: (params.limit as number) ?? 10,
+        });
+      },
+    },
+    {
+      name: 'cognee_add',
+      description:
+        'Ingest vault entries into Cognee for vector indexing. Auto-schedules cognify after ingest.',
+      auth: 'write',
+      schema: z.object({
+        entryIds: z.array(z.string()).describe('Vault entry IDs to ingest into Cognee.'),
+      }),
+      handler: async (params) => {
+        const ids = params.entryIds as string[];
+        const entries = ids
+          .map((id) => vault.get(id))
+          .filter((e): e is IntelligenceEntry => e !== null && e !== undefined);
+        if (entries.length === 0) return { added: 0, error: 'No matching vault entries found' };
+        return cognee.addEntries(entries);
+      },
+    },
+    {
+      name: 'cognee_cognify',
+      description:
+        'Trigger Cognee knowledge graph processing on the vault dataset. Usually auto-scheduled after add.',
+      auth: 'write',
+      handler: async () => {
+        return cognee.cognify();
+      },
+    },
+    {
+      name: 'cognee_config',
+      description: 'Get current Cognee client configuration and cached health status.',
+      auth: 'read',
+      handler: async () => {
+        return { config: cognee.getConfig(), cachedStatus: cognee.getStatus() };
+      },
+    },
+    // ─── Cognee Graph ────────────────────────────────────────────
+    {
+      name: 'cognee_get_node',
+      description: 'Get a specific Cognee graph node by UUID with all properties and connections.',
+      auth: 'read',
+      schema: z.object({
+        nodeId: z.string().describe('UUID of the graph node'),
+      }),
+      handler: async (params) => {
+        try {
+          const results = await cognee.search(params.nodeId as string, {
+            searchType: 'GRAPH_COMPLETION' as CogneeSearchType,
+            limit: 1,
+          });
+          if (!results || (Array.isArray(results) && results.length === 0)) {
+            return { found: false, nodeId: params.nodeId };
+          }
+          return {
+            found: true,
+            nodeId: params.nodeId,
+            node: Array.isArray(results) ? results[0] : results,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+    {
+      name: 'cognee_graph_stats',
+      description:
+        'Cognee graph statistics — availability, endpoint, latency from last health check.',
+      auth: 'read',
+      handler: async () => {
+        try {
+          const status = cognee.getStatus();
+          const health = await cognee.healthCheck();
+          return {
+            available: status?.available ?? false,
+            url: status?.url ?? cognee.getConfig().baseUrl,
+            latencyMs: status?.latencyMs ?? health.latencyMs ?? null,
+            error: status?.error ?? health.error ?? null,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+    {
+      name: 'cognee_export_status',
+      description: 'Check Cognee dataset and processing status — availability, pending operations.',
+      auth: 'read',
+      handler: async () => {
+        try {
+          const status = cognee.getStatus();
+          const config = cognee.getConfig();
+          return {
+            available: status?.available ?? false,
+            dataset: config.dataset ?? 'default',
+            pendingCognify: false,
+            url: status?.url ?? config.baseUrl,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createCogneeSyncOps(syncManager),
+  ];
+}