@soleri/core 2.1.0 → 2.4.0

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

@@ -0,0 +1,186 @@
+/**
+ * Extended memory operations — 8 ops for advanced memory management.
+ *
+ * These complement the 4 base memory ops in core-ops.ts:
+ *   memory_search, memory_capture, memory_list, session_capture
+ *
+ * New ops: memory_delete, memory_stats, memory_export, memory_import,
+ *          memory_prune, memory_deduplicate, memory_topics, memory_by_project
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+export function createMemoryExtraOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault } = runtime;
+
+  return [
+    {
+      name: 'memory_delete',
+      description: 'Delete a memory by ID. Returns whether the deletion was successful.',
+      auth: 'write',
+      schema: z.object({
+        memoryId: z.string().describe('The memory ID to delete'),
+      }),
+      handler: async (params) => {
+        const memoryId = params.memoryId as string;
+        const existing = vault.getMemory(memoryId);
+        if (!existing) {
+          return { deleted: false, error: `Memory "${memoryId}" not found.` };
+        }
+        const deleted = vault.deleteMemory(memoryId);
+        return { deleted, memoryId };
+      },
+    },
+    {
+      name: 'memory_stats',
+      description:
+        'Detailed memory statistics — counts by type, project, date range, plus oldest/newest timestamps and archived count.',
+      auth: 'read',
+      schema: z.object({
+        projectPath: z.string().optional().describe('Filter stats to a specific project'),
+        fromDate: z
+          .number()
+          .optional()
+          .describe('Unix timestamp — only include memories created after this date'),
+        toDate: z
+          .number()
+          .optional()
+          .describe('Unix timestamp — only include memories created before this date'),
+      }),
+      handler: async (params) => {
+        return vault.memoryStatsDetailed({
+          projectPath: params.projectPath as string | undefined,
+          fromDate: params.fromDate as number | undefined,
+          toDate: params.toDate as number | undefined,
+        });
+      },
+    },
+    {
+      name: 'memory_export',
+      description:
+        'Export memories as a JSON array. Optionally filter by project or type. Useful for backup and migration.',
+      auth: 'read',
+      schema: z.object({
+        projectPath: z.string().optional().describe('Filter to a specific project'),
+        type: z.enum(['session', 'lesson', 'preference']).optional().describe('Filter by memory type'),
+        includeArchived: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe('Whether to include archived memories'),
+      }),
+      handler: async (params) => {
+        const memories = vault.exportMemories({
+          projectPath: params.projectPath as string | undefined,
+          type: params.type as string | undefined,
+          includeArchived: (params.includeArchived as boolean | undefined) ?? false,
+        });
+        return { exported: true, count: memories.length, memories };
+      },
+    },
+    {
+      name: 'memory_import',
+      description:
+        'Import memories from a JSON array. Duplicates (same ID) are skipped. Returns imported and skipped counts.',
+      auth: 'write',
+      schema: z.object({
+        memories: z
+          .array(
+            z.object({
+              id: z.string(),
+              projectPath: z.string(),
+              type: z.enum(['session', 'lesson', 'preference']),
+              context: z.string(),
+              summary: z.string(),
+              topics: z.array(z.string()).optional().default([]),
+              filesModified: z.array(z.string()).optional().default([]),
+              toolsUsed: z.array(z.string()).optional().default([]),
+              createdAt: z.number(),
+              archivedAt: z.number().nullable().optional().default(null),
+            }),
+          )
+          .describe('Array of memory objects to import'),
+      }),
+      handler: async (params) => {
+        const memories = (params.memories as Array<Record<string, unknown>>).map((m) => ({
+          id: m.id as string,
+          projectPath: m.projectPath as string,
+          type: m.type as 'session' | 'lesson' | 'preference',
+          context: m.context as string,
+          summary: m.summary as string,
+          topics: (m.topics as string[]) ?? [],
+          filesModified: (m.filesModified as string[]) ?? [],
+          toolsUsed: (m.toolsUsed as string[]) ?? [],
+          createdAt: m.createdAt as number,
+          archivedAt: (m.archivedAt as number | null) ?? null,
+        }));
+        const result = vault.importMemories(memories);
+        return { ...result, total: memories.length };
+      },
+    },
+    {
+      name: 'memory_prune',
+      description:
+        'Delete non-archived memories older than N days. Destructive — cannot be undone.',
+      auth: 'admin',
+      schema: z.object({
+        olderThanDays: z
+          .number()
+          .min(1)
+          .describe('Delete memories older than this many days'),
+      }),
+      handler: async (params) => {
+        const days = params.olderThanDays as number;
+        const result = vault.pruneMemories(days);
+        return { ...result, olderThanDays: days };
+      },
+    },
+    {
+      name: 'memory_deduplicate',
+      description:
+        'Find and remove duplicate memories (same summary + project + type). Keeps the earliest entry in each duplicate group.',
+      auth: 'admin',
+      schema: z.object({}),
+      handler: async () => {
+        return vault.deduplicateMemories();
+      },
+    },
+    {
+      name: 'memory_topics',
+      description:
+        'List all unique topics across memories, with occurrence counts. Sorted by frequency descending.',
+      auth: 'read',
+      schema: z.object({}),
+      handler: async () => {
+        const topics = vault.memoryTopics();
+        return { count: topics.length, topics };
+      },
+    },
+    {
+      name: 'memory_by_project',
+      description:
+        'List memories grouped by project path. Each group includes the project path, count, and the memories themselves.',
+      auth: 'read',
+      schema: z.object({
+        includeMemories: z
+          .boolean()
+          .optional()
+          .default(true)
+          .describe('Whether to include full memory objects or just counts'),
+      }),
+      handler: async (params) => {
+        const includeMemories = (params.includeMemories as boolean | undefined) ?? true;
+        const groups = vault.memoriesByProject();
+        if (!includeMemories) {
+          return {
+            count: groups.length,
+            projects: groups.map((g) => ({ project: g.project, count: g.count })),
+          };
+        }
+        return { count: groups.length, projects: groups };
+      },
+    },
+  ];
+}

package/src/runtime/orchestrate-ops.ts

@@ -0,0 +1,272 @@
+/**
+ * Orchestration operations — compose planning + brain + vault into high-level workflows.
+ *
+ * These ops are convenience wrappers that sequence multiple module calls:
+ *   - orchestrate_plan: brain-informed plan creation
+ *   - orchestrate_execute: start plan + brain session together
+ *   - orchestrate_complete: finish plan + brain session + extract knowledge
+ *   - orchestrate_status: combined status across all modules
+ *   - orchestrate_quick_capture: one-call knowledge capture without full planning
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+/**
+ * Create the 5 orchestration operations for an agent runtime.
+ */
+export function createOrchestrateOps(runtime: AgentRuntime): OpDefinition[] {
+  const { planner, brainIntelligence, vault } = runtime;
+
+  return [
+    // ─── orchestrate_plan ─────────────────────────────────────────
+    {
+      name: 'orchestrate_plan',
+      description:
+        'Create a brain-informed plan with recommendations from pattern strengths. ' +
+        'Fetches relevant brain recommendations for the domain/task, then creates a plan ' +
+        'with those recommendations injected as decisions.',
+      auth: 'write',
+      schema: z.object({
+        objective: z.string().describe('What the plan aims to achieve'),
+        scope: z.string().describe('Boundaries of the work'),
+        domain: z.string().optional().describe('Domain for brain recommendations (e.g. "component", "styling")'),
+        tasks: z
+          .array(z.object({ title: z.string(), description: z.string() }))
+          .optional()
+          .describe('Optional pre-defined tasks'),
+      }),
+      handler: async (params) => {
+        const objective = params.objective as string;
+        const scope = params.scope as string;
+        const domain = params.domain as string | undefined;
+        const tasks = (params.tasks as Array<{ title: string; description: string }>) ?? [];
+
+        // Get brain recommendations — graceful degradation if no data
+        let recommendations: Array<{ pattern: string; strength: number }> = [];
+        try {
+          const raw = brainIntelligence.recommend({
+            domain,
+            task: objective,
+            limit: 5,
+          });
+          recommendations = raw.map((r) => ({
+            pattern: r.pattern,
+            strength: r.strength,
+          }));
+        } catch {
+          // Brain has no data yet — proceed without recommendations
+        }
+
+        // Build decisions from recommendations
+        const decisions = recommendations.map(
+          (r) => `Brain pattern: ${r.pattern} (strength: ${r.strength.toFixed(1)})`,
+        );
+
+        // Create plan with recommendations as context
+        const plan = planner.create({
+          objective,
+          scope,
+          decisions,
+          tasks,
+        });
+
+        return { plan, recommendations };
+      },
+    },
+
+    // ─── orchestrate_execute ──────────────────────────────────────
+    {
+      name: 'orchestrate_execute',
+      description:
+        'Start plan execution and open a brain session to track the work. ' +
+        'The plan must be in "approved" status. Returns both the updated plan and session ID.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('ID of the approved plan to start executing'),
+        domain: z.string().optional().describe('Domain for brain session tracking'),
+        context: z.string().optional().describe('Additional context for the brain session'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const domain = params.domain as string | undefined;
+        const context = params.context as string | undefined;
+
+        // Start plan execution
+        const plan = planner.startExecution(planId);
+
+        // Start brain session linked to this plan
+        const session = brainIntelligence.lifecycle({
+          action: 'start',
+          domain,
+          context,
+          planId,
+        });
+
+        return { plan, session };
+      },
+    },
+
+    // ─── orchestrate_complete ─────────────────────────────────────
+    {
+      name: 'orchestrate_complete',
+      description:
+        'Complete plan execution, end brain session, and extract knowledge. ' +
+        'Performs three steps: marks plan completed, ends the brain session with outcome, ' +
+        'and runs knowledge extraction on the session.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string().describe('ID of the executing plan to complete'),
+        sessionId: z.string().describe('ID of the brain session to end'),
+        outcome: z
+          .enum(['completed', 'abandoned', 'partial'])
+          .optional()
+          .default('completed')
+          .describe('Plan outcome'),
+        toolsUsed: z.array(z.string()).optional().describe('Tools used during execution'),
+        filesModified: z.array(z.string()).optional().describe('Files modified during execution'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const sessionId = params.sessionId as string;
+        const outcome = (params.outcome as string) ?? 'completed';
+        const toolsUsed = (params.toolsUsed as string[]) ?? [];
+        const filesModified = (params.filesModified as string[]) ?? [];
+
+        // Complete the plan
+        const plan = planner.complete(planId);
+
+        // End brain session with outcome
+        const session = brainIntelligence.lifecycle({
+          action: 'end',
+          sessionId,
+          planId,
+          planOutcome: outcome,
+          toolsUsed,
+          filesModified,
+        });
+
+        // Extract knowledge from the session — graceful if nothing to extract
+        let extraction = null;
+        try {
+          extraction = brainIntelligence.extractKnowledge(sessionId);
+        } catch {
+          // Session may not have enough signal for extraction — that's OK
+        }
+
+        return { plan, session, extraction };
+      },
+    },
+
+    // ─── orchestrate_status ───────────────────────────────────────
+    {
+      name: 'orchestrate_status',
+      description:
+        'Get combined orchestration status: active plans, brain session context, ' +
+        'vault stats, and recent brain recommendations.',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional().describe('Filter recommendations by domain'),
+        sessionLimit: z.number().optional().describe('Number of recent sessions to include (default 5)'),
+      }),
+      handler: async (params) => {
+        const domain = params.domain as string | undefined;
+        const sessionLimit = (params.sessionLimit as number) ?? 5;
+
+        // Active plans
+        const activePlans = planner.getActive();
+
+        // Brain session context
+        const sessionContext = brainIntelligence.getSessionContext(sessionLimit);
+
+        // Vault stats
+        const vaultStats = vault.stats();
+
+        // Recent recommendations — graceful degradation
+        let recommendations: Array<{ pattern: string; strength: number }> = [];
+        try {
+          const raw = brainIntelligence.recommend({
+            domain,
+            limit: 5,
+          });
+          recommendations = raw.map((r) => ({
+            pattern: r.pattern,
+            strength: r.strength,
+          }));
+        } catch {
+          // No recommendations available
+        }
+
+        // Brain intelligence stats
+        const brainStats = brainIntelligence.getStats();
+
+        return {
+          activePlans,
+          sessionContext,
+          vaultStats,
+          recommendations,
+          brainStats,
+        };
+      },
+    },
+
+    // ─── orchestrate_quick_capture ────────────────────────────────
+    {
+      name: 'orchestrate_quick_capture',
+      description:
+        'Capture knowledge from a completed task without full plan lifecycle. ' +
+        'Creates a brain session, records the context, ends it, and extracts knowledge — all in one call.',
+      auth: 'write',
+      schema: z.object({
+        domain: z.string().describe('Knowledge domain (e.g. "component", "accessibility")'),
+        context: z.string().describe('What was done — summary of the task'),
+        toolsUsed: z.array(z.string()).optional().describe('Tools used during the task'),
+        filesModified: z.array(z.string()).optional().describe('Files modified during the task'),
+        outcome: z
+          .enum(['completed', 'abandoned', 'partial'])
+          .optional()
+          .default('completed')
+          .describe('Task outcome'),
+      }),
+      handler: async (params) => {
+        const domain = params.domain as string;
+        const context = params.context as string;
+        const toolsUsed = (params.toolsUsed as string[]) ?? [];
+        const filesModified = (params.filesModified as string[]) ?? [];
+        const outcome = (params.outcome as string) ?? 'completed';
+
+        // Start session
+        const startedSession = brainIntelligence.lifecycle({
+          action: 'start',
+          domain,
+          context,
+          toolsUsed,
+          filesModified,
+        });
+
+        // End session immediately with outcome
+        const endedSession = brainIntelligence.lifecycle({
+          action: 'end',
+          sessionId: startedSession.id,
+          toolsUsed,
+          filesModified,
+          planOutcome: outcome,
+        });
+
+        // Extract knowledge — graceful if nothing to extract
+        let extraction = null;
+        try {
+          extraction = brainIntelligence.extractKnowledge(startedSession.id);
+        } catch {
+          // Not enough signal — that's fine
+        }
+
+        return {
+          session: endedSession,
+          extraction,
+        };
+      },
+    },
+  ];
+}