@soleri/core 2.9.0 → 2.11.0

package/src/playbooks/playbook-executor.ts

@@ -0,0 +1,301 @@
+/**
+ * Playbook Executor — in-memory runtime for step-by-step playbook execution.
+ *
+ * Lifecycle: start → step (repeat) → complete
+ *
+ * Sessions are ephemeral (in-memory, not persisted). For persistent workflows,
+ * use the planning system instead.
+ */
+
+import type {
+  PlaybookDefinition,
+  MergedPlaybook,
+  PlaybookGate,
+  PlaybookTaskTemplate,
+} from './playbook-types.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type PlaybookStepStatus = 'pending' | 'active' | 'done' | 'skipped';
+
+export interface PlaybookStepState {
+  index: number;
+  title: string;
+  description: string;
+  status: PlaybookStepStatus;
+  output?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+export interface PlaybookSession {
+  id: string;
+  playbookId: string;
+  label: string;
+  steps: PlaybookStepState[];
+  gates: PlaybookGate[];
+  taskTemplates: PlaybookTaskTemplate[];
+  tools: string[];
+  verificationCriteria: string[];
+  currentStepIndex: number;
+  status: 'active' | 'completed' | 'aborted';
+  startedAt: number;
+  completedAt?: number;
+}
+
+export interface StartResult {
+  sessionId: string;
+  label: string;
+  totalSteps: number;
+  currentStep: PlaybookStepState;
+  tools: string[];
+  gates: PlaybookGate[];
+}
+
+export interface StepResult {
+  sessionId: string;
+  completedStep: PlaybookStepState;
+  nextStep: PlaybookStepState | null;
+  progress: { done: number; total: number };
+  isComplete: boolean;
+}
+
+export interface CompleteResult {
+  sessionId: string;
+  label: string;
+  status: 'completed' | 'aborted';
+  steps: PlaybookStepState[];
+  gatesPassed: boolean;
+  unsatisfiedGates: string[];
+  duration: number;
+}
+
+// =============================================================================
+// STEP PARSER
+// =============================================================================
+
+/**
+ * Parse step strings from a playbook's `steps` field into structured steps.
+ * Expects numbered steps like "1. Title\n   - detail\n   - detail"
+ */
+function parseSteps(stepsText: string): Array<{ title: string; description: string }> {
+  const lines = stepsText.split('\n');
+  const steps: Array<{ title: string; description: string }> = [];
+  let current: { title: string; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    const stepMatch = line.match(/^\s*(\d+)\.\s+(.+)/);
+    if (stepMatch) {
+      if (current) {
+        steps.push({ title: current.title, description: current.lines.join('\n').trim() });
+      }
+      current = { title: stepMatch[2].trim(), lines: [] };
+    } else if (current && line.trim()) {
+      current.lines.push(line);
+    }
+  }
+  if (current) {
+    steps.push({ title: current.title, description: current.lines.join('\n').trim() });
+  }
+
+  return steps;
+}
+
+// =============================================================================
+// EXECUTOR
+// =============================================================================
+
+export class PlaybookExecutor {
+  private sessions = new Map<string, PlaybookSession>();
+
+  /**
+   * Start a playbook execution session.
+   * Accepts either a PlaybookDefinition or MergedPlaybook.
+   */
+  start(playbook: PlaybookDefinition | MergedPlaybook): StartResult {
+    const sessionId = `pbk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    let label: string;
+    let playbookId: string;
+    let stepsText: string;
+    let gates: PlaybookGate[];
+    let taskTemplates: PlaybookTaskTemplate[];
+    let tools: string[];
+    let verificationCriteria: string[];
+
+    if ('mergedGates' in playbook) {
+      // MergedPlaybook
+      label = playbook.label;
+      playbookId = playbook.generic?.id ?? playbook.domain?.id ?? 'unknown';
+      stepsText = playbook.generic?.steps ?? playbook.domain?.steps ?? '';
+      gates = playbook.mergedGates;
+      taskTemplates = playbook.mergedTasks;
+      tools = playbook.mergedTools;
+      verificationCriteria = playbook.mergedVerification;
+    } else {
+      // PlaybookDefinition
+      label = playbook.title;
+      playbookId = playbook.id;
+      stepsText = playbook.steps;
+      gates = playbook.gates;
+      taskTemplates = playbook.taskTemplates;
+      tools = playbook.toolInjections;
+      verificationCriteria = playbook.verificationCriteria;
+    }
+
+    const parsed = parseSteps(stepsText);
+    if (parsed.length === 0) {
+      parsed.push({ title: label, description: 'Execute the playbook.' });
+    }
+
+    const steps: PlaybookStepState[] = parsed.map((s, i) => ({
+      index: i,
+      title: s.title,
+      description: s.description,
+      status: i === 0 ? 'active' : 'pending',
+    }));
+
+    const session: PlaybookSession = {
+      id: sessionId,
+      playbookId,
+      label,
+      steps,
+      gates,
+      taskTemplates,
+      tools,
+      verificationCriteria,
+      currentStepIndex: 0,
+      status: 'active',
+      startedAt: Date.now(),
+    };
+
+    steps[0].startedAt = Date.now();
+    this.sessions.set(sessionId, session);
+
+    return {
+      sessionId,
+      label,
+      totalSteps: steps.length,
+      currentStep: steps[0],
+      tools,
+      gates,
+    };
+  }
+
+  /**
+   * Advance to the next step. Marks the current step as done (or skipped).
+   */
+  step(
+    sessionId: string,
+    options?: { output?: string; skip?: boolean },
+  ): StepResult | { error: string } {
+    const session = this.sessions.get(sessionId);
+    if (!session) return { error: `Session not found: ${sessionId}` };
+    if (session.status !== 'active') return { error: `Session is ${session.status}, not active` };
+
+    const current = session.steps[session.currentStepIndex];
+    current.status = options?.skip ? 'skipped' : 'done';
+    current.output = options?.output;
+    current.completedAt = Date.now();
+
+    const nextIndex = session.currentStepIndex + 1;
+    const isComplete = nextIndex >= session.steps.length;
+
+    let nextStep: PlaybookStepState | null = null;
+    if (!isComplete) {
+      session.currentStepIndex = nextIndex;
+      session.steps[nextIndex].status = 'active';
+      session.steps[nextIndex].startedAt = Date.now();
+      nextStep = session.steps[nextIndex];
+    }
+
+    const done = session.steps.filter((s) => s.status === 'done' || s.status === 'skipped').length;
+
+    return {
+      sessionId,
+      completedStep: current,
+      nextStep,
+      progress: { done, total: session.steps.length },
+      isComplete,
+    };
+  }
+
+  /**
+   * Complete a playbook session. Validates gates and returns summary.
+   */
+  complete(
+    sessionId: string,
+    options?: { abort?: boolean; gateResults?: Record<string, boolean> },
+  ): CompleteResult | { error: string } {
+    const session = this.sessions.get(sessionId);
+    if (!session) return { error: `Session not found: ${sessionId}` };
+    if (session.status !== 'active') return { error: `Session is already ${session.status}` };
+
+    const abort = options?.abort ?? false;
+    const gateResults = options?.gateResults ?? {};
+
+    // Mark any remaining active/pending steps
+    for (const step of session.steps) {
+      if (step.status === 'active' || step.status === 'pending') {
+        step.status = abort ? 'skipped' : step.status;
+        if (step.status === 'active') {
+          step.status = 'done';
+          step.completedAt = Date.now();
+        }
+      }
+    }
+
+    // Validate gates
+    const completionGates = session.gates.filter((g) => g.phase === 'completion');
+    const unsatisfiedGates: string[] = [];
+    for (const gate of completionGates) {
+      if (!gateResults[gate.checkType]) {
+        unsatisfiedGates.push(`${gate.checkType}: ${gate.requirement}`);
+      }
+    }
+
+    session.status = abort ? 'aborted' : 'completed';
+    session.completedAt = Date.now();
+
+    const result: CompleteResult = {
+      sessionId,
+      label: session.label,
+      status: session.status,
+      steps: session.steps,
+      gatesPassed: unsatisfiedGates.length === 0,
+      unsatisfiedGates,
+      duration: session.completedAt - session.startedAt,
+    };
+
+    // Clean up after completion
+    this.sessions.delete(sessionId);
+
+    return result;
+  }
+
+  /**
+   * Get the current state of a session.
+   */
+  getSession(sessionId: string): PlaybookSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * List all active sessions.
+   */
+  listSessions(): Array<{ id: string; label: string; progress: string; startedAt: number }> {
+    return Array.from(this.sessions.values())
+      .filter((s) => s.status === 'active')
+      .map((s) => {
+        const done = s.steps.filter((st) => st.status === 'done' || st.status === 'skipped').length;
+        return {
+          id: s.id,
+          label: s.label,
+          progress: `${done}/${s.steps.length}`,
+          startedAt: s.startedAt,
+        };
+      });
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Plugin System — Barrel Exports
+ */
+
+export {
+  pluginManifestSchema,
+  type PluginManifest,
+  type PluginStatus,
+  type PluginProvenance,
+  type LoadedPlugin,
+  type RegisteredPlugin,
+  type PluginFacadeBuilder,
+  type PluginContext,
+  type LoadResult,
+} from './types.js';
+
+export { loadPlugins, validateDependencies, sortByDependencies } from './plugin-loader.js';
+
+export { PluginRegistry } from './plugin-registry.js';

package/src/plugins/plugin-loader.ts

@@ -0,0 +1,183 @@
+/**
+ * Plugin Loader — scans directories, validates manifests, loads plugins.
+ *
+ * Plugin directories (checked in order, first occurrence wins):
+ *   1. ~/.{agentId}/plugins/ (global plugins)
+ *   2. .{agentId}/plugins/  (project plugins)
+ *   3. Custom directories (via config)
+ *
+ * Each plugin is a directory containing `soleri-plugin.json`.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  pluginManifestSchema,
+  type LoadedPlugin,
+  type LoadResult,
+  type PluginProvenance,
+} from './types.js';
+
+// =============================================================================
+// LOADER
+// =============================================================================
+
+const MANIFEST_FILENAME = 'soleri-plugin.json';
+
+/**
+ * Load all plugins from standard + custom directories.
+ */
+export function loadPlugins(
+  agentId: string,
+  projectPath?: string,
+  extraDirs: string[] = [],
+): LoadResult {
+  const result: LoadResult = { loaded: [], errors: [] };
+  const seen = new Set<string>();
+
+  const dirs: Array<{ path: string; provenance: PluginProvenance }> = [];
+
+  // Global: ~/.{agentId}/plugins/
+  const globalDir = join(homedir(), `.${agentId}`, 'plugins');
+  if (existsSync(globalDir)) {
+    dirs.push({ path: globalDir, provenance: 'global' });
+  }
+
+  // Project: .{agentId}/plugins/
+  if (projectPath) {
+    const projectDir = join(projectPath, `.${agentId}`, 'plugins');
+    if (existsSync(projectDir)) {
+      dirs.push({ path: projectDir, provenance: 'project' });
+    }
+  }
+
+  // Custom
+  for (const dir of extraDirs) {
+    if (existsSync(dir)) {
+      dirs.push({ path: dir, provenance: 'custom' });
+    }
+  }
+
+  for (const { path: parentDir, provenance } of dirs) {
+    try {
+      const entries = readdirSync(parentDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        const pluginDir = join(parentDir, entry.name);
+        const loaded = loadSinglePlugin(pluginDir, provenance);
+
+        if (loaded.error) {
+          result.errors.push({ directory: pluginDir, error: loaded.error });
+          continue;
+        }
+
+        if (loaded.plugin) {
+          if (seen.has(loaded.plugin.manifest.id)) continue; // first wins
+          seen.add(loaded.plugin.manifest.id);
+          result.loaded.push(loaded.plugin);
+        }
+      }
+    } catch {
+      // Directory not scannable — skip
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load a single plugin from a directory.
+ */
+function loadSinglePlugin(
+  pluginDir: string,
+  provenance: PluginProvenance,
+): { plugin?: LoadedPlugin; error?: string } {
+  const manifestPath = join(pluginDir, MANIFEST_FILENAME);
+
+  if (!existsSync(manifestPath)) {
+    return { error: `No ${MANIFEST_FILENAME} found in ${pluginDir}` };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (e) {
+    return {
+      error: `Invalid JSON in ${manifestPath}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+
+  const parseResult = pluginManifestSchema.safeParse(raw);
+  if (!parseResult.success) {
+    const issues = parseResult.error.issues
+      .map((i) => `${i.path.join('.')}: ${i.message}`)
+      .join('; ');
+    return { error: `Invalid manifest in ${pluginDir}: ${issues}` };
+  }
+
+  return {
+    plugin: {
+      manifest: parseResult.data,
+      directory: pluginDir,
+      provenance,
+    },
+  };
+}
+
+// =============================================================================
+// DEPENDENCY HELPERS
+// =============================================================================
+
+/**
+ * Validate that all plugin dependencies are satisfiable.
+ */
+export function validateDependencies(
+  plugins: LoadedPlugin[],
+): Array<{ pluginId: string; missingDep: string }> {
+  const available = new Set(plugins.map((p) => p.manifest.id));
+  const errors: Array<{ pluginId: string; missingDep: string }> = [];
+
+  for (const { manifest } of plugins) {
+    for (const dep of manifest.dependencies) {
+      if (!available.has(dep)) {
+        errors.push({ pluginId: manifest.id, missingDep: dep });
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Topological sort by dependency order (no-deps first).
+ * Detects and breaks circular dependencies.
+ */
+export function sortByDependencies(plugins: LoadedPlugin[]): LoadedPlugin[] {
+  const byId = new Map(plugins.map((p) => [p.manifest.id, p]));
+  const sorted: LoadedPlugin[] = [];
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  function visit(id: string): void {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) return; // circular — break
+    visiting.add(id);
+    const plugin = byId.get(id);
+    if (plugin) {
+      for (const dep of plugin.manifest.dependencies) {
+        visit(dep);
+      }
+      sorted.push(plugin);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  }
+
+  for (const { manifest } of plugins) {
+    visit(manifest.id);
+  }
+
+  return sorted;
+}

package/src/plugins/plugin-registry.ts

@@ -0,0 +1,187 @@
+/**
+ * Plugin Registry — tracks loaded plugins and their lifecycle.
+ *
+ * Not a singleton — lives on AgentRuntime for testability.
+ * Lifecycle: load → register → activate → (deactivate | error)
+ */
+
+import type {
+  LoadedPlugin,
+  RegisteredPlugin,
+  PluginContext,
+  PluginFacadeBuilder,
+} from './types.js';
+import type { FacadeConfig, OpDefinition } from '../facades/types.js';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export class PluginRegistry {
+  private plugins = new Map<string, RegisteredPlugin>();
+
+  /**
+   * Register a loaded plugin. Does NOT activate it — call activate() separately.
+   */
+  register(loaded: LoadedPlugin): RegisteredPlugin {
+    const existing = this.plugins.get(loaded.manifest.id);
+    if (existing) {
+      throw new Error(`Plugin "${loaded.manifest.id}" is already registered`);
+    }
+
+    const registered: RegisteredPlugin = {
+      id: loaded.manifest.id,
+      manifest: loaded.manifest,
+      directory: loaded.directory,
+      provenance: loaded.provenance,
+      status: 'registered',
+      facades: [],
+      registeredAt: Date.now(),
+    };
+
+    this.plugins.set(registered.id, registered);
+    return registered;
+  }
+
+  /**
+   * Activate a plugin — builds facades from its manifest or JS module.
+   *
+   * If the plugin directory contains an `index.js` with a `createFacades` export,
+   * that function is called to build facades dynamically. Otherwise, facade stubs
+   * are created from the manifest's `facades` array (static ops with no-op handlers).
+   */
+  async activate(pluginId: string, ctx: PluginContext): Promise<RegisteredPlugin> {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) throw new Error(`Plugin "${pluginId}" is not registered`);
+    if (plugin.status === 'active') return plugin;
+
+    try {
+      // Try dynamic facade builder first
+      let facades = await this.tryLoadFacadeBuilder(plugin, ctx);
+
+      // Fall back to static manifest facades
+      if (!facades) {
+        facades = this.buildStaticFacades(plugin);
+      }
+
+      plugin.facades = facades;
+      plugin.status = 'active';
+      plugin.activatedAt = Date.now();
+      plugin.error = undefined;
+    } catch (e) {
+      plugin.status = 'error';
+      plugin.error = e instanceof Error ? e.message : String(e);
+    }
+
+    return plugin;
+  }
+
+  /**
+   * Deactivate a plugin — removes its facades from the runtime.
+   */
+  deactivate(pluginId: string): boolean {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) return false;
+
+    plugin.status = 'deactivated';
+    plugin.facades = [];
+    return true;
+  }
+
+  /**
+   * Unregister a plugin completely.
+   */
+  unregister(pluginId: string): boolean {
+    const plugin = this.plugins.get(pluginId);
+    if (!plugin) return false;
+
+    if (plugin.status === 'active') {
+      this.deactivate(pluginId);
+    }
+
+    return this.plugins.delete(pluginId);
+  }
+
+  /**
+   * Get a registered plugin by ID.
+   */
+  get(pluginId: string): RegisteredPlugin | undefined {
+    return this.plugins.get(pluginId);
+  }
+
+  /**
+   * List all registered plugins.
+   */
+  list(): RegisteredPlugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Get all active facades from all active plugins.
+   */
+  getActiveFacades(): FacadeConfig[] {
+    const facades: FacadeConfig[] = [];
+    for (const plugin of this.plugins.values()) {
+      if (plugin.status === 'active') {
+        facades.push(...plugin.facades);
+      }
+    }
+    return facades;
+  }
+
+  /**
+   * Get all active ops (flattened from all active plugin facades).
+   */
+  getActiveOps(): OpDefinition[] {
+    return this.getActiveFacades().flatMap((f) => f.ops);
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────
+
+  /**
+   * Try to load a JS module with `createFacades` export from the plugin directory.
+   * Returns null if no module found or no export.
+   */
+  private async tryLoadFacadeBuilder(
+    plugin: RegisteredPlugin,
+    ctx: PluginContext,
+  ): Promise<FacadeConfig[] | null> {
+    const moduleFile = join(plugin.directory, 'index.js');
+    if (!existsSync(moduleFile)) {
+      return null;
+    }
+
+    try {
+      // Dynamic import of plugin's index.js
+      const mod = (await import(pathToFileURL(moduleFile).href)) as {
+        createFacades?: PluginFacadeBuilder;
+      };
+      if (typeof mod.createFacades === 'function') {
+        return mod.createFacades(ctx);
+      }
+      throw new Error(`Plugin module "${moduleFile}" must export createFacades(ctx)`);
+    } catch (e) {
+      throw new Error(
+        `Failed to load plugin module "${moduleFile}": ${e instanceof Error ? e.message : String(e)}`, { cause: e },
+      );
+    }
+  }
+
+  /**
+   * Build facade configs from the manifest's static facade definitions.
+   * These have no-op handlers — useful for schema discovery and documentation.
+   */
+  private buildStaticFacades(plugin: RegisteredPlugin): FacadeConfig[] {
+    return plugin.manifest.facades.map((f) => ({
+      name: f.name,
+      description: f.description,
+      ops: f.ops.map((op) => ({
+        name: op.name,
+        description: op.description,
+        auth: op.auth as 'read' | 'write' | 'admin',
+        handler: async () => ({
+          error: `Op "${op.name}" is a static plugin op — no handler implementation provided. Add an index.js with createFacades() to ${plugin.directory}`,
+        }),
+      })),
+    }));
+  }
+}