@soleri/core 9.3.0 → 9.3.1

package/src/planning/task-complexity-assessor.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect } from 'vitest';
+import {
+  assessTaskComplexity,
+  type AssessmentInput,
+  type AssessmentResult,
+} from './task-complexity-assessor.js';
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function assess(partial: Partial<AssessmentInput> & { prompt: string }): AssessmentResult {
+  return assessTaskComplexity(partial);
+}
+
+function signalByName(result: AssessmentResult, name: string) {
+  return result.signals.find((s) => s.name === name);
+}
+
+// ─── Simple Tasks ───────────────────────────────────────────────────
+
+describe('assessTaskComplexity — simple tasks', () => {
+  it('classifies "rename variable X" as simple', () => {
+    const result = assess({ prompt: 'rename variable X to Y' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies "fix typo in README" as simple', () => {
+    const result = assess({ prompt: 'fix typo in README' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies "add CSS class" as simple', () => {
+    const result = assess({ prompt: 'add CSS class to the header' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBeLessThan(40);
+  });
+
+  it('classifies single-file estimate as simple', () => {
+    const result = assess({ prompt: 'update button color', filesEstimated: 1 });
+    expect(result.classification).toBe('simple');
+    expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+  });
+
+  it('classifies task with 2 files as simple', () => {
+    const result = assess({ prompt: 'update two files', filesEstimated: 2 });
+    expect(result.classification).toBe('simple');
+    expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+  });
+});
+
+// ─── Complex Tasks ──────────────────────────────────────────────────
+
+describe('assessTaskComplexity — complex tasks', () => {
+  it('classifies "add authentication" touching multiple files as complex', () => {
+    const result = assess({ prompt: 'add authentication to the API', filesEstimated: 4 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+  });
+
+  it('classifies "refactor the vault module" as complex via cross-cutting when combined with files', () => {
+    const result = assess({ prompt: 'refactor across the vault module', filesEstimated: 5 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+  });
+
+  it('classifies "migrate database schema" touching multiple files as complex', () => {
+    const result = assess({ prompt: 'migrate database schema to v2', filesEstimated: 3 });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(true);
+    expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+  });
+
+  it('classifies many-file task with design decision as complex', () => {
+    const result = assess({ prompt: 'how should we update styles across the app', filesEstimated: 5 });
+    expect(result.classification).toBe('complex');
+    expect(result.score).toBeGreaterThanOrEqual(40);
+    expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+  });
+
+  it('classifies task with design decision as complex', () => {
+    const result = assess({
+      prompt: 'how should we structure the new cache layer',
+      filesEstimated: 3,
+    });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'design-decisions-needed')!.triggered).toBe(true);
+  });
+
+  it('classifies task with new dependency as complex', () => {
+    const result = assess({
+      prompt: 'add a new package for rate limiting and install it',
+      filesEstimated: 3,
+    });
+    expect(result.classification).toBe('complex');
+    expect(signalByName(result, 'new-dependencies')!.triggered).toBe(true);
+  });
+});
+
+// ─── Edge Cases ─────────────────────────────────────────────────────
+
+describe('assessTaskComplexity — edge cases', () => {
+  it('handles empty prompt as simple', () => {
+    const result = assess({ prompt: '' });
+    expect(result.classification).toBe('simple');
+    expect(result.score).toBe(0);
+  });
+
+  it('clamps score to 0 minimum (negative weights only)', () => {
+    const result = assess({
+      prompt: 'do the thing',
+      hasParentPlan: true,
+    });
+    expect(result.score).toBe(0);
+    expect(result.classification).toBe('simple');
+  });
+
+  it('clamps score to 100 maximum', () => {
+    const result = assess({
+      prompt: 'add authentication, migrate the DB, install new package, how should we design this, refactor across all modules',
+      filesEstimated: 10,
+      domains: ['vault', 'brain', 'planning'],
+    });
+    expect(result.score).toBeLessThanOrEqual(100);
+    expect(result.score).toBeGreaterThanOrEqual(0);
+  });
+
+  it('parent context reduces complexity', () => {
+    const withoutParent = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+    });
+    const withParent = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+      hasParentPlan: true,
+    });
+    expect(withParent.score).toBeLessThan(withoutParent.score);
+    expect(signalByName(withParent, 'approach-already-described')!.triggered).toBe(true);
+  });
+
+  it('parentIssueContext also reduces complexity', () => {
+    const result = assess({
+      prompt: 'add authorization to the API',
+      filesEstimated: 4,
+      parentIssueContext: 'Use middleware pattern as described in RFC-42',
+    });
+    expect(signalByName(result, 'approach-already-described')!.triggered).toBe(true);
+  });
+
+  it('borderline score at exactly 40 is complex', () => {
+    // file-count (25) + new-dependencies (15) = 40
+    const result = assess({
+      prompt: 'install the redis package',
+      filesEstimated: 3,
+    });
+    expect(result.score).toBe(40);
+    expect(result.classification).toBe('complex');
+  });
+
+  it('borderline score at 39 is simple', () => {
+    // file-count (25) + new-dependencies (15) + approach-described (-15) = 25
+    const result = assess({
+      prompt: 'install the redis package',
+      filesEstimated: 3,
+      hasParentPlan: true,
+    });
+    expect(result.score).toBeLessThan(40);
+    expect(result.classification).toBe('simple');
+  });
+});
+
+// ─── Individual Signals ─────────────────────────────────────────────
+
+describe('assessTaskComplexity — individual signals', () => {
+  describe('file-count signal', () => {
+    it('triggers at 3 files', () => {
+      const result = assess({ prompt: 'task', filesEstimated: 3 });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(true);
+      expect(signalByName(result, 'file-count')!.weight).toBe(25);
+    });
+
+    it('does not trigger at 2 files', () => {
+      const result = assess({ prompt: 'task', filesEstimated: 2 });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+    });
+
+    it('does not trigger when no estimate provided', () => {
+      const result = assess({ prompt: 'task' });
+      expect(signalByName(result, 'file-count')!.triggered).toBe(false);
+    });
+  });
+
+  describe('cross-cutting-keywords signal', () => {
+    it.each([
+      'add authentication',
+      'implement authorization',
+      'migrate the database',
+      'refactor across modules',
+      'handle cross-cutting concerns',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(true);
+    });
+
+    it('does not trigger for benign text', () => {
+      const result = assess({ prompt: 'fix button alignment' });
+      expect(signalByName(result, 'cross-cutting-keywords')!.triggered).toBe(false);
+    });
+  });
+
+  describe('new-dependencies signal', () => {
+    it.each([
+      'add dependency for caching',
+      'install redis',
+      'new package for validation',
+      'npm install lodash',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'new-dependencies')!.triggered).toBe(true);
+    });
+
+    it('does not trigger for normal text', () => {
+      const result = assess({ prompt: 'update existing code' });
+      expect(signalByName(result, 'new-dependencies')!.triggered).toBe(false);
+    });
+  });
+
+  describe('design-decisions-needed signal', () => {
+    it.each([
+      'how should we handle caching',
+      'which approach for the API',
+      'design decision on storage',
+      'architectural decision for events',
+      'evaluate the trade-off between speed and accuracy',
+    ])('triggers for: "%s"', (prompt) => {
+      const result = assess({ prompt });
+      expect(signalByName(result, 'design-decisions-needed')!.triggered).toBe(true);
+    });
+  });
+
+  describe('approach-already-described signal', () => {
+    it('triggers with hasParentPlan', () => {
+      const result = assess({ prompt: 'task', hasParentPlan: true });
+      const signal = signalByName(result, 'approach-already-described')!;
+      expect(signal.triggered).toBe(true);
+      expect(signal.weight).toBe(-15);
+    });
+
+    it('triggers with parentIssueContext', () => {
+      const result = assess({ prompt: 'task', parentIssueContext: 'Steps described here' });
+      expect(signalByName(result, 'approach-already-described')!.triggered).toBe(true);
+    });
+
+    it('does not trigger with empty parentIssueContext', () => {
+      const result = assess({ prompt: 'task', parentIssueContext: '   ' });
+      expect(signalByName(result, 'approach-already-described')!.triggered).toBe(false);
+    });
+  });
+
+  describe('multi-domain signal', () => {
+    it('triggers with 2+ domains', () => {
+      const result = assess({ prompt: 'task', domains: ['vault', 'brain'] });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(true);
+      expect(signalByName(result, 'multi-domain')!.weight).toBe(5);
+    });
+
+    it('does not trigger with single domain', () => {
+      const result = assess({ prompt: 'task', domains: ['vault'] });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(false);
+    });
+
+    it('does not trigger with no domains', () => {
+      const result = assess({ prompt: 'task' });
+      expect(signalByName(result, 'multi-domain')!.triggered).toBe(false);
+    });
+  });
+});
+
+// ─── Reasoning Output ───────────────────────────────────────────────
+
+describe('assessTaskComplexity — reasoning', () => {
+  it('includes signal names in reasoning when triggered', () => {
+    const result = assess({ prompt: 'migrate the database', filesEstimated: 5 });
+    expect(result.reasoning).toContain('cross-cutting-keywords');
+    expect(result.reasoning).toContain('file-count');
+  });
+
+  it('provides fallback reasoning when nothing triggers', () => {
+    const result = assess({ prompt: 'fix typo' });
+    expect(result.reasoning).toContain('No complexity signals detected');
+  });
+
+  it('always returns 6 signals', () => {
+    const result = assess({ prompt: 'anything' });
+    expect(result.signals).toHaveLength(6);
+  });
+});

package/src/planning/task-complexity-assessor.ts

@@ -0,0 +1,183 @@
+/**
+ * Task Complexity Assessor — pure function that classifies tasks as simple or complex.
+ *
+ * Used by the planning module to decide whether a decomposed GH issue
+ * needs a full plan or can be executed directly.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export interface AssessmentInput {
+  /** User's task description. */
+  prompt: string;
+  /** Estimated number of files to touch. */
+  filesEstimated?: number;
+  /** GH issue body if available. */
+  parentIssueContext?: string;
+  /** Whether the approach is already described in a parent plan. */
+  hasParentPlan?: boolean;
+  /** Which domains are involved. */
+  domains?: string[];
+}
+
+export interface AssessmentSignal {
+  name: string;
+  weight: number;
+  triggered: boolean;
+  detail: string;
+}
+
+export interface AssessmentResult {
+  classification: 'simple' | 'complex';
+  /** 0-100 complexity score. Threshold at 40. */
+  score: number;
+  signals: AssessmentSignal[];
+  /** One-line explanation. */
+  reasoning: string;
+}
+
+// ─── Signal Detectors ───────────────────────────────────────────────
+
+const CROSS_CUTTING_PATTERNS = [
+  /\bauth(?:entication|orization)?\b/i,
+  /\bmigrat(?:e|ion|ing)\b/i,
+  /\brefactor(?:ing)?\s+across\b/i,
+  /\bcross[- ]cutting\b/i,
+];
+
+const NEW_DEPENDENCY_PATTERNS = [
+  /\badd\s+dep(?:endency|endencies)?\b/i,
+  /\binstall\b/i,
+  /\bnew\s+package\b/i,
+  /\bnpm\s+install\b/i,
+  /\badd\s+(?:a\s+)?(?:new\s+)?(?:npm\s+)?package\b/i,
+];
+
+const DESIGN_DECISION_PATTERNS = [
+  /\bhow\s+should\b/i,
+  /\bwhich\s+approach\b/i,
+  /\bdesign\s+decision\b/i,
+  /\barchitectur(?:e|al)\s+(?:decision|choice)\b/i,
+  /\btrade[- ]?off/i,
+];
+
+function detectFileCount(input: AssessmentInput): AssessmentSignal {
+  const files = input.filesEstimated ?? 0;
+  const triggered = files >= 3;
+  return {
+    name: 'file-count',
+    weight: 25,
+    triggered,
+    detail: triggered
+      ? `Estimated ${files} files (≥3 threshold)`
+      : files > 0
+        ? `Estimated ${files} file${files === 1 ? '' : 's'} (under threshold)`
+        : 'No file estimate provided',
+  };
+}
+
+function detectCrossCutting(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = CROSS_CUTTING_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'cross-cutting-keywords',
+    weight: 20,
+    triggered: !!match,
+    detail: match
+      ? `Detected cross-cutting keyword: "${text.match(match)?.[0]}"`
+      : 'No cross-cutting keywords detected',
+  };
+}
+
+function detectNewDependencies(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = NEW_DEPENDENCY_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'new-dependencies',
+    weight: 15,
+    triggered: !!match,
+    detail: match
+      ? `Detected dependency signal: "${text.match(match)?.[0]}"`
+      : 'No new dependency signals detected',
+  };
+}
+
+function detectDesignDecisions(input: AssessmentInput): AssessmentSignal {
+  const text = input.prompt;
+  const match = DESIGN_DECISION_PATTERNS.find((p) => p.test(text));
+  return {
+    name: 'design-decisions-needed',
+    weight: 20,
+    triggered: !!match,
+    detail: match
+      ? `Detected design decision signal: "${text.match(match)?.[0]}"`
+      : 'No design decision signals detected',
+  };
+}
+
+function detectApproachDescribed(input: AssessmentInput): AssessmentSignal {
+  const hasContext = !!(input.hasParentPlan || input.parentIssueContext?.trim());
+  return {
+    name: 'approach-already-described',
+    weight: -15,
+    triggered: hasContext,
+    detail: hasContext
+      ? 'Approach already described in parent plan or issue'
+      : 'No pre-existing approach context',
+  };
+}
+
+function detectMultiDomain(input: AssessmentInput): AssessmentSignal {
+  const domains = input.domains ?? [];
+  const triggered = domains.length >= 2;
+  return {
+    name: 'multi-domain',
+    weight: 5,
+    triggered,
+    detail: triggered
+      ? `Involves ${domains.length} domains: ${domains.join(', ')}`
+      : domains.length === 1
+        ? `Single domain: ${domains[0]}`
+        : 'No domains specified',
+  };
+}
+
+// ─── Assessor ───────────────────────────────────────────────────────
+
+const COMPLEXITY_THRESHOLD = 40;
+
+/**
+ * Assess task complexity from structured input.
+ *
+ * Returns a classification (`simple` | `complex`), a numeric score (0-100),
+ * the individual signals that contributed, and a one-line reasoning string.
+ *
+ * Pure function — no side effects, no DB, no MCP calls.
+ */
+export function assessTaskComplexity(input: AssessmentInput): AssessmentResult {
+  const signals: AssessmentSignal[] = [
+    detectFileCount(input),
+    detectCrossCutting(input),
+    detectNewDependencies(input),
+    detectDesignDecisions(input),
+    detectApproachDescribed(input),
+    detectMultiDomain(input),
+  ];
+
+  const rawScore = signals.reduce(
+    (sum, s) => sum + (s.triggered ? s.weight : 0),
+    0,
+  );
+
+  // Clamp to 0-100
+  const score = Math.max(0, Math.min(100, rawScore));
+  const classification = score >= COMPLEXITY_THRESHOLD ? 'complex' : 'simple';
+
+  const triggered = signals.filter((s) => s.triggered);
+  const reasoning =
+    triggered.length === 0
+      ? 'No complexity signals detected — treating as simple task'
+      : `${classification === 'complex' ? 'Complex' : 'Simple'}: ${triggered.map((s) => s.name).join(', ')} (score ${score})`;
+
+  return { classification, score, signals, reasoning };
+}

package/src/runtime/admin-ops.test.ts

@@ -133,6 +133,29 @@ describe('createAdminOps', () => {
       expect(grouped.vault).toContain('vault_search');
     });
 
+    it('returns routing hints in grouped mode', async () => {
+      const op = findOp(ops, 'admin_tool_list');
+      const allOps = [
+        { name: 'admin_health', description: 'Health check', auth: 'read' },
+      ];
+      const result = (await op.handler({ _allOps: allOps })) as Record<string, unknown>;
+      const routing = result.routing as Record<string, string>;
+      expect(routing).toBeDefined();
+      expect(typeof routing).toBe('object');
+      // Spot-check a few known intent signals
+      expect(routing['search knowledge']).toBe('vault.search_intelligent');
+      expect(routing['plan this']).toBe('plan.create_plan');
+      expect(routing['health check']).toBe('admin.admin_health');
+    });
+
+    it('returns routing hints in fallback mode', async () => {
+      const op = findOp(ops, 'admin_tool_list');
+      const result = (await op.handler({})) as Record<string, unknown>;
+      const routing = result.routing as Record<string, string>;
+      expect(routing).toBeDefined();
+      expect(Object.keys(routing).length).toBeGreaterThan(0);
+    });
+
     it('returns verbose format when verbose=true', async () => {
       const op = findOp(ops, 'admin_tool_list');
       const allOps = [{ name: 'admin_health', description: 'Health check', auth: 'read' }];

package/src/runtime/admin-ops.ts

@@ -10,6 +10,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { ENGINE_MODULE_MANIFEST } from '../engine/module-manifest.js';
 
 /**
  * Resolve the @soleri/core package.json version.
@@ -113,6 +114,7 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
           return {
             count: allOps.length,
             ops: grouped,
+            routing: buildRoutingHints(),
           };
         }
         // Fallback — just describe admin ops
@@ -130,6 +132,7 @@ export function createAdminOps(runtime: AgentRuntime): OpDefinition[] {
               'admin_diagnostic',
             ],
           },
+          routing: buildRoutingHints(),
         };
       },
     },
@@ -321,6 +324,22 @@ function formatBytes(bytes: number): string {
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
 }
 
+/**
+ * Build a flat routing map from ENGINE_MODULE_MANIFEST intentSignals.
+ * Keys are natural-language phrases, values are `{suffix}.{op}` paths.
+ */
+function buildRoutingHints(): Record<string, string> {
+  const routing: Record<string, string> = {};
+  for (const mod of ENGINE_MODULE_MANIFEST) {
+    if (mod.intentSignals) {
+      for (const [phrase, op] of Object.entries(mod.intentSignals)) {
+        routing[phrase] = `${mod.suffix}.${op}`;
+      }
+    }
+  }
+  return routing;
+}
+
 function formatUptime(seconds: number): string {
   if (seconds < 60) return `${seconds}s`;
   const minutes = Math.floor(seconds / 60);