@soleri/core 2.8.0 → 2.10.0

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

@@ -0,0 +1,114 @@
+/**
+ * Memory facade — session & cross-project memory ops.
+ * capture, search, dedup, promote.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createMemoryExtraOps } from '../memory-extra-ops.js';
+import { createMemoryCrossProjectOps } from '../memory-cross-project-ops.js';
+
+export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault } = runtime;
+
+  return [
+    // ─── Memory (inline from core-ops.ts) ───────────────────────
+    {
+      name: 'memory_search',
+      description: 'Search memories using full-text search.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string(),
+        type: z.enum(['session', 'lesson', 'preference']).optional(),
+        projectPath: z.string().optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return vault.searchMemories(params.query as string, {
+          type: params.type as string | undefined,
+          projectPath: params.projectPath as string | undefined,
+          limit: (params.limit as number) ?? 10,
+        });
+      },
+    },
+    {
+      name: 'memory_capture',
+      description: 'Capture a memory — session summary, lesson learned, or preference.',
+      auth: 'write',
+      schema: z.object({
+        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([]),
+      }),
+      handler: async (params) => {
+        const memory = vault.captureMemory({
+          projectPath: params.projectPath as string,
+          type: params.type as 'session' | 'lesson' | 'preference',
+          context: params.context as string,
+          summary: params.summary as string,
+          topics: (params.topics as string[]) ?? [],
+          filesModified: (params.filesModified as string[]) ?? [],
+          toolsUsed: (params.toolsUsed as string[]) ?? [],
+        });
+        return { captured: true, memory };
+      },
+    },
+    {
+      name: 'memory_list',
+      description: 'List memories with optional filters.',
+      auth: 'read',
+      schema: z.object({
+        type: z.enum(['session', 'lesson', 'preference']).optional(),
+        projectPath: z.string().optional(),
+        limit: z.number().optional(),
+        offset: z.number().optional(),
+      }),
+      handler: async (params) => {
+        const memories = vault.listMemories({
+          type: params.type as string | undefined,
+          projectPath: params.projectPath as string | undefined,
+          limit: (params.limit as number) ?? 50,
+          offset: (params.offset as number) ?? 0,
+        });
+        const stats = vault.memoryStats();
+        return { memories, stats };
+      },
+    },
+    {
+      name: 'session_capture',
+      description:
+        'Capture a session summary before context compaction. Called automatically by PreCompact hook.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().default('.'),
+        summary: z.string().describe('Brief summary of what was accomplished in this session'),
+        topics: z.array(z.string()).optional().default([]),
+        filesModified: z.array(z.string()).optional().default([]),
+        toolsUsed: z.array(z.string()).optional().default([]),
+      }),
+      handler: async (params) => {
+        const { resolve } = await import('node:path');
+        const projectPath = resolve((params.projectPath as string) ?? '.');
+        const memory = vault.captureMemory({
+          projectPath,
+          type: 'session',
+          context: 'Auto-captured before context compaction',
+          summary: params.summary as string,
+          topics: (params.topics as string[]) ?? [],
+          filesModified: (params.filesModified as string[]) ?? [],
+          toolsUsed: (params.toolsUsed as string[]) ?? [],
+        });
+        return { captured: true, memory, message: 'Session summary saved to memory.' };
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createMemoryExtraOps(runtime),
+    ...createMemoryCrossProjectOps(runtime),
+  ];
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Orchestrate facade — execution orchestration ops.
+ * project registration, playbooks, plan/execute/complete.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createOrchestrateOps } from '../orchestrate-ops.js';
+import { createProjectOps } from '../project-ops.js';
+import { createPlaybookOps } from '../playbook-ops.js';
+
+export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, governance, projectRegistry } = runtime;
+
+  return [
+    // ─── Register (inline from core-ops.ts) ─────────────────────
+    {
+      name: 'register',
+      description:
+        'Register a project for this session. Call on every new session to track usage and get context.',
+      auth: 'write',
+      schema: z.object({
+        projectPath: z.string().optional().default('.'),
+        name: z.string().optional().describe('Project display name (derived from path if omitted)'),
+      }),
+      handler: async (params) => {
+        const { resolve } = await import('node:path');
+        const projectPath = resolve((params.projectPath as string) ?? '.');
+        const project = vault.registerProject(projectPath, params.name as string | undefined);
+        // Also track in project registry for cross-project features
+        projectRegistry.register(projectPath, params.name as string | undefined);
+        const stats = vault.stats();
+        const isNew = project.sessionCount === 1;
+
+        // Expire stale proposals on session start (fire-and-forget)
+        const policy = governance.getPolicy(projectPath);
+        const expired = governance.expireStaleProposals(policy.autoCapture.autoExpireDays);
+
+        const proposalStats = governance.getProposalStats(projectPath);
+        const quotaStatus = governance.getQuotaStatus(projectPath);
+
+        return {
+          project,
+          is_new: isNew,
+          message: isNew
+            ? 'Welcome! New project registered.'
+            : 'Welcome back! Session #' + project.sessionCount + ' for ' + project.name + '.',
+          vault: { entries: stats.totalEntries, domains: Object.keys(stats.byDomain) },
+          governance: {
+            pendingProposals: proposalStats.pending,
+            quotaPercent:
+              quotaStatus.maxTotal > 0
+                ? Math.round((quotaStatus.total / quotaStatus.maxTotal) * 100)
+                : 0,
+            isQuotaWarning: quotaStatus.isWarning,
+            expiredThisSession: expired,
+          },
+        };
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createOrchestrateOps(runtime),
+    ...createProjectOps(runtime),
+    ...createPlaybookOps(runtime),
+  ];
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Plan facade — plan lifecycle ops.
+ * create, approve, execute, reconcile, complete, grading.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createPlanningExtraOps } from '../planning-extra-ops.js';
+import { createGradingOps } from '../grading-ops.js';
+
+export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { planner } = runtime;
+
+  return [
+    // ─── Planning (inline from core-ops.ts) ─────────────────────
+    {
+      name: 'create_plan',
+      description:
+        'Create a new plan in draft status. Plans track multi-step tasks with decisions and sub-tasks.',
+      auth: 'write',
+      schema: z.object({
+        objective: z.string().describe('What the plan aims to achieve'),
+        scope: z.string().describe('Which parts of the codebase are affected'),
+        decisions: z.array(z.string()).optional().default([]),
+        tasks: z
+          .array(z.object({ title: z.string(), description: z.string() }))
+          .optional()
+          .default([]),
+      }),
+      handler: async (params) => {
+        const plan = planner.create({
+          objective: params.objective as string,
+          scope: params.scope as string,
+          decisions: (params.decisions as string[]) ?? [],
+          tasks: (params.tasks as Array<{ title: string; description: string }>) ?? [],
+        });
+        return { created: true, plan };
+      },
+    },
+    {
+      name: 'get_plan',
+      description: 'Get a plan by ID, or list all active plans if no ID provided.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().optional().describe('Plan ID. Omit to list all active plans.'),
+      }),
+      handler: async (params) => {
+        if (params.planId) {
+          const plan = planner.get(params.planId as string);
+          if (!plan) return { error: 'Plan not found: ' + params.planId };
+          return plan;
+        }
+        return { active: planner.getActive(), executing: planner.getExecuting() };
+      },
+    },
+    {
+      name: 'approve_plan',
+      description: 'Approve a draft plan and optionally start execution.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string(),
+        startExecution: z
+          .boolean()
+          .optional()
+          .default(false)
+          .describe('If true, immediately start execution after approval'),
+      }),
+      handler: async (params) => {
+        let plan = planner.approve(params.planId as string);
+        if (params.startExecution) {
+          plan = planner.startExecution(plan.id);
+        }
+        return { approved: true, executing: plan.status === 'executing', plan };
+      },
+    },
+    {
+      name: 'update_task',
+      description: 'Update a task status within an executing plan.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string(),
+        taskId: z.string(),
+        status: z.enum(['pending', 'in_progress', 'completed', 'skipped', 'failed']),
+      }),
+      handler: async (params) => {
+        const plan = planner.updateTask(
+          params.planId as string,
+          params.taskId as string,
+          params.status as 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed',
+        );
+        const task = plan.tasks.find((t) => t.id === params.taskId);
+        return { updated: true, task, plan: { id: plan.id, status: plan.status } };
+      },
+    },
+    {
+      name: 'complete_plan',
+      description: 'Mark an executing plan as completed.',
+      auth: 'write',
+      schema: z.object({
+        planId: z.string(),
+      }),
+      handler: async (params) => {
+        const plan = planner.complete(params.planId as string);
+        const taskSummary = {
+          completed: plan.tasks.filter((t) => t.status === 'completed').length,
+          skipped: plan.tasks.filter((t) => t.status === 'skipped').length,
+          failed: plan.tasks.filter((t) => t.status === 'failed').length,
+          total: plan.tasks.length,
+        };
+        return { completed: true, plan, taskSummary };
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createPlanningExtraOps(runtime),
+    ...createGradingOps(runtime),
+  ];
+}

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

@@ -0,0 +1,223 @@
+/**
+ * Vault facade — knowledge management ops.
+ * search, CRUD, import/export, intake, archival.
+ */
+
+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 { createVaultExtraOps } from '../vault-extra-ops.js';
+import { createCaptureOps } from '../capture-ops.js';
+import { createIntakeOps } from '../intake-ops.js';
+
+export function createVaultFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, brain, cognee, llmClient, syncManager, intakePipeline } = runtime;
+
+  return [
+    // ─── Search / Vault (inline from core-ops.ts) ───────────────
+    {
+      name: 'search',
+      description:
+        'Search across all knowledge domains. Results ranked by TF-IDF + severity + recency + tag overlap + domain match.',
+      auth: 'read',
+      schema: z.object({
+        query: z.string(),
+        domain: z.string().optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']).optional(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        tags: z.array(z.string()).optional(),
+        limit: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return brain.intelligentSearch(params.query as string, {
+          domain: params.domain as string | undefined,
+          type: params.type as string | undefined,
+          severity: params.severity as string | undefined,
+          tags: params.tags as string[] | undefined,
+          limit: (params.limit as number) ?? 10,
+        });
+      },
+    },
+    {
+      name: 'vault_stats',
+      description: 'Get vault statistics — entry counts by type, domain, severity.',
+      auth: 'read',
+      handler: async () => vault.stats(),
+    },
+    {
+      name: 'list_all',
+      description: 'List all knowledge entries with optional filters.',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']).optional(),
+        severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
+        tags: z.array(z.string()).optional(),
+        limit: z.number().optional(),
+        offset: z.number().optional(),
+      }),
+      handler: async (params) => {
+        return vault.list({
+          domain: params.domain as string | undefined,
+          type: params.type as string | undefined,
+          severity: params.severity as string | undefined,
+          tags: params.tags as string[] | undefined,
+          limit: (params.limit as number) ?? 50,
+          offset: (params.offset as number) ?? 0,
+        });
+      },
+    },
+    {
+      name: 'export',
+      description:
+        'Export vault entries as JSON intelligence bundles — one per domain. Enables version control and sharing.',
+      auth: 'read',
+      schema: z.object({
+        domain: z.string().optional().describe('Export only this domain. Omit to export all.'),
+      }),
+      handler: async (params) => {
+        const stats = vault.stats();
+        const domains = params.domain ? [params.domain as string] : Object.keys(stats.byDomain);
+        const bundles: Array<{ domain: string; version: string; entries: IntelligenceEntry[] }> =
+          [];
+        for (const d of domains) {
+          const entries = vault.list({ domain: d, limit: 10000 });
+          bundles.push({ domain: d, version: '1.0.0', entries });
+        }
+        return {
+          exported: true,
+          bundles,
+          totalEntries: bundles.reduce((sum, b) => sum + b.entries.length, 0),
+          domains: bundles.map((b) => b.domain),
+        };
+      },
+    },
+
+    // ─── Enriched Capture ────────────────────────────────────────
+    {
+      name: 'capture_enriched',
+      description:
+        'Unified LLM-enriched capture — accepts minimal fields (title, description, type), uses LLM to auto-infer tags, category, and severity.',
+      auth: 'write',
+      schema: z.object({
+        title: z.string().describe('Knowledge title'),
+        description: z.string().describe('Knowledge description'),
+        type: z
+          .enum(['pattern', 'anti-pattern', 'rule', 'playbook'])
+          .optional()
+          .describe('Entry type. If omitted, LLM infers from content.'),
+        domain: z.string().optional().describe('Domain. If omitted, LLM infers.'),
+        tags: z.array(z.string()).optional().describe('Tags. LLM adds more if needed.'),
+      }),
+      handler: async (params) => {
+        try {
+          const title = params.title as string;
+          const description = params.description as string;
+
+          // Try LLM enrichment for auto-tagging
+          let inferredTags: string[] = (params.tags as string[] | undefined) ?? [];
+          let inferredType = (params.type as IntelligenceEntry['type'] | undefined) ?? 'pattern';
+          const inferredDomain = (params.domain as string | undefined) ?? 'general';
+          let inferredSeverity: IntelligenceEntry['severity'] = 'suggestion';
+          const enriched = false;
+
+          try {
+            const captureId = `enriched-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+            const enrichResult = brain.enrichAndCapture({
+              id: captureId,
+              title,
+              description,
+              type: inferredType,
+              domain: inferredDomain,
+              severity: inferredSeverity,
+              tags: inferredTags,
+            });
+
+            if (enrichResult.captured) {
+              return {
+                captured: true,
+                enriched: true,
+                entryId: enrichResult.id,
+                autoTags: enrichResult.autoTags,
+                duplicate: enrichResult.duplicate ?? null,
+              };
+            }
+          } catch {
+            // LLM enrichment failed — fall back to basic capture
+          }
+
+          // Fallback: basic capture without LLM enrichment
+          // Infer type from keywords
+          const lowerDesc = description.toLowerCase();
+          if (!params.type) {
+            if (
+              lowerDesc.includes('avoid') ||
+              lowerDesc.includes("don't") ||
+              lowerDesc.includes('anti-pattern')
+            )
+              inferredType = 'anti-pattern';
+            else if (
+              lowerDesc.includes('rule') ||
+              lowerDesc.includes('must') ||
+              lowerDesc.includes('always')
+            )
+              inferredType = 'rule';
+          }
+
+          // Infer severity from keywords
+          if (
+            lowerDesc.includes('critical') ||
+            lowerDesc.includes('security') ||
+            lowerDesc.includes('breaking')
+          )
+            inferredSeverity = 'critical';
+          else if (
+            lowerDesc.includes('warning') ||
+            lowerDesc.includes('careful') ||
+            lowerDesc.includes('avoid')
+          )
+            inferredSeverity = 'warning';
+
+          // Auto-generate tags from title words
+          if (inferredTags.length === 0) {
+            inferredTags = title
+              .toLowerCase()
+              .split(/\s+/)
+              .filter(
+                (w) =>
+                  w.length > 3 && !['with', 'from', 'that', 'this', 'have', 'been'].includes(w),
+              )
+              .slice(0, 5);
+          }
+
+          const entry: IntelligenceEntry = {
+            id: `enriched-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+            type: inferredType,
+            domain: inferredDomain,
+            title,
+            severity: inferredSeverity,
+            description,
+            tags: inferredTags,
+          };
+
+          vault.add(entry);
+
+          return {
+            captured: true,
+            enriched,
+            entry,
+            autoTags: inferredTags,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createVaultExtraOps(runtime),
+    ...createCaptureOps(runtime),
+    ...createIntakeOps(intakePipeline),
+  ];
+}

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

@@ -1,9 +1,9 @@
 /**
- * Extra vault operations — 23 ops that extend the 4 base vault ops in core-ops.ts.
+ * Extra vault operations — 25 ops that extend the 4 base vault ops in core-ops.ts.
  *
  * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3),
  *         analytics (1), seed canonical (1), knowledge lifecycle (4), temporal (3),
- *         archival (3).
+ *         archival (3), content hashing (2).
  */
 
 import { z } from 'zod';
@@ -586,6 +586,42 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return vault.optimize();
       },
     },
+
+    // ── Content hashing (#166) ────────────────────────────────────────
+    {
+      name: 'vault_content_hash',
+      description: 'Compute content hash for an entry without inserting',
+      auth: 'read' as const,
+      schema: z.object({
+        type: z.string(),
+        domain: z.string(),
+        title: z.string(),
+        description: z.string(),
+        tags: z.array(z.string()).optional(),
+        example: z.string().optional(),
+        counterExample: z.string().optional(),
+      }),
+      handler: async (params) => {
+        const { computeContentHash: hashFn } = await import('../vault/content-hash.js');
+        const hash = hashFn(params as unknown as Parameters<typeof hashFn>[0]);
+        const existingId = vault.findByContentHash(hash);
+        return { hash, duplicate: existingId !== null, existingId };
+      },
+    },
+    {
+      name: 'vault_dedup_status',
+      description: 'Report content hash coverage and duplicate statistics',
+      auth: 'read' as const,
+      handler: async () => {
+        const stats = vault.contentHashStats();
+        const duplicates = stats.total - stats.uniqueHashes;
+        return {
+          ...stats,
+          duplicates,
+          coverage: stats.total > 0 ? Math.round((stats.hashed / stats.total) * 100) : 100,
+        };
+      },
+    },
   ];
 }
 

package/src/streams/index.ts

@@ -0,0 +1,3 @@
+export { ReplayableStream } from './replayable-stream.js';
+export { normalize, collect } from './normalize.js';
+export type { NestableInput } from './normalize.js';

package/src/streams/normalize.ts

@@ -0,0 +1,56 @@
+/**
+ * Input type that supports arbitrary nesting of sync/async values.
+ */
+export type NestableInput<T> =
+  | T
+  | T[]
+  | Promise<T | T[]>
+  | AsyncIterable<T>
+  | Iterable<NestableInput<T>>;
+
+function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+  return (
+    value !== null &&
+    value !== undefined &&
+    typeof value === 'object' &&
+    Symbol.asyncIterator in value
+  );
+}
+
+function isSyncIterable<T>(value: unknown): value is Iterable<T> {
+  return (
+    value !== null && value !== undefined && typeof value === 'object' && Symbol.iterator in value
+  );
+}
+
+/**
+ * Recursively flatten nested async/sync inputs into a flat AsyncIterable<T>.
+ * Discrimination: Promise → AsyncIterable → Iterable (excluding strings) → leaf T.
+ */
+export async function* normalize<T>(input: NestableInput<T>): AsyncIterable<T> {
+  if (input instanceof Promise) {
+    const resolved = await input;
+    yield* normalize<T>(resolved as NestableInput<T>);
+  } else if (isAsyncIterable<T>(input)) {
+    for await (const item of input) {
+      yield item;
+    }
+  } else if (typeof input !== 'string' && isSyncIterable<NestableInput<T>>(input)) {
+    for (const item of input) {
+      yield* normalize<T>(item);
+    }
+  } else {
+    yield input as T;
+  }
+}
+
+/**
+ * Collect an AsyncIterable<T> into a Promise<T[]>.
+ */
+export async function collect<T>(source: AsyncIterable<T>): Promise<T[]> {
+  const items: T[] = [];
+  for await (const item of source) {
+    items.push(item);
+  }
+  return items;
+}