@soleri/core 9.3.0 → 9.4.0

package/src/runtime/orchestrate-ops.ts

@@ -9,6 +9,8 @@
  *   - orchestrate_quick_capture: one-call knowledge capture without full planning
  */
 
+import fs from 'node:fs';
+import path from 'node:path';
 import { z } from 'zod';
 import type { OpDefinition, FacadeConfig } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
@@ -18,6 +20,7 @@ import { createDispatcher } from '../flows/dispatch-registry.js';
 import { runEpilogue } from '../flows/epilogue.js';
 import type { OrchestrationPlan, ExecutionResult } from '../flows/types.js';
 import type { ContextHealthStatus } from './context-health.js';
+import type { OperatorSignals } from '../operator/operator-context-types.js';
 import {
   detectGitHubContext,
   findMatchingMilestone,
@@ -472,7 +475,10 @@ export function createOrchestrateOps(
         'end brain session, and clean up.',
       auth: 'write',
       schema: z.object({
-        planId: z.string().describe('ID of the executing plan to complete'),
+        planId: z
+          .string()
+          .optional()
+          .describe('ID of the executing plan to complete (optional for direct tasks)'),
         sessionId: z.string().describe('ID of the brain session to end'),
         outcome: z
           .enum(['completed', 'abandoned', 'partial'])
@@ -495,9 +501,51 @@ export function createOrchestrateOps(
           .optional()
           .default(false)
           .describe('Set true to bypass rationalization gate and impact warnings after review'),
+        operatorSignals: z
+          .object({
+            expertise: z
+              .array(
+                z.object({
+                  topic: z.string(),
+                  level: z.enum(['learning', 'intermediate', 'expert']),
+                  evidence: z.string().optional(),
+                  confidence: z.number().min(0).max(1).optional(),
+                }),
+              )
+              .default([]),
+            corrections: z
+              .array(
+                z.object({
+                  rule: z.string(),
+                  quote: z.string().optional(),
+                  scope: z.enum(['global', 'project']).default('global'),
+                }),
+              )
+              .default([]),
+            interests: z
+              .array(
+                z.object({
+                  tag: z.string(),
+                  context: z.string().optional(),
+                }),
+              )
+              .default([]),
+            patterns: z
+              .array(
+                z.object({
+                  pattern: z.string(),
+                  frequency: z.enum(['once', 'occasional', 'frequent']).optional(),
+                }),
+              )
+              .default([]),
+          })
+          .default({})
+          .describe(
+            'Your silent assessment of the operator this session. Fill what you observed, empty arrays for what you did not. Never announce this to the operator.',
+          ),
       }),
       handler: async (params) => {
-        const planId = params.planId as string;
+        const planId = params.planId as string | undefined;
         const sessionId = params.sessionId as string;
         const outcome = (params.outcome as string) ?? 'completed';
         const completionSummary = (params.summary as string) ?? '';
@@ -505,20 +553,26 @@ export function createOrchestrateOps(
         const filesModified = (params.filesModified as string[]) ?? [];
         const overrideRationalization = (params.overrideRationalization as boolean) ?? false;
 
-        // Anti-rationalization gate: check completion summary before completing
-        if (outcome === 'completed' && !overrideRationalization) {
-          const criteria = collectAcceptanceCriteria(planner, planId);
-          if (criteria.length > 0 && completionSummary) {
-            const report = detectRationalizations(criteria, completionSummary);
-            if (report.detected) {
-              captureRationalizationAntiPattern(vault, report);
-              return {
-                blocked: true,
-                reason: 'Rationalization language detected in completion summary',
-                rationalization: report,
-                hint: 'Address the unmet criteria, or set overrideRationalization: true to bypass this gate.',
-              };
-            }
+        // Look up plan — optional for direct tasks that skipped planning
+        const planObj = planId ? planner.get(planId) : null;
+
+        // Anti-rationalization gate: only if we have acceptance criteria from a plan
+        const criteria = planObj && planId ? collectAcceptanceCriteria(planner, planId) : [];
+        if (
+          outcome === 'completed' &&
+          criteria.length > 0 &&
+          completionSummary &&
+          !overrideRationalization
+        ) {
+          const report = detectRationalizations(criteria, completionSummary);
+          if (report.detected) {
+            captureRationalizationAntiPattern(vault, report);
+            return {
+              blocked: true,
+              reason: 'Rationalization language detected in completion summary',
+              rationalization: report,
+              hint: 'Address the unmet criteria, or set overrideRationalization: true to bypass this gate.',
+            };
           }
         }
 
@@ -527,7 +581,6 @@ export function createOrchestrateOps(
         if (filesModified.length > 0) {
           try {
             const analyzer = new ImpactAnalyzer();
-            const planObj = planner.get(planId);
             const scopeHints = planObj?.scope ? [planObj.scope] : undefined;
             impactReport = analyzer.analyzeImpact(
               filesModified,
@@ -549,10 +602,31 @@ export function createOrchestrateOps(
           }
         }
 
-        // Complete the planner plan (legacy lifecycle)
-        const plan = planner.complete(planId);
+        // Complete the planner plan (legacy lifecycle) — best-effort
+        // The epilogue (brain session, knowledge extraction, flow epilogue) MUST run
+        // even if plan transition fails (e.g. already completed, missing, invalid state).
+        const warnings: string[] = [];
+        let completedPlan;
+        if (planObj && planId) {
+          try {
+            completedPlan = planner.complete(planId);
+          } catch (err) {
+            warnings.push(`Plan transition skipped: ${(err as Error).message}`);
+            completedPlan = {
+              id: planId,
+              status: planObj.status ?? 'completed',
+              objective: planObj.objective ?? (completionSummary || 'Direct execution'),
+            };
+          }
+        } else {
+          completedPlan = {
+            id: planId ?? `direct-${Date.now()}`,
+            status: 'completed',
+            objective: completionSummary || 'Direct execution',
+          };
+        }
 
-        // End brain session
+        // End brain session — runs regardless of plan existence
         const session = brainIntelligence.lifecycle({
           action: 'end',
           sessionId,
@@ -562,7 +636,7 @@ export function createOrchestrateOps(
           filesModified,
         });
 
-        // Extract knowledge
+        // Extract knowledge — runs regardless of plan existence
         let extraction = null;
         try {
           extraction = brainIntelligence.extractKnowledge(sessionId);
@@ -572,31 +646,49 @@ export function createOrchestrateOps(
 
         // Run flow-engine epilogue if we have a flow plan
         let epilogueResult = null;
-        const entry = planStore.get(planId);
-        if (entry) {
-          try {
-            const dispatch = buildDispatch(agentId, runtime, facades);
-            const summary = `${outcome}: ${entry.plan.summary}. Tools: ${toolsUsed.join(', ') || 'none'}. Files: ${filesModified.join(', ') || 'none'}.`;
-            epilogueResult = await runEpilogue(
-              dispatch,
-              entry.plan.context.probes,
-              entry.plan.context.projectPath,
-              summary,
-            );
-          } catch {
-            // Epilogue is best-effort
+        if (planId) {
+          const entry = planStore.get(planId);
+          if (entry) {
+            try {
+              const dispatch = buildDispatch(agentId, runtime, facades);
+              const summary = `${outcome}: ${entry.plan.summary}. Tools: ${toolsUsed.join(', ') || 'none'}. Files: ${filesModified.join(', ') || 'none'}.`;
+              epilogueResult = await runEpilogue(
+                dispatch,
+                entry.plan.context.probes,
+                entry.plan.context.projectPath,
+                summary,
+              );
+            } catch {
+              // Epilogue is best-effort
+            }
+
+            // Clean up plan store
+            planStore.delete(planId);
           }
+        }
 
-          // Clean up plan store
-          planStore.delete(planId);
+        // Compound operator signals (silent learning)
+        const signals = params.operatorSignals as OperatorSignals | undefined;
+        if (signals && runtime.operatorContextStore) {
+          runtime.operatorContextStore.compoundSignals(signals, sessionId);
+
+          // Re-render operator context file if profile drifted
+          const agentDir = runtime.config.agentDir;
+          if (runtime.operatorContextStore.hasDrifted() && agentDir) {
+            const content = runtime.operatorContextStore.renderContextFile();
+            const contextPath = path.join(agentDir, 'instructions', 'operator-context.md');
+            fs.mkdirSync(path.dirname(contextPath), { recursive: true });
+            fs.writeFileSync(contextPath, content, 'utf-8');
+          }
         }
 
         return {
-          plan,
+          plan: completedPlan,
           session,
           extraction,
           epilogue: epilogueResult,
           ...(impactReport ? { impactAnalysis: impactReport } : {}),
+          ...(warnings.length > 0 ? { warnings } : {}),
         };
       },
     },

package/src/runtime/plan-feedback-helper.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi } from 'vitest';
+import { recordPlanFeedback } from './plan-feedback-helper.js';
+
+// ─── Mock Factories ───────────────────────────────────────────────────
+
+function makeBrain() {
+  return {
+    recordFeedback: vi.fn(),
+  };
+}
+
+function makeBrainIntelligence() {
+  return {
+    maybeAutoBuildOnFeedback: vi.fn(),
+  };
+}
+
+function makePlan(decisions: (string | { decision: string })[] = []) {
+  return {
+    objective: 'Test objective',
+    decisions,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────
+
+describe('recordPlanFeedback', () => {
+  it('should extract entryIds from decision strings and record feedback', () => {
+    const brain = makeBrain();
+    const intelligence = makeBrainIntelligence();
+    const plan = makePlan([
+      'Brain pattern: TDD (strength: 52.5) [entryId:method-tdd-123]',
+      'Brain pattern: Vault hooks (strength: 87.5) [entryId:arch-vault-456]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown, intelligence as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'method-tdd-123',
+      'accepted',
+    );
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'arch-vault-456',
+      'accepted',
+    );
+    expect(intelligence.maybeAutoBuildOnFeedback).toHaveBeenCalledOnce();
+  });
+
+  it('should handle decision objects with .decision property', () => {
+    const brain = makeBrain();
+    const plan = makePlan([{ decision: 'Use vault pattern [entryId:obj-entry-1]' }]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'obj-entry-1', 'accepted');
+  });
+
+  it('should skip decisions without entryId markers', () => {
+    const brain = makeBrain();
+    const plan = makePlan([
+      'Brain pattern: TDD (strength: 52.5)',
+      'Some decision without an entry ID',
+      'Brain pattern: Vault hooks (strength: 87.5) [entryId:arch-vault-456]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'arch-vault-456',
+      'accepted',
+    );
+  });
+
+  it('should skip malformed entryId markers gracefully', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Brain pattern: X [entryId:]', 'Brain pattern: Y [entryId:valid-id]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    // [entryId:] won't match because the regex requires at least one char after :
+    // Actually the regex [^\]]+ requires 1+ chars, so empty entryId won't match
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'valid-id', 'accepted');
+  });
+
+  it('should not double-record duplicate entryIds', () => {
+    const brain = makeBrain();
+    const plan = makePlan([
+      'Decision 1 [entryId:same-entry]',
+      'Decision 2 [entryId:same-entry]',
+      'Decision 3 [entryId:different-entry]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'same-entry', 'accepted');
+    expect(brain.recordFeedback).toHaveBeenCalledWith(
+      'Test objective',
+      'different-entry',
+      'accepted',
+    );
+  });
+
+  it('should gracefully handle recordFeedback throwing', () => {
+    const brain = makeBrain();
+    brain.recordFeedback.mockImplementationOnce(() => {
+      throw new Error('Entry not found');
+    });
+    const plan = makePlan([
+      'Decision 1 [entryId:missing-entry]',
+      'Decision 2 [entryId:valid-entry]',
+    ]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    // First one throws, second succeeds
+    expect(count).toBe(1);
+    expect(brain.recordFeedback).toHaveBeenCalledTimes(2);
+  });
+
+  it('should return 0 and not call maybeAutoBuild when no entryIds found', () => {
+    const brain = makeBrain();
+    const intelligence = makeBrainIntelligence();
+    const plan = makePlan(['Decision without markers', 'Another plain decision']);
+
+    const count = recordPlanFeedback(plan, brain as unknown, intelligence as unknown);
+
+    expect(count).toBe(0);
+    expect(brain.recordFeedback).not.toHaveBeenCalled();
+    expect(intelligence.maybeAutoBuildOnFeedback).not.toHaveBeenCalled();
+  });
+
+  it('should handle empty decisions array', () => {
+    const brain = makeBrain();
+    const plan = makePlan([]);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(0);
+    expect(brain.recordFeedback).not.toHaveBeenCalled();
+  });
+
+  it('should work without brainIntelligence (optional param)', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Decision [entryId:entry-1]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(1);
+    // No error thrown despite missing brainIntelligence
+  });
+
+  it('should extract multiple entryIds from a single decision string', () => {
+    const brain = makeBrain();
+    const plan = makePlan(['Combined: [entryId:first-entry] and also [entryId:second-entry]']);
+
+    const count = recordPlanFeedback(plan, brain as unknown);
+
+    expect(count).toBe(2);
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'first-entry', 'accepted');
+    expect(brain.recordFeedback).toHaveBeenCalledWith('Test objective', 'second-entry', 'accepted');
+  });
+});

package/src/runtime/plan-feedback-helper.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared helper for recording brain feedback from plan decisions and context.
+ *
+ * Used by both plan_complete_lifecycle (planning-extra-ops.ts) and
+ * orchestrate_complete (orchestrate-ops.ts) to close the brain learning loop.
+ */
+
+import type { Brain } from '../brain/brain.js';
+import type { BrainIntelligence } from '../brain/intelligence.js';
+
+/** Regex to extract vault entry IDs embedded in decision/context strings. */
+const ENTRY_ID_REGEX = /\[entryId:([^\]]+)\]/g;
+
+/**
+ * Extract entry IDs from an array of decision or context strings,
+ * record positive feedback for each, and optionally trigger auto-rebuild.
+ *
+ * @returns Number of feedback entries recorded.
+ */
+export function recordPlanFeedback(
+  plan: { objective: string; decisions: (string | { decision: string })[] },
+  brain: Brain,
+  brainIntelligence?: BrainIntelligence,
+): number {
+  let feedbackRecorded = 0;
+  const seen = new Set<string>();
+
+  // Collect all strings to scan: decisions + any context strings
+  const strings: string[] = [];
+
+  for (const d of plan.decisions) {
+    const str = typeof d === 'string' ? d : d.decision;
+    strings.push(str);
+  }
+
+  for (const str of strings) {
+    // Use matchAll to find all entryId markers in each string
+    for (const match of str.matchAll(ENTRY_ID_REGEX)) {
+      const entryId = match[1];
+      // Skip duplicates within the same plan
+      if (seen.has(entryId)) continue;
+      seen.add(entryId);
+
+      try {
+        brain.recordFeedback(plan.objective, entryId, 'accepted');
+        feedbackRecorded++;
+      } catch {
+        // Graceful degradation — skip if entry not found or already recorded
+      }
+    }
+  }
+
+  // Trigger auto-rebuild check after recording feedback
+  if (feedbackRecorded > 0 && brainIntelligence) {
+    try {
+      brainIntelligence.maybeAutoBuildOnFeedback();
+    } catch {
+      // Auto-rebuild is best-effort
+    }
+  }
+
+  return feedbackRecorded;
+}

package/src/runtime/planning-extra-ops.test.ts

@@ -69,7 +69,7 @@ function createMockRuntime(): AgentRuntime {
 
   return {
     planner: {
-      iterate: vi.fn(() => plan),
+      iterate: vi.fn(() => ({ plan, mutated: 1 })),
       splitTasks: vi.fn(() => ({
         ...plan,
         tasks: [plan.tasks[0], { id: 'task-2', title: 'Task 2' }],
@@ -159,6 +159,48 @@ describe('createPlanningExtraOps', () => {
       );
     });
 
+    it('returns iterated: false when no changes detected', async () => {
+      vi.mocked(runtime.planner.iterate).mockReturnValue({
+        plan: makePlan() as unknown,
+        mutated: 0,
+      } as unknown);
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(false);
+      expect(result.reason).toBe('no changes detected');
+    });
+
+    it('passes alternatives to planner.iterate', async () => {
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+        alternatives: [
+          { approach: 'Alt A', pros: ['fast'], cons: ['fragile'], rejected_reason: 'Too risky' },
+        ],
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(true);
+      expect(runtime.planner.iterate).toHaveBeenCalledWith(
+        'plan-1',
+        expect.objectContaining({
+          alternatives: [expect.objectContaining({ approach: 'Alt A' })],
+        }),
+      );
+    });
+
+    it('passes decisions to planner.iterate', async () => {
+      const result = (await findOp(ops, 'plan_iterate').handler({
+        planId: 'plan-1',
+        decisions: [{ decision: 'Use FTS5', rationale: 'Performance' }],
+      })) as Record<string, unknown>;
+      expect(result.iterated).toBe(true);
+      expect(runtime.planner.iterate).toHaveBeenCalledWith(
+        'plan-1',
+        expect.objectContaining({
+          decisions: [{ decision: 'Use FTS5', rationale: 'Performance' }],
+        }),
+      );
+    });
+
     it('returns error on failure', async () => {
       vi.mocked(runtime.planner.iterate).mockImplementation(() => {
         throw new Error('Not a draft');