@soleri/core 9.10.0 → 9.12.1

package/src/runtime/quality-signals.test.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { analyzeQualitySignals, captureQualitySignals } from './quality-signals.js';
+import {
+  analyzeQualitySignals,
+  captureQualitySignals,
+  buildFixTrailSummary,
+} from './quality-signals.js';
 import type { EvidenceReport } from '../planning/evidence-collector.js';
 
 // ---------------------------------------------------------------------------
@@ -104,7 +108,7 @@ describe('analyzeQualitySignals', () => {
     expect(result.antiPatterns).toHaveLength(0);
   });
 
-  it('does not flag task with fixIterations === 2 (at threshold, not above)', () => {
+  it('flags task with fixIterations === 2 (at threshold)', () => {
     const report = makeReport({
       taskEvidence: [
         {
@@ -120,7 +124,28 @@ describe('analyzeQualitySignals', () => {
 
     const result = analyzeQualitySignals(report);
 
+    expect(result.antiPatterns).toHaveLength(1);
+    expect(result.antiPatterns[0].fixIterations).toBe(2);
+  });
+
+  it('does not flag task with fixIterations === 1 (below threshold)', () => {
+    const report = makeReport({
+      taskEvidence: [
+        {
+          taskId: 't4b',
+          taskTitle: 'Single retry task',
+          plannedStatus: 'completed',
+          matchedFiles: [],
+          verdict: 'DONE',
+          fixIterations: 1,
+        },
+      ],
+    });
+
+    const result = analyzeQualitySignals(report);
+
     expect(result.antiPatterns).toHaveLength(0);
+    expect(result.cleanTasks).toHaveLength(0);
   });
 
   it('detects scope creep from unplanned changes', () => {
@@ -199,9 +224,14 @@ describe('captureQualitySignals', () => {
     expect(entry.tags).toContain('auto-captured');
 
     expect(brain.recordFeedback).toHaveBeenCalledWith(
-      'quality-signal:rework:Fix login',
-      't1',
-      'dismissed',
+      expect.objectContaining({
+        query: 'Fix login',
+        entryId: 'plan-1',
+        action: 'dismissed',
+        confidence: 0.7,
+        source: 'evidence-quality',
+        reason: 'Task needed 3 fix iterations — high rework',
+      }),
     );
 
     expect(result.captured).toBe(1);
@@ -226,9 +256,14 @@ describe('captureQualitySignals', () => {
     const result = captureQualitySignals(analysis, vault, brain, 'plan-1');
 
     expect(brain.recordFeedback).toHaveBeenCalledWith(
-      'quality-signal:clean:Add feature',
-      't2',
-      'accepted',
+      expect.objectContaining({
+        query: 'Add feature',
+        entryId: 'plan-1',
+        action: 'accepted',
+        confidence: 0.9,
+        source: 'evidence-quality',
+        reason: 'Clean first-try completion — no rework needed',
+      }),
     );
     expect(result.feedback).toBe(1);
     expect(result.captured).toBe(0);
@@ -281,6 +316,83 @@ describe('captureQualitySignals', () => {
     expect(entry.severity).toBe('critical');
   });
 
+  it('records positive feedback with evidence-quality source for clean first-try tasks', () => {
+    const analysis = {
+      antiPatterns: [],
+      cleanTasks: [
+        {
+          taskId: 'clean-1',
+          taskTitle: 'Smooth task',
+          kind: 'clean' as const,
+          fixIterations: 0,
+          verdict: 'DONE',
+        },
+      ],
+      scopeCreep: [],
+    };
+
+    captureQualitySignals(analysis, vault, brain, 'plan-99');
+
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'accepted',
+        confidence: 0.9,
+        source: 'evidence-quality',
+        entryId: 'plan-99',
+      }),
+    );
+  });
+
+  it('records negative feedback with evidence-quality source for high-rework tasks', () => {
+    const analysis = {
+      antiPatterns: [
+        {
+          taskId: 'rework-1',
+          taskTitle: 'Painful task',
+          kind: 'anti-pattern' as const,
+          fixIterations: 3,
+          verdict: 'DONE',
+        },
+      ],
+      cleanTasks: [],
+      scopeCreep: [],
+    };
+
+    captureQualitySignals(analysis, vault, brain, 'plan-99');
+
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'dismissed',
+        confidence: 0.7,
+        source: 'evidence-quality',
+        reason: 'Task needed 3 fix iterations — high rework',
+        context: JSON.stringify({ taskId: 'rework-1', reworkCount: 3, verdict: 'DONE' }),
+      }),
+    );
+  });
+
+  it('does not record evidence-quality feedback for tasks with 1 fix iteration', () => {
+    // 1 fix iteration = neither clean (fixIterations !== 0) nor anti-pattern (< 2)
+    const analysis = analyzeQualitySignals(
+      makeReport({
+        taskEvidence: [
+          {
+            taskId: 't-mid',
+            taskTitle: 'Single retry',
+            plannedStatus: 'completed',
+            matchedFiles: [],
+            verdict: 'DONE',
+            fixIterations: 1,
+          },
+        ],
+      }),
+    );
+
+    captureQualitySignals(analysis, vault, brain, 'plan-99');
+
+    expect(brain.recordFeedback).not.toHaveBeenCalled();
+  });
+
   it('handles mixed signals correctly', () => {
     const analysis = {
       antiPatterns: [
@@ -310,3 +422,65 @@ describe('captureQualitySignals', () => {
     expect(result.feedback).toBe(2); // 1 dismissed + 1 accepted
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildFixTrailSummary
+// ---------------------------------------------------------------------------
+
+describe('buildFixTrailSummary', () => {
+  it('returns summary string for tasks with rework iterations', () => {
+    const report = makeReport({
+      taskEvidence: [
+        {
+          taskId: 'a',
+          taskTitle: 'Task A',
+          plannedStatus: 'completed',
+          matchedFiles: [],
+          verdict: 'DONE',
+          fixIterations: 2,
+        },
+        {
+          taskId: 'b',
+          taskTitle: 'Task B',
+          plannedStatus: 'completed',
+          matchedFiles: [],
+          verdict: 'DONE',
+          fixIterations: 0,
+        },
+        {
+          taskId: 'c',
+          taskTitle: 'Task C',
+          plannedStatus: 'completed',
+          matchedFiles: [],
+          verdict: 'DONE',
+          fixIterations: 3,
+        },
+      ],
+    });
+
+    const summary = buildFixTrailSummary(report);
+    expect(summary).toBe('Task A: 2 fix iterations; Task C: 3 fix iterations');
+  });
+
+  it('returns undefined when no tasks have rework', () => {
+    const report = makeReport({
+      taskEvidence: [
+        {
+          taskId: 'a',
+          taskTitle: 'Clean',
+          plannedStatus: 'completed',
+          matchedFiles: [],
+          verdict: 'DONE',
+          fixIterations: 0,
+        },
+      ],
+    });
+
+    expect(buildFixTrailSummary(report)).toBeUndefined();
+  });
+
+  it('returns undefined for empty task evidence', () => {
+    const report = makeReport({ taskEvidence: [] });
+    expect(buildFixTrailSummary(report)).toBeUndefined();
+  });
+});

package/src/runtime/quality-signals.ts

@@ -34,8 +34,12 @@ export interface QualityAnalysis {
 // Thresholds
 // ---------------------------------------------------------------------------
 
-/** Tasks with more than this many fix iterations are flagged as anti-patterns. */
+/** Tasks with this many or more fix iterations are flagged as anti-patterns. */
 const REWORK_THRESHOLD = 2;
+/** Brain feedback confidence for clean first-try tasks. */
+const CLEAN_TASK_CONFIDENCE = 0.9;
+/** Brain feedback confidence for high-rework anti-pattern tasks. */
+const REWORK_TASK_CONFIDENCE = 0.7;
 
 // ---------------------------------------------------------------------------
 // Analysis
@@ -44,7 +48,7 @@ const REWORK_THRESHOLD = 2;
 /**
  * Analyze an evidence report for quality signals.
  *
- * - fixIterations > 2 → anti-pattern (rework)
+ * - fixIterations >= 2 → anti-pattern (rework)
  * - fixIterations === 0 + verdict DONE → clean (first-pass success)
  * - unplannedChanges → scope-creep signals
  */
@@ -59,7 +63,7 @@ export function analyzeQualitySignals(
   for (const te of report.taskEvidence) {
     const iterations = te.fixIterations ?? 0;
 
-    if (iterations > REWORK_THRESHOLD) {
+    if (iterations >= REWORK_THRESHOLD) {
       antiPatterns.push({
         taskId: te.taskId,
         taskTitle: te.taskTitle,
@@ -148,7 +152,19 @@ export function captureQualitySignals(
   // Record negative brain feedback for rework tasks
   for (const ap of analysis.antiPatterns) {
     try {
-      brain.recordFeedback(`quality-signal:rework:${ap.taskTitle}`, ap.taskId, 'dismissed');
+      brain.recordFeedback({
+        query: ap.taskTitle,
+        entryId: planId,
+        action: 'dismissed',
+        confidence: REWORK_TASK_CONFIDENCE,
+        source: 'evidence-quality',
+        reason: `Task needed ${ap.fixIterations} fix iterations — high rework`,
+        context: JSON.stringify({
+          taskId: ap.taskId,
+          reworkCount: ap.fixIterations,
+          verdict: ap.verdict,
+        }),
+      });
       feedback++;
     } catch {
       // Best-effort
@@ -158,7 +174,14 @@ export function captureQualitySignals(
   // Record positive brain feedback for clean tasks
   for (const ct of analysis.cleanTasks) {
     try {
-      brain.recordFeedback(`quality-signal:clean:${ct.taskTitle}`, ct.taskId, 'accepted');
+      brain.recordFeedback({
+        query: ct.taskTitle,
+        entryId: planId,
+        action: 'accepted',
+        confidence: CLEAN_TASK_CONFIDENCE,
+        source: 'evidence-quality',
+        reason: 'Clean first-try completion — no rework needed',
+      });
       feedback++;
     } catch {
       // Best-effort
@@ -167,3 +190,19 @@ export function captureQualitySignals(
 
   return { captured, skipped, feedback };
 }
+
+// ---------------------------------------------------------------------------
+// Fix-trail summary for knowledge extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a human-readable fix-trail summary from an evidence report.
+ * Returns `undefined` when no tasks had rework iterations.
+ */
+export function buildFixTrailSummary(report: EvidenceReport): string | undefined {
+  const entries = report.taskEvidence
+    .filter((te) => (te.fixIterations ?? 0) > 0)
+    .map((te) => `${te.taskTitle}: ${te.fixIterations} fix iterations`);
+
+  return entries.length > 0 ? entries.join('; ') : undefined;
+}

package/src/runtime/runtime.ts

@@ -56,6 +56,9 @@ import { PipelineRunner } from '../queue/pipeline-runner.js';
 import { evaluateQuality } from '../curator/quality-gate.js';
 import { classifyEntry } from '../curator/classifier.js';
 import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
+import type { EmbeddingProvider } from '../embeddings/types.js';
+import { OpenAIEmbeddingProvider } from '../embeddings/openai-provider.js';
+import { EmbeddingPipeline } from '../embeddings/pipeline.js';
 import { loadPersona } from '../persona/loader.js';
 import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
@@ -104,12 +107,46 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     }
   }
 
+  // Feature Flags — file-based + env var + runtime toggles (created early so other modules can check)
+  const flags = new FeatureFlags(getAgentFlagsPath(agentId));
+
   // Planner — multi-step task tracking
   const planner = new Planner(plansPath);
 
+  // ─── Embedding Provider (optional) ────────────────────────────────
+  // Only initialized when both config.embedding is present AND the
+  // 'embedding-enabled' feature flag is on. Brain continues without
+  // embeddings when either condition is unmet (vector weight stays 0).
+  let embeddingProvider: EmbeddingProvider | undefined;
+  let embeddingPipeline: EmbeddingPipeline | undefined;
+
+  if (config.embedding && flags.isEnabled('embedding-enabled')) {
+    try {
+      const embeddingConfig = config.embedding;
+      if (embeddingConfig.provider === 'openai') {
+        const openaiPool = new KeyPool(loadKeyPoolConfig(agentId).openai);
+        embeddingProvider = new OpenAIEmbeddingProvider(embeddingConfig, openaiPool);
+      }
+      // Future providers (ollama, etc.) would be added here
+
+      if (embeddingProvider) {
+        embeddingPipeline = new EmbeddingPipeline(embeddingProvider, vault.getProvider());
+        logger.info(
+          `[Embedding] Initialized: ${embeddingProvider.providerName}/${embeddingProvider.model} (${embeddingProvider.dimensions}d)`,
+        );
+      }
+    } catch (err) {
+      logger.warn(
+        `[Embedding] Failed to initialize: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      // Graceful degradation — continue without embeddings
+    }
+  }
+
   // Brain — intelligence layer (TF-IDF scoring, auto-tagging, dedup)
   // Pass vaultManager so intelligentSearch queries all connected sources (not just agent tier)
-  const brain = new Brain(vault, vaultManager);
+  // Pass embeddingProvider for hybrid FTS5+vector search when available
+  const brain = new Brain(vault, vaultManager, embeddingProvider);
 
   // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
   const brainIntelligence = new BrainIntelligence(vault, brain);
@@ -366,7 +403,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     intakePipeline,
     textIngester,
     authPolicy: { mode: 'permissive', callerLevel: 'admin' },
-    flags: new FeatureFlags(getAgentFlagsPath(agentId)),
+    flags,
     health,
     playbookExecutor,
     pluginRegistry,
@@ -392,6 +429,8 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       const p = loadPersona(agentId, config.persona ?? undefined);
       return generatePersonaInstructions(p);
     })(),
+    embeddingProvider,
+    embeddingPipeline,
     adapterRegistry,
     subagentDispatcher,
     contextHealth: new ContextHealthMonitor(),

package/src/runtime/types.ts

@@ -39,6 +39,20 @@ import type { ContextHealthMonitor } from './context-health.js';
 import type { ShutdownRegistry } from './shutdown-registry.js';
 import type { RuntimeAdapterRegistry } from '../adapters/registry.js';
 import type { SubagentDispatcher } from '../subagent/dispatcher.js';
+import type { EmbeddingConfig, EmbeddingProvider } from '../embeddings/types.js';
+import type { EmbeddingPipeline } from '../embeddings/pipeline.js';
+
+/** Pre-flight manifest returned by session_start for agent self-awareness. */
+export interface PreflightManifest {
+  tools: Array<{ facade: string; op: string; description: string }>;
+  skills: string[];
+  activePlans: Array<{ planId: string; title: string; status: string }>;
+  vaultSummary: {
+    entryCount: number;
+    connected: boolean;
+    domains: string[];
+  };
+}
 
 /**
  * Configuration for creating an agent runtime.
@@ -63,6 +77,8 @@ export interface AgentRuntimeConfig {
   agentDir?: string;
   /** Persona configuration from agent.yaml. If omitted, Italian Craftsperson default is used. */
   persona?: Partial<import('../persona/types.js').PersonaConfig>;
+  /** Embedding provider configuration. If omitted, embeddings are disabled. */
+  embedding?: EmbeddingConfig;
 }
 
 /**
@@ -135,6 +151,10 @@ export interface AgentRuntime {
   adapterRegistry: RuntimeAdapterRegistry;
   /** Subagent dispatcher — spawn and manage child agent processes. */
   subagentDispatcher: SubagentDispatcher;
+  /** Embedding provider — generates dense vectors for hybrid search (optional). */
+  embeddingProvider?: EmbeddingProvider;
+  /** Embedding pipeline — batch and incremental embedding of vault entries (optional). */
+  embeddingPipeline?: EmbeddingPipeline;
   /** Context health monitor — tracks tool call volume and context window fill. */
   contextHealth: ContextHealthMonitor;
   /** Shutdown registry — centralized cleanup for timers, watchers, child processes. */

package/src/skills/__tests__/sync-skills.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+let sourceDir: string;
+let fakeHome: string;
+
+function setup(): void {
+  const base = join(tmpdir(), `soleri-sync-test-${Date.now()}`);
+  mkdirSync(base, { recursive: true });
+
+  sourceDir = join(base, 'source-skills');
+  mkdirSync(sourceDir, { recursive: true });
+
+  fakeHome = join(base, 'fake-home');
+  mkdirSync(join(fakeHome, '.claude', 'skills'), { recursive: true });
+}
+
+function teardown(): void {
+  if (fakeHome) {
+    const base = join(fakeHome, '..');
+    rmSync(base, { recursive: true, force: true });
+  }
+}
+
+/** Create a source skill directory with a minimal SKILL.md */
+function createSourceSkill(name: string, content?: string): string {
+  const dir = join(sourceDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, 'SKILL.md'),
+    content ?? `---\nname: ${name}\n---\n\n# ${name}\n\nA test skill.\n`,
+  );
+  return dir;
+}
+
+/** Create a directory in the fake ~/.claude/skills/ target */
+function createTargetSkillDir(name: string): string {
+  const dir = join(fakeHome, '.claude', 'skills', name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: ${name}\n---\n\nStale skill.\n`);
+  return dir;
+}
+
+function targetSkillsDir(): string {
+  return join(fakeHome, '.claude', 'skills');
+}
+
+function targetDirExists(name: string): boolean {
+  return existsSync(join(targetSkillsDir(), name));
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('syncSkillsToClaudeCode — orphan cleanup', () => {
+  beforeEach(() => {
+    setup();
+    // Mock homedir() so syncSkillsToClaudeCode writes to our temp directory
+    vi.mock('node:os', async (importOriginal) => {
+      const original = await importOriginal<typeof import('node:os')>();
+      return {
+        ...original,
+        homedir: () => fakeHome,
+      };
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    teardown();
+  });
+
+  it('removes orphan directories that match the agent prefix', async () => {
+    // Source has "my-skill", target has stale "test-agent-old-skill"
+    createSourceSkill('my-skill');
+    createTargetSkillDir('test-agent-old-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // The orphan should be reported as removed
+    expect(result.removed).toContain('test-agent-old-skill');
+    // The orphan directory should be gone
+    expect(targetDirExists('test-agent-old-skill')).toBe(false);
+  });
+
+  it('does NOT remove directories that do not match the agent prefix', async () => {
+    createSourceSkill('my-skill');
+    // "other-agent-skill" does NOT start with "test-agent-"
+    createTargetSkillDir('other-agent-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // Should still exist — not our prefix
+    expect(targetDirExists('other-agent-skill')).toBe(true);
+    expect(result.removed).not.toContain('other-agent-skill');
+  });
+
+  it('does NOT remove a skill directory that was just synced', async () => {
+    createSourceSkill('active-skill');
+    // This directory matches the prefix AND is a current skill
+    createTargetSkillDir('test-agent-active-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    // "active-skill" should be synced (installed/updated/skipped), not removed
+    const synced = [...result.installed, ...result.updated, ...result.skipped];
+    expect(synced).toContain('active-skill');
+    expect(result.removed).not.toContain('test-agent-active-skill');
+    expect(targetDirExists('test-agent-active-skill')).toBe(true);
+  });
+
+  it('returns an empty removed array when there are no orphans', async () => {
+    createSourceSkill('only-skill');
+
+    const { syncSkillsToClaudeCode } = await import('../sync-skills.js');
+    const result = syncSkillsToClaudeCode([sourceDir], 'Test Agent');
+
+    expect(result.removed).toBeDefined();
+    expect(Array.isArray(result.removed)).toBe(true);
+    expect(result.removed).toHaveLength(0);
+  });
+});