@soleri/core 2.1.0 → 2.5.0

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

@@ -0,0 +1,85 @@
+/**
+ * Extra curator operations — 5 ops that extend the 8 base curator ops in core-ops.ts.
+ *
+ * Groups: entry history (2), queue stats (1), metadata enrichment (1), hybrid detection (1).
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+export function createCuratorExtraOps(runtime: AgentRuntime): OpDefinition[] {
+  const { curator } = runtime;
+
+  return [
+    // ─── Entry History ──────────────────────────────────────────────
+    {
+      name: 'curator_entry_history',
+      description: 'Get version history (snapshots) for a vault entry.',
+      auth: 'read',
+      schema: z.object({
+        entryId: z.string().describe('Entry ID to get history for.'),
+      }),
+      handler: async (params) => {
+        const history = curator.getVersionHistory(params.entryId as string);
+        return { entryId: params.entryId, history, count: history.length };
+      },
+    },
+    {
+      name: 'curator_record_snapshot',
+      description: "Manually record a snapshot of an entry's current state.",
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string().describe('Entry ID to snapshot.'),
+        changedBy: z.string().optional().describe('Who made the change. Default "system".'),
+        changeReason: z.string().optional().describe('Why the snapshot was recorded.'),
+      }),
+      handler: async (params) => {
+        return curator.recordSnapshot(
+          params.entryId as string,
+          params.changedBy as string | undefined,
+          params.changeReason as string | undefined,
+        );
+      },
+    },
+
+    // ─── Queue Stats ────────────────────────────────────────────────
+    {
+      name: 'curator_queue_stats',
+      description:
+        'Grooming queue statistics — total, groomed, ungroomed, stale (30+ days), fresh (7 days), average days since groom.',
+      auth: 'read',
+      handler: async () => {
+        return curator.getQueueStats();
+      },
+    },
+
+    // ─── Metadata Enrichment ────────────────────────────────────────
+    {
+      name: 'curator_enrich',
+      description:
+        'Rule-based metadata enrichment — auto-capitalize title, normalize tags, infer severity/type from keywords, trim description.',
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string().describe('Entry ID to enrich.'),
+      }),
+      handler: async (params) => {
+        return curator.enrichMetadata(params.entryId as string);
+      },
+    },
+
+    // ─── Hybrid Contradiction Detection (#36) ────────────────────────
+    {
+      name: 'curator_hybrid_contradictions',
+      description:
+        'Detect contradictions using hybrid TF-IDF + Cognee vector similarity. Falls back to TF-IDF only when Cognee is unavailable.',
+      auth: 'read',
+      schema: z.object({
+        threshold: z.number().optional().describe('Similarity threshold (default 0.4)'),
+      }),
+      handler: async (params) => {
+        return curator.detectContradictionsHybrid(params.threshold as number | undefined);
+      },
+    },
+  ];
+}

package/src/runtime/domain-ops.ts

@@ -25,7 +25,7 @@ export function createDomainFacade(
   agentId: string,
   domain: string,
 ): FacadeConfig {
-  const { vault, brain } = runtime;
+  const { vault, brain, governance } = runtime;
   const facadeName = `${agentId}_${domain.replace(/-/g, '_')}`;
 
   const ops: OpDefinition[] = [
@@ -36,7 +36,7 @@ export function createDomainFacade(
       schema: z.object({
         tags: z.array(z.string()).optional(),
         severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
-        type: z.enum(['pattern', 'anti-pattern', 'rule']).optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']).optional(),
         limit: z.number().optional(),
       }),
       handler: async (params) => {
@@ -83,7 +83,7 @@ export function createDomainFacade(
       auth: 'write',
       schema: z.object({
         id: z.string(),
-        type: z.enum(['pattern', 'anti-pattern', 'rule']),
+        type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']),
         title: z.string(),
         severity: z.enum(['critical', 'warning', 'suggestion']),
         description: z.string(),
@@ -92,21 +92,73 @@ export function createDomainFacade(
         counterExample: z.string().optional(),
         why: z.string().optional(),
         tags: z.array(z.string()).optional().default([]),
+        projectPath: z.string().optional().default('.'),
       }),
       handler: async (params) => {
-        return brain.enrichAndCapture({
-          id: params.id as string,
-          type: params.type as 'pattern' | 'anti-pattern' | 'rule',
-          domain,
-          title: params.title as string,
-          severity: params.severity as 'critical' | 'warning' | 'suggestion',
-          description: params.description as string,
-          context: params.context as string | undefined,
-          example: params.example as string | undefined,
-          counterExample: params.counterExample as string | undefined,
-          why: params.why as string | undefined,
-          tags: params.tags as string[],
+        const projectPath = (params.projectPath as string | undefined) ?? '.';
+        const entryType = params.type as string;
+        const title = params.title as string;
+
+        const decision = governance.evaluateCapture(projectPath, {
+          type: entryType,
+          category: domain,
+          title,
         });
+
+        switch (decision.action) {
+          case 'capture': {
+            const result = brain.enrichAndCapture({
+              id: params.id as string,
+              type: params.type as 'pattern' | 'anti-pattern' | 'rule',
+              domain,
+              title,
+              severity: params.severity as 'critical' | 'warning' | 'suggestion',
+              description: params.description as string,
+              context: params.context as string | undefined,
+              example: params.example as string | undefined,
+              counterExample: params.counterExample as string | undefined,
+              why: params.why as string | undefined,
+              tags: params.tags as string[],
+            });
+            return { ...result, governance: { action: 'capture' as const } };
+          }
+          case 'propose': {
+            const proposalId = governance.propose(
+              projectPath,
+              {
+                entryId: params.id as string,
+                title,
+                type: entryType,
+                category: domain,
+                data: {
+                  severity: params.severity,
+                  description: params.description,
+                  context: params.context,
+                  example: params.example,
+                  counterExample: params.counterExample,
+                  why: params.why,
+                  tags: params.tags,
+                },
+              },
+              'domain-capture',
+            );
+            return {
+              captured: false,
+              id: params.id as string,
+              autoTags: [],
+              governance: { action: 'propose' as const, proposalId, reason: decision.reason },
+            };
+          }
+          default: {
+            // reject or quarantine
+            return {
+              captured: false,
+              id: params.id as string,
+              autoTags: [],
+              governance: { action: decision.action, reason: decision.reason },
+            };
+          }
+        }
       },
     },
     {

package/src/runtime/grading-ops.ts

@@ -0,0 +1,130 @@
+/**
+ * Plan grading operations — 5 ops for iterative plan quality scoring.
+ * Uses 6-pass gap analysis with severity-weighted scoring (ported from Salvador).
+ *
+ * Ops: plan_grade, plan_check_history, plan_latest_check,
+ *      plan_meets_grade, plan_auto_improve.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+
+const planGradeSchema = z.enum(['A+', 'A', 'B', 'C', 'D', 'F']);
+
+/**
+ * Create the 5 plan grading operations for an agent runtime.
+ */
+export function createGradingOps(runtime: AgentRuntime): OpDefinition[] {
+  const { planner } = runtime;
+
+  return [
+    {
+      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.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('The plan ID to grade.'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        return planner.grade(planId);
+      },
+    },
+
+    {
+      name: 'plan_check_history',
+      description:
+        'Get all grading checks for a plan (history). Shows score progression across iterations.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('The plan ID.'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const checks = planner.getCheckHistory(planId);
+        return { planId, count: checks.length, checks };
+      },
+    },
+
+    {
+      name: 'plan_latest_check',
+      description: 'Get the latest grading check for a plan.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('The plan ID.'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const check = planner.getLatestCheck(planId);
+        return check ?? { planId, check: null, message: 'No checks found for this plan.' };
+      },
+    },
+
+    {
+      name: 'plan_meets_grade',
+      description:
+        'Check if a plan meets a target grade. Thresholds: A+=95, A=90, B=80, C=70, D=60.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('The plan ID.'),
+        targetGrade: planGradeSchema.describe('Target grade: A+, A, B, C, D, or F.'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const targetGrade = params.targetGrade as 'A+' | 'A' | 'B' | 'C' | 'D' | 'F';
+        return planner.meetsGrade(planId, targetGrade);
+      },
+    },
+
+    {
+      name: 'plan_auto_improve',
+      description:
+        'Grade a plan and return gaps grouped by severity with actionable recommendations. Critical gaps first.',
+      auth: 'read',
+      schema: z.object({
+        planId: z.string().describe('The plan ID.'),
+      }),
+      handler: async (params) => {
+        const planId = params.planId as string;
+        const check = planner.grade(planId);
+
+        // Sort gaps by severity: critical > major > minor > info
+        const severityOrder: Record<string, number> = { critical: 0, major: 1, minor: 2, info: 3 };
+        const sortedGaps = [...check.gaps].sort(
+          (a, b) => (severityOrder[a.severity] ?? 4) - (severityOrder[b.severity] ?? 4),
+        );
+
+        // Group by severity for structured output
+        const grouped: Record<
+          string,
+          Array<{
+            category: string;
+            description: string;
+            recommendation: string;
+            location?: string;
+          }>
+        > = {};
+        for (const g of sortedGaps) {
+          if (!grouped[g.severity]) grouped[g.severity] = [];
+          grouped[g.severity].push({
+            category: g.category,
+            description: g.description,
+            recommendation: g.recommendation,
+            ...(g.location ? { location: g.location } : {}),
+          });
+        }
+
+        return {
+          grade: check.grade,
+          score: check.score,
+          iteration: check.iteration,
+          totalGaps: check.gaps.length,
+          gapsBySeverity: grouped,
+          nextAction: check.score >= 90 ? 'approve' : 'iterate',
+        };
+      },
+    },
+  ];
+}

package/src/runtime/intake-ops.ts

@@ -0,0 +1,126 @@
+/**
+ * Intake operations — 4 ops for book/PDF ingestion.
+ *
+ * Ops: intake_ingest_book, intake_process, intake_status, intake_preview.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { IntakePipeline } from '../intake/intake-pipeline.js';
+
+/**
+ * Create the 4 intake operations.
+ *
+ * The pipeline is optional — when null, all ops return a graceful error.
+ */
+export function createIntakeOps(pipeline: IntakePipeline | null): OpDefinition[] {
+  return [
+    // ─── Ingest Book ──────────────────────────────────────────────
+    {
+      name: 'intake_ingest_book',
+      description:
+        'Ingest a PDF book — parse, hash, chunk into fixed-size page windows, and create a resumable job.',
+      auth: 'write',
+      schema: z.object({
+        pdfPath: z.string().describe('Absolute path to the PDF file.'),
+        title: z.string().describe('Book title for citation and chunk labeling.'),
+        domain: z.string().describe('Knowledge domain (e.g., "design-systems", "accessibility").'),
+        author: z.string().optional().describe('Book author for metadata.'),
+        chunkPageSize: z.number().optional().describe('Number of pages per chunk. Defaults to 10.'),
+        tags: z
+          .array(z.string())
+          .optional()
+          .describe('Additional tags applied to all extracted entries.'),
+      }),
+      handler: async (params) => {
+        if (!pipeline) {
+          return { error: 'Intake pipeline not configured' };
+        }
+        const config = {
+          pdfPath: params.pdfPath as string,
+          title: params.title as string,
+          domain: params.domain as string,
+          author: params.author as string | undefined,
+          chunkPageSize: params.chunkPageSize as number | undefined,
+          tags: params.tags as string[] | undefined,
+        };
+        return pipeline.ingestBook(config);
+      },
+    },
+
+    // ─── Process Chunks ───────────────────────────────────────────
+    {
+      name: 'intake_process',
+      description:
+        'Process pending chunks for a job — extract text, classify via LLM, dedup, and store unique items in the vault.',
+      auth: 'write',
+      schema: z.object({
+        jobId: z.string().describe('Job ID returned from intake_ingest_book.'),
+        count: z
+          .number()
+          .optional()
+          .describe('Max number of chunks to process in this batch. Defaults to 5.'),
+      }),
+      handler: async (params) => {
+        if (!pipeline) {
+          return { error: 'Intake pipeline not configured' };
+        }
+        return pipeline.processChunks(params.jobId as string, params.count as number | undefined);
+      },
+    },
+
+    // ─── Status ───────────────────────────────────────────────────
+    {
+      name: 'intake_status',
+      description:
+        'Get intake job status. With jobId: returns job record and chunks. Without: lists all jobs.',
+      auth: 'read',
+      schema: z.object({
+        jobId: z.string().optional().describe('Job ID to inspect. Omit to list all jobs.'),
+      }),
+      handler: async (params) => {
+        if (!pipeline) {
+          return { error: 'Intake pipeline not configured' };
+        }
+        const jobId = params.jobId as string | undefined;
+        if (jobId) {
+          const job = pipeline.getJob(jobId);
+          if (!job) {
+            return { error: `Job not found: ${jobId}` };
+          }
+          const chunks = pipeline.getChunks(jobId);
+          return { job, chunks };
+        }
+        return { jobs: pipeline.listJobs() };
+      },
+    },
+
+    // ─── Preview ──────────────────────────────────────────────────
+    {
+      name: 'intake_preview',
+      description:
+        'Preview what the pipeline would extract from a page range — parses and classifies without storing.',
+      auth: 'read',
+      schema: z.object({
+        pdfPath: z.string().describe('Absolute path to the PDF file.'),
+        title: z.string().describe('Book title for citation context.'),
+        domain: z.string().describe('Knowledge domain for classification context.'),
+        pageStart: z.number().describe('First page of the range (1-indexed, inclusive).'),
+        pageEnd: z.number().describe('Last page of the range (1-indexed, inclusive).'),
+      }),
+      handler: async (params) => {
+        if (!pipeline) {
+          return { error: 'Intake pipeline not configured' };
+        }
+        const { pdfPath, title, domain, pageStart, pageEnd } = params as {
+          pdfPath: string;
+          title: string;
+          domain: string;
+          pageStart: number;
+          pageEnd: number;
+        };
+        return pipeline.preview({ pdfPath, title, domain }, pageStart, pageEnd);
+      },
+    },
+  ];
+}