@soleri/core 2.11.0 → 7.0.0

package/src/capabilities/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Capability type system for Soleri's three-layer architecture.
+ *
+ * Capabilities are the atomic unit of agent functionality — what the agent
+ * CAN DO, not which tool it calls. Flows reference capabilities by intent
+ * (e.g., "color.validate"), and the registry resolves them to pack handlers
+ * at runtime.
+ *
+ * @see docs/architecture/capability-packs.md
+ */
+
+import type { PackRuntime } from '../domain-packs/pack-runtime.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ---------------------------------------------------------------------------
+// Capability definition & handler
+// ---------------------------------------------------------------------------
+
+export interface CapabilityDefinition {
+  /** Namespaced ID: domain.action (e.g., "color.validate", "token.check") */
+  id: string;
+
+  /** Human-readable description of what this capability does */
+  description: string;
+
+  /** What this capability produces (output contract) */
+  provides: string[];
+
+  /** What this capability requires as input */
+  requires: string[];
+
+  /** Other capabilities that must be available (auto-resolved) */
+  depends?: string[];
+
+  /** Vault knowledge entry IDs to auto-load when this capability runs */
+  knowledge?: string[];
+}
+
+/**
+ * Capability handler — the actual implementation.
+ *
+ * Declared separately from CapabilityDefinition because:
+ * - Manifest declares the definition (static, serializable)
+ * - Pack's onActivate() registers the handler (runtime, async)
+ */
+export type CapabilityHandler = (
+  params: Record<string, unknown>,
+  context: CapabilityContext,
+) => Promise<CapabilityResult>;
+
+// ---------------------------------------------------------------------------
+// Capability context & result
+// ---------------------------------------------------------------------------
+
+/**
+ * CapabilityContext — extends PackRuntime with knowledge and composition.
+ *
+ * PackRuntime already provides: vault, getProject, listProjects, createCheck,
+ * validateCheck, validateAndConsume. This adds:
+ * - knowledge: auto-loaded from pack bundle + user vault
+ * - brain: recommendations from the learning loop
+ * - invoke: call another capability (composition)
+ */
+export interface CapabilityContext {
+  /** Pack runtime (vault, projects, checks) — from existing PackRuntime */
+  runtime: PackRuntime;
+
+  /** Auto-loaded knowledge from pack + user vault */
+  knowledge: KnowledgeContext;
+
+  /** Brain recommendations for this capability */
+  brain: BrainRecommendation[];
+
+  /** Request another capability (for composition) */
+  invoke: (capabilityId: string, params: Record<string, unknown>) => Promise<CapabilityResult>;
+}
+
+export interface CapabilityResult {
+  success: boolean;
+  data: Record<string, unknown>;
+  /** Which "provides" fields were actually produced */
+  produced: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Knowledge & brain
+// ---------------------------------------------------------------------------
+
+export interface KnowledgeContext {
+  /** Entries from the pack's bundled knowledge (IntelligenceBundle) */
+  pack: IntelligenceEntry[];
+  /** Entries from user's project vault (searched by capability's knowledge[] IDs) */
+  vault: IntelligenceEntry[];
+  /** Combined, deduplicated, ranked by relevance */
+  merged: IntelligenceEntry[];
+}
+
+export interface BrainRecommendation {
+  pattern: string;
+  strength: number;
+  source: string;
+}
+
+// ---------------------------------------------------------------------------
+// Registry types
+// ---------------------------------------------------------------------------
+
+export interface RegisteredCapability {
+  definition: CapabilityDefinition;
+  providers: Array<{
+    packId: string;
+    handler: CapabilityHandler;
+    /** Higher = preferred (see Multi-Provider Resolution in RFC) */
+    priority: number;
+  }>;
+}
+
+export interface ResolvedCapability {
+  available: boolean;
+  capabilityId: string;
+  handler?: CapabilityHandler;
+  providers?: string[];
+  knowledge?: string[];
+  missingDependencies?: string[];
+  suggestion?: PackSuggestion[];
+}
+
+export interface PackSuggestion {
+  packId: string;
+  provides: string[];
+}
+
+export interface FlowValidation {
+  valid: boolean;
+  available: string[];
+  missing: string[];
+  degraded: Array<{
+    capability: string;
+    impact: 'blocking' | 'degraded' | 'optional';
+    suggestion: PackSuggestion[];
+  }>;
+  canRunPartially: boolean;
+}

package/src/control/intent-router.ts

@@ -18,6 +18,30 @@ import type {
   MorphResult,
 } from './types.js';
 
+// ─── Token Stemming ─────────────────────────────────────────────────
+// Lightweight suffix stripping for intent matching.
+// Handles: "crashes" → "crash", "deploying" → "deploy", "broken" → "broke",
+// "issues" → "issue", "building" → "build", "optimizing" → "optimize"
+
+function stemToken(token: string): string {
+  if (token.length < 4) return token;
+  // Order matters — check longer suffixes first
+  if (token.endsWith('ying')) return token.slice(0, -4) + 'y'; // deploying → deploy
+  if (token.endsWith('izing')) return token.slice(0, -3) + 'e'; // optimizing → optimize
+  if (token.endsWith('ating')) return token.slice(0, -3) + 'e'; // creating → create
+  if (token.endsWith('ting')) return token.slice(0, -4) + 't'; // getting → get (approx)
+  if (token.endsWith('ning')) return token.slice(0, -4) + 'n'; // planning → plan (approx)
+  if (token.endsWith('ing')) return token.slice(0, -3); // fixing → fix, building → build
+  if (token.endsWith('ies')) return token.slice(0, -3) + 'y'; // queries → query
+  if (token.endsWith('shes')) return token.slice(0, -2); // crashes → crash
+  if (token.endsWith('ches')) return token.slice(0, -2); // searches → search
+  if (token.endsWith('ses')) return token.slice(0, -2); // releases → releas (close enough)
+  if (token.endsWith('es') && token.length > 4) return token.slice(0, -1); // issues → issue
+  if (token.endsWith('ed') && token.length > 4) return token.slice(0, -2); // fixed → fix
+  if (token.endsWith('s') && !token.endsWith('ss') && token.length > 3) return token.slice(0, -1); // bugs → bug
+  return token;
+}
+
 // ─── Default Mode Definitions ───────────────────────────────────────
 
 const DEFAULT_MODES: ModeConfig[] = [
@@ -33,7 +57,23 @@ const DEFAULT_MODES: ModeConfig[] = [
     intent: 'fix',
     description: 'Fixing bugs, errors, and broken behavior',
     behaviorRules: ['Identify root cause first', 'Verify fix with tests', 'Check for regressions'],
-    keywords: ['fix', 'bug', 'broken', 'error', 'crash', 'issue', 'debug', 'repair', 'janky'],
+    keywords: [
+      'fix',
+      'bug',
+      'broken',
+      'error',
+      'crash',
+      'issue',
+      'debug',
+      'repair',
+      'janky',
+      'fail',
+      'wrong',
+      'stuck',
+      'regression',
+      'fault',
+      'defect',
+    ],
   },
   {
     mode: 'VALIDATE-MODE',
@@ -152,7 +192,11 @@ export class IntentRouter {
   // ─── Intent Classification ──────────────────────────────────────────
 
   routeIntent(prompt: string): IntentClassification {
-    const tokens = new Set(prompt.toLowerCase().split(/\s+/).filter(Boolean));
+    const rawTokens = prompt.toLowerCase().split(/\s+/).filter(Boolean);
+    // Stem tokens: strip common suffixes for fuzzy matching
+    // "crashes" → "crash", "broken" stays "broken", "deploying" → "deploy"
+    const stemmed = rawTokens.map((t) => stemToken(t));
+    const tokens = new Set([...rawTokens, ...stemmed]);
     const modes = this.getModes();
 
     let bestMode: ModeConfig | null = null;

package/src/domain-packs/index.ts

@@ -0,0 +1,27 @@
+export {
+  type DomainPack,
+  type DomainPackManifest,
+  type DomainPackRef,
+  type KnowledgeManifest,
+  type PackSkillDefinition,
+  type ValidateResult,
+  validateDomainPack,
+  SEMANTIC_FACADE_NAMES,
+} from './types.js';
+
+export { loadDomainPack, loadDomainPacksFromConfig, resolveDependencies } from './loader.js';
+
+export { installKnowledge, type KnowledgeInstallResult } from './knowledge-installer.js';
+
+export { installSkills, type SkillsInstallResult } from './skills-installer.js';
+
+export { injectDomainRules, removeDomainRules } from './inject-rules.js';
+
+export {
+  type PackRuntime,
+  type PackProjectContext,
+  type PackCheckContext,
+  createPackRuntime,
+} from './pack-runtime.js';
+
+export { resolveToken, listProjectTokens, buildReverseIndex } from './token-resolver.js';

package/src/domain-packs/inject-rules.ts

@@ -0,0 +1,74 @@
+/**
+ * Domain-level CLAUDE.md injection for domain packs.
+ *
+ * Each pack can inject behavioral rules under its own marker:
+ *   <!-- domain:packName --> ... <!-- /domain:packName -->
+ *
+ * Injection is idempotent — existing content between markers is replaced.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const OPEN_MARKER = (name: string) => `<!-- domain:${name} -->`;
+const CLOSE_MARKER = (name: string) => `<!-- /domain:${name} -->`;
+
+/**
+ * Inject domain rules into a CLAUDE.md file.
+ *
+ * @param filePath - Path to CLAUDE.md
+ * @param packName - Domain pack name (used in markers)
+ * @param rulesContent - Markdown content to inject
+ */
+export function injectDomainRules(filePath: string, packName: string, rulesContent: string): void {
+  if (!rulesContent || rulesContent.trim().length === 0) return;
+
+  const open = OPEN_MARKER(packName);
+  const close = CLOSE_MARKER(packName);
+  const block = `${open}\n${rulesContent.trim()}\n${close}`;
+
+  if (!existsSync(filePath)) {
+    writeFileSync(filePath, block + '\n', 'utf-8');
+    return;
+  }
+
+  let content = readFileSync(filePath, 'utf-8');
+
+  // Replace existing block if present (idempotent)
+  const openIdx = content.indexOf(open);
+  const closeIdx = content.indexOf(close);
+
+  if (openIdx !== -1 && closeIdx !== -1) {
+    const before = content.slice(0, openIdx);
+    const after = content.slice(closeIdx + close.length);
+    content = before + block + after;
+  } else {
+    // Append at end
+    content = content.trimEnd() + '\n\n' + block + '\n';
+  }
+
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Remove domain rules from a CLAUDE.md file.
+ *
+ * @param filePath - Path to CLAUDE.md
+ * @param packName - Domain pack name
+ */
+export function removeDomainRules(filePath: string, packName: string): void {
+  if (!existsSync(filePath)) return;
+
+  const open = OPEN_MARKER(packName);
+  const close = CLOSE_MARKER(packName);
+
+  let content = readFileSync(filePath, 'utf-8');
+  const openIdx = content.indexOf(open);
+  const closeIdx = content.indexOf(close);
+
+  if (openIdx !== -1 && closeIdx !== -1) {
+    const before = content.slice(0, openIdx);
+    const after = content.slice(closeIdx + close.length);
+    content = (before + after).replace(/\n{3,}/g, '\n\n');
+    writeFileSync(filePath, content, 'utf-8');
+  }
+}

package/src/domain-packs/knowledge-installer.ts

@@ -0,0 +1,116 @@
+/**
+ * Three-tier knowledge installer for domain packs.
+ *
+ * Respects KnowledgeManifest tiers:
+ * - canonical/: seed_canonical (immutable, highest authority)
+ * - curated/: import via vault (curator-eligible)
+ * - captured/: import via vault (tier=captured)
+ *
+ * All entries tagged with origin=pack and source=packName.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { AgentRuntime } from '../runtime/types.js';
+import type { DomainPack } from './types.js';
+
+export interface KnowledgeInstallResult {
+  canonical: number;
+  curated: number;
+  captured: number;
+  skipped: number;
+}
+
+/**
+ * Install knowledge from a domain pack into the agent's vault.
+ *
+ * @param pack - The domain pack with knowledge manifest
+ * @param runtime - Agent runtime with vault access
+ * @param rootDir - Absolute path to the pack's root directory
+ */
+export async function installKnowledge(
+  pack: DomainPack,
+  runtime: AgentRuntime,
+  rootDir: string,
+): Promise<KnowledgeInstallResult> {
+  const result: KnowledgeInstallResult = { canonical: 0, curated: 0, captured: 0, skipped: 0 };
+
+  if (!pack.knowledge) return result;
+
+  const { vault } = runtime;
+  const knowledge = pack.knowledge;
+
+  // Tier 1: Canonical (immutable)
+  if (knowledge.canonical) {
+    const dir = resolve(rootDir, knowledge.canonical);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'canonical',
+        origin: 'pack',
+        source: pack.name,
+        immutable: true,
+      });
+      result.canonical = count;
+    }
+  }
+
+  // Tier 2: Curated (grooming-eligible)
+  if (knowledge.curated) {
+    const dir = resolve(rootDir, knowledge.curated);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'curated',
+        origin: 'pack',
+        source: pack.name,
+      });
+      result.curated = count;
+    }
+  }
+
+  // Tier 3: Captured (seed learnings)
+  if (knowledge.captured) {
+    const dir = resolve(rootDir, knowledge.captured);
+    if (existsSync(dir)) {
+      const count = importMarkdownEntries(vault, dir, {
+        tier: 'captured',
+        origin: 'pack',
+        source: pack.name,
+      });
+      result.captured = count;
+    }
+  }
+
+  return result;
+}
+
+/** Import markdown files from a directory into the vault. */
+function importMarkdownEntries(
+  vault: AgentRuntime['vault'],
+  dir: string,
+  meta: { tier: string; origin: string; source: string; immutable?: boolean },
+): number {
+  const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+  let imported = 0;
+
+  for (const file of files) {
+    const content = readFileSync(join(dir, file), 'utf-8');
+    const id = `pack-${meta.source}-${file.replace(/\.md$/, '')}`;
+
+    // Skip if canonical entry already exists (immutable = never overwrite)
+    if (meta.immutable && vault.get(id)) continue;
+
+    vault.add({
+      id,
+      type: 'pattern',
+      title: file.replace(/\.md$/, '').replace(/-/g, ' '),
+      description: content.slice(0, 200),
+      severity: 'suggestion',
+      tags: [`pack:${meta.source}`, `tier:${meta.tier}`],
+      domain: meta.source,
+      origin: meta.origin as 'pack' | 'agent' | 'user',
+    });
+    imported++;
+  }
+
+  return imported;
+}

package/src/domain-packs/loader.ts

@@ -0,0 +1,124 @@
+/**
+ * Domain Pack loader — resolves, validates, and dependency-sorts domain packs.
+ */
+
+import { validateDomainPack } from './types.js';
+import type { DomainPack, DomainPackManifest, DomainPackRef } from './types.js';
+
+/**
+ * Load a single domain pack from an npm package.
+ *
+ * @param packageName - npm package name (e.g., '@soleri/domain-design')
+ * @returns Validated DomainPackManifest
+ * @throws If package cannot be imported or fails validation
+ */
+export async function loadDomainPack(packageName: string): Promise<DomainPackManifest> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = await import(packageName);
+  } catch (err) {
+    throw new Error(
+      `Failed to import domain pack "${packageName}": ${err instanceof Error ? err.message : String(err)}`, { cause: err },
+    );
+  }
+
+  // Support both default export and named 'pack' export
+  const packCandidate = mod.default ?? mod.pack;
+  if (!packCandidate) {
+    throw new Error(`Domain pack "${packageName}" has no default or named "pack" export.`);
+  }
+
+  const result = validateDomainPack(packCandidate);
+  if (!result.success) {
+    throw new Error(`Domain pack "${packageName}" failed validation: ${result.errors.message}`);
+  }
+
+  return {
+    ...result.data,
+    packageName,
+  };
+}
+
+/**
+ * Load all domain packs from AgentConfig refs.
+ *
+ * @param refs - Array of DomainPackRef from agent config
+ * @returns Validated and dependency-sorted packs
+ */
+export async function loadDomainPacksFromConfig(
+  refs: DomainPackRef[],
+): Promise<DomainPackManifest[]> {
+  const packs = await Promise.all(refs.map((ref) => loadDomainPack(ref.package)));
+  return resolveDependencies(packs);
+}
+
+/**
+ * Topological sort of domain packs by their `requires` field.
+ *
+ * @param packs - Array of domain packs (validated)
+ * @returns Sorted array (dependencies before dependents)
+ * @throws On circular dependencies or missing dependencies
+ */
+export function resolveDependencies<T extends DomainPack>(packs: T[]): T[] {
+  const byName = new Map<string, T>();
+  for (const pack of packs) {
+    byName.set(pack.name, pack);
+  }
+
+  // Check for missing dependencies
+  for (const pack of packs) {
+    if (pack.requires) {
+      for (const dep of pack.requires) {
+        if (!byName.has(dep)) {
+          throw new Error(
+            `Domain pack "${pack.name}" requires "${dep}" but it was not found in the loaded packs.`,
+          );
+        }
+      }
+    }
+  }
+
+  // Kahn's algorithm for topological sort
+  const inDegree = new Map<string, number>();
+  const adjList = new Map<string, string[]>();
+
+  for (const pack of packs) {
+    inDegree.set(pack.name, 0);
+    adjList.set(pack.name, []);
+  }
+
+  for (const pack of packs) {
+    if (pack.requires) {
+      for (const dep of pack.requires) {
+        adjList.get(dep)!.push(pack.name);
+        inDegree.set(pack.name, (inDegree.get(pack.name) ?? 0) + 1);
+      }
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name);
+  }
+
+  const sorted: T[] = [];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    sorted.push(byName.get(current)!);
+
+    for (const dependent of adjList.get(current) ?? []) {
+      const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length !== packs.length) {
+    const remaining = packs
+      .filter((p) => !sorted.some((s) => s.name === p.name))
+      .map((p) => p.name);
+    throw new Error(`Circular dependency detected among domain packs: ${remaining.join(', ')}`);
+  }
+
+  return sorted;
+}

package/src/domain-packs/pack-runtime.ts

@@ -0,0 +1,99 @@
+/**
+ * PackRuntime — the subset of AgentRuntime available to domain packs.
+ *
+ * Domain packs receive this via onActivate(runtime). It exposes only what
+ * packs need: vault search, project registry, and session store.
+ * Packs should NOT depend on the full AgentRuntime interface.
+ */
+
+import type { Vault } from '../vault/vault.js';
+
+/**
+ * Minimal project context for token resolution.
+ * Matches the shape of ProjectRegistry entries.
+ */
+export interface PackProjectContext {
+  id: string;
+  name: string;
+  path: string;
+  colors?: {
+    [scale: string]: {
+      scale: Record<string, string>;
+      base: string;
+    };
+  };
+  semanticTokens?: Record<string, string>;
+}
+
+/**
+ * Session check for tool chaining (contrast → component create).
+ */
+export interface PackCheckContext {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+/**
+ * The runtime interface domain packs receive via onActivate.
+ *
+ * Designed for graceful degradation: packs work without runtime
+ * (simplified mode), but gain full power when connected.
+ */
+export interface PackRuntime {
+  /** Vault for knowledge search and capture */
+  vault: Vault;
+
+  /** Get a registered project by ID (for token resolution) */
+  getProject(projectId: string): PackProjectContext | undefined;
+
+  /** List all registered projects */
+  listProjects(): Array<{ id: string; name: string; path: string }>;
+
+  /** Create a session check (for tool chaining) */
+  createCheck(type: string, data: Record<string, unknown>): string;
+
+  /** Validate a session check */
+  validateCheck(checkId: string, expectedType: string): PackCheckContext | null;
+
+  /** Validate and consume a session check (single-use) */
+  validateAndConsume(checkId: string, expectedType: string): PackCheckContext | null;
+}
+
+/**
+ * Create a PackRuntime from an AgentRuntime.
+ *
+ * This adapter extracts the subset of runtime that packs need,
+ * avoiding tight coupling to the full AgentRuntime interface.
+ */
+export function createPackRuntime(runtime: {
+  vault: Vault;
+  projectRegistry: {
+    getProject(id: string): PackProjectContext | undefined;
+    listProjects(): Array<{ id: string; name: string; path: string }>;
+  };
+  sessionStore?: {
+    createCheck(type: string, data: Record<string, unknown>): string;
+    validateCheck(id: string, type: string): PackCheckContext | null;
+    validateAndConsume(id: string, type: string): PackCheckContext | null;
+  };
+}): PackRuntime {
+  return {
+    vault: runtime.vault,
+    getProject: (id) => runtime.projectRegistry.getProject(id),
+    listProjects: () => runtime.projectRegistry.listProjects(),
+    createCheck: (type, data) => {
+      if (!runtime.sessionStore) throw new Error('Session store not available');
+      return runtime.sessionStore.createCheck(type, data);
+    },
+    validateCheck: (id, type) => {
+      if (!runtime.sessionStore) return null;
+      return runtime.sessionStore.validateCheck(id, type);
+    },
+    validateAndConsume: (id, type) => {
+      if (!runtime.sessionStore) return null;
+      return runtime.sessionStore.validateAndConsume(id, type);
+    },
+  };
+}