@soleri/core 2.7.0 → 2.9.0

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/grading-ops.ts

@@ -1,6 +1,6 @@
 /**
  * Plan grading operations — 5 ops for iterative plan quality scoring.
- * Uses 6-pass gap analysis with severity-weighted scoring (ported from Salvador).
+ * Uses 7-pass gap analysis with severity-weighted scoring + substance bonuses.
  *
  * Ops: plan_grade, plan_check_history, plan_latest_check,
  *      plan_meets_grade, plan_auto_improve.
@@ -22,7 +22,7 @@ export function createGradingOps(runtime: AgentRuntime): OpDefinition[] {
     {
       name: 'plan_grade',
       description:
-        'Grade a plan using 6-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2). Returns grade, score, gaps with recommendations, and iteration number.',
+        'Grade a plan using 7-pass gap analysis — severity-weighted scoring (critical=30, major=15, minor=2) with substance bonuses for vault-informed depth. Returns grade, score, gaps with recommendations, and iteration number.',
       auth: 'read',
       schema: z.object({
         planId: z.string().describe('The plan ID to grade.'),

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

package/src/streams/replayable-stream.ts

@@ -0,0 +1,92 @@
+/**
+ * Multi-consumer async stream that replays from a buffer.
+ * Source executes exactly once — new iterators replay from buffer[0].
+ */
+export class ReplayableStream<T> implements AsyncIterable<T> {
+  private buffer: T[] = [];
+  private source: AsyncIterator<T>;
+  private done = false;
+  private error: unknown = undefined;
+  private waiters: Array<{
+    resolve: (result: IteratorResult<T, undefined>) => void;
+    reject: (err: unknown) => void;
+  }> = [];
+  private advancing = false;
+
+  constructor(source: AsyncIterable<T>) {
+    this.source = source[Symbol.asyncIterator]();
+  }
+
+  private async advance(): Promise<void> {
+    if (this.advancing || this.done) return;
+    this.advancing = true;
+    try {
+      const result = await this.source.next();
+      if (result.done) {
+        this.done = true;
+        for (const waiter of this.waiters) {
+          waiter.resolve({ value: undefined, done: true });
+        }
+        this.waiters.length = 0;
+      } else {
+        this.buffer.push(result.value);
+        for (const waiter of this.waiters) {
+          waiter.resolve({ value: result.value, done: false });
+        }
+        this.waiters.length = 0;
+      }
+    } catch (err) {
+      this.done = true;
+      this.error = err;
+      for (const waiter of this.waiters) {
+        waiter.reject(err);
+      }
+      this.waiters.length = 0;
+    } finally {
+      this.advancing = false;
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    let index = 0;
+    return {
+      next: async (): Promise<IteratorResult<T>> => {
+        if (index < this.buffer.length) {
+          return { value: this.buffer[index++], done: false };
+        }
+        if (this.done) {
+          if (this.error) throw this.error;
+          return { value: undefined, done: true };
+        }
+        // Need to advance the source
+        return new Promise<IteratorResult<T, undefined>>((resolve, reject) => {
+          this.waiters.push({ resolve, reject });
+          if (!this.advancing) {
+            this.advance().catch(() => {
+              // Error already propagated to waiters via reject
+            });
+          }
+        }).then((result) => {
+          if (!result.done) index++;
+          return result;
+        });
+      },
+    };
+  }
+
+  async collect(): Promise<T[]> {
+    const items: T[] = [];
+    for await (const item of this) {
+      items.push(item);
+    }
+    return items;
+  }
+
+  get bufferedCount(): number {
+    return this.buffer.length;
+  }
+
+  get isDone(): boolean {
+    return this.done;
+  }
+}

package/src/vault/content-hash.ts

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+
+export interface HashableEntry {
+  type: string;
+  domain: string;
+  title: string;
+  description: string;
+  tags?: string[];
+  example?: string;
+  counterExample?: string;
+}
+
+/**
+ * Compute a deterministic SHA-256 content hash for a vault entry.
+ * Normalizes fields (lowercase domain, trim, sort tags/keys) before hashing.
+ * Returns 40-char hex string. Excludes mutable fields (id, severity, timestamps).
+ */
+export function computeContentHash(entry: HashableEntry): string {
+  const normalized = {
+    counterExample: (entry.counterExample ?? '').trim(),
+    description: entry.description.trim(),
+    domain: entry.domain.toLowerCase().trim(),
+    example: (entry.example ?? '').trim(),
+    tags: [...(entry.tags ?? [])].sort(),
+    title: entry.title.trim(),
+    type: entry.type.trim(),
+  };
+  // Keys already alphabetical — JSON.stringify preserves insertion order
+  const json = JSON.stringify(normalized);
+  return createHash('sha256').update(json, 'utf8').digest('hex').slice(0, 40);
+}