@soleri/core 2.1.0 → 2.4.0

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

@@ -0,0 +1,327 @@
+/**
+ * Extended planning operations — 9 ops for advanced plan lifecycle management.
+ *
+ * These complement the 5 basic planning ops in core-ops.ts with:
+ * iteration, splitting, reconciliation, lifecycle completion,
+ * dispatch, review, archival, task listing, and statistics.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import type { DriftItem } from '../planning/planner.js';
+
+/**
+ * Create 9 extended planning operations for an agent runtime.
+ *
+ * Groups: mutation (plan_iterate, plan_split, plan_reconcile, plan_complete_lifecycle,
+ *         plan_review, plan_archive), query (plan_dispatch, plan_list_tasks, plan_stats).
+ */
+export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
+  const { planner, vault } = runtime;
+
+  return [
+    // ─── Plan Iteration ───────────────────────────────────────────
+    {
+      name: 'plan_iterate',
+      description:
+        'Revise a draft plan — change objective, scope, decisions, or add/remove tasks. Only works on draft plans.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('ID of the draft plan to iterate on'),
+        objective: z.string().optional().describe('New objective (replaces existing)'),
+        scope: z.string().optional().describe('New scope (replaces existing)'),
+        decisions: z.array(z.string()).optional().describe('New decisions list (replaces existing)'),
+        addTasks: z
+          .array(z.object({ title: z.string(), description: z.string() }))
+          .optional()
+          .describe('Tasks to append'),
+        removeTasks: z
+          .array(z.string())
+          .optional()
+          .describe('Task IDs to remove'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.iterate(params.planId as string, {
+            objective: params.objective as string | undefined,
+            scope: params.scope as string | undefined,
+            decisions: params.decisions as string[] | undefined,
+            addTasks: params.addTasks as Array<{ title: string; description: string }> | undefined,
+            removeTasks: params.removeTasks as string[] | undefined,
+          });
+          return { iterated: true, plan };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Split ───────────────────────────────────────────────
+    {
+      name: 'plan_split',
+      description:
+        'Split a plan into sub-tasks with dependency tracking. Replaces existing tasks with a new set. Works on draft or approved plans.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to split tasks for'),
+        tasks: z
+          .array(
+            z.object({
+              title: z.string(),
+              description: z.string(),
+              dependsOn: z.array(z.string()).optional().describe('Task IDs this task depends on'),
+            }),
+          )
+          .describe('New task list with optional dependency references (task-1, task-2, etc.)'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.splitTasks(
+            params.planId as string,
+            params.tasks as Array<{ title: string; description: string; dependsOn?: string[] }>,
+          );
+          return { split: true, taskCount: plan.tasks.length, plan };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Reconcile ───────────────────────────────────────────
+    {
+      name: 'plan_reconcile',
+      description:
+        'Capture what actually happened vs what was planned. Produces a drift analysis with accuracy score. Works on executing or completed plans.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to reconcile'),
+        actualOutcome: z.string().describe('Description of what actually happened'),
+        driftItems: z
+          .array(
+            z.object({
+              type: z.enum(['skipped', 'added', 'modified', 'reordered']),
+              description: z.string(),
+              impact: z.enum(['low', 'medium', 'high']),
+              rationale: z.string(),
+            }),
+          )
+          .optional()
+          .describe('Specific drift items — differences between plan and reality'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.reconcile(params.planId as string, {
+            actualOutcome: params.actualOutcome as string,
+            driftItems: params.driftItems as DriftItem[] | undefined,
+          });
+          return {
+            reconciled: true,
+            accuracy: plan.reconciliation!.accuracy,
+            driftCount: plan.reconciliation!.driftItems.length,
+            plan,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Complete Lifecycle ──────────────────────────────────
+    {
+      name: 'plan_complete_lifecycle',
+      description:
+        'Extract knowledge from a completed and reconciled plan. Captures patterns and anti-patterns into the vault based on drift analysis.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID (must be completed with reconciliation data)'),
+        patterns: z
+          .array(z.string())
+          .optional()
+          .describe('Patterns discovered during execution'),
+        antiPatterns: z
+          .array(z.string())
+          .optional()
+          .describe('Anti-patterns discovered during execution'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.get(params.planId as string);
+          if (!plan) return { error: `Plan not found: ${params.planId}` };
+          if (plan.status !== 'completed')
+            return { error: `Plan must be completed — current status: '${plan.status}'` };
+
+          const patterns = (params.patterns as string[] | undefined) ?? [];
+          const antiPatterns = (params.antiPatterns as string[] | undefined) ?? [];
+          let captured = 0;
+
+          // Capture patterns into vault
+          for (const p of patterns) {
+            vault.add({
+              id: `plan-pattern-${plan.id}-${captured}`,
+              type: 'pattern',
+              domain: 'planning',
+              title: p,
+              severity: 'suggestion',
+              description: `Discovered during plan: ${plan.objective}`,
+              tags: ['plan-knowledge', plan.id],
+            });
+            captured++;
+          }
+
+          // Capture anti-patterns into vault
+          for (const ap of antiPatterns) {
+            vault.add({
+              id: `plan-antipattern-${plan.id}-${captured}`,
+              type: 'anti-pattern',
+              domain: 'planning',
+              title: ap,
+              severity: 'warning',
+              description: `Discovered during plan: ${plan.objective}`,
+              tags: ['plan-knowledge', plan.id],
+            });
+            captured++;
+          }
+
+          return {
+            completed: true,
+            knowledgeCaptured: captured,
+            patternsAdded: patterns.length,
+            antiPatternsAdded: antiPatterns.length,
+            reconciliation: plan.reconciliation ?? null,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Dispatch ────────────────────────────────────────────
+    {
+      name: 'plan_dispatch',
+      description:
+        'Get task execution instructions for subagents. Returns the task, its unmet dependencies, and whether it is ready to execute.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        taskId: z.string().describe('Task ID to get dispatch instructions for'),
+      }),
+      handler: async (params) => {
+        try {
+          const dispatch = planner.getDispatch(
+            params.planId as string,
+            params.taskId as string,
+          );
+          return dispatch;
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Review ──────────────────────────────────────────────
+    {
+      name: 'plan_review',
+      description:
+        'Submit review evidence for a plan or specific task. Records reviewer, outcome, and comments.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('Plan ID to review'),
+        taskId: z.string().optional().describe('Specific task ID (omit to review the whole plan)'),
+        reviewer: z.string().describe('Name or ID of reviewer'),
+        outcome: z
+          .enum(['approved', 'rejected', 'needs_changes'])
+          .describe('Review outcome'),
+        comments: z.string().describe('Review comments'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.addReview(params.planId as string, {
+            taskId: params.taskId as string | undefined,
+            reviewer: params.reviewer as string,
+            outcome: params.outcome as 'approved' | 'rejected' | 'needs_changes',
+            comments: params.comments as string,
+          });
+          return {
+            reviewed: true,
+            totalReviews: plan.reviews?.length ?? 0,
+            plan: { id: plan.id, status: plan.status },
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Archive ─────────────────────────────────────────────
+    {
+      name: 'plan_archive',
+      description:
+        'Archive completed plans older than N days. Removes them from active store and returns the archived plans.',
+      auth: 'admin',
+      schema: z.object({
+        olderThanDays: z.number().describe('Archive plans completed more than this many days ago'),
+      }),
+      handler: async (params) => {
+        try {
+          const olderThanDays = (params.olderThanDays as number) ?? 30;
+          const archived = planner.archive(olderThanDays);
+          return { archived: archived.length, plans: archived.map((p) => ({ id: p.id, objective: p.objective })) };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan List Tasks ──────────────────────────────────────────
+    {
+      name: 'plan_list_tasks',
+      description:
+        'List all tasks for a plan with their current status. Optionally filter by status.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('Plan ID'),
+        status: z
+          .enum(['pending', 'in_progress', 'completed', 'skipped', 'failed'])
+          .optional()
+          .describe('Filter tasks by status'),
+      }),
+      handler: async (params) => {
+        try {
+          const plan = planner.get(params.planId as string);
+          if (!plan) return { error: `Plan not found: ${params.planId}` };
+
+          const statusFilter = params.status as string | undefined;
+          const tasks = statusFilter
+            ? plan.tasks.filter((t) => t.status === statusFilter)
+            : plan.tasks;
+
+          return {
+            planId: plan.id,
+            planStatus: plan.status,
+            total: plan.tasks.length,
+            filtered: tasks.length,
+            tasks,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Plan Stats ───────────────────────────────────────────────
+    {
+      name: 'plan_stats',
+      description:
+        'Planning statistics — total plans, breakdown by status, average tasks per plan, task status distribution.',
+      auth: 'read',
+      handler: async () => {
+        try {
+          return planner.stats();
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+  ];
+}

package/src/runtime/project-ops.ts

@@ -0,0 +1,196 @@
+/**
+ * Project registry operations — 12 ops for managing projects, rules, and links.
+ *
+ * These ops expose the ProjectRegistry module as facade operations.
+ * All state is persisted in the Vault's SQLite database.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+/**
+ * Create the 12 project registry operations for an agent runtime.
+ *
+ * Groups: projects (3), rules (4), links (4), misc (1).
+ */
+export function createProjectOps(runtime: AgentRuntime): OpDefinition[] {
+  const { projectRegistry } = runtime;
+
+  return [
+    // ─── Projects ───────────────────────────────────────────────────
+    {
+      name: 'project_get',
+      description: 'Get a registered project by ID.',
+      auth: 'read',
+      schema: z.object({
+        projectId: z.string().describe('Project ID to look up'),
+      }),
+      handler: async (params) => {
+        const project = projectRegistry.get(params.projectId as string);
+        if (!project) {
+          return { found: false, project: null };
+        }
+        return { found: true, project };
+      },
+    },
+    {
+      name: 'project_list',
+      description: 'List all registered projects, ordered by last accessed time.',
+      auth: 'read',
+      handler: async () => {
+        const projects = projectRegistry.list();
+        return { count: projects.length, projects };
+      },
+    },
+    {
+      name: 'project_unregister',
+      description: 'Unregister a project — removes it and all associated rules and links.',
+      auth: 'write',
+      schema: z.object({
+        projectId: z.string().describe('Project ID to unregister'),
+      }),
+      handler: async (params) => {
+        const removed = projectRegistry.unregister(params.projectId as string);
+        return { removed, projectId: params.projectId };
+      },
+    },
+
+    // ─── Rules ──────────────────────────────────────────────────────
+    {
+      name: 'project_get_rules',
+      description: 'Get all rules for a specific project.',
+      auth: 'read',
+      schema: z.object({
+        projectId: z.string().describe('Project ID'),
+      }),
+      handler: async (params) => {
+        const rules = projectRegistry.getRules(params.projectId as string);
+        return { count: rules.length, rules };
+      },
+    },
+    {
+      name: 'project_list_rules',
+      description: 'List all projects with their associated rules.',
+      auth: 'read',
+      handler: async () => {
+        const result = projectRegistry.listRulesAll();
+        return {
+          count: result.length,
+          projects: result.map((r) => ({
+            project: r.project,
+            ruleCount: r.rules.length,
+            rules: r.rules,
+          })),
+        };
+      },
+    },
+    {
+      name: 'project_add_rule',
+      description: 'Add a rule to a project — behavior, preference, restriction, or convention.',
+      auth: 'write',
+      schema: z.object({
+        projectId: z.string().describe('Project ID to add the rule to'),
+        category: z.enum(['behavior', 'preference', 'restriction', 'convention']).describe('Rule category'),
+        text: z.string().describe('Rule text'),
+        priority: z.number().default(0).describe('Priority (higher = more important)'),
+      }),
+      handler: async (params) => {
+        const rule = projectRegistry.addRule(params.projectId as string, {
+          category: params.category as 'behavior' | 'preference' | 'restriction' | 'convention',
+          text: params.text as string,
+          priority: (params.priority as number) ?? 0,
+        });
+        return { added: true, rule };
+      },
+    },
+    {
+      name: 'project_remove_rule',
+      description: 'Remove a project rule by its ID.',
+      auth: 'write',
+      schema: z.object({
+        ruleId: z.string().describe('Rule ID to remove'),
+      }),
+      handler: async (params) => {
+        const removed = projectRegistry.removeRule(params.ruleId as string);
+        return { removed, ruleId: params.ruleId };
+      },
+    },
+
+    // ─── Links ──────────────────────────────────────────────────────
+    {
+      name: 'project_link',
+      description: 'Create a link between two projects (related, parent, child, fork).',
+      auth: 'write',
+      schema: z.object({
+        sourceId: z.string().describe('Source project ID'),
+        targetId: z.string().describe('Target project ID'),
+        linkType: z.enum(['related', 'parent', 'child', 'fork']).describe('Type of link'),
+      }),
+      handler: async (params) => {
+        const link = projectRegistry.link(
+          params.sourceId as string,
+          params.targetId as string,
+          params.linkType as 'related' | 'parent' | 'child' | 'fork',
+        );
+        return { linked: true, link };
+      },
+    },
+    {
+      name: 'project_unlink',
+      description: 'Remove links between two projects. Omit linkType to remove all link types.',
+      auth: 'write',
+      schema: z.object({
+        sourceId: z.string().describe('Source project ID'),
+        targetId: z.string().describe('Target project ID'),
+        linkType: z.enum(['related', 'parent', 'child', 'fork']).optional().describe('Specific link type to remove'),
+      }),
+      handler: async (params) => {
+        const count = projectRegistry.unlink(
+          params.sourceId as string,
+          params.targetId as string,
+          params.linkType as 'related' | 'parent' | 'child' | 'fork' | undefined,
+        );
+        return { removed: count, sourceId: params.sourceId, targetId: params.targetId };
+      },
+    },
+    {
+      name: 'project_get_links',
+      description: 'Get all links for a project (both incoming and outgoing).',
+      auth: 'read',
+      schema: z.object({
+        projectId: z.string().describe('Project ID'),
+      }),
+      handler: async (params) => {
+        const links = projectRegistry.getLinks(params.projectId as string);
+        return { count: links.length, links };
+      },
+    },
+    {
+      name: 'project_linked_projects',
+      description: 'Get linked projects with full details — project info, link type, and direction.',
+      auth: 'read',
+      schema: z.object({
+        projectId: z.string().describe('Project ID'),
+      }),
+      handler: async (params) => {
+        const linked = projectRegistry.getLinkedProjects(params.projectId as string);
+        return { count: linked.length, linked };
+      },
+    },
+
+    // ─── Misc ───────────────────────────────────────────────────────
+    {
+      name: 'project_touch',
+      description: 'Update the last accessed timestamp for a project.',
+      auth: 'write',
+      schema: z.object({
+        projectId: z.string().describe('Project ID to touch'),
+      }),
+      handler: async (params) => {
+        projectRegistry.touch(params.projectId as string);
+        return { touched: true, projectId: params.projectId };
+      },
+    },
+  ];
+}

package/src/runtime/runtime.ts

@@ -14,9 +14,17 @@ import { Brain } from '../brain/brain.js';
 import { BrainIntelligence } from '../brain/intelligence.js';
 import { Planner } from '../planning/planner.js';
 import { Curator } from '../curator/curator.js';
+import { Governance } from '../governance/governance.js';
+import { CogneeClient } from '../cognee/client.js';
+import { LoopManager } from '../loop/loop-manager.js';
+import { IdentityManager } from '../control/identity-manager.js';
+import { IntentRouter } from '../control/intent-router.js';
 import { KeyPool, loadKeyPoolConfig } from '../llm/key-pool.js';
 import { loadIntelligenceData } from '../intelligence/loader.js';
 import { LLMClient } from '../llm/llm-client.js';
+import { Telemetry } from '../telemetry/telemetry.js';
+import { ProjectRegistry } from '../project/project-registry.js';
+import { createLogger } from '../logging/logger.js';
 import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
 
 /**
@@ -33,6 +41,9 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   const vaultPath = config.vaultPath ?? join(agentHome, 'vault.db');
   const plansPath = config.plansPath ?? join(agentHome, 'plans.json');
 
+  // Logger — structured output to stderr
+  const logger = createLogger({ level: config.logLevel, prefix: `[${agentId}]` });
+
   // Vault — persistent SQLite knowledge store
   const vault = new Vault(vaultPath);
 
@@ -56,6 +67,31 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Curator — vault self-maintenance (dedup, contradictions, grooming, health)
   const curator = new Curator(vault);
 
+  // Governance — policy engine + proposal tracker for gated knowledge capture
+  const governance = new Governance(vault);
+
+  // Cognee — vector search client (graceful degradation if Cognee is down)
+  const cogneePartial: Partial<import('../cognee/types.js').CogneeConfig> = { dataset: agentId };
+  if (process.env.COGNEE_BASE_URL) cogneePartial.baseUrl = process.env.COGNEE_BASE_URL;
+  if (process.env.COGNEE_API_TOKEN) cogneePartial.apiToken = process.env.COGNEE_API_TOKEN;
+  if (process.env.COGNEE_DATASET) cogneePartial.dataset = process.env.COGNEE_DATASET;
+  const cognee = new CogneeClient(cogneePartial);
+
+  // Loop Manager — iterative validation loop tracking (in-memory, session-scoped)
+  const loop = new LoopManager();
+
+  // Identity Manager — agent persona CRUD with versioning/rollback
+  const identityManager = new IdentityManager(vault);
+
+  // Intent Router — keyword-based intent classification and mode management
+  const intentRouter = new IntentRouter(vault);
+
+  // Telemetry — in-memory facade call tracking
+  const telemetry = new Telemetry();
+
+  // Project Registry — multi-project tracking with rules and links
+  const projectRegistry = new ProjectRegistry(vault.getDb());
+
   // LLM key pools and client
   const keyPoolFiles = loadKeyPoolConfig(agentId);
   const openaiKeyPool = new KeyPool(keyPoolFiles.openai);
@@ -64,13 +100,25 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
 
   return {
     config,
+    logger,
     vault,
     brain,
     brainIntelligence,
     planner,
     curator,
+    governance,
+    cognee,
+    loop,
+    identityManager,
+    intentRouter,
     keyPool: { openai: openaiKeyPool, anthropic: anthropicKeyPool },
     llmClient,
-    close: () => vault.close(),
+    telemetry,
+    projectRegistry,
+    createdAt: Date.now(),
+    close: () => {
+      cognee.resetPendingCognify();
+      vault.close();
+    },
   };
 }

package/src/runtime/types.ts

@@ -3,8 +3,17 @@ import type { Brain } from '../brain/brain.js';
 import type { BrainIntelligence } from '../brain/intelligence.js';
 import type { Planner } from '../planning/planner.js';
 import type { Curator } from '../curator/curator.js';
+import type { Governance } from '../governance/governance.js';
+import type { CogneeClient } from '../cognee/client.js';
 import type { KeyPool } from '../llm/key-pool.js';
 import type { LLMClient } from '../llm/llm-client.js';
+import type { IdentityManager } from '../control/identity-manager.js';
+import type { IntentRouter } from '../control/intent-router.js';
+import type { LoopManager } from '../loop/loop-manager.js';
+import type { Telemetry } from '../telemetry/telemetry.js';
+import type { ProjectRegistry } from '../project/project-registry.js';
+import type { Logger } from '../logging/logger.js';
+import type { LogLevel } from '../logging/types.js';
 
 /**
  * Configuration for creating an agent runtime.
@@ -19,6 +28,8 @@ export interface AgentRuntimeConfig {
   plansPath?: string;
   /** Intelligence data directory to seed vault from. Optional. */
   dataDir?: string;
+  /** Minimum log level. Default: 'info' (or SOLERI_LOG_LEVEL env var). */
+  logLevel?: LogLevel;
 }
 
 /**
@@ -27,13 +38,23 @@ export interface AgentRuntimeConfig {
  */
 export interface AgentRuntime {
   config: AgentRuntimeConfig;
+  logger: Logger;
   vault: Vault;
   brain: Brain;
   brainIntelligence: BrainIntelligence;
   planner: Planner;
   curator: Curator;
+  governance: Governance;
+  cognee: CogneeClient;
+  loop: LoopManager;
+  identityManager: IdentityManager;
+  intentRouter: IntentRouter;
   keyPool: { openai: KeyPool; anthropic: KeyPool };
   llmClient: LLMClient;
+  telemetry: Telemetry;
+  projectRegistry: ProjectRegistry;
+  /** Timestamp (ms since epoch) when this runtime was created. */
+  createdAt: number;
   /** Close the vault database connection. Call on shutdown. */
   close(): void;
 }