@soleri/core 7.0.0 → 8.1.0

package/src/runtime/chain-ops.ts

@@ -0,0 +1,121 @@
+/**
+ * Chain operations — 5 ops for composable multi-step workflows.
+ *
+ * Ops: chain_execute, chain_status, chain_resume, chain_list, chain_step_approve
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from './types.js';
+import { chainDefSchema } from '../flows/chain-types.js';
+
+export function createChainOps(runtime: AgentRuntime): OpDefinition[] {
+  const { chainRunner } = runtime;
+
+  /**
+   * Dispatch function that routes op calls to the appropriate facade handler.
+   * Looks up the op across all registered facades.
+   */
+  const createDispatch = (allOps: OpDefinition[]) => {
+    return async (op: string, params: Record<string, unknown>): Promise<unknown> => {
+      const opDef = allOps.find((o) => o.name === op);
+      if (!opDef) throw new Error(`Unknown op: ${op}`);
+      return opDef.handler(params);
+    };
+  };
+
+  // We need access to all ops for dispatch. The plan facade passes them in.
+  // For now, store a reference that gets set after facade registration.
+  let allOps: OpDefinition[] = [];
+
+  const ops: OpDefinition[] = [
+    {
+      name: 'chain_execute',
+      description:
+        "Execute a multi-step chain workflow. Steps run sequentially, each step's output feeds the next via $variable references. " +
+        'Gates (user-approval, auto-test, vault-check) can pause execution.',
+      auth: 'write',
+      schema: z.object({
+        chain: chainDefSchema.describe('Chain definition with steps'),
+        input: z
+          .record(z.unknown())
+          .optional()
+          .default({})
+          .describe('Initial input params (accessible as $input.*)'),
+        startFromStep: z.string().optional().describe('Skip to a specific step ID'),
+      }),
+      handler: async (params) => {
+        const chainDef = params.chain as z.infer<typeof chainDefSchema>;
+        const input = (params.input as Record<string, unknown>) ?? {};
+        const dispatch = createDispatch(allOps);
+        return chainRunner.execute(
+          chainDef,
+          input,
+          dispatch,
+          undefined,
+          params.startFromStep as string | undefined,
+        );
+      },
+    },
+    {
+      name: 'chain_status',
+      description:
+        'Get the current status of a chain instance — steps completed, paused gates, outputs.',
+      auth: 'read',
+      schema: z.object({
+        instanceId: z.string().describe('Chain instance ID'),
+      }),
+      handler: async (params) => {
+        const instance = chainRunner.getInstance(params.instanceId as string);
+        if (!instance) return { error: `Chain instance not found: ${params.instanceId}` };
+        return instance;
+      },
+    },
+    {
+      name: 'chain_resume',
+      description: 'Resume a paused chain from where it stopped (after a gate approval).',
+      auth: 'write',
+      schema: z.object({
+        instanceId: z.string().describe('Chain instance ID to resume'),
+        chain: chainDefSchema.describe('Chain definition (needed to know remaining steps)'),
+      }),
+      handler: async (params) => {
+        const chainDef = params.chain as z.infer<typeof chainDefSchema>;
+        const dispatch = createDispatch(allOps);
+        return chainRunner.resume(params.instanceId as string, chainDef, dispatch);
+      },
+    },
+    {
+      name: 'chain_list',
+      description: 'List all chain instances — running, paused, completed, failed.',
+      auth: 'read',
+      schema: z.object({
+        limit: z.number().optional().default(20),
+      }),
+      handler: async (params) => {
+        return chainRunner.list(params.limit as number);
+      },
+    },
+    {
+      name: 'chain_step_approve',
+      description: 'Approve a gate-paused step and resume chain execution from the next step.',
+      auth: 'write',
+      schema: z.object({
+        instanceId: z.string().describe('Chain instance ID'),
+        chain: chainDefSchema.describe('Chain definition (needed to continue execution)'),
+      }),
+      handler: async (params) => {
+        const chainDef = params.chain as z.infer<typeof chainDefSchema>;
+        const dispatch = createDispatch(allOps);
+        return chainRunner.approve(params.instanceId as string, chainDef, dispatch);
+      },
+    },
+  ];
+
+  // Expose a setter for wiring all ops after facade registration
+  (ops as OpDefinition[] & { _setAllOps: (o: OpDefinition[]) => void })._setAllOps = (o) => {
+    allOps = o;
+  };
+
+  return ops;
+}

package/src/runtime/claude-md-helpers.ts

@@ -0,0 +1,218 @@
+/**
+ * CLAUDE.md injection helpers — marker-based, idempotent section management.
+ *
+ * Supports injecting agent sections into existing CLAUDE.md files
+ * (project-level or global ~/.claude/CLAUDE.md) using HTML comment markers.
+ *
+ * Marker format: <!-- agent:{agentId}:mode --> ... <!-- /agent:{agentId}:mode -->
+ * This allows multiple Soleri agents to coexist in the same CLAUDE.md.
+ */
+
+import type { AgentRuntimeConfig } from './types.js';
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface AgentSection {
+  agentId: string;
+  content: string;
+}
+
+export type InjectionPosition = 'start' | 'end' | 'after-title';
+
+interface FacadeSummary {
+  name: string;
+  ops: string[];
+}
+
+// ─── Marker Helpers ───────────────────────────────────────────────────
+
+function startMarker(agentId: string): string {
+  return `<!-- agent:${agentId}:mode -->`;
+}
+
+function endMarker(agentId: string): string {
+  return `<!-- /agent:${agentId}:mode -->`;
+}
+
+/**
+ * Check if content already has sections for this agent.
+ */
+export function hasSections(content: string, agentId: string): boolean {
+  return content.includes(startMarker(agentId)) && content.includes(endMarker(agentId));
+}
+
+/**
+ * Remove existing agent sections from content.
+ */
+export function removeSections(content: string, agentId: string): string {
+  const start = startMarker(agentId);
+  const end = endMarker(agentId);
+
+  const startIdx = content.indexOf(start);
+  const endIdx = content.indexOf(end);
+
+  if (startIdx === -1 || endIdx === -1) return content;
+
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + end.length).trimStart();
+
+  return before + (after ? '\n\n' + after : '\n');
+}
+
+/**
+ * Inject a section into content at the specified position.
+ */
+export function injectAtPosition(
+  content: string,
+  section: string,
+  position: InjectionPosition,
+): string {
+  switch (position) {
+    case 'start':
+      return section + '\n\n' + content;
+
+    case 'end':
+      return content.trimEnd() + '\n\n' + section + '\n';
+
+    case 'after-title': {
+      const lines = content.split('\n');
+      // Find first # heading
+      const titleIdx = lines.findIndex((line) => /^#\s/.test(line));
+      if (titleIdx === -1) {
+        // No title found — prepend
+        return section + '\n\n' + content;
+      }
+      // Insert after title line (and any blank line following it)
+      let insertIdx = titleIdx + 1;
+      while (insertIdx < lines.length && lines[insertIdx].trim() === '') {
+        insertIdx++;
+      }
+      lines.splice(insertIdx, 0, '', section, '');
+      return lines.join('\n');
+    }
+  }
+}
+
+/**
+ * Wrap content in agent markers.
+ */
+export function wrapInMarkers(agentId: string, content: string): string {
+  return `${startMarker(agentId)}\n${content}\n${endMarker(agentId)}`;
+}
+
+// ─── Content Composition ──────────────────────────────────────────────
+
+/**
+ * Compose agent mode section from runtime config.
+ */
+export function composeAgentModeSection(config: AgentRuntimeConfig): string {
+  const { agentId } = config;
+  const name = agentId.charAt(0).toUpperCase() + agentId.slice(1);
+
+  return [
+    `## ${name} Mode`,
+    '',
+    `**Activate:** "Hello, ${name}!" → \`${agentId}_core op:activate params:{ projectPath: "." }\``,
+    `**Deactivate:** "Goodbye, ${name}!" → \`${agentId}_core op:activate params:{ deactivate: true }\``,
+    '',
+    `On activation, adopt the returned persona. Stay in character until deactivated.`,
+  ].join('\n');
+}
+
+/**
+ * Compose integration section with tools table and session protocol.
+ */
+export function composeIntegrationSection(
+  config: AgentRuntimeConfig,
+  facades?: FacadeSummary[],
+): string {
+  const { agentId } = config;
+  const name = agentId.charAt(0).toUpperCase() + agentId.slice(1);
+
+  const lines: string[] = [
+    `## ${name} Integration`,
+    '',
+    `On session start: \`${agentId}_core op:register params:{ projectPath: "." }\``,
+    '',
+    '### Essential Tools',
+    '',
+    '| Facade | Key Ops |',
+    '|--------|---------|',
+  ];
+
+  if (facades && facades.length > 0) {
+    for (const f of facades) {
+      const opsStr = f.ops
+        .slice(0, 5)
+        .map((o) => `\`${o}\``)
+        .join(', ');
+      const suffix = f.ops.length > 5 ? ', ...' : '';
+      lines.push(`| \`${f.name}\` | ${opsStr}${suffix} |`);
+    }
+  } else {
+    // Default facade table
+    lines.push(
+      `| \`${agentId}_vault\` | \`search_intelligent\`, \`capture_knowledge\`, \`capture_quick\` |`,
+    );
+    lines.push(
+      `| \`${agentId}_plan\` | \`create_plan\`, \`approve_plan\`, \`plan_split\`, \`plan_reconcile\` |`,
+    );
+    lines.push(`| \`${agentId}_brain\` | \`recommend\`, \`strengths\`, \`feedback\` |`);
+    lines.push(`| \`${agentId}_memory\` | \`memory_search\`, \`session_capture\` |`);
+    lines.push(
+      `| \`${agentId}_admin\` | \`admin_health\`, \`admin_tool_list\`, \`admin_setup_global\` |`,
+    );
+    lines.push(`| \`${agentId}_curator\` | \`curator_groom\`, \`curator_status\` |`);
+  }
+
+  lines.push('');
+  lines.push(`> Full list: \`${agentId}_admin op:admin_tool_list\``);
+
+  return lines.join('\n');
+}
+
+/**
+ * Build full injection content (mode + integration, wrapped in markers).
+ */
+export function buildInjectionContent(
+  config: AgentRuntimeConfig,
+  options: { includeIntegration?: boolean; facades?: FacadeSummary[] } = {},
+): string {
+  const { includeIntegration = true, facades } = options;
+
+  const sections = [composeAgentModeSection(config)];
+
+  if (includeIntegration) {
+    sections.push(composeIntegrationSection(config, facades));
+  }
+
+  return wrapInMarkers(config.agentId, sections.join('\n\n'));
+}
+
+// ─── Engine Rules ────────────────────────────────────────────────────
+
+const ENGINE_RULES_START = '<!-- soleri:engine-rules -->';
+const ENGINE_RULES_END = '<!-- /soleri:engine-rules -->';
+
+/**
+ * Check if engine rules are present in content.
+ */
+function hasEngineRules(content: string): boolean {
+  return content.includes(ENGINE_RULES_START) && content.includes(ENGINE_RULES_END);
+}
+
+/**
+ * Inject or update engine rules in content.
+ */
+export function injectEngineRulesBlock(content: string, engineRulesContent: string): string {
+  if (hasEngineRules(content)) {
+    // Replace existing
+    const startIdx = content.indexOf(ENGINE_RULES_START);
+    const endIdx = content.indexOf(ENGINE_RULES_END);
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + ENGINE_RULES_END.length);
+    return before + engineRulesContent + after;
+  }
+  // Append
+  return content.trimEnd() + '\n\n' + engineRulesContent + '\n';
+}

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

@@ -1,7 +1,8 @@
 /**
- * Extra curator operations — 5 ops that extend the 8 base curator ops in core-ops.ts.
+ * Extra curator operations — 8 ops that extend the 8 base curator ops in core-ops.ts.
  *
- * Groups: entry history (2), queue stats (1), metadata enrichment (1), hybrid detection (1).
+ * Groups: entry history (2), queue stats (1), metadata enrichment (1), hybrid detection (1),
+ *         pipeline status (1), schedule start (1), schedule stop (1).
  */
 
 import { z } from 'zod';
@@ -9,7 +10,8 @@ import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
 
 export function createCuratorExtraOps(runtime: AgentRuntime): OpDefinition[] {
-  const { curator } = runtime;
+  const { curator, jobQueue, pipelineRunner } = runtime;
+  let consolidationInterval: ReturnType<typeof setInterval> | null = null;
 
   return [
     // ─── Entry History ──────────────────────────────────────────────
@@ -81,5 +83,86 @@ export function createCuratorExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return curator.detectContradictionsHybrid(params.threshold as number | undefined);
       },
     },
+
+    // ─── Pipeline & Scheduling (#210) ────────────────────────────────
+    {
+      name: 'curator_pipeline_status',
+      description:
+        'Get job queue and pipeline runner status — pending/running/completed/failed counts, runner state, tick count.',
+      auth: 'read',
+      handler: async () => {
+        return {
+          queue: jobQueue.getStats(),
+          runner: pipelineRunner.getStatus(),
+        };
+      },
+    },
+    {
+      name: 'curator_enqueue_pipeline',
+      description:
+        'Enqueue a processing pipeline for a vault entry — tag-normalize → dedup-check → auto-link. ' +
+        'Jobs execute in DAG order via the background pipeline runner.',
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string().describe('Vault entry ID to process'),
+      }),
+      handler: async (params) => {
+        const entryId = params.entryId as string;
+        const pipelineId = `pipe-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+        const step1 = jobQueue.enqueue('tag-normalize', { entryId, pipelineId });
+        const step2 = jobQueue.enqueue('dedup-check', { entryId, pipelineId, dependsOn: [step1] });
+        const step3 = jobQueue.enqueue('auto-link', { entryId, pipelineId, dependsOn: [step2] });
+        return { pipelineId, jobs: [step1, step2, step3] };
+      },
+    },
+    {
+      name: 'curator_schedule_start',
+      description:
+        'Start periodic consolidation — runs curator.consolidate() at the specified interval. ' +
+        'Also starts the pipeline runner for background job processing.',
+      auth: 'write',
+      schema: z.object({
+        intervalMinutes: z
+          .number()
+          .optional()
+          .default(60)
+          .describe('Consolidation interval in minutes (default: 60)'),
+      }),
+      handler: async (params) => {
+        const intervalMs = (params.intervalMinutes as number) * 60 * 1000;
+
+        // Start pipeline runner
+        pipelineRunner.start();
+
+        // Start consolidation scheduler
+        if (consolidationInterval) clearInterval(consolidationInterval);
+        consolidationInterval = setInterval(() => {
+          try {
+            curator.consolidate();
+          } catch {
+            /* best-effort */
+          }
+        }, intervalMs);
+
+        return {
+          started: true,
+          pipelineRunner: pipelineRunner.getStatus(),
+          consolidationIntervalMs: intervalMs,
+        };
+      },
+    },
+    {
+      name: 'curator_schedule_stop',
+      description: 'Stop periodic consolidation and pipeline runner.',
+      auth: 'write',
+      handler: async () => {
+        pipelineRunner.stop();
+        if (consolidationInterval) {
+          clearInterval(consolidationInterval);
+          consolidationInterval = null;
+        }
+        return { stopped: true };
+      },
+    },
   ];
 }

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

@@ -8,6 +8,8 @@ import type { OpDefinition } from '../../facades/types.js';
 import type { AgentRuntime } from '../types.js';
 import { createAdminOps } from '../admin-ops.js';
 import { createAdminExtraOps } from '../admin-extra-ops.js';
+import { createAdminSetupOps } from '../admin-setup-ops.js';
+import { createSessionBriefingOps } from '../session-briefing.js';
 import { createPluginOps } from '../plugin-ops.js';
 import { createPackOps } from '../pack-ops.js';
 import { createTelemetryOps } from '../telemetry-ops.js';
@@ -56,8 +58,7 @@ export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
       }),
       handler: async (params) => {
         return llmClient.complete({
-          provider: 'openai',
-          model: (params.model as string) ?? '',
+          model: (params.model as string) || undefined,
           systemPrompt: params.systemPrompt as string,
           userPrompt: params.userPrompt as string,
           temperature: params.temperature as number | undefined,
@@ -100,6 +101,8 @@ export function createAdminFacadeOps(runtime: AgentRuntime): OpDefinition[] {
     // ─── Satellite ops ───────────────────────────────────────────
     ...createAdminOps(runtime),
     ...createAdminExtraOps(runtime),
+    ...createAdminSetupOps(runtime),
+    ...createSessionBriefingOps(runtime),
   ];
 
   // Plugin ops must mutate the same live op array that MCP dispatch reads.

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

@@ -107,5 +107,73 @@ export function createAgencyFacadeOps(runtime: AgentRuntime): OpDefinition[] {
         return question ?? { clarificationNeeded: false };
       },
     },
+
+    // ─── Proactive Intelligence (#211) ─────────────────────────────
+    {
+      name: 'agency_suggestions',
+      description:
+        'Evaluate suggestion rules and return triggered proactive suggestions, sorted by priority.',
+      auth: 'read',
+      handler: async () => agencyManager.generateSuggestions(),
+    },
+    {
+      name: 'agency_rich_clarify',
+      description:
+        'Generate structured clarification questions with urgency, options, and implications.',
+      auth: 'read',
+      schema: z.object({
+        prompt: z.string().describe('The ambiguous prompt to clarify'),
+      }),
+      handler: async (params) => agencyManager.generateRichClarification(params.prompt as string),
+    },
+    {
+      name: 'agency_suppress_warning',
+      description: 'Suppress a warning by ID — prevents it from appearing in pending warnings.',
+      auth: 'write',
+      schema: z.object({
+        warningId: z.string(),
+      }),
+      handler: async (params) => {
+        agencyManager.suppressWarning(params.warningId as string);
+        return { suppressed: true, warningId: params.warningId };
+      },
+    },
+    {
+      name: 'agency_unsuppress_warning',
+      description: 'Remove suppression for a warning.',
+      auth: 'write',
+      schema: z.object({
+        warningId: z.string(),
+      }),
+      handler: async (params) => {
+        agencyManager.unsuppressWarning(params.warningId as string);
+        return { unsuppressed: true, warningId: params.warningId };
+      },
+    },
+    {
+      name: 'agency_dismiss_pattern',
+      description: 'Dismiss a surfaced pattern for 24h — prevents re-surfacing.',
+      auth: 'write',
+      schema: z.object({
+        entryId: z.string(),
+      }),
+      handler: async (params) => {
+        agencyManager.dismissPattern(params.entryId as string);
+        return { dismissed: true, entryId: params.entryId, ttlHours: 24 };
+      },
+    },
+    {
+      name: 'agency_notifications',
+      description: 'Drain pending notifications — returns and clears the notification queue.',
+      auth: 'read',
+      handler: async () => agencyManager.drainNotifications(),
+    },
+    {
+      name: 'agency_full_status',
+      description:
+        'Full agency status including suggestions, suppressions, dismissals, and notifications.',
+      auth: 'read',
+      handler: async () => agencyManager.getFullStatus(),
+    },
   ];
 }