@soleri/core 2.7.0 → 2.9.0

package/src/extensions/middleware.ts

@@ -0,0 +1,53 @@
+import type { FacadeConfig } from '../facades/types.js';
+import type { OpMiddleware } from './types.js';
+
+/**
+ * Wrap all ops in the given facades with middleware.
+ *
+ * Middleware chain follows the onion model:
+ * - before hooks: first middleware → last middleware → handler
+ * - after hooks:  last middleware → first middleware (reverse)
+ *
+ * This mutates the facade ops in-place (replaces handlers).
+ */
+export function wrapWithMiddleware(facades: FacadeConfig[], middleware: OpMiddleware[]): void {
+  if (middleware.length === 0) return;
+
+  for (const facade of facades) {
+    for (const op of facade.ops) {
+      const originalHandler = op.handler;
+
+      op.handler = async (params: Record<string, unknown>) => {
+        // Run before hooks (first → last)
+        let currentParams = params;
+        for (const mw of middleware) {
+          if (mw.before) {
+            currentParams = await mw.before({
+              facade: facade.name,
+              op: op.name,
+              params: currentParams,
+            });
+          }
+        }
+
+        // Run original handler
+        let result = await originalHandler(currentParams);
+
+        // Run after hooks (last → first)
+        for (let i = middleware.length - 1; i >= 0; i--) {
+          const mw = middleware[i];
+          if (mw.after) {
+            result = await mw.after({
+              facade: facade.name,
+              op: op.name,
+              params: currentParams,
+              result,
+            });
+          }
+        }
+
+        return result;
+      };
+    }
+  }
+}

package/src/extensions/types.ts

@@ -0,0 +1,64 @@
+import type { OpDefinition, FacadeConfig } from '../facades/types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+/**
+ * Middleware that wraps op execution with before/after hooks.
+ *
+ * - `before` runs before the op handler. Return modified params or throw to reject.
+ * - `after` runs after the op handler. Return modified result or throw.
+ *
+ * Multiple middleware are chained: before hooks run first→last,
+ * after hooks run last→first (onion model).
+ */
+export interface OpMiddleware {
+  /** Middleware name (for logging/debugging) */
+  name: string;
+  /** Runs before op handler. Return modified params or throw to reject. */
+  before?: (ctx: MiddlewareContext) => Promise<Record<string, unknown>>;
+  /** Runs after op handler. Return modified result or throw. */
+  after?: (ctx: MiddlewareContext & { result: unknown }) => Promise<unknown>;
+}
+
+export interface MiddlewareContext {
+  facade: string;
+  op: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * User-defined extensions for a Soleri agent.
+ *
+ * Extensions live in `src/extensions/` and are auto-discovered by the entry
+ * point at startup. Core ops from `@soleri/core` are never modified — extensions
+ * are additive (new ops, new facades) or decorative (middleware).
+ *
+ * @example
+ * ```ts
+ * // src/extensions/index.ts
+ * import type { AgentExtensions } from '@soleri/core';
+ * import type { AgentRuntime } from '@soleri/core';
+ *
+ * export default function loadExtensions(runtime: AgentRuntime): AgentExtensions {
+ *   return {
+ *     ops: [myCustomOp(runtime)],
+ *     facades: [myCustomFacade(runtime)],
+ *     middleware: [auditLogger],
+ *   };
+ * }
+ * ```
+ */
+export interface AgentExtensions {
+  /** Extra ops merged into the core facade */
+  ops?: OpDefinition[];
+  /** New facades registered as separate MCP tools */
+  facades?: FacadeConfig[];
+  /** Middleware applied to all ops across all facades */
+  middleware?: OpMiddleware[];
+  /** Lifecycle hooks */
+  hooks?: {
+    /** Called after runtime init, before MCP server starts */
+    onStartup?: (runtime: AgentRuntime) => Promise<void>;
+    /** Called on SIGTERM/SIGINT before process exits */
+    onShutdown?: (runtime: AgentRuntime) => Promise<void>;
+  };
+}

package/src/index.ts

@@ -29,8 +29,6 @@ export type {
   MergedPlaybook,
   PlaybookMatchResult,
 } from './playbooks/index.js';
-export { createPlaybookOps } from './runtime/playbook-ops.js';
-
 // ─── Text Utilities ─────────────────────────────────────────────────
 export {
   tokenize,
@@ -239,6 +237,10 @@ export {
 export { KeyPool, loadKeyPoolConfig } from './llm/key-pool.js';
 export type { KeyPoolFiles } from './llm/key-pool.js';
 
+// ─── Extensions ──────────────────────────────────────────────────────
+export type { AgentExtensions, OpMiddleware, MiddlewareContext } from './extensions/index.js';
+export { wrapWithMiddleware } from './extensions/index.js';
+
 // ─── Facades ─────────────────────────────────────────────────────────
 export { registerFacade, registerAllFacades } from './facades/facade-factory.js';
 export { facadeInputSchema } from './facades/types.js';
@@ -285,22 +287,8 @@ export type { LogLevel, LogEntry, LogContext, LoggerConfig } from './logging/typ
 
 // ─── Runtime Factory ────────────────────────────────────────────────
 export { createAgentRuntime } from './runtime/runtime.js';
-export { createCoreOps } from './runtime/core-ops.js';
+export { createSemanticFacades } from './runtime/facades/index.js';
 export { createDomainFacade, createDomainFacades } from './runtime/domain-ops.js';
-export { createPlanningExtraOps } from './runtime/planning-extra-ops.js';
-export { createMemoryExtraOps } from './runtime/memory-extra-ops.js';
-export { createVaultExtraOps } from './runtime/vault-extra-ops.js';
-export { createAdminOps } from './runtime/admin-ops.js';
-export { createAdminExtraOps } from './runtime/admin-extra-ops.js';
-export { createLoopOps } from './runtime/loop-ops.js';
-export { createOrchestrateOps } from './runtime/orchestrate-ops.js';
-export { createGradingOps } from './runtime/grading-ops.js';
-export { createCaptureOps } from './runtime/capture-ops.js';
-export { createCuratorExtraOps } from './runtime/curator-extra-ops.js';
-export { createProjectOps } from './runtime/project-ops.js';
-export { createMemoryCrossProjectOps } from './runtime/memory-cross-project-ops.js';
-export { createCogneeSyncOps } from './runtime/cognee-sync-ops.js';
-export { createIntakeOps } from './runtime/intake-ops.js';
 export type { AgentRuntimeConfig, AgentRuntime } from './runtime/types.js';
 
 // ─── Errors ────────────────────────────────────────────────────────────
@@ -337,6 +325,15 @@ export type {
   FtsSearchOptions,
 } from './persistence/index.js';
 
+// ─── Streams ──────────────────────────────────────────────────────────
+export { ReplayableStream } from './streams/index.js';
+export { normalize, collect } from './streams/index.js';
+export type { NestableInput } from './streams/index.js';
+
+// ─── Content Hashing ──────────────────────────────────────────────────
+export { computeContentHash } from './vault/content-hash.js';
+export type { HashableEntry } from './vault/content-hash.js';
+
 // ─── Prompts ───────────────────────────────────────────────────────────
 export { TemplateManager, parseVariables, resolveIncludes } from './prompts/index.js';
 export type { PromptTemplate, TemplateVariable, RenderOptions } from './prompts/index.js';

package/src/planning/gap-analysis.ts

@@ -3,13 +3,14 @@
  * Ported from Salvador MCP's plan-gap-content.ts / plan-gap-technical.ts /
  * plan-gap-domain.ts / plan-gap-antipattern.ts.
  *
- * 6 built-in passes (always run):
+ * 7 built-in passes (always run):
  *   1. Structure     — required fields present and sufficiently long
  *   2. Completeness  — measurable objectives, decision rationale, scope exclusions
  *   3. Feasibility   — overly broad scope, missing dependency awareness
  *   4. Risk          — breaking changes without mitigation, missing verification
  *   5. Clarity       — ambiguous language, vague criteria
  *   6. Semantic Quality — generic objectives, shallow rationale, non-concrete approach
+ *   7. Knowledge Depth — BONUS: vault pattern refs, acceptance criteria, domain indicators
  *
  * Opt-in pass factories (registered via customPasses):
  *   - createToolFeasibilityPass  — validates tool_chain entries and ordering
@@ -517,6 +518,98 @@ function analyzeSemanticQuality(plan: Plan): PlanGap[] {
   return gaps;
 }
 
+// ─── Pass 7: Knowledge Depth (Substance Bonuses) ────────────────
+
+/**
+ * Patterns that indicate vault/knowledge-informed content in task descriptions.
+ * Each match earns a bonus point — rewarding plans that reference specific
+ * patterns, anti-patterns, or domain knowledge rather than generic guidance.
+ */
+const KNOWLEDGE_INDICATORS = [
+  /vault\s*pattern/i,
+  /vault\s*patterns/i,
+  /anti-pattern/i,
+  /wcag\s*[\d.]+/i,
+  /aria-[a-z]+/i,
+  /\d+(\.\d+)?:\d+\s*(contrast|ratio)/i,
+  /\d+px\s*(touch|target|minimum|min)/i,
+  /acceptance\s*criteria/i,
+];
+
+/** Checks if task descriptions reference specific named patterns (e.g. "zod-form-validation"). */
+const NAMED_PATTERN_REGEX = /[a-z]+-[a-z]+-[a-z]+/;
+
+function analyzeKnowledgeDepth(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const allTaskText = taskText(plan);
+
+  // Bonus: tasks reference vault patterns by name
+  let namedPatternCount = 0;
+  for (const task of plan.tasks) {
+    const desc = task.description || '';
+    const matches = desc.match(/[a-z]+-[a-z]+(-[a-z]+)*/g) || [];
+    // Filter to likely pattern IDs (hyphenated, 2+ segments, not common words)
+    const patternRefs = matches.filter(
+      (m) => m.length > 8 && NAMED_PATTERN_REGEX.test(m) && !['front-end', 'back-end', 'real-time', 'client-side', 'server-side'].includes(m),
+    );
+    namedPatternCount += patternRefs.length;
+  }
+
+  if (namedPatternCount >= 5) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth', `${namedPatternCount} vault pattern references across tasks — strong knowledge-informed plan.`, '', 'tasks', 'vault_pattern_refs_high'),
+    );
+    gaps.push(
+      gap('bonus', 'knowledge-depth', 'Vault pattern density indicates expert-level domain knowledge.', '', 'tasks', 'vault_pattern_density'),
+    );
+  } else if (namedPatternCount >= 2) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth', `${namedPatternCount} vault pattern references across tasks.`, '', 'tasks', 'vault_pattern_refs_medium'),
+    );
+  }
+
+  // Bonus: tasks have specific acceptance criteria
+  let tasksWithCriteria = 0;
+  let totalCriteria = 0;
+  for (const task of plan.tasks) {
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      tasksWithCriteria++;
+      totalCriteria += task.acceptanceCriteria.length;
+    }
+  }
+
+  if (plan.tasks.length > 0 && tasksWithCriteria / plan.tasks.length >= 0.8) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth', `${tasksWithCriteria}/${plan.tasks.length} tasks have acceptance criteria (${totalCriteria} total).`, '', 'tasks', 'high_acceptance_criteria'),
+    );
+  }
+
+  // Bonus: knowledge indicator patterns in task text
+  let indicatorHits = 0;
+  for (const pattern of KNOWLEDGE_INDICATORS) {
+    if (pattern.test(allTaskText)) indicatorHits++;
+  }
+
+  if (indicatorHits >= 4) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth', `${indicatorHits} domain-specific knowledge indicators found (WCAG, ARIA, contrast ratios, touch targets, etc.).`, '', 'tasks', 'domain_knowledge_indicators'),
+    );
+  }
+
+  // Bonus: rich task descriptions (avg > 80 chars per task)
+  if (plan.tasks.length > 0) {
+    const avgDescLength =
+      plan.tasks.reduce((sum, t) => sum + (t.description?.length ?? 0), 0) / plan.tasks.length;
+    if (avgDescLength >= 80) {
+      gaps.push(
+        gap('bonus', 'knowledge-depth', `Task descriptions average ${Math.round(avgDescLength)} chars — detailed and specific.`, '', 'tasks', 'rich_task_descriptions'),
+      );
+    }
+  }
+
+  return gaps;
+}
+
 // ─── Types ───────────────────────────────────────────────────────
 
 /** A custom gap analysis pass that agents can register. */
@@ -762,6 +855,7 @@ export function runGapAnalysis(plan: Plan, options?: GapAnalysisOptions): PlanGa
     ...analyzeRisk(plan),
     ...analyzeClarity(plan),
     ...analyzeSemanticQuality(plan),
+    ...analyzeKnowledgeDepth(plan),
   ];
 
   // Run custom passes (domain-specific checks like tool-feasibility, UI context, etc.)

package/src/planning/gap-types.ts

@@ -5,7 +5,7 @@
 
 // ─── Severity & Category ─────────────────────────────────────────
 
-export type GapSeverity = 'critical' | 'major' | 'minor' | 'info';
+export type GapSeverity = 'critical' | 'major' | 'minor' | 'info' | 'bonus';
 
 export type GapCategory =
   | 'structure'
@@ -14,6 +14,7 @@ export type GapCategory =
   | 'risk'
   | 'clarity'
   | 'semantic-quality'
+  | 'knowledge-depth'
   | 'tool-feasibility'
   | 'flow-alignment'
   | 'anti-pattern';
@@ -32,12 +33,13 @@ export interface PlanGap {
 
 // ─── Scoring Constants ───────────────────────────────────────────
 
-/** Points deducted per gap severity. */
+/** Points deducted per gap severity. Negative = bonus (adds points). */
 export const SEVERITY_WEIGHTS: Record<GapSeverity, number> = {
   critical: 30,
   major: 15,
   minor: 2,
   info: 0,
+  bonus: -3,
 };
 
 /**
@@ -48,6 +50,14 @@ export const CATEGORY_PENALTY_CAPS: Record<string, number> = {
   clarity: 10,
 };
 
+/**
+ * Maximum bonus per category.
+ * Substance bonuses offset structural penalties but are capped to prevent gaming.
+ */
+export const CATEGORY_BONUS_CAPS: Record<string, number> = {
+  'knowledge-depth': 15,
+};
+
 // ─── Validation Thresholds ───────────────────────────────────────
 
 export const MIN_OBJECTIVE_LENGTH = 10;

package/src/planning/planner.ts

@@ -2,7 +2,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
 import type { PlanGap } from './gap-types.js';
-import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS } from './gap-types.js';
+import { SEVERITY_WEIGHTS, CATEGORY_PENALTY_CAPS, CATEGORY_BONUS_CAPS } from './gap-types.js';
 import { runGapAnalysis } from './gap-analysis.js';
 import type { GapAnalysisOptions } from './gap-analysis.js';
 
@@ -207,7 +207,8 @@ export interface PlanCheck {
  * - Score = max(0, 100 - totalDeductions)
  */
 export function calculateScore(gaps: PlanGap[], iteration: number = 1): number {
-  const categoryTotals = new Map<string, number>();
+  const categoryDeductions = new Map<string, number>();
+  const categoryBonuses = new Map<string, number>();
 
   for (const gap of gaps) {
     let weight: number = SEVERITY_WEIGHTS[gap.severity];
@@ -220,16 +221,27 @@ export function calculateScore(gaps: PlanGap[], iteration: number = 1): number {
     }
 
     const category = gap.category;
-    categoryTotals.set(category, (categoryTotals.get(category) ?? 0) + weight);
+    if (weight < 0) {
+      // Bonus — accumulate as positive value for capping, apply as negative deduction
+      categoryBonuses.set(category, (categoryBonuses.get(category) ?? 0) + Math.abs(weight));
+    } else {
+      categoryDeductions.set(category, (categoryDeductions.get(category) ?? 0) + weight);
+    }
   }
 
   let deductions = 0;
-  for (const [category, total] of categoryTotals) {
+  for (const [category, total] of categoryDeductions) {
     const cap = CATEGORY_PENALTY_CAPS[category];
     deductions += cap !== undefined ? Math.min(total, cap) : total;
   }
 
-  return Math.max(0, 100 - deductions);
+  let bonuses = 0;
+  for (const [category, total] of categoryBonuses) {
+    const cap = CATEGORY_BONUS_CAPS[category];
+    bonuses += cap !== undefined ? Math.min(total, cap) : total;
+  }
+
+  return Math.max(0, Math.min(100, 100 - deductions + bonuses));
 }
 
 /**

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

@@ -0,0 +1,101 @@
+/**
+ * Admin facade — infrastructure ops.
+ * health, config, telemetry, tokens, LLM, prompts.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createAdminOps } from '../admin-ops.js';
+import { createAdminExtraOps } from '../admin-extra-ops.js';
+
+export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  const { llmClient, keyPool } = runtime;
+
+  return [
+    // ─── LLM (inline from core-ops.ts) ──────────────────────────
+    {
+      name: 'llm_rotate',
+      description:
+        'Force rotate the active API key for a provider. Useful when rate-limited or key is failing.',
+      auth: 'write',
+      schema: z.object({
+        provider: z.enum(['openai', 'anthropic']),
+      }),
+      handler: async (params) => {
+        const provider = params.provider as 'openai' | 'anthropic';
+        const pool = keyPool[provider];
+        if (!pool.hasKeys) return { rotated: false, error: `No ${provider} keys configured` };
+        const newKey = pool.rotateOnError();
+        return {
+          rotated: newKey !== null,
+          activeKeyIndex: pool.activeKeyIndex,
+          poolSize: pool.poolSize,
+          exhausted: pool.exhausted,
+        };
+      },
+    },
+    {
+      name: 'llm_call',
+      description: 'Make an LLM completion call. Uses model routing config and key pool rotation.',
+      auth: 'write',
+      schema: z.object({
+        systemPrompt: z.string().describe('System prompt for the LLM.'),
+        userPrompt: z.string().describe('User prompt / task input.'),
+        model: z
+          .string()
+          .optional()
+          .describe('Model name. Routed via model-routing.json if omitted.'),
+        temperature: z.number().optional().describe('Sampling temperature (0-2). Default 0.3.'),
+        maxTokens: z.number().optional().describe('Max output tokens. Default 500.'),
+        caller: z.string().optional().describe('Caller name for routing. Default "core-ops".'),
+        task: z.string().optional().describe('Task name for routing.'),
+      }),
+      handler: async (params) => {
+        return llmClient.complete({
+          provider: 'openai',
+          model: (params.model as string) ?? '',
+          systemPrompt: params.systemPrompt as string,
+          userPrompt: params.userPrompt as string,
+          temperature: params.temperature as number | undefined,
+          maxTokens: params.maxTokens as number | undefined,
+          caller: (params.caller as string) ?? 'core-ops',
+          task: params.task as string | undefined,
+        });
+      },
+    },
+
+    // ─── Prompt Templates (inline from core-ops.ts) ─────────────
+    {
+      name: 'render_prompt',
+      description:
+        'Render a prompt template with variable substitution. Templates are .prompt files loaded from the templates directory.',
+      auth: 'read' as const,
+      schema: z.object({
+        template: z.string().describe('Template name (without .prompt extension)'),
+        variables: z.record(z.string()).optional().default({}),
+        strict: z.boolean().optional().default(true),
+      }),
+      handler: async (params) => {
+        const rendered = runtime.templateManager.render(
+          params.template as string,
+          (params.variables ?? {}) as Record<string, string>,
+          { strict: params.strict as boolean },
+        );
+        return { rendered };
+      },
+    },
+    {
+      name: 'list_templates',
+      description: 'List all loaded prompt templates.',
+      auth: 'read' as const,
+      handler: async () => ({
+        templates: runtime.templateManager.listTemplates(),
+      }),
+    },
+
+    // ─── Satellite ops ───────────────────────────────────────────
+    ...createAdminOps(runtime),
+    ...createAdminExtraOps(runtime),
+  ];
+}