@soleri/core 9.14.4 → 9.15.0

package/src/planning/planner.ts

@@ -77,8 +77,38 @@ export class Planner {
     }
   }
 
-  private save(): void {
+  private refresh(): void {
+    this.store = this.load();
+  }
+
+  private mergeLatestStore(deletedPlanIds: string[] = []): void {
+    const deleted = new Set(deletedPlanIds);
+    const latest = this.load();
+    const merged = new Map<string, Plan>();
+
+    for (const plan of latest.plans) {
+      if (!deleted.has(plan.id)) {
+        merged.set(plan.id, plan);
+      }
+    }
+
+    for (const plan of this.store.plans) {
+      if (deleted.has(plan.id)) continue;
+      const existing = merged.get(plan.id);
+      if (!existing || plan.updatedAt >= existing.updatedAt) {
+        merged.set(plan.id, plan);
+      }
+    }
+
+    this.store = {
+      version: latest.version ?? this.store.version ?? '1.0',
+      plans: [...merged.values()],
+    };
+  }
+
+  private save(deletedPlanIds: string[] = []): void {
     mkdirSync(dirname(this.filePath), { recursive: true });
+    this.mergeLatestStore(deletedPlanIds);
     writeFileSync(this.filePath, JSON.stringify(this.store, null, 2), 'utf-8');
   }
 
@@ -88,8 +118,13 @@ export class Planner {
     plan.updatedAt = r.updatedAt;
   }
 
+  private findPlan(planId: string): Plan | null {
+    return this.store.plans.find((p) => p.id === planId) ?? null;
+  }
+
   private requirePlan(planId: string): Plan {
-    const plan = this.get(planId);
+    this.refresh();
+    const plan = this.findPlan(planId);
     if (!plan) throw new Error(`Plan not found: ${planId}`);
     return plan;
   }
@@ -101,6 +136,7 @@ export class Planner {
   }
 
   create(params: Parameters<typeof createPlanObject>[0]): Plan {
+    this.refresh();
     const plan = createPlanObject(params);
     this.store.plans.push(plan);
     this.save();
@@ -108,18 +144,21 @@ export class Planner {
   }
 
   get(planId: string): Plan | null {
-    return this.store.plans.find((p) => p.id === planId) ?? null;
+    this.refresh();
+    return this.findPlan(planId);
   }
 
   list(): Plan[] {
+    this.refresh();
     return [...this.store.plans];
   }
 
   remove(planId: string): boolean {
+    this.refresh();
     const idx = this.store.plans.findIndex((p) => p.id === planId);
     if (idx < 0) return false;
     this.store.plans.splice(idx, 1);
-    this.save();
+    this.save([planId]);
     return true;
   }
 
@@ -220,10 +259,12 @@ export class Planner {
   }
 
   getExecuting(): Plan[] {
+    this.refresh();
     return this.store.plans.filter((p) => p.status === 'executing' || p.status === 'validating');
   }
 
   getActive(): Plan[] {
+    this.refresh();
     return this.store.plans.filter(
       (p) =>
         p.status === 'brainstorming' ||
@@ -435,6 +476,7 @@ export class Planner {
   }
 
   archive(olderThanDays?: number): Plan[] {
+    this.refresh();
     const cutoff =
       olderThanDays !== undefined
         ? Date.now() - olderThanDays * 24 * 60 * 60 * 1000
@@ -460,6 +502,7 @@ export class Planner {
     closedIds: string[];
     closedPlans: Array<{ id: string; previousStatus: string; reason: string }>;
   } {
+    this.refresh();
     const now = Date.now();
     const forceAll = olderThanMs === 0;
     const defaultTtl = forceAll ? 0 : 30 * 60 * 1000; // 30 minutes for draft/approved
@@ -522,6 +565,7 @@ export class Planner {
     totalTasks: number;
     tasksByStatus: Record<TaskStatus, number>;
   } {
+    this.refresh();
     const plans = this.store.plans;
     const byStatus = {
       brainstorming: 0,

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

@@ -46,6 +46,11 @@ vi.mock('./claude-md-helpers.js', () => ({
   injectEngineRulesBlock: vi.fn((content: string) => content),
 }));
 
+vi.mock('../paths.js', () => ({
+  agentPlansPath: vi.fn(() => '/mock-home/.soleri/test-agent/plans.json'),
+  agentVaultPath: vi.fn(() => '/mock-home/.soleri/test-agent/vault.db'),
+}));
+
 vi.mock('../skills/sync-skills.js', () => ({
   discoverSkills: vi.fn(() => [{ name: 'skill-1', path: '/mock/skills/skill-1' }]),
   syncSkillsToClaudeCode: vi.fn(() => ({
@@ -330,5 +335,44 @@ describe('createAdminSetupOps', () => {
       expect(activePlans[0].status).toBe('executing');
       expect(result.recommendation).toContain('need attention');
     });
+
+    it('uses configured or resolved .soleri plan paths and understands planner stores', async () => {
+      runtime = {
+        ...createMockRuntime(),
+        config: {
+          agentId: 'test-agent',
+          dataDir: '/mock/agent-data',
+          agentDir: '/mock/agent-dir',
+        },
+      } as unknown as AgentRuntime;
+      ops = createAdminSetupOps(runtime);
+
+      mockDirs.add('/mock-home/.soleri/test-agent');
+      mockFs['/mock-home/.soleri/test-agent/vault.db'] = 'binary';
+      mockFs['/mock-home/.soleri/test-agent/plans.json'] = JSON.stringify({
+        version: '1.0',
+        plans: [
+          { id: 'plan-1', status: 'executing' },
+          { id: 'plan-2', status: 'completed' },
+        ],
+      });
+
+      const result = (await findOp(ops, 'admin_check_persistence').handler({})) as Record<
+        string,
+        unknown
+      >;
+
+      expect((result.storageDirectory as Record<string, unknown>).path).toBe(
+        '/mock-home/.soleri/test-agent',
+      );
+      expect(
+        ((result.files as Record<string, unknown>).plans as Record<string, unknown>).path,
+      ).toBe('/mock-home/.soleri/test-agent/plans.json');
+      expect(
+        ((result.files as Record<string, unknown>).plans as Record<string, unknown>).items,
+      ).toBe(2);
+      expect(result.status).toBe('PERSISTENCE_ACTIVE');
+      expect(result.activePlans).toEqual([{ id: 'plan-1', status: 'executing' }]);
+    });
   });
 });

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

@@ -27,6 +27,10 @@ import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import {
+  agentPlansPath as getAgentPlansPath,
+  agentVaultPath as getAgentVaultPath,
+} from '../paths.js';
 import {
   hasSections,
   removeSections,
@@ -74,19 +78,63 @@ function getFileInfo(path: string): { exists: boolean; size: number; items: numb
   try {
     const stat = statSync(path);
     const content = JSON.parse(readFileSync(path, 'utf-8'));
-    const items = content.items
-      ? Object.keys(content.items).length
-      : content.contexts
-        ? content.contexts.length
-        : Array.isArray(content)
-          ? content.length
-          : 0;
+    const items = countPersistedItems(content);
     return { exists: true, size: stat.size, items };
   } catch {
     return { exists: true, size: 0, items: -1 };
   }
 }
 
+function countPersistedItems(content: unknown): number {
+  if (Array.isArray(content)) return content.length;
+  if (!content || typeof content !== 'object') return 0;
+
+  const data = content as Record<string, unknown>;
+  if (Array.isArray(data.plans)) return data.plans.length;
+  if (data.items && typeof data.items === 'object') return Object.keys(data.items).length;
+  if (Array.isArray(data.contexts)) return data.contexts.length;
+  return 0;
+}
+
+function extractActivePlans(content: unknown): Array<{ id: string; status: string }> {
+  if (!content || typeof content !== 'object') return [];
+
+  const plans = Array.isArray((content as Record<string, unknown>).plans)
+    ? ((content as Record<string, unknown>).plans as unknown[])
+    : null;
+  if (plans) {
+    return plans.flatMap((plan) => {
+      if (!plan || typeof plan !== 'object') return [];
+      const p = plan as Record<string, unknown>;
+      const id = typeof p.id === 'string' ? p.id : null;
+      const lifecycle =
+        typeof p.lifecycleStatus === 'string'
+          ? p.lifecycleStatus
+          : typeof p.status === 'string'
+            ? p.status
+            : null;
+      if (!id || (lifecycle !== 'executing' && lifecycle !== 'reconciling')) return [];
+      return [{ id, status: lifecycle }];
+    });
+  }
+
+  const items = (content as Record<string, unknown>).items;
+  if (!items || typeof items !== 'object') return [];
+
+  return Object.entries(items).flatMap(([id, plan]) => {
+    if (!plan || typeof plan !== 'object') return [];
+    const p = plan as Record<string, unknown>;
+    const lifecycle =
+      typeof p.lifecycleStatus === 'string'
+        ? p.lifecycleStatus
+        : typeof p.status === 'string'
+          ? p.status
+          : null;
+    if (lifecycle !== 'executing' && lifecycle !== 'reconciling') return [];
+    return [{ id, status: lifecycle }];
+  });
+}
+
 /** Discover hookify rule files in a directory */
 function discoverHookifyFiles(dir: string): Array<{ name: string; path: string }> {
   if (!existsSync(dir)) return [];
@@ -621,15 +669,15 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'read',
       handler: async () => {
         const { agentId, plansPath, vaultPath } = config;
-        const storageDir = join(homedir(), `.${agentId}`);
+        const plansFile = plansPath ?? getAgentPlansPath(agentId);
+        const vaultFile = vaultPath ?? getAgentVaultPath(agentId);
+        const storageDir = dirname(plansFile);
         const storageDirExists = existsSync(storageDir);
 
         // Check plan storage
-        const plansFile = plansPath ?? join(storageDir, 'plans.json');
         const plansInfo = getFileInfo(plansFile);
 
         // Check vault
-        const vaultFile = vaultPath ?? join(storageDir, 'vault.db');
         const vaultExists = existsSync(vaultFile);
         let vaultSize = 0;
         if (vaultExists) {
@@ -655,16 +703,7 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
         if (plansInfo.exists) {
           try {
             const plansData = JSON.parse(readFileSync(plansFile, 'utf-8'));
-            const items = plansData.items ?? plansData;
-            if (typeof items === 'object' && items !== null) {
-              for (const [id, plan] of Object.entries(items)) {
-                const p = plan as Record<string, unknown>;
-                const lifecycle = (p.lifecycleStatus ?? p.status) as string | undefined;
-                if (lifecycle === 'executing' || lifecycle === 'reconciling') {
-                  activePlans.push({ id, status: lifecycle });
-                }
-              }
-            }
+            activePlans.push(...extractActivePlans(plansData));
           } catch {
             // Parse error — not critical
           }

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

@@ -24,7 +24,7 @@ import {
 import type { SkillStep, EvidenceType } from '../../skills/step-tracker.js';
 
 export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[] {
-  const { vault, governance, projectRegistry } = runtime;
+  const { vault, governance, projectRegistry, brainIntelligence } = runtime;
 
   return [
     // ─── Session Start (inline from core-ops.ts) ─────────────────────
@@ -150,6 +150,31 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
           vaultStats: stats,
         });
 
+        // Auto-close orphaned brain sessions (endedAt IS NULL, startedAt < now - 2h)
+        let orphansClosed = 0;
+        try {
+          const TWO_HOURS_MS = 2 * 60 * 60 * 1000;
+          const cutoff = new Date(Date.now() - TWO_HOURS_MS);
+          const activeSessions = brainIntelligence.listSessions({ active: true, limit: 1000 });
+          for (const s of activeSessions) {
+            if (new Date(s.startedAt) < cutoff) {
+              try {
+                brainIntelligence.lifecycle({
+                  action: 'end',
+                  sessionId: s.id,
+                  planOutcome: 'abandoned',
+                  context: 'auto-closed: orphan from previous conversation',
+                });
+                orphansClosed++;
+              } catch {
+                // Best-effort per session — never let one failure abort the rest
+              }
+            }
+          }
+        } catch {
+          // Non-critical — don't fail session start over orphan cleanup
+        }
+
         return {
           project,
           is_new: isNew,
@@ -167,6 +192,7 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
             expiredThisSession: expired,
           },
           preflight,
+          orphansClosed,
           ...(stagingWarning ? { stagingWarning } : {}),
           ...(dreamInfo ? { dream: dreamInfo } : {}),
         };

package/src/runtime/runtime.ts

@@ -148,6 +148,15 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Pass embeddingProvider for hybrid FTS5+vector search when available
   const brain = new Brain(vault, vaultManager, embeddingProvider);
 
+  // Wire canonical tag config if provided
+  if (config.canonicalTags && config.canonicalTags.length > 0) {
+    brain.setCanonicalTagConfig({
+      canonicalTags: config.canonicalTags,
+      tagConstraintMode: config.tagConstraintMode ?? 'suggest',
+      metadataTagPrefixes: config.metadataTagPrefixes ?? ['source:'],
+    });
+  }
+
   // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
   const brainIntelligence = new BrainIntelligence(vault, brain);
 
@@ -199,6 +208,15 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   const intakePipeline = new IntakePipeline(vault.getProvider(), vault, llmClient);
   const textIngester = new TextIngester(vault, llmClient);
 
+  // Wire canonical tag config into TextIngester if provided
+  if (config.canonicalTags && config.canonicalTags.length > 0) {
+    textIngester.setCanonicalTagConfig({
+      canonicalTags: config.canonicalTags,
+      tagConstraintMode: config.tagConstraintMode ?? 'suggest',
+      metadataTagPrefixes: config.metadataTagPrefixes ?? ['source:'],
+    });
+  }
+
   // Playbook Executor — in-memory step-by-step workflow sessions
   const playbookExecutor = new PlaybookExecutor();
 

package/src/runtime/types.ts

@@ -79,6 +79,25 @@ export interface AgentRuntimeConfig {
   persona?: Partial<import('../persona/types.js').PersonaConfig>;
   /** Embedding provider configuration. If omitted, embeddings are disabled. */
   embedding?: EmbeddingConfig;
+  /**
+   * Canonical tag taxonomy configuration.
+   * When set, tags are normalized against this list during capture and ingestion.
+   */
+  canonicalTags?: string[];
+  /**
+   * Tag constraint mode.
+   * - 'enforce': tags not matching canonical list are dropped (unless within edit-distance 3).
+   * - 'suggest': tags are mapped to nearest canonical if within edit-distance 2 (default).
+   * - 'off': no normalization — behavior unchanged from pre-taxonomy.
+   * Default: 'suggest'
+   */
+  tagConstraintMode?: 'enforce' | 'suggest' | 'off';
+  /**
+   * Metadata tag prefixes — tags with these prefixes (e.g. 'source:') are treated as metadata
+   * and are exempt from canonical normalization.
+   * Default: ['source:']
+   */
+  metadataTagPrefixes?: string[];
 }
 
 /**

package/src/skills/validate-skills.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Unit tests for validate-skills — the user-installed SKILL.md validator.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { validateSkillDocs } from './validate-skills.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function createSkillsDir(): string {
+  return mkdtempSync(join(tmpdir(), 'soleri-validate-skills-test-'));
+}
+
+function addSkill(skillsDir: string, skillName: string, content: string): void {
+  const skillDir = join(skillsDir, skillName);
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe('validateSkillDocs', () => {
+  let skillsDir: string;
+
+  beforeEach(() => {
+    skillsDir = createSkillsDir();
+  });
+
+  afterEach(() => {
+    rmSync(skillsDir, { recursive: true, force: true });
+  });
+
+  it('returns valid=true and no errors when the skills directory is empty', () => {
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFiles).toBe(0);
+    expect(result.totalExamples).toBe(0);
+  });
+
+  it('returns valid=true for a SKILL.md with no op-call examples', () => {
+    addSkill(
+      skillsDir,
+      'my-skill',
+      `# My Skill
+
+This skill does something useful.
+
+## Usage
+
+Just invoke it.
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+    expect(result.totalFiles).toBe(1);
+    expect(result.totalExamples).toBe(0);
+  });
+
+  it('returns valid=true when op-call params match the schema', () => {
+    addSkill(
+      skillsDir,
+      'capture-skill',
+      `# Capture Skill
+
+Captures knowledge to the vault.
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { projectPath: ".", entries: [{ type: "pattern", domain: "testing", title: "Use vitest", description: "Prefer vitest for unit tests", severity: "info" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('reports an error when severity has an invalid enum value', () => {
+    // "suggestion" is not in the capture_knowledge severity enum (valid: critical, warning, info)
+    addSkill(
+      skillsDir,
+      'bad-severity-skill',
+      `# Bad Skill
+
+Example with wrong severity enum:
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const severityError = result.errors.find(
+      (e) => e.op === 'capture_knowledge' && e.message.toLowerCase().includes('invalid'),
+    );
+    expect(severityError).toBeDefined();
+    expect(severityError!.file).toContain('bad-severity-skill');
+  });
+
+  it('reports an error when scope receives an object instead of a string', () => {
+    // create_plan scope expects z.string() but we pass an object
+    addSkill(
+      skillsDir,
+      'bad-scope-skill',
+      `# Bad Scope Skill
+
+Example with wrong scope type:
+
+\`\`\`
+YOUR_AGENT_core op:create_plan params: { title: "My Plan", objective: "Do something", scope: { included: [] } }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const scopeError = result.errors.find(
+      (e) => e.op === 'create_plan' && e.message.includes('scope'),
+    );
+    expect(scopeError).toBeDefined();
+    expect(scopeError!.message).toContain('Expected string');
+  });
+
+  it('returns structured error objects with required fields', () => {
+    addSkill(
+      skillsDir,
+      'structured-error-skill',
+      `# Structured Error Skill
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+
+    if (result.errors.length > 0) {
+      const err = result.errors[0];
+      expect(err).toHaveProperty('file');
+      expect(err).toHaveProperty('op');
+      expect(err).toHaveProperty('message');
+      expect(typeof err.file).toBe('string');
+      expect(typeof err.op).toBe('string');
+      expect(typeof err.message).toBe('string');
+    }
+  });
+
+  it('includes the file path and op name in each error', () => {
+    addSkill(
+      skillsDir,
+      'named-skill',
+      `# Named Skill
+
+\`\`\`
+YOUR_AGENT_core op:capture_knowledge params: { entries: [{ type: "pattern", domain: "testing", title: "Test", description: "A test", severity: "suggestion" }] }
+\`\`\`
+`,
+    );
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.errors.length).toBeGreaterThan(0);
+
+    const err = result.errors[0];
+    expect(err.file).toContain('named-skill');
+    expect(err.op).toBe('capture_knowledge');
+  });
+
+  it('builds a non-empty schema registry', () => {
+    const result = validateSkillDocs(skillsDir);
+    expect(result.registrySize).toBeGreaterThan(50);
+  });
+
+  it('handles a skills directory that does not exist', () => {
+    const nonExistentDir = join(skillsDir, 'does-not-exist');
+    const result = validateSkillDocs(nonExistentDir);
+    expect(result.valid).toBe(true);
+    expect(result.totalFiles).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('counts multiple skill files correctly', () => {
+    addSkill(
+      skillsDir,
+      'skill-one',
+      `# Skill One\n\n\`\`\`\nYOUR_AGENT_core op:capture_quick params: { title: "Test", content: "Content" }\n\`\`\`\n`,
+    );
+    addSkill(skillsDir, 'skill-two', `# Skill Two\n\nNo examples here.\n`);
+
+    const result = validateSkillDocs(skillsDir);
+    expect(result.totalFiles).toBe(2);
+  });
+});