@soleri/core 9.0.4 → 9.2.0

package/src/runtime/facades/plan-facade.test.ts

@@ -0,0 +1,266 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Vault } from '../../vault/vault.js';
+import { Planner } from '../../planning/planner.js';
+import { Brain } from '../../brain/brain.js';
+import { BrainIntelligence } from '../../brain/intelligence.js';
+import { Curator } from '../../curator/curator.js';
+import { ChainRunner } from '../../flows/chain-runner.js';
+import { createPlanFacadeOps } from './plan-facade.js';
+import { captureOps, executeOp } from '../../engine/test-helpers.js';
+import type { CapturedOp } from '../../engine/test-helpers.js';
+import type { AgentRuntime } from '../types.js';
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function makeRuntime(vault: Vault): AgentRuntime {
+  const brain = new Brain(vault);
+  const plansPath = join(tmpdir(), `plan-test-${Date.now()}.json`);
+  const planner = new Planner(plansPath);
+  const brainIntelligence = new BrainIntelligence(vault, brain);
+  const curator = new Curator(vault, brain);
+  const linkManager = null;
+  const chainRunner = new ChainRunner(vault.getProvider());
+  return {
+    vault, planner, brain, brainIntelligence, curator, linkManager, chainRunner,
+  } as unknown as AgentRuntime;
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────
+
+describe('plan-facade', () => {
+  let vault: Vault;
+  let ops: Map<string, CapturedOp>;
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+    ops = captureOps(createPlanFacadeOps(makeRuntime(vault)));
+  });
+
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('registers base + extra + grading + chain ops', () => {
+    // 5 base + 22 extra + 5 grading + 5 chain = 37
+    expect(ops.size).toBeGreaterThanOrEqual(32);
+    expect([...ops.keys()]).toContain('create_plan');
+    expect([...ops.keys()]).toContain('get_plan');
+    expect([...ops.keys()]).toContain('approve_plan');
+    expect([...ops.keys()]).toContain('update_task');
+    expect([...ops.keys()]).toContain('complete_plan');
+    expect([...ops.keys()]).toContain('plan_grade');
+    expect([...ops.keys()]).toContain('chain_execute');
+  });
+
+  it('has correct auth levels for base ops', () => {
+    expect(ops.get('create_plan')!.auth).toBe('write');
+    expect(ops.get('get_plan')!.auth).toBe('read');
+    expect(ops.get('approve_plan')!.auth).toBe('write');
+    expect(ops.get('update_task')!.auth).toBe('write');
+    expect(ops.get('complete_plan')!.auth).toBe('write');
+  });
+
+  // ─── create_plan ───────────────────────────────────────────────
+
+  it('create_plan creates a draft plan', async () => {
+    const result = await executeOp(ops, 'create_plan', {
+      objective: 'Build auth module',
+      scope: 'packages/core/src/auth',
+    });
+    expect(result.success).toBe(true);
+    const data = result.data as { created: boolean; plan: Record<string, unknown> };
+    expect(data.created).toBe(true);
+    expect(data.plan.status).toBe('draft');
+    expect(data.plan.objective).toBe('Build auth module');
+  });
+
+  it('create_plan with tasks and decisions', async () => {
+    const result = await executeOp(ops, 'create_plan', {
+      objective: 'Refactor vault',
+      scope: 'vault module',
+      decisions: ['Use SQLite FTS5'],
+      tasks: [{ title: 'Add FTS5 index', description: 'Create FTS5 table' }],
+    });
+    expect(result.success).toBe(true);
+    const plan = (result.data as Record<string, unknown>).plan as Record<string, unknown>;
+    expect((plan.tasks as unknown[]).length).toBe(1);
+  });
+
+  // ─── get_plan ──────────────────────────────────────────────────
+
+  it('get_plan returns plan by ID', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Test', scope: 'test',
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    const result = await executeOp(ops, 'get_plan', { planId });
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).objective).toBe('Test');
+  });
+
+  it('get_plan lists all active plans when no ID', async () => {
+    await executeOp(ops, 'create_plan', { objective: 'A', scope: 'a' });
+    const result = await executeOp(ops, 'get_plan', {});
+    expect(result.success).toBe(true);
+    const data = result.data as { active: unknown[] };
+    expect(data.active.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('get_plan returns error for nonexistent plan', async () => {
+    const result = await executeOp(ops, 'get_plan', { planId: 'nonexistent' });
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).error).toContain('not found');
+  });
+
+  // ─── approve_plan ──────────────────────────────────────────────
+
+  it('approve_plan approves a draft plan', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Test approval',
+      scope: 'test',
+      decisions: ['decision 1', 'decision 2'],
+      tasks: [
+        { title: 'Task 1', description: 'desc 1' },
+        { title: 'Task 2', description: 'desc 2' },
+      ],
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+
+    const result = await executeOp(ops, 'approve_plan', { planId });
+    expect(result.success).toBe(true);
+    const data = result.data as { approved: boolean };
+    // May be rejected by grade gate — either outcome is valid
+    expect(typeof data.approved).toBe('boolean');
+  });
+
+  it('approve_plan with startExecution', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Test exec',
+      scope: 'test',
+      decisions: ['d1', 'd2', 'd3'],
+      tasks: [
+        { title: 'T1', description: 'd1' },
+        { title: 'T2', description: 'd2' },
+        { title: 'T3', description: 'd3' },
+      ],
+      alternatives: [
+        { approach: 'Alt A', pros: ['fast'], cons: ['fragile'], rejected_reason: 'Too risky' },
+        { approach: 'Alt B', pros: ['safe'], cons: ['slow'], rejected_reason: 'Too slow' },
+      ],
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+
+    const result = await executeOp(ops, 'approve_plan', { planId, startExecution: true });
+    expect(result.success).toBe(true);
+  });
+
+  // ─── update_task ───────────────────────────────────────────────
+
+  it('update_task changes task status', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Task update test',
+      scope: 'test',
+      decisions: ['d1', 'd2', 'd3'],
+      tasks: [{ title: 'Task 1', description: 'desc' }],
+      alternatives: [
+        { approach: 'Alt', pros: ['x'], cons: ['y'], rejected_reason: 'z' },
+        { approach: 'Alt2', pros: ['a'], cons: ['b'], rejected_reason: 'c' },
+      ],
+    });
+    const plan = (createResult.data as Record<string, unknown>).plan as Record<string, unknown>;
+    const planId = plan.id as string;
+    const taskId = ((plan.tasks as Array<Record<string, unknown>>)[0]).id as string;
+
+    // Approve and start execution first
+    await executeOp(ops, 'approve_plan', { planId, startExecution: true });
+
+    const result = await executeOp(ops, 'update_task', {
+      planId, taskId, status: 'completed',
+    });
+    expect(result.success).toBe(true);
+    const data = result.data as { updated: boolean };
+    expect(data.updated).toBe(true);
+  });
+
+  // ─── complete_plan ─────────────────────────────────────────────
+
+  it('complete_plan completes an executing plan', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Complete test',
+      scope: 'test',
+      decisions: ['d1', 'd2', 'd3'],
+      tasks: [{ title: 'T1', description: 'd1' }],
+      alternatives: [
+        { approach: 'A', pros: ['x'], cons: ['y'], rejected_reason: 'z' },
+        { approach: 'B', pros: ['a'], cons: ['b'], rejected_reason: 'c' },
+      ],
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+    await executeOp(ops, 'approve_plan', { planId, startExecution: true });
+
+    const result = await executeOp(ops, 'complete_plan', { planId });
+    expect(result.success).toBe(true);
+    const data = result.data as { completed: boolean; taskSummary: Record<string, number> };
+    expect(data.completed).toBe(true);
+    expect(data.taskSummary).toHaveProperty('total');
+  });
+
+  // ─── plan_iterate ──────────────────────────────────────────────
+
+  it('plan_iterate revises a draft plan', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Initial', scope: 'test',
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+
+    const result = await executeOp(ops, 'plan_iterate', {
+      planId, objective: 'Revised objective',
+    });
+    expect(result.success).toBe(true);
+    const data = result.data as { iterated?: boolean; error?: string };
+    expect(data.iterated).toBe(true);
+  });
+
+  // ─── plan_stats ────────────────────────────────────────────────
+
+  it('plan_stats returns statistics', async () => {
+    const result = await executeOp(ops, 'plan_stats', {});
+    expect(result.success).toBe(true);
+    expect(result.data).toHaveProperty('total');
+  });
+
+  // ─── plan_grade ────────────────────────────────────────────────
+
+  it('plan_grade grades a plan', async () => {
+    const createResult = await executeOp(ops, 'create_plan', {
+      objective: 'Grade test',
+      scope: 'test',
+      decisions: ['Use pattern X'],
+      tasks: [{ title: 'Task 1', description: 'desc' }],
+    });
+    const planId = ((createResult.data as Record<string, unknown>).plan as Record<string, unknown>).id as string;
+
+    const result = await executeOp(ops, 'plan_grade', { planId });
+    expect(result.success).toBe(true);
+    const data = result.data as { grade: string; score: number };
+    expect(data.grade).toBeDefined();
+    expect(data.score).toBeGreaterThanOrEqual(0);
+  });
+
+  // ─── chain_list ────────────────────────────────────────────────
+
+  it('chain_list returns empty initially', async () => {
+    const result = await executeOp(ops, 'chain_list', {});
+    expect(result.success).toBe(true);
+  });
+
+  // ─── chain_status ──────────────────────────────────────────────
+
+  it('chain_status returns error for unknown instance', async () => {
+    const result = await executeOp(ops, 'chain_status', { instanceId: 'nonexistent' });
+    expect(result.success).toBe(true);
+    expect((result.data as Record<string, unknown>).error).toContain('not found');
+  });
+});

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

@@ -9,6 +9,7 @@ import type { AgentRuntime } from '../types.js';
 import { createPlanningExtraOps } from '../planning-extra-ops.js';
 import { createGradingOps } from '../grading-ops.js';
 import { createChainOps } from '../chain-ops.js';
+import { PlanGradeRejectionError } from '../../planning/planner.js';
 
 export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
   const { planner } = runtime;
@@ -23,11 +24,22 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       schema: z.object({
         objective: z.string().describe('What the plan aims to achieve'),
         scope: z.string().describe('Which parts of the codebase are affected'),
-        decisions: z.array(z.string()).optional().default([]),
+        decisions: z.array(z.union([z.string(), z.object({ decision: z.string(), rationale: z.string() })])).optional().default([]),
         tasks: z
           .array(z.object({ title: z.string(), description: z.string() }))
           .optional()
           .default([]),
+        alternatives: z
+          .array(
+            z.object({
+              approach: z.string().describe('The alternative approach considered'),
+              pros: z.array(z.string()).describe('Advantages of this approach'),
+              cons: z.array(z.string()).describe('Disadvantages of this approach'),
+              rejected_reason: z.string().describe('Why this alternative was rejected'),
+            }),
+          )
+          .optional()
+          .describe('Rejected alternative approaches — plans with 2+ alternatives score higher'),
       }),
       handler: async (params) => {
         const plan = planner.create({
@@ -35,6 +47,7 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           scope: params.scope as string,
           decisions: (params.decisions as string[]) ?? [],
           tasks: (params.tasks as Array<{ title: string; description: string }>) ?? [],
+          alternatives: params.alternatives as Array<{ approach: string; pros: string[]; cons: string[]; rejected_reason: string }> | undefined,
         });
         return { created: true, plan };
       },
@@ -68,11 +81,33 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
           .describe('If true, immediately start execution after approval'),
       }),
       handler: async (params) => {
-        let plan = planner.approve(params.planId as string);
-        if (params.startExecution) {
-          plan = planner.startExecution(plan.id);
+        try {
+          let plan = planner.approve(params.planId as string);
+          if (params.startExecution) {
+            plan = planner.startExecution(plan.id);
+          }
+          return { approved: true, executing: plan.status === 'executing', plan };
+        } catch (err) {
+          if (err instanceof PlanGradeRejectionError) {
+            return {
+              approved: false,
+              error: 'grade_gate_rejection',
+              message: err.message,
+              grade: err.grade,
+              score: err.score,
+              minGrade: err.minGrade,
+              gaps: err.gaps.map((g) => ({
+                severity: g.severity,
+                category: g.category,
+                description: g.description,
+                recommendation: g.recommendation,
+              })),
+              recommendation:
+                'Iterate on the plan using `op:create_plan` to address the gaps above, then re-grade with `op:plan_grade` before approving.',
+            };
+          }
+          throw err;
         }
-        return { approved: true, executing: plan.status === 'executing', plan };
       },
     },
     {
@@ -96,7 +131,8 @@ export function createPlanFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     },
     {
       name: 'complete_plan',
-      description: 'Mark an executing plan as completed.',
+      description:
+        'Mark a reconciled plan as completed. If the plan is still executing, it will be auto-reconciled first. Use `plan_reconcile` to provide a detailed drift report before completing.',
       auth: 'write',
       schema: z.object({
         planId: z.string(),

package/src/runtime/facades/review-facade.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createReviewFacadeOps } from './review-facade.js';
+import type { AgentRuntime } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Mock runtime
+// ---------------------------------------------------------------------------
+
+function mockRuntime(): AgentRuntime {
+  return {
+    config: { agentId: 'test-agent' },
+    knowledgeReview: {
+      submit: vi.fn().mockReturnValue({ entryId: 'e1', status: 'pending_review' }),
+      approve: vi.fn().mockReturnValue({ entryId: 'e1', status: 'approved' }),
+      reject: vi.fn().mockReturnValue({ entryId: 'e1', status: 'rejected' }),
+      listPending: vi.fn().mockReturnValue([]),
+      stats: vi.fn().mockReturnValue({ pending: 0, approved: 5, rejected: 1 }),
+    },
+  } as unknown as AgentRuntime;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createReviewFacadeOps', () => {
+  let ops: ReturnType<typeof createReviewFacadeOps>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    ops = createReviewFacadeOps(mockRuntime());
+  });
+
+  it('returns 5 ops matching review-ops', () => {
+    expect(ops.length).toBe(5);
+  });
+
+  it('includes all expected op names', () => {
+    const names = ops.map((o) => o.name);
+    expect(names).toContain('vault_submit_review');
+    expect(names).toContain('vault_approve');
+    expect(names).toContain('vault_reject');
+    expect(names).toContain('vault_pending_reviews');
+    expect(names).toContain('vault_review_stats');
+  });
+
+  it('all ops have required fields', () => {
+    for (const op of ops) {
+      expect(op.name).toBeDefined();
+      expect(op.description).toBeDefined();
+      expect(op.auth).toBeDefined();
+      expect(typeof op.handler).toBe('function');
+    }
+  });
+
+  it('approve and reject require admin auth', () => {
+    const approveOp = ops.find((o) => o.name === 'vault_approve');
+    const rejectOp = ops.find((o) => o.name === 'vault_reject');
+    expect(approveOp!.auth).toBe('admin');
+    expect(rejectOp!.auth).toBe('admin');
+  });
+
+  it('submit uses write auth', () => {
+    const op = ops.find((o) => o.name === 'vault_submit_review');
+    expect(op!.auth).toBe('write');
+  });
+
+  it('pending_reviews and review_stats use read auth', () => {
+    const pending = ops.find((o) => o.name === 'vault_pending_reviews');
+    const stats = ops.find((o) => o.name === 'vault_review_stats');
+    expect(pending!.auth).toBe('read');
+    expect(stats!.auth).toBe('read');
+  });
+
+  it('handlers are callable', async () => {
+    const rt = mockRuntime();
+    const rtOps = createReviewFacadeOps(rt);
+    const submitOp = rtOps.find((o) => o.name === 'vault_submit_review')!;
+    const result = (await submitOp.handler({ entryId: 'e1' })) as Record<string, unknown>;
+    expect(result.status).toBe('pending_review');
+  });
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Review facade — knowledge review workflow.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createReviewOps } from '../review-ops.js';
+
+export function createReviewFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return [...createReviewOps(runtime)];
+}

package/src/runtime/facades/sync-facade.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createSyncFacadeOps } from './sync-facade.js';
+import type { AgentRuntime } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Mocks (same as sync-ops — facade delegates to createSyncOps)
+// ---------------------------------------------------------------------------
+
+vi.mock('../../vault/git-vault-sync.js', () => ({
+  GitVaultSync: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this.init = vi.fn().mockResolvedValue(undefined);
+    this.syncAll = vi.fn().mockResolvedValue({ pushed: 5 });
+    this.pull = vi.fn().mockResolvedValue({ imported: 3, conflicts: 0 });
+    this.sync = vi.fn().mockResolvedValue({ pushed: 2, pulled: 1 });
+  }),
+}));
+
+vi.mock('../../vault/linking.js', () => ({
+  LinkManager: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this.getAllLinksForEntries = vi.fn().mockReturnValue([]);
+    this.addLink = vi.fn();
+  }),
+}));
+
+vi.mock('../../vault/obsidian-sync.js', () => ({
+  ObsidianSync: vi.fn().mockImplementation(function (this: Record<string, unknown>) {
+    this.export = vi.fn().mockResolvedValue({ exported: 10 });
+    this.import = vi.fn().mockResolvedValue({ imported: 5 });
+    this.sync = vi.fn().mockResolvedValue({ pushed: 3, pulled: 2 });
+  }),
+}));
+
+// ---------------------------------------------------------------------------
+// Mock runtime
+// ---------------------------------------------------------------------------
+
+function mockRuntime(): AgentRuntime {
+  return {
+    config: { agentId: 'test-agent' },
+    vault: {
+      get: vi.fn(),
+      seed: vi.fn(),
+      seedDedup: vi.fn().mockReturnValue([]),
+      list: vi.fn().mockReturnValue([]),
+      exportAll: vi.fn().mockReturnValue({ entries: [] }),
+      getProvider: vi.fn().mockReturnValue({
+        all: vi.fn().mockReturnValue([]),
+        get: vi.fn(),
+        run: vi.fn(),
+      }),
+    },
+  } as unknown as AgentRuntime;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('createSyncFacadeOps', () => {
+  let ops: ReturnType<typeof createSyncFacadeOps>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    ops = createSyncFacadeOps(mockRuntime());
+  });
+
+  it('returns 8 ops matching sync-ops', () => {
+    expect(ops.length).toBe(8);
+  });
+
+  it('includes all expected op names', () => {
+    const names = ops.map((o) => o.name);
+    expect(names).toContain('vault_git_push');
+    expect(names).toContain('vault_git_pull');
+    expect(names).toContain('vault_git_sync');
+    expect(names).toContain('obsidian_export');
+    expect(names).toContain('obsidian_import');
+    expect(names).toContain('obsidian_sync');
+    expect(names).toContain('vault_export_pack');
+    expect(names).toContain('vault_import_pack');
+  });
+
+  it('all ops have required fields', () => {
+    for (const op of ops) {
+      expect(op.name).toBeDefined();
+      expect(op.description).toBeDefined();
+      expect(op.auth).toBeDefined();
+      expect(typeof op.handler).toBe('function');
+    }
+  });
+
+  it('git ops use write auth', () => {
+    const gitOps = ops.filter((o) => o.name.startsWith('vault_git_'));
+    for (const op of gitOps) {
+      expect(op.auth).toBe('write');
+    }
+  });
+
+  it('obsidian_export uses read auth', () => {
+    const op = ops.find((o) => o.name === 'obsidian_export');
+    expect(op!.auth).toBe('read');
+  });
+
+  it('vault_export_pack uses read auth', () => {
+    const op = ops.find((o) => o.name === 'vault_export_pack');
+    expect(op!.auth).toBe('read');
+  });
+
+  it('vault_import_pack uses write auth', () => {
+    const op = ops.find((o) => o.name === 'vault_import_pack');
+    expect(op!.auth).toBe('write');
+  });
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Sync facade — git, Obsidian, and pack sync operations.
+ */
+
+import type { OpDefinition } from '../../facades/types.js';
+import type { AgentRuntime } from '../types.js';
+import { createSyncOps } from '../sync-ops.js';
+
+export function createSyncFacadeOps(runtime: AgentRuntime): OpDefinition[] {
+  return [...createSyncOps(runtime)];
+}