@soleri/core 2.1.0 → 2.5.0

package/src/runtime/loop-ops.ts

@@ -0,0 +1,277 @@
+/**
+ * Loop operations — 9 ops for iterative validation loops.
+ *
+ * Ops: loop_start, loop_iterate, loop_iterate_gate, loop_status,
+ *      loop_cancel, loop_history, loop_is_active, loop_complete,
+ *      loop_anomaly_check.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import type { LoopMode, LoopKnowledge } from '../loop/types.js';
+
+const loopModeSchema = z.enum([
+  'token-migration',
+  'contrast-fix',
+  'component-build',
+  'plan-iteration',
+  'custom',
+]);
+
+/**
+ * Default max iterations per mode.
+ */
+const DEFAULT_MAX_ITERATIONS: Record<LoopMode, number> = {
+  'token-migration': 20,
+  'contrast-fix': 15,
+  'component-build': 20,
+  'plan-iteration': 10,
+  custom: 20,
+};
+
+/**
+ * Default target scores per mode.
+ */
+const DEFAULT_TARGET_SCORES: Partial<Record<LoopMode, number>> = {
+  'token-migration': 95,
+  'component-build': 90,
+  'plan-iteration': 90,
+};
+
+/**
+ * Create the 9 loop operations for an agent runtime.
+ */
+export function createLoopOps(runtime: AgentRuntime): OpDefinition[] {
+  const { loop } = runtime;
+
+  return [
+    {
+      name: 'loop_start',
+      description:
+        'Start an iterative validation loop. Modes: token-migration, contrast-fix, component-build, plan-iteration, custom.',
+      auth: 'write',
+      schema: z.object({
+        mode: loopModeSchema,
+        prompt: z.string().describe('Task description for the loop.'),
+        maxIterations: z
+          .number()
+          .optional()
+          .describe('Max iterations. Defaults vary by mode (10-20).'),
+        targetScore: z
+          .number()
+          .optional()
+          .describe('Target validation score (0-100). Defaults vary by mode.'),
+        targetGrade: z
+          .string()
+          .optional()
+          .describe('Target grade for plan-iteration mode (e.g., "A", "A+").'),
+        completionPromise: z
+          .string()
+          .optional()
+          .describe('Completion promise text — loop completes when this appears in output.'),
+        validationInstructions: z
+          .string()
+          .optional()
+          .describe('Validation instructions appended to the prompt each iteration.'),
+        intent: z
+          .string()
+          .optional()
+          .describe('Detected intent for brain session recording (e.g., "BUILD", "FIX").'),
+      }),
+      handler: async (params) => {
+        const mode = params.mode as LoopMode;
+        const prompt = params.prompt as string;
+        const maxIterations =
+          (params.maxIterations as number | undefined) ?? DEFAULT_MAX_ITERATIONS[mode];
+        const targetScore =
+          (params.targetScore as number | undefined) ?? DEFAULT_TARGET_SCORES[mode];
+
+        const state = loop.startLoop({
+          mode,
+          prompt,
+          maxIterations,
+          targetScore,
+          targetGrade: params.targetGrade as string | undefined,
+          completionPromise: params.completionPromise as string | undefined,
+          validationInstructions: params.validationInstructions as string | undefined,
+          intent: params.intent as string | undefined,
+        });
+
+        return {
+          started: true,
+          loopId: state.id,
+          mode,
+          maxIterations,
+          targetScore: targetScore ?? null,
+        };
+      },
+    },
+    {
+      name: 'loop_iterate',
+      description:
+        'Record a validation iteration result. If max iterations reached on a failing result, the loop auto-closes.',
+      auth: 'write',
+      schema: z.object({
+        passed: z.boolean().describe('Whether this iteration passed validation.'),
+        validationScore: z.number().optional().describe('Numeric validation score (0-100).'),
+        validationResult: z.string().optional().describe('Free-text validation result summary.'),
+      }),
+      handler: async (params) => {
+        const iteration = loop.iterate({
+          passed: params.passed as boolean,
+          validationScore: params.validationScore as number | undefined,
+          validationResult: params.validationResult as string | undefined,
+        });
+
+        const status = loop.getStatus();
+        return {
+          iteration: iteration.iteration,
+          passed: iteration.passed,
+          validationScore: iteration.validationScore ?? null,
+          loopActive: loop.isActive(),
+          loopStatus: status?.status ?? 'max-iterations',
+        };
+      },
+    },
+    {
+      name: 'loop_iterate_gate',
+      description:
+        'Gate-based loop iteration — accepts LLM output, scans for completion signals ' +
+        '(promise tags, heuristic detection), and returns allow/block decision. ' +
+        'Primary method for Stop hook integration.',
+      auth: 'write',
+      schema: z.object({
+        lastOutput: z.string().describe('The LLM response to scan for completion signals.'),
+        knowledge: z
+          .object({
+            items: z.array(z.string()).optional(),
+            patternsApplied: z.array(z.string()).optional(),
+            antiPatternsAvoided: z.array(z.string()).optional(),
+          })
+          .optional()
+          .describe('Knowledge items discovered during this iteration.'),
+        durationMs: z
+          .number()
+          .optional()
+          .describe('Duration of this iteration in milliseconds (for anomaly detection).'),
+      }),
+      handler: async (params) => {
+        const decision = loop.iterateWithGate(
+          params.lastOutput as string,
+          params.knowledge as LoopKnowledge | undefined,
+          params.durationMs as number | undefined,
+        );
+        return decision;
+      },
+    },
+    {
+      name: 'loop_status',
+      description: 'Get current loop status, config, and iteration history.',
+      auth: 'read',
+      handler: async () => {
+        const status = loop.getStatus();
+        if (!status) {
+          return { active: false, loop: null };
+        }
+        return {
+          active: true,
+          loop: status,
+        };
+      },
+    },
+    {
+      name: 'loop_cancel',
+      description: 'Cancel the active loop.',
+      auth: 'write',
+      handler: async () => {
+        const cancelled = loop.cancelLoop();
+        return {
+          cancelled: true,
+          loopId: cancelled.id,
+          iterations: cancelled.iterations.length,
+          status: cancelled.status,
+        };
+      },
+    },
+    {
+      name: 'loop_history',
+      description: 'Get history of all completed, cancelled, and max-iterations loops.',
+      auth: 'read',
+      handler: async () => {
+        const history = loop.getHistory();
+        return {
+          count: history.length,
+          loops: history.map((l) => ({
+            id: l.id,
+            mode: l.config.mode,
+            prompt: l.config.prompt,
+            status: l.status,
+            iterations: l.iterations.length,
+            startedAt: l.startedAt,
+            completedAt: l.completedAt,
+          })),
+        };
+      },
+    },
+    {
+      name: 'loop_is_active',
+      description: 'Check if a validation loop is currently running.',
+      auth: 'read',
+      handler: async () => {
+        return { active: loop.isActive() };
+      },
+    },
+    {
+      name: 'loop_complete',
+      description: 'Mark the active loop as completed (validation passed).',
+      auth: 'write',
+      handler: async () => {
+        const completed = loop.completeLoop();
+        return {
+          completed: true,
+          loopId: completed.id,
+          iterations: completed.iterations.length,
+          status: completed.status,
+        };
+      },
+    },
+    {
+      name: 'loop_anomaly_check',
+      description:
+        'Check active loop iterations for anomalous patterns — fast iterations with low scores, repeated failures, no-progress loops.',
+      auth: 'read',
+      handler: async () => {
+        const status = loop.getStatus();
+        if (!status) {
+          return { active: false, anomalies: [], summary: 'No active loop' };
+        }
+
+        const { detectAnomaly } = await import('../loop/loop-manager.js');
+        const anomalies: string[] = [];
+
+        for (const iter of status.iterations) {
+          const warning = detectAnomaly(iter, status.config.mode);
+          if (warning) anomalies.push(warning);
+        }
+
+        // Check for repeated failures (3+ consecutive non-passing iterations)
+        const recent = status.iterations.slice(-3);
+        if (recent.length >= 3 && recent.every((i) => !i.passed)) {
+          anomalies.push(
+            `Warning: ${recent.length} consecutive failing iterations — consider cancelling or adjusting approach`,
+          );
+        }
+
+        return {
+          active: true,
+          loopId: status.id,
+          mode: status.config.mode,
+          totalIterations: status.iterations.length,
+          anomalies,
+          hasAnomalies: anomalies.length > 0,
+        };
+      },
+    },
+  ];
+}

package/src/runtime/memory-cross-project-ops.ts

@@ -0,0 +1,191 @@
+/**
+ * Cross-project memory operations — 3 ops for sharing knowledge across linked projects.
+ *
+ * Ops: memory_promote_to_global, memory_configure, memory_cross_project_search.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+/**
+ * Create the 3 cross-project memory operations for an agent runtime.
+ */
+export function createMemoryCrossProjectOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, projectRegistry } = runtime;
+
+  return [
+    {
+      name: 'memory_promote_to_global',
+      description:
+        'Promote a vault entry to the global pool by adding a _global tag. Promoted entries surface in cross-project searches across all linked projects.',
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string().describe('The vault entry ID to promote.'),
+      }),
+      handler: async (params) => {
+        const entryId = params.entryId as string;
+        const entry = vault.get(entryId);
+        if (!entry) return { promoted: false, error: `Entry not found: ${entryId}` };
+
+        const tags = entry.tags ?? [];
+        if (tags.includes('_global')) {
+          return { promoted: false, entryId, message: 'Entry is already promoted to global.' };
+        }
+
+        vault.update(entryId, { tags: [...tags, '_global'] });
+        return { promoted: true, entryId, tags: [...tags, '_global'] };
+      },
+    },
+
+    {
+      name: 'memory_configure',
+      description:
+        'Configure cross-project memory settings for a project. Stores config in the project registry metadata.',
+      auth: 'admin',
+      schema: z.object({
+        projectPath: z.string().describe('Project path to configure.'),
+        crossProjectEnabled: z
+          .boolean()
+          .optional()
+          .describe('Enable/disable cross-project memory search.'),
+        extraPaths: z
+          .array(z.string())
+          .optional()
+          .describe('Additional project paths to include in cross-project searches.'),
+      }),
+      handler: async (params) => {
+        const projectPath = params.projectPath as string;
+        const project = projectRegistry.getByPath(projectPath);
+        if (!project) {
+          return { configured: false, error: `Project not registered: ${projectPath}` };
+        }
+
+        const currentMeta = project.metadata ?? {};
+        const memoryConfig = (currentMeta.memoryConfig as Record<string, unknown>) ?? {};
+
+        if (params.crossProjectEnabled !== undefined) {
+          memoryConfig.crossProjectEnabled = params.crossProjectEnabled;
+        }
+        if (params.extraPaths !== undefined) {
+          memoryConfig.extraPaths = params.extraPaths;
+        }
+
+        projectRegistry.register(projectPath, project.name, {
+          ...currentMeta,
+          memoryConfig,
+        });
+
+        return { configured: true, projectPath, memoryConfig };
+      },
+    },
+
+    {
+      name: 'memory_cross_project_search',
+      description:
+        'Search memories across the current project and all linked projects. Results weighted: current=1.0, global=0.9, linked=0.8. Requires cross-project search to be enabled.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string().describe('Search query.'),
+        projectPath: z.string().describe('Current project path.'),
+        type: z
+          .enum(['session', 'lesson', 'preference'])
+          .optional()
+          .describe('Filter by memory type.'),
+        limit: z.number().optional().describe('Max results per project (default 10).'),
+      }),
+      handler: async (params) => {
+        const query = params.query as string;
+        const projectPath = params.projectPath as string;
+        const type = params.type as string | undefined;
+        const limit = (params.limit as number) ?? 10;
+
+        // Search current project (weight 1.0)
+        const currentResults = vault.searchMemories(query, { projectPath, type, limit });
+        const weightedResults = currentResults.map((m) => ({
+          memory: m,
+          weight: 1.0,
+          source: 'current' as const,
+        }));
+
+        // Search for globally promoted entries (search broadly, then filter for _global tag)
+        const allResults = vault.search(query, { limit: limit * 3 });
+        const globalEntries = allResults
+          .filter((r) => r.entry.tags?.includes('_global'))
+          .slice(0, limit)
+          .map((r) => ({
+            entry: r.entry,
+            score: r.score,
+            weight: 0.9,
+            source: 'global' as const,
+          }));
+
+        // Get linked projects and search their memories
+        const project = projectRegistry.getByPath(projectPath);
+        const linkedMemories: Array<{
+          memory: (typeof currentResults)[0];
+          weight: number;
+          source: 'linked';
+          linkedProject: string;
+        }> = [];
+
+        if (project) {
+          const config = (project.metadata?.memoryConfig as Record<string, unknown>) ?? {};
+          const enabled = config.crossProjectEnabled !== false; // default enabled
+
+          if (enabled) {
+            const linked = projectRegistry.getLinkedProjects(project.id);
+            for (const { project: linkedProj } of linked) {
+              const results = vault.searchMemories(query, {
+                projectPath: linkedProj.path,
+                type,
+                limit: Math.ceil(limit / 2), // fewer results from linked projects
+              });
+              for (const m of results) {
+                linkedMemories.push({
+                  memory: m,
+                  weight: 0.8,
+                  source: 'linked',
+                  linkedProject: linkedProj.path,
+                });
+              }
+            }
+
+            // Also search extra paths
+            const extraPaths = (config.extraPaths as string[]) ?? [];
+            for (const extraPath of extraPaths) {
+              const results = vault.searchMemories(query, {
+                projectPath: extraPath,
+                type,
+                limit: Math.ceil(limit / 2),
+              });
+              for (const m of results) {
+                linkedMemories.push({
+                  memory: m,
+                  weight: 0.7,
+                  source: 'linked',
+                  linkedProject: extraPath,
+                });
+              }
+            }
+          }
+        }
+
+        // Deduplicate by memory ID
+        const seen = new Set(weightedResults.map((r) => r.memory.id));
+        const dedupedLinked = linkedMemories.filter((r) => {
+          if (seen.has(r.memory.id)) return false;
+          seen.add(r.memory.id);
+          return true;
+        });
+
+        return {
+          memories: weightedResults,
+          globalEntries,
+          linkedMemories: dedupedLinked,
+          totalResults: weightedResults.length + globalEntries.length + dedupedLinked.length,
+        };
+      },
+    },
+  ];
+}

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 };
+      },
+    },
+  ];
+}