@soleri/core 2.12.0 → 8.0.0

package/src/capabilities/registry.ts

@@ -0,0 +1,290 @@
+/**
+ * Capability Registry — runtime resolution engine for the three-layer architecture.
+ *
+ * Maps capability IDs (domain.action) to pack handlers. Resolves dependencies,
+ * checks availability, and supports graceful degradation when capabilities are
+ * missing.
+ *
+ * Registration flow:
+ * 1. Pack manifest declares capabilities (static, serializable)
+ * 2. Pack's onActivate() provides handlers (runtime, async)
+ * 3. registerPack() reconciles declarations with handlers
+ *
+ * @see docs/architecture/capability-packs.md
+ */
+
+import type {
+  CapabilityDefinition,
+  CapabilityHandler,
+  RegisteredCapability,
+  ResolvedCapability,
+  PackSuggestion,
+  FlowValidation,
+} from './types.js';
+import { chainToCapability } from './chain-mapping.js';
+
+// ---------------------------------------------------------------------------
+// Flow shape accepted by validateFlow — intentionally minimal so callers
+// don't need to import the full Flow type from ../flows/types.js.
+// ---------------------------------------------------------------------------
+
+export interface FlowForValidation {
+  steps: Array<{
+    needs?: string[];
+    chains?: string[];
+  }>;
+  onMissingCapability?: {
+    default?: string;
+    blocking?: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class CapabilityRegistry {
+  private capabilities = new Map<string, RegisteredCapability>();
+  private packs = new Map<string, { id: string; capabilities: CapabilityDefinition[] }>();
+
+  // -----------------------------------------------------------------------
+  // Registration
+  // -----------------------------------------------------------------------
+
+  /**
+   * Register all capabilities from an installed pack.
+   *
+   * For each definition in `definitions`, the corresponding handler is looked
+   * up in `handlers`. If no handler is found the capability is skipped with a
+   * warning. When multiple packs provide the same capability, providers are
+   * sorted by priority (descending) — highest priority wins on resolve().
+   *
+   * @param packId      - Unique identifier for the pack
+   * @param definitions - Capability definitions from the pack manifest
+   * @param handlers    - Map of capabilityId → handler from onActivate()
+   * @param priority    - Higher = preferred (core=100, user=75, domain=50, fallback=0)
+   */
+  registerPack(
+    packId: string,
+    definitions: CapabilityDefinition[],
+    handlers: Map<string, CapabilityHandler>,
+    priority: number = 0,
+  ): void {
+    for (const definition of definitions) {
+      const handler = handlers.get(definition.id);
+      if (!handler) {
+        console.warn(
+          `Pack "${packId}" declares capability "${definition.id}" but no handler provided — skipping`,
+        );
+        continue;
+      }
+
+      const existing = this.capabilities.get(definition.id);
+      if (existing) {
+        // Add as additional provider, keep sorted by priority descending
+        existing.providers.push({ packId, handler, priority });
+        existing.providers.sort((a, b) => b.priority - a.priority);
+      } else {
+        this.capabilities.set(definition.id, {
+          definition,
+          providers: [{ packId, handler, priority }],
+        });
+      }
+    }
+
+    // Store pack metadata for suggestPacksFor() lookups
+    this.packs.set(packId, { id: packId, capabilities: definitions });
+  }
+
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+
+  /**
+   * Check if a capability is registered (has at least one provider).
+   */
+  has(capabilityId: string): boolean {
+    return this.capabilities.has(capabilityId);
+  }
+
+  /**
+   * Resolve a capability — returns the highest-priority handler, knowledge
+   * refs, and provider list. If the capability is missing or has unsatisfied
+   * dependencies, returns `available: false` with suggestions.
+   */
+  resolve(capabilityId: string): ResolvedCapability {
+    const registered = this.capabilities.get(capabilityId);
+
+    if (!registered) {
+      return {
+        available: false,
+        capabilityId,
+        suggestion: this.suggestPacksFor([capabilityId]),
+      };
+    }
+
+    // Check dependency satisfaction
+    const depends = registered.definition.depends ?? [];
+    const missingDeps = depends.filter((dep) => !this.capabilities.has(dep));
+
+    if (missingDeps.length > 0) {
+      return {
+        available: false,
+        capabilityId,
+        missingDependencies: missingDeps,
+        suggestion: this.suggestPacksFor(missingDeps),
+      };
+    }
+
+    // Resolved — return the highest-priority provider (index 0 after sort)
+    const primary = registered.providers[0];
+    return {
+      available: true,
+      capabilityId,
+      handler: primary.handler,
+      providers: registered.providers.map((p) => p.packId),
+      knowledge: registered.definition.knowledge ?? [],
+    };
+  }
+
+  /**
+   * List all registered capabilities grouped by domain.
+   *
+   * Domain is derived from the first segment of the capability ID
+   * (e.g., "color" from "color.validate").
+   */
+  list(): Map<string, CapabilityDefinition[]> {
+    const grouped = new Map<string, CapabilityDefinition[]>();
+
+    for (const [id, registered] of this.capabilities) {
+      const domain = id.split('.')[0];
+      const group = grouped.get(domain) ?? [];
+      group.push(registered.definition);
+      grouped.set(domain, group);
+    }
+
+    return grouped;
+  }
+
+  /**
+   * Search registered packs for capabilities matching the requested IDs.
+   *
+   * This searches ALL packs (not just capabilities currently registered with
+   * handlers) — useful for suggesting which packs to install when a capability
+   * is missing.
+   */
+  suggestPacksFor(capabilityIds: string[]): PackSuggestion[] {
+    if (capabilityIds.length === 0) return [];
+
+    const idSet = new Set(capabilityIds);
+    const suggestions: PackSuggestion[] = [];
+
+    for (const [, pack] of this.packs) {
+      const provides = pack.capabilities.filter((cap) => idSet.has(cap.id)).map((cap) => cap.id);
+
+      if (provides.length > 0) {
+        suggestions.push({ packId: pack.id, provides });
+      }
+    }
+
+    return suggestions;
+  }
+
+  // -----------------------------------------------------------------------
+  // Validation
+  // -----------------------------------------------------------------------
+
+  /**
+   * Validate a flow's capability requirements against installed packs.
+   *
+   * Reads both `needs` (v2 preferred) and `chains` (v1 deprecated) fields.
+   * For v1 chains, attempts best-effort mapping via chainToCapability().
+   *
+   * Missing capabilities are classified as either "blocking" or "degraded"
+   * based on the flow's onMissingCapability config.
+   */
+  validateFlow(flow: FlowForValidation): FlowValidation {
+    // Collect all capability IDs needed across all steps
+    const needed = new Set<string>();
+
+    for (const step of flow.steps) {
+      // v2: needs field (preferred)
+      if (step.needs) {
+        for (const cap of step.needs) {
+          needed.add(cap);
+        }
+      }
+
+      // v1: chains field (deprecated, best-effort mapping)
+      if (step.chains) {
+        for (const chain of step.chains) {
+          const capId = chainToCapability(chain);
+          if (capId) needed.add(capId);
+        }
+      }
+    }
+
+    // Partition into available vs missing
+    const available: string[] = [];
+    const missing: string[] = [];
+
+    for (const capId of needed) {
+      if (this.has(capId)) {
+        available.push(capId);
+      } else {
+        missing.push(capId);
+      }
+    }
+
+    // Classify missing capabilities by impact
+    const blockingSet = new Set(flow.onMissingCapability?.blocking ?? []);
+
+    const degraded = missing.map((capability) => ({
+      capability,
+      impact: blockingSet.has(capability) ? ('blocking' as const) : ('degraded' as const),
+      suggestion: this.suggestPacksFor([capability]),
+    }));
+
+    const hasBlocker = degraded.some((d) => d.impact === 'blocking');
+
+    return {
+      valid: missing.length === 0,
+      available,
+      missing,
+      degraded,
+      canRunPartially: !hasBlocker,
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // Inspection (useful for debugging / CLI commands)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Total number of registered capabilities.
+   */
+  get size(): number {
+    return this.capabilities.size;
+  }
+
+  /**
+   * Total number of registered packs.
+   */
+  get packCount(): number {
+    return this.packs.size;
+  }
+
+  /**
+   * Get all registered capability IDs.
+   */
+  ids(): string[] {
+    return [...this.capabilities.keys()];
+  }
+
+  /**
+   * Get the RegisteredCapability for a given ID, or undefined.
+   */
+  get(capabilityId: string): RegisteredCapability | undefined {
+    return this.capabilities.get(capabilityId);
+  }
+}

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/context/context-engine.ts

@@ -71,11 +71,34 @@ const STOP_PATTERNS = new Set([
   'out-of-the-box',
 ]);
 
-// ─── Confidence Thresholds ──────────────────────────────────────────
+// ─── Scoring Constants (tunable) ────────────────────────────────────
 
+/** Confidence thresholds for discrete levels. */
 const HIGH_CONFIDENCE = 0.75;
 const MEDIUM_CONFIDENCE = 0.45;
 
+/** Weights for knowledge item multi-signal scoring. */
+const KNOWLEDGE_WEIGHTS = {
+  /** Base FTS/vector score weight. */
+  baseScore: 0.4,
+  /** Title keyword overlap weight. */
+  titleMatch: 0.25,
+  /** Tag overlap weight. */
+  tagOverlap: 0.2,
+  /** Intent/domain alignment weight. */
+  intentBoost: 0.15,
+};
+
+/** Weights for confidence computation. */
+const CONFIDENCE_WEIGHTS = {
+  entitySignalPerEntity: 0.08,
+  entitySignalMax: 0.4,
+  actionSignal: 0.2,
+  knowledgeSignalMultiplier: 0.3,
+  sourceDiversityPerExtra: 0.05,
+  sourceDiversityMax: 0.1,
+};
+
 // ─── Class ──────────────────────────────────────────────────────────
 
 export class ContextEngine {
@@ -120,7 +143,13 @@ export class ContextEngine {
         if (seen.has(key)) continue;
         if (type === 'pattern' && STOP_PATTERNS.has(value)) continue;
         seen.add(key);
-        entities.push({ type, value, confidence });
+        entities.push({
+          type,
+          value,
+          confidence,
+          start: match.index,
+          end: match.index + match[0].length,
+        });
       }
     }
 
@@ -147,15 +176,31 @@ export class ContextEngine {
         domain,
         limit: this.config.vaultSearchLimit,
       });
-      // Normalize FTS5 -rank scores to 0-1 range
+      // Normalize FTS5 -rank scores to 0-1 range, then apply multi-signal scoring
       const maxScore = vaultResults.length > 0 ? Math.max(...vaultResults.map((r) => r.score)) : 1;
+      const promptTokens = new Set(
+        prompt
+          .toLowerCase()
+          .split(/\s+/)
+          .filter((t) => t.length >= 3),
+      );
       for (const r of vaultResults) {
+        const baseScore = maxScore > 0 ? r.score / maxScore : 0.5;
+        const enrichedScore = scoreKnowledgeItem(
+          baseScore,
+          r.entry.title,
+          r.entry.tags,
+          promptTokens,
+          domain,
+          r.entry.domain,
+        );
         items.push({
           id: r.entry.id,
           title: r.entry.title,
-          score: maxScore > 0 ? r.score / maxScore : 0.5,
+          score: enrichedScore,
           source: 'vault',
           domain: r.entry.domain,
+          tags: r.entry.tags,
         });
         vaultHits++;
       }
@@ -252,25 +297,29 @@ export class ContextEngine {
   ): number {
     let score = 0;
 
-    // Entity signal (0-0.4): more entities = clearer prompt
+    // Entity signal: more entities = clearer prompt
     const entityCount = entities.entities.length;
-    const entitySignal = Math.min(0.4, entityCount * 0.08);
-    score += entitySignal;
+    score += Math.min(
+      CONFIDENCE_WEIGHTS.entitySignalMax,
+      entityCount * CONFIDENCE_WEIGHTS.entitySignalPerEntity,
+    );
 
-    // Action signal (0-0.2): explicit actions boost confidence
+    // Action signal: explicit actions boost confidence
     const actions = entities.byType.action ?? [];
-    if (actions.length > 0) score += 0.2;
+    if (actions.length > 0) score += CONFIDENCE_WEIGHTS.actionSignal;
 
-    // Knowledge signal (0-0.3): relevant knowledge found
+    // Knowledge signal: relevant knowledge found
     if (knowledge.items.length > 0) {
-      const topScore = knowledge.items[0].score;
-      score += topScore * 0.3;
+      score += knowledge.items[0].score * CONFIDENCE_WEIGHTS.knowledgeSignalMultiplier;
     }
 
-    // Source diversity bonus (0-0.1): multiple sources = more confident
+    // Source diversity bonus: multiple sources = more confident
     const sources = new Set(knowledge.items.map((i) => i.source));
-    if (sources.size >= 2) score += 0.05;
-    if (sources.size >= 3) score += 0.05;
+    const diversityBonus = Math.min(
+      CONFIDENCE_WEIGHTS.sourceDiversityMax,
+      Math.max(0, sources.size - 1) * CONFIDENCE_WEIGHTS.sourceDiversityPerExtra,
+    );
+    score += diversityBonus;
 
     return Math.min(1, score);
   }
@@ -300,3 +349,53 @@ export class ContextEngine {
     return [...domains];
   }
 }
+
+// ─── Multi-Signal Knowledge Scoring ─────────────────────────────────
+
+/**
+ * Score a knowledge item using multiple signals:
+ * - baseScore: FTS5 rank or vector similarity (0-1)
+ * - titleMatch: keyword overlap between prompt and entry title
+ * - tagOverlap: how many prompt tokens appear in entry tags
+ * - intentBoost: domain alignment between query domain and entry domain
+ */
+function scoreKnowledgeItem(
+  baseScore: number,
+  title: string,
+  tags: string[],
+  promptTokens: Set<string>,
+  queryDomain: string | undefined,
+  entryDomain: string | undefined,
+): number {
+  // Title match: fraction of prompt tokens found in title
+  const titleTokens = new Set(
+    title
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length >= 3),
+  );
+  let titleOverlap = 0;
+  for (const t of promptTokens) {
+    if (titleTokens.has(t)) titleOverlap++;
+  }
+  const titleMatch = promptTokens.size > 0 ? titleOverlap / promptTokens.size : 0;
+
+  // Tag overlap: fraction of tags that match prompt tokens
+  const lowerTags = tags.map((t) => t.toLowerCase());
+  let tagHits = 0;
+  for (const tag of lowerTags) {
+    if (promptTokens.has(tag)) tagHits++;
+  }
+  const tagOverlap = lowerTags.length > 0 ? tagHits / lowerTags.length : 0;
+
+  // Intent boost: 1.0 if domains match, 0.0 otherwise
+  const intentBoost = queryDomain && entryDomain && queryDomain === entryDomain ? 1.0 : 0.0;
+
+  return Math.min(
+    1.0,
+    baseScore * KNOWLEDGE_WEIGHTS.baseScore +
+      titleMatch * KNOWLEDGE_WEIGHTS.titleMatch +
+      tagOverlap * KNOWLEDGE_WEIGHTS.tagOverlap +
+      intentBoost * KNOWLEDGE_WEIGHTS.intentBoost,
+  );
+}

package/src/context/types.ts

@@ -10,6 +10,10 @@ export interface ExtractedEntity {
   type: EntityType;
   value: string;
   confidence: number;
+  /** Start offset in the original prompt. */
+  start?: number;
+  /** End offset in the original prompt. */
+  end?: number;
 }
 
 export interface EntityExtractionResult {
@@ -25,6 +29,7 @@ export interface KnowledgeItem {
   score: number;
   source: 'vault' | 'cognee' | 'brain';
   domain?: string;
+  tags?: string[];
 }
 
 export interface KnowledgeRetrievalResult {