@soleri/core 9.4.0 → 9.5.0

package/src/runtime/curator-extra-ops.ts

@@ -10,9 +10,18 @@ import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 
 export function createCuratorExtraOps(runtime: AgentRuntime): OpDefinition[] {
-  const { curator, jobQueue, pipelineRunner } = runtime;
+  const { curator, jobQueue, pipelineRunner, shutdownRegistry } = runtime;
   let consolidationInterval: ReturnType<typeof setInterval> | null = null;
 
+  // Register cleanup for any consolidation interval started during this session
+  shutdownRegistry.register('curatorConsolidation', () => {
+    if (consolidationInterval) {
+      clearInterval(consolidationInterval);
+      consolidationInterval = null;
+    }
+    pipelineRunner.stop();
+  });
+
   return [
     // ─── Entry History ──────────────────────────────────────────────
     {

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

@@ -30,6 +30,13 @@ function mockRuntime(): AgentRuntime {
       start: vi.fn(),
       stop: vi.fn(),
     },
+    shutdownRegistry: {
+      register: vi.fn(),
+      closeAll: vi.fn(),
+      closeAllSync: vi.fn(),
+      size: 0,
+      isClosed: false,
+    },
   } as unknown as AgentRuntime;
 }
 

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

@@ -195,6 +195,193 @@ export function createMemoryFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       },
     },
 
+    // ─── Handoff ────────────────────────────────────────────────
+    {
+      name: 'handoff_generate',
+      description:
+        'Generate a structured handoff document for context transitions. ' +
+        'Pulls from active plan (if any) and recent session memories to produce ' +
+        'a markdown document that can bootstrap a new context window. ' +
+        'Ephemeral — NOT persisted to vault.',
+      auth: 'read',
+      schema: z.object({
+        projectPath: z
+          .string()
+          .optional()
+          .default('.')
+          .describe('Project path for filtering memories'),
+        sessionLimit: z
+          .number()
+          .optional()
+          .default(3)
+          .describe('Number of recent session memories to include'),
+      }),
+      handler: async (params) => {
+        const { planner } = runtime;
+        const projectPath = params.projectPath as string;
+        const sessionLimit = (params.sessionLimit as number) ?? 3;
+
+        const sections: string[] = [];
+        const now = new Date().toISOString();
+
+        sections.push('# Handoff Document');
+        sections.push('');
+        sections.push(`Generated: ${now}`);
+        sections.push('');
+
+        // ─── Active Plan Context ───────────────────────────
+        const activePlans = planner.getActive();
+        if (activePlans.length > 0) {
+          const plan = activePlans[0]; // Most relevant active plan
+          sections.push('## Active Plan');
+          sections.push('');
+          sections.push(`| Field | Value |`);
+          sections.push(`|-------|-------|`);
+          sections.push(`| **Plan ID** | ${plan.id} |`);
+          sections.push(`| **Objective** | ${plan.objective} |`);
+          sections.push(`| **Status** | ${plan.status} |`);
+          sections.push(`| **Scope** | ${plan.scope} |`);
+          sections.push('');
+
+          // Decisions
+          if (plan.decisions.length > 0) {
+            sections.push('### Decisions');
+            sections.push('');
+            for (const d of plan.decisions) {
+              if (typeof d === 'string') {
+                sections.push(`- ${d}`);
+              } else {
+                sections.push(`- **${d.decision}** — ${d.rationale}`);
+              }
+            }
+            sections.push('');
+          }
+
+          // Task status summary
+          if (plan.tasks.length > 0) {
+            sections.push('### Tasks');
+            sections.push('');
+            sections.push('| # | Task | Status |');
+            sections.push('|---|------|--------|');
+            for (let i = 0; i < plan.tasks.length; i++) {
+              const t = plan.tasks[i];
+              sections.push(`| ${i + 1} | ${t.title} | ${t.status} |`);
+            }
+            sections.push('');
+          }
+
+          // Approach
+          if (plan.approach) {
+            sections.push('### Approach');
+            sections.push('');
+            sections.push(plan.approach);
+            sections.push('');
+          }
+
+          // Additional active plans (just IDs)
+          if (activePlans.length > 1) {
+            sections.push('### Other Active Plans');
+            sections.push('');
+            for (let i = 1; i < activePlans.length; i++) {
+              const p = activePlans[i];
+              sections.push(`- **${p.id}**: ${p.objective} (${p.status})`);
+            }
+            sections.push('');
+          }
+        } else {
+          sections.push('## Active Plan');
+          sections.push('');
+          sections.push('No active plans.');
+          sections.push('');
+        }
+
+        // ─── Recent Session Context ────────────────────────
+        const recentSessions = vault.listMemories({
+          type: 'session',
+          projectPath,
+          limit: sessionLimit,
+        });
+
+        if (recentSessions.length > 0) {
+          sections.push('## Recent Sessions');
+          sections.push('');
+          for (const session of recentSessions) {
+            sections.push(`### ${session.createdAt}`);
+            sections.push('');
+            if (session.summary) {
+              sections.push(session.summary);
+              sections.push('');
+            }
+            if (session.nextSteps && session.nextSteps.length > 0) {
+              sections.push('**Next steps:**');
+              for (const step of session.nextSteps) {
+                sections.push(`- ${step}`);
+              }
+              sections.push('');
+            }
+            if (session.decisions && session.decisions.length > 0) {
+              sections.push('**Decisions:**');
+              for (const d of session.decisions) {
+                sections.push(`- ${d}`);
+              }
+              sections.push('');
+            }
+            if (session.filesModified && session.filesModified.length > 0) {
+              sections.push(`**Files modified:** ${session.filesModified.join(', ')}`);
+              sections.push('');
+            }
+          }
+        } else {
+          sections.push('## Recent Sessions');
+          sections.push('');
+          sections.push('No recent session memories found.');
+          sections.push('');
+        }
+
+        // ─── Resumption Hints ──────────────────────────────
+        sections.push('## Resumption');
+        sections.push('');
+        sections.push('Use this document to restore context after a context window transition.');
+        sections.push('');
+        if (activePlans.length > 0) {
+          const plan = activePlans[0];
+          const pendingTasks = plan.tasks.filter(
+            (t) => t.status === 'pending' || t.status === 'in_progress',
+          );
+          if (pendingTasks.length > 0) {
+            sections.push('**Immediate next actions:**');
+            for (const t of pendingTasks.slice(0, 5)) {
+              sections.push(
+                `- ${t.status === 'in_progress' ? '[IN PROGRESS]' : '[PENDING]'} ${t.title}`,
+              );
+            }
+            sections.push('');
+          }
+          if (plan.status === 'executing') {
+            sections.push(
+              '> Plan is in `executing` state. Continue with pending tasks or call `op:plan_reconcile` if complete.',
+            );
+          } else if (plan.status === 'reconciling') {
+            sections.push(
+              '> Plan is in `reconciling` state. Call `op:plan_complete_lifecycle` to finalize.',
+            );
+          }
+        }
+
+        const markdown = sections.join('\n');
+
+        return {
+          handoff: markdown,
+          meta: {
+            activePlanCount: activePlans.length,
+            activePlanId: activePlans.length > 0 ? activePlans[0].id : null,
+            recentSessionCount: recentSessions.length,
+            generatedAt: now,
+          },
+        };
+      },
+    },
+
     // ─── Satellite ops ───────────────────────────────────────────
     ...createMemoryExtraOps(runtime),
     ...createMemoryCrossProjectOps(runtime),

package/src/runtime/orchestrate-ops.ts

@@ -847,7 +847,7 @@ export function createOrchestrateOps(
         }
 
         // 2. Detect GitHub context
-        const ctx = detectGitHubContext(projectPath);
+        const ctx = await detectGitHubContext(projectPath);
         if (!ctx) {
           return {
             status: 'skipped',
@@ -885,7 +885,7 @@ export function createOrchestrateOps(
             };
           }
 
-          const updated = updateGitHubIssueBody(ctx.repo, linkToIssue, body);
+          const updated = await updateGitHubIssueBody(ctx.repo, linkToIssue, body);
           if (!updated) {
             return {
               status: 'error',
@@ -949,7 +949,7 @@ export function createOrchestrateOps(
             continue;
           }
 
-          const issueNumber = createGitHubIssue(ctx.repo, task.title, body, {
+          const issueNumber = await createGitHubIssue(ctx.repo, task.title, body, {
             milestone: milestoneNumber,
             labels: labels.length > 0 ? labels : undefined,
           });

package/src/runtime/runtime.test.ts

@@ -81,7 +81,10 @@ vi.mock('../governance/governance.js', () => ({
 }));
 
 vi.mock('../loop/loop-manager.js', () => ({
-  LoopManager: mockClass(),
+  LoopManager: vi.fn(function (this: Record<string, unknown>) {
+    this.isActive = vi.fn().mockReturnValue(false);
+    this.cancelLoop = vi.fn();
+  }),
 }));
 
 vi.mock('../control/identity-manager.js', () => ({
@@ -185,7 +188,9 @@ vi.mock('../context/context-engine.js', () => ({
 }));
 
 vi.mock('../agency/agency-manager.js', () => ({
-  AgencyManager: mockClass(),
+  AgencyManager: vi.fn(function (this: Record<string, unknown>) {
+    this.disable = vi.fn();
+  }),
 }));
 
 vi.mock('../vault/knowledge-review.js', () => ({
@@ -220,6 +225,7 @@ vi.mock('../queue/job-queue.js', () => ({
 vi.mock('../queue/pipeline-runner.js', () => ({
   PipelineRunner: vi.fn(function (this: Record<string, unknown>) {
     this.registerHandler = vi.fn();
+    this.stop = vi.fn();
   }),
 }));
 
@@ -261,6 +267,18 @@ vi.mock('./context-health.js', () => ({
   }),
 }));
 
+vi.mock('./shutdown-registry.js', () => ({
+  ShutdownRegistry: vi.fn(function (this: Record<string, unknown>) {
+    this.register = vi.fn();
+    this.closeAll = vi.fn().mockResolvedValue(undefined);
+    this.closeAllSync = vi.fn();
+    this.size = 0;
+    this.isClosed = false;
+    this.entries = [];
+    this.closed = false;
+  }),
+}));
+
 vi.mock('node:fs', () => ({
   existsSync: vi.fn().mockReturnValue(false),
   mkdirSync: vi.fn(),
@@ -360,4 +378,34 @@ describe('createAgentRuntime', () => {
   it('initializes context health monitor', () => {
     expect(runtime.contextHealth).toBeDefined();
   });
+
+  it('initializes shutdown registry', () => {
+    expect(runtime.shutdownRegistry).toBeDefined();
+    expect(runtime.shutdownRegistry.register).toBeDefined();
+  });
+
+  it('registers cleanup callbacks with shutdown registry', () => {
+    // vaultManager, pipelineRunner, agencyManager, loopManager
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'vaultManager',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'pipelineRunner',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'agencyManager',
+      expect.any(Function),
+    );
+    expect(runtime.shutdownRegistry.register).toHaveBeenCalledWith(
+      'loopManager',
+      expect.any(Function),
+    );
+  });
+
+  it('close() calls shutdownRegistry.closeAllSync()', () => {
+    runtime.close();
+    expect(runtime.shutdownRegistry.closeAllSync).toHaveBeenCalled();
+  });
 });

package/src/runtime/runtime.ts

@@ -60,6 +60,7 @@ import { loadPersona } from '../persona/loader.js';
 import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
 import { ContextHealthMonitor } from './context-health.js';
+import { ShutdownRegistry } from './shutdown-registry.js';
 
 /**
  * Create a fully initialized agent runtime.
@@ -221,6 +222,117 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   learningRadar.setOperatorProfile(operatorProfile);
   brainIntelligence.setOperatorProfile(operatorProfile);
 
+  // ─── Shutdown Registry ────────────────────────────────────────────
+  const shutdownRegistry = new ShutdownRegistry();
+
+  // Build pipeline runner before the runtime object so we can reference it
+  const pipelineRunner = (() => {
+    const jq = new JobQueue(vault.getProvider());
+    const pr = new PipelineRunner(jq);
+    // Register default job handlers for curator pipeline
+    pr.registerHandler('tag-normalize', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const result = curator.normalizeTag(entry.tags[0] ?? '');
+      return result;
+    });
+    pr.registerHandler('dedup-check', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('auto-link', async (job) => {
+      if (linkManager) {
+        const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
+        for (const s of suggestions) {
+          linkManager.addLink(
+            job.entryId ?? '',
+            s.entryId,
+            s.suggestedType,
+            `pipeline: ${s.reason}`,
+          );
+        }
+        return { linked: suggestions.length };
+      }
+      return { skipped: true, reason: 'link manager not available' };
+    });
+    pr.registerHandler('quality-gate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return evaluateQuality(entry, llmClient);
+    });
+    pr.registerHandler('classify', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return classifyEntry(entry, llmClient);
+    });
+
+    // ─── 9 additional handlers for full Salvador parity (#216) ────
+    pr.registerHandler('enrich-frontmatter', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.enrichMetadata(entry.id);
+    });
+    pr.registerHandler('detect-staleness', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      // Check if entry is older than 90 days (using validFrom or fallback to 0)
+      const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
+      const ageMs = Date.now() - entryTimestamp;
+      const staleDays = 90;
+      const isStale = ageMs > staleDays * 86400000;
+      return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
+    });
+    pr.registerHandler('detect-duplicate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('detect-contradiction', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const contradictions = curator.detectContradictions(0.4);
+      const relevant = contradictions.filter(
+        (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
+      );
+      return { found: relevant.length, contradictions: relevant };
+    });
+    pr.registerHandler('consolidate-duplicates', async (_job) => {
+      return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+    });
+    pr.registerHandler('archive-stale', async (_job) => {
+      // Run consolidation with stale detection
+      const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+      return { archived: result.staleEntries.length, result };
+    });
+    pr.registerHandler('verify-searchable', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const searchResults = vault.search(entry.title, { limit: 1 });
+      const found = searchResults.some((r) => r.entry.id === entry.id);
+      return { searchable: found, entryId: entry.id };
+    });
+    return pr;
+  })();
+
+  // ─── Register cleanup callbacks (LIFO: first registered = last closed) ──
+  // Vault manager closes last (other modules may flush to vault during close)
+  shutdownRegistry.register('vaultManager', () => vaultManager.close());
+  // Pipeline runner — clear its polling interval
+  shutdownRegistry.register('pipelineRunner', () => pipelineRunner.stop());
+  // Agency manager — close FSWatchers and debounce timers
+  shutdownRegistry.register('agencyManager', () => agencyManager.disable());
+  // Loop manager — clear accumulated state
+  shutdownRegistry.register('loopManager', () => {
+    if (loop.isActive()) {
+      try {
+        loop.cancelLoop();
+      } catch {
+        // Loop may already be inactive
+      }
+    }
+  });
+
   return {
     config,
     logger,
@@ -256,94 +368,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     knowledgeSynthesizer: new KnowledgeSynthesizer(brain, llmClient),
     chainRunner: new ChainRunner(vault.getProvider()),
     jobQueue: new JobQueue(vault.getProvider()),
-    pipelineRunner: (() => {
-      const jq = new JobQueue(vault.getProvider());
-      const pr = new PipelineRunner(jq);
-      // Register default job handlers for curator pipeline
-      pr.registerHandler('tag-normalize', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const result = curator.normalizeTag(entry.tags[0] ?? '');
-        return result;
-      });
-      pr.registerHandler('dedup-check', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('auto-link', async (job) => {
-        if (linkManager) {
-          const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
-          for (const s of suggestions) {
-            linkManager.addLink(
-              job.entryId ?? '',
-              s.entryId,
-              s.suggestedType,
-              `pipeline: ${s.reason}`,
-            );
-          }
-          return { linked: suggestions.length };
-        }
-        return { skipped: true, reason: 'link manager not available' };
-      });
-      pr.registerHandler('quality-gate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return evaluateQuality(entry, llmClient);
-      });
-      pr.registerHandler('classify', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return classifyEntry(entry, llmClient);
-      });
-
-      // ─── 9 additional handlers for full Salvador parity (#216) ────
-      pr.registerHandler('enrich-frontmatter', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.enrichMetadata(entry.id);
-      });
-      pr.registerHandler('detect-staleness', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        // Check if entry is older than 90 days (using validFrom or fallback to 0)
-        const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
-        const ageMs = Date.now() - entryTimestamp;
-        const staleDays = 90;
-        const isStale = ageMs > staleDays * 86400000;
-        return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
-      });
-      pr.registerHandler('detect-duplicate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('detect-contradiction', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const contradictions = curator.detectContradictions(0.4);
-        const relevant = contradictions.filter(
-          (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
-        );
-        return { found: relevant.length, contradictions: relevant };
-      });
-      pr.registerHandler('consolidate-duplicates', async (_job) => {
-        return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-      });
-      pr.registerHandler('archive-stale', async (_job) => {
-        // Run consolidation with stale detection
-        const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-        return { archived: result.staleEntries.length, result };
-      });
-      pr.registerHandler('verify-searchable', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const searchResults = vault.search(entry.title, { limit: 1 });
-        const found = searchResults.some((r) => r.entry.id === entry.id);
-        return { searchable: found, entryId: entry.id };
-      });
-      return pr;
-    })(),
+    pipelineRunner,
     operatorProfile,
     persona: (() => {
       const p = loadPersona(agentId, config.persona ?? undefined);
@@ -355,9 +380,12 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       return generatePersonaInstructions(p);
     })(),
     contextHealth: new ContextHealthMonitor(),
+    shutdownRegistry,
     createdAt: Date.now(),
     close: () => {
-      vaultManager.close();
+      // Synchronous close — runs all registered callbacks in LIFO order,
+      // then closes the vault (registered first, so runs last).
+      shutdownRegistry.closeAllSync();
     },
   };
 }