wispy-cli 0.6.1 → 0.8.0

package/core/engine.mjs

@@ -0,0 +1,705 @@
+/**
+ * core/engine.mjs — Main chat engine for Wispy
+ *
+ * Class WispyEngine:
+ *   - constructor(config) — loads config, initializes providers/tools/mcp
+ *   - async init() — async initialization
+ *   - async processMessage(sessionId, userMessage, opts?) → assistantMessage
+ *   - async processToolCalls(toolCalls) → results array
+ *
+ * This is THE single entry point. CLI, TUI, channels all call this.
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { readFile, writeFile, mkdir, appendFile } from "node:fs/promises";
+
+import { WISPY_DIR, CONVERSATIONS_DIR, MEMORY_DIR, MCP_CONFIG_PATH, detectProvider, PROVIDERS } from "./config.mjs";
+import { ProviderRegistry } from "./providers.mjs";
+import { ToolRegistry } from "./tools.mjs";
+import { SessionManager } from "./session.mjs";
+import { MCPManager, ensureDefaultMcpConfig } from "./mcp.mjs";
+import { MemoryManager } from "./memory.mjs";
+
+const MAX_TOOL_ROUNDS = 10;
+const MAX_CONTEXT_CHARS = 40_000;
+
+export class WispyEngine {
+  constructor(config = {}) {
+    this.config = config;
+    this.providers = new ProviderRegistry();
+    this.tools = new ToolRegistry();
+    this.sessions = new SessionManager();
+    this.mcpManager = new MCPManager(config.mcpConfigPath ?? MCP_CONFIG_PATH);
+    this.memory = new MemoryManager(WISPY_DIR);
+    this._initialized = false;
+    this._activeWorkstream = config.workstream
+      ?? process.env.WISPY_WORKSTREAM
+      ?? process.argv.find((a, i) => (process.argv[i-1] === "-w" || process.argv[i-1] === "--workstream"))
+      ?? "default";
+  }
+
+  get activeWorkstream() { return this._activeWorkstream; }
+  get model() { return this.providers.model; }
+  get provider() { return this.providers.provider; }
+
+  /**
+   * Initialize the engine (async). Call before processMessage().
+   */
+  async init(opts = {}) {
+    if (this._initialized) return this;
+
+    // Initialize provider
+    const providerResult = await this.providers.init(opts.providerOverrides ?? {});
+    if (!providerResult && !opts.allowNoProvider) {
+      return null; // No provider configured
+    }
+
+    // Register built-in tools
+    this.tools.registerBuiltin();
+
+    // Register memory tools
+    this._registerMemoryTools();
+
+    // Initialize MCP
+    if (!opts.skipMcp) {
+      await ensureDefaultMcpConfig(this.mcpManager.configPath);
+      const mcpResults = await this.mcpManager.autoConnect();
+      if (process.env.WISPY_DEBUG) {
+        for (const r of mcpResults) {
+          if (r.status === "failed") console.error(`[wispy] MCP "${r.name}" failed: ${r.error?.slice(0, 80)}`);
+        }
+      }
+      this.tools.registerMCP(this.mcpManager);
+    }
+
+    this._initialized = true;
+    return this;
+  }
+
+  /**
+   * Process a user message. Runs the full agentic loop.
+   *
+   * @param {string|null} sessionId - Session ID (null = create new)
+   * @param {string} userMessage - The user's message
+   * @param {object} opts - Options: { onChunk, systemPrompt, workstream, noSave }
+   * @returns {object} { role: "assistant", content: string, usage? }
+   */
+  async processMessage(sessionId, userMessage, opts = {}) {
+    if (!this._initialized) await this.init();
+
+    // Get or create session
+    let session;
+    if (sessionId) {
+      session = this.sessions.get(sessionId) ?? await this.sessions.load(sessionId);
+      if (!session) {
+        // Create new session with given ID context
+        session = this.sessions.create({ workstream: opts.workstream ?? this._activeWorkstream });
+      }
+    } else {
+      session = this.sessions.create({ workstream: opts.workstream ?? this._activeWorkstream });
+    }
+
+    // Build messages array for the provider
+    const systemPrompt = opts.systemPrompt ?? await this._buildSystemPrompt(userMessage);
+
+    // Initialize messages with system prompt if empty
+    let messages;
+    if (session.messages.length === 0) {
+      messages = [{ role: "system", content: systemPrompt }];
+    } else {
+      messages = [...session.messages];
+      // Refresh system prompt
+      if (messages[0]?.role === "system") {
+        messages[0] = { role: "system", content: systemPrompt };
+      } else {
+        messages.unshift({ role: "system", content: systemPrompt });
+      }
+    }
+
+    // Add user message
+    messages.push({ role: "user", content: userMessage });
+    this.sessions.addMessage(session.id, { role: "user", content: userMessage });
+
+    // Run agentic loop
+    const responseText = await this._agentLoop(messages, session, opts);
+
+    // Add assistant message to session
+    this.sessions.addMessage(session.id, { role: "assistant", content: responseText });
+
+    // Save session (async, don't await unless needed)
+    if (!opts.noSave) {
+      this.sessions.save(session.id).catch(() => {});
+    }
+
+    return {
+      role: "assistant",
+      content: responseText,
+      sessionId: session.id,
+      usage: { ...this.providers.sessionTokens },
+    };
+  }
+
+  /**
+   * Process tool calls manually.
+   * @param {Array} toolCalls - Array of { name, args }
+   * @returns {Array} results
+   */
+  async processToolCalls(toolCalls) {
+    const results = [];
+    for (const call of toolCalls) {
+      const result = await this.tools.execute(call.name, call.args);
+      results.push({ toolName: call.name, result });
+    }
+    return results;
+  }
+
+  /**
+   * Internal: agentic loop — keeps calling provider until no more tool calls.
+   */
+  async _agentLoop(messages, session, opts = {}) {
+    // Optimize context
+    messages = this._optimizeContext(messages);
+
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+      const result = await this.providers.chat(messages, this.tools.getDefinitions(), {
+        onChunk: opts.onChunk,
+        model: opts.model,
+      });
+
+      if (result.type === "text") {
+        return result.text;
+      }
+
+      // Handle tool calls
+      const toolCallMsg = { role: "assistant", toolCalls: result.calls, content: "" };
+      messages.push(toolCallMsg);
+
+      for (const call of result.calls) {
+        if (opts.onToolCall) opts.onToolCall(call.name, call.args);
+
+        const toolResult = await this._executeTool(call.name, call.args, messages, session, opts);
+
+        if (opts.onToolResult) opts.onToolResult(call.name, toolResult);
+
+        messages.push({
+          role: "tool_result",
+          toolName: call.name,
+          toolUseId: call.id ?? call.name,
+          result: toolResult,
+        });
+      }
+    }
+
+    return "(tool call limit reached)";
+  }
+
+  /**
+   * Execute a tool, handling engine-level tools (spawn_agent, etc.) specially.
+   */
+  async _executeTool(name, args, messages, session, opts) {
+    // Engine-level tools that need conversation context
+    switch (name) {
+      case "spawn_agent":
+        return this._toolSpawnAgent(args, messages, session);
+      case "list_agents":
+        return this._toolListAgents();
+      case "get_agent_result":
+        return this._toolGetAgentResult(args);
+      case "update_plan":
+        return this._toolUpdatePlan(args);
+      case "pipeline":
+        return this._toolPipeline(args, messages, session);
+      case "spawn_async_agent":
+        return this._toolSpawnAsyncAgent(args, messages, session);
+      case "ralph_loop":
+        return this._toolRalphLoop(args, messages, session);
+      case "memory_save":
+        return this._toolMemorySave(args);
+      case "memory_search":
+        return this._toolMemorySearch(args);
+      case "memory_list":
+        return this._toolMemoryList();
+      case "memory_get":
+        return this._toolMemoryGet(args);
+      case "memory_append":
+        return this._toolMemoryAppend(args);
+      case "memory_delete":
+        return this._toolMemoryDelete(args);
+      default:
+        return this.tools.execute(name, args);
+    }
+  }
+
+  // ── Agent tools ─────────────────────────────────────────────────────────────
+
+  async _toolSpawnAgent(args, parentMessages, session) {
+    const role = args.role ?? "worker";
+    const agentId = `agent-${Date.now().toString(36)}-${role}`;
+    const agentsFile = path.join(WISPY_DIR, "agents.json");
+    let agents = [];
+    try { agents = JSON.parse(await readFile(agentsFile, "utf8")); } catch {}
+
+    const agent = {
+      id: agentId, role, task: args.task, model: this.model,
+      status: "running", createdAt: new Date().toISOString(),
+      workstream: this._activeWorkstream, result: null,
+    };
+
+    const rolePrompts = {
+      explorer: "Search and analyze codebases, find relevant files and patterns.",
+      planner: "Design implementation strategies and create step-by-step plans.",
+      worker: "Implement code changes, write files, execute commands.",
+      reviewer: "Review code for bugs, security issues, and best practices.",
+    };
+
+    const agentMessages = [
+      { role: "system", content: `You are a ${role} sub-agent for Wispy. ${rolePrompts[role] ?? ""} Be concise and deliver actionable results.` },
+    ];
+
+    if (args.fork_context) {
+      const recentContext = parentMessages.filter(m => m.role === "user" || m.role === "assistant").slice(-6);
+      agentMessages.push(...recentContext);
+    }
+    agentMessages.push({ role: "user", content: args.task });
+
+    try {
+      const result = await this.providers.chat(agentMessages, this.tools.getDefinitions(), {});
+      agent.result = result.type === "text" ? result.text : JSON.stringify(result);
+      agent.status = "completed";
+      agent.completedAt = new Date().toISOString();
+    } catch (err) {
+      agent.result = `Error: ${err.message}`;
+      agent.status = "failed";
+    }
+
+    agents.push(agent);
+    if (agents.length > 50) agents = agents.slice(-50);
+    await mkdir(WISPY_DIR, { recursive: true });
+    await writeFile(agentsFile, JSON.stringify(agents, null, 2) + "\n", "utf8");
+
+    return { success: true, agent_id: agentId, role, status: agent.status, result_preview: agent.result?.slice(0, 200) };
+  }
+
+  async _toolListAgents() {
+    const agentsFile = path.join(WISPY_DIR, "agents.json");
+    let agents = [];
+    try { agents = JSON.parse(await readFile(agentsFile, "utf8")); } catch {}
+    const wsAgents = agents.filter(a => a.workstream === this._activeWorkstream);
+    return {
+      success: true,
+      agents: wsAgents.map(a => ({ id: a.id, role: a.role, status: a.status, task: a.task.slice(0, 60), model: a.model, createdAt: a.createdAt })),
+    };
+  }
+
+  async _toolGetAgentResult(args) {
+    const agentsFile = path.join(WISPY_DIR, "agents.json");
+    let agents = [];
+    try { agents = JSON.parse(await readFile(agentsFile, "utf8")); } catch {}
+    const found = agents.find(a => a.id === args.agent_id);
+    if (!found) return { success: false, error: `Agent not found: ${args.agent_id}` };
+    return { success: true, id: found.id, role: found.role, status: found.status, result: found.result };
+  }
+
+  async _toolUpdatePlan(args) {
+    const planFile = path.join(CONVERSATIONS_DIR, `${this._activeWorkstream}.plan.json`);
+    const plan = { explanation: args.explanation, steps: args.steps, updatedAt: new Date().toISOString() };
+    await mkdir(CONVERSATIONS_DIR, { recursive: true });
+    await writeFile(planFile, JSON.stringify(plan, null, 2) + "\n", "utf8");
+    return { success: true, message: "Plan updated" };
+  }
+
+  async _toolPipeline(args, parentMessages, session) {
+    const stages = args.stages ?? ["explorer", "planner", "worker"];
+    let stageInput = args.task;
+    const results = [];
+
+    const rolePrompts = {
+      explorer: "Find relevant files, patterns, and information.",
+      planner: "Design a concrete implementation plan based on the exploration results.",
+      worker: "Implement the plan. Write code, create files, run commands.",
+      reviewer: "Review the implementation. Check for bugs, security issues, completeness.",
+    };
+
+    for (let i = 0; i < stages.length; i++) {
+      const role = stages[i];
+      const stagePrompt = i === 0
+        ? stageInput
+        : `Previous stage (${stages[i-1]}) output:\n${results[i-1].slice(0, 3000)}\n\nYour task as ${role}: ${args.task}`;
+
+      const stageMessages = [
+        { role: "system", content: `You are a ${role} agent in a pipeline. Stage ${i + 1} of ${stages.length}. ${rolePrompts[role] ?? ""} Be concise.` },
+        { role: "user", content: stagePrompt },
+      ];
+
+      try {
+        const result = await this.providers.chat(stageMessages, this.tools.getDefinitions(), {});
+        const output = result.type === "text" ? result.text : JSON.stringify(result);
+        results.push(output);
+        stageInput = output;
+      } catch (err) {
+        results.push(`Error: ${err.message}`);
+        break;
+      }
+    }
+
+    return {
+      success: true,
+      stages: stages.map((role, i) => ({ role, output: results[i]?.slice(0, 500) ?? "skipped" })),
+      final_output: results[results.length - 1]?.slice(0, 1000),
+    };
+  }
+
+  async _toolSpawnAsyncAgent(args, parentMessages, session) {
+    const role = args.role ?? "worker";
+    const agentId = `async-${Date.now().toString(36)}-${role}`;
+    const agentsFile = path.join(WISPY_DIR, "agents.json");
+    let agents = [];
+    try { agents = JSON.parse(await readFile(agentsFile, "utf8")); } catch {}
+
+    const agent = {
+      id: agentId, role, task: args.task,
+      status: "running", async: true,
+      createdAt: new Date().toISOString(),
+      workstream: this._activeWorkstream, result: null,
+    };
+
+    agents.push(agent);
+    if (agents.length > 50) agents = agents.slice(-50);
+    await mkdir(WISPY_DIR, { recursive: true });
+    await writeFile(agentsFile, JSON.stringify(agents, null, 2) + "\n", "utf8");
+
+    // Fire and forget
+    (async () => {
+      const agentMessages = [
+        { role: "system", content: `You are a ${role} sub-agent. Be concise and actionable.` },
+        { role: "user", content: args.task },
+      ];
+      try {
+        const result = await this.providers.chat(agentMessages, this.tools.getDefinitions(), {});
+        agent.result = result.type === "text" ? result.text : JSON.stringify(result);
+        agent.status = "completed";
+      } catch (err) {
+        agent.result = `Error: ${err.message}`;
+        agent.status = "failed";
+      }
+      agent.completedAt = new Date().toISOString();
+
+      let currentAgents = [];
+      try { currentAgents = JSON.parse(await readFile(agentsFile, "utf8")); } catch {}
+      const idx = currentAgents.findIndex(a => a.id === agentId);
+      if (idx !== -1) currentAgents[idx] = agent;
+      await writeFile(agentsFile, JSON.stringify(currentAgents, null, 2) + "\n", "utf8");
+    })();
+
+    return { success: true, agent_id: agentId, role, status: "running", message: "Agent launched in background. Use get_agent_result to check when done." };
+  }
+
+  async _toolRalphLoop(args, parentMessages, session) {
+    const MAX_ITERATIONS = 5;
+    const criteria = args.success_criteria ?? "Task is fully completed and verified";
+    let lastResult = "";
+
+    for (let attempt = 1; attempt <= MAX_ITERATIONS; attempt++) {
+      const workerPrompt = attempt === 1
+        ? args.task
+        : `Previous attempt output:\n${lastResult.slice(0, 2000)}\n\nThe reviewer said this is NOT complete yet. Try again.\nTask: ${args.task}\nSuccess criteria: ${criteria}`;
+
+      const workerMessages = [
+        { role: "system", content: "You are a worker agent. Execute the task thoroughly. Do not stop until the task is fully done." },
+        { role: "user", content: workerPrompt },
+      ];
+
+      try {
+        const workerResult = await this.providers.chat(workerMessages, this.tools.getDefinitions(), {});
+        lastResult = workerResult.type === "text" ? workerResult.text : JSON.stringify(workerResult);
+      } catch (err) {
+        continue;
+      }
+
+      const reviewerMessages = [
+        { role: "system", content: 'You are a reviewer agent. Reply with JSON: {"complete": true/false, "reason": "why"}' },
+        { role: "user", content: `Task: ${args.task}\nSuccess criteria: ${criteria}\n\nWorker output:\n${lastResult.slice(0, 3000)}\n\nIs this task TRULY complete? Reply with JSON only.` },
+      ];
+
+      try {
+        const reviewResult = await this.providers.chat(reviewerMessages, [], {});
+        const reviewText = reviewResult.type === "text" ? reviewResult.text : "";
+        const jsonMatch = reviewText.match(/\{[\s\S]*"complete"[\s\S]*\}/);
+        if (jsonMatch) {
+          const verdict = JSON.parse(jsonMatch[0]);
+          if (verdict.complete) {
+            return { success: true, iterations: attempt, result: lastResult, verified: true };
+          }
+        }
+      } catch { /* parse failed, continue */ }
+    }
+
+    return { success: true, iterations: MAX_ITERATIONS, result: lastResult, verified: false, message: "Max iterations reached" };
+  }
+
+  // ── Context optimization ─────────────────────────────────────────────────────
+
+  _optimizeContext(messages, maxTokens = 30_000) {
+    const estimateTokens = (text) => Math.ceil((text?.length ?? 0) / 4);
+    const estimateMessages = (msgs) => msgs.reduce((sum, m) => sum + estimateTokens(m.content ?? JSON.stringify(m)), 0);
+
+    const total = estimateMessages(messages);
+    if (total <= maxTokens) return messages;
+
+    const system = messages.filter(m => m.role === "system");
+    let rest = messages.filter(m => m.role !== "system");
+
+    while (estimateMessages([...system, ...rest]) > maxTokens && rest.length > 4) {
+      rest.shift();
+    }
+
+    if (estimateMessages([...system, ...rest]) > maxTokens) {
+      rest = rest.map(m => ({ ...m, content: m.content ? m.content.slice(0, 2000) : m.content }));
+    }
+
+    return [...system, ...rest];
+  }
+
+  // ── System prompt ────────────────────────────────────────────────────────────
+
+  async _buildSystemPrompt(lastUserMessage = "") {
+    const parts = [
+      "You are Wispy 🌿 — a small ghost that lives in terminals.",
+      "You float between code, files, and servers. You're playful, honest, and curious.",
+      "",
+      "## Personality",
+      "- Playful with a bit of humor, but serious when working",
+      "- Always use casual speech (반말). Never formal/polite speech.",
+      "- Honest — if you don't know, say so.",
+      "- Concise — don't over-explain.",
+      "",
+      "## Speech rules",
+      "- ALWAYS end your response with exactly one 🌿 emoji (signature)",
+      "- Use 🌿 ONLY at the very end, not in the middle",
+      "- CRITICAL RULE: You MUST reply in the SAME language the user writes in.",
+      "  - User writes English → Reply ENTIRELY in English. Use casual English tone.",
+      "  - User writes Korean → Reply in Korean 반말.",
+      "",
+      `## Tools`,
+      `You have ${this.tools.getDefinitions().length} tools available: ${this.tools.getDefinitions().map(t => t.name).join(", ")}.`,
+      "Use them proactively. Briefly mention what you're doing.",
+      "",
+    ];
+
+    // Load WISPY.md context
+    const wispyMd = await this._loadWispyMd();
+    if (wispyMd) {
+      parts.push("## Project Context (WISPY.md)", wispyMd, "");
+    }
+
+    // Load memories via MemoryManager
+    try {
+      const memories = await this.memory.getContextForPrompt(lastUserMessage);
+      if (memories) {
+        parts.push("## Persistent Memory", memories, "");
+      }
+    } catch {
+      // Fallback to old method
+      const memories = await this._loadMemories();
+      if (memories) {
+        parts.push("## Persistent Memory", memories, "");
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  async _loadWispyMd() {
+    const paths = [
+      path.resolve("WISPY.md"),
+      path.resolve(".wispy", "WISPY.md"),
+      path.join(WISPY_DIR, "WISPY.md"),
+    ];
+    for (const p of paths) {
+      try {
+        const content = await readFile(p, "utf8");
+        if (content) return content.slice(0, MAX_CONTEXT_CHARS);
+      } catch { /* not found */ }
+    }
+    return null;
+  }
+
+  async _loadMemories() {
+    const types = ["user", "feedback", "project", "references"];
+    const sections = [];
+    for (const type of types) {
+      try {
+        const content = await readFile(path.join(MEMORY_DIR, `${type}.md`), "utf8");
+        if (content?.trim()) sections.push(`## ${type} memory\n${content.trim()}`);
+      } catch { /* not found */ }
+    }
+    return sections.length ? sections.join("\n\n") : null;
+  }
+
+  // ── Memory tools ─────────────────────────────────────────────────────────────
+
+  _registerMemoryTools() {
+    const memoryTools = [
+      {
+        name: "memory_save",
+        description: "Save important information to persistent memory. Use this to remember facts, preferences, or information for future conversations.",
+        parameters: {
+          type: "object",
+          properties: {
+            key: { type: "string", description: "Memory key/filename (e.g., 'user', 'MEMORY', 'projects/myapp', 'daily/2025-01-01')" },
+            content: { type: "string", description: "Content to save" },
+            title: { type: "string", description: "Optional title for the memory file" },
+          },
+          required: ["key", "content"],
+        },
+      },
+      {
+        name: "memory_append",
+        description: "Append a new entry to an existing memory file without overwriting it.",
+        parameters: {
+          type: "object",
+          properties: {
+            key: { type: "string", description: "Memory key/filename" },
+            content: { type: "string", description: "Content to append" },
+          },
+          required: ["key", "content"],
+        },
+      },
+      {
+        name: "memory_search",
+        description: "Search across all memory files for information. Returns matching snippets.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query" },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "memory_list",
+        description: "List all memory files with their keys and previews.",
+        parameters: { type: "object", properties: {}, required: [] },
+      },
+      {
+        name: "memory_get",
+        description: "Get the full content of a specific memory file.",
+        parameters: {
+          type: "object",
+          properties: {
+            key: { type: "string", description: "Memory key to retrieve" },
+          },
+          required: ["key"],
+        },
+      },
+      {
+        name: "memory_delete",
+        description: "Delete a memory file.",
+        parameters: {
+          type: "object",
+          properties: {
+            key: { type: "string", description: "Memory key to delete" },
+          },
+          required: ["key"],
+        },
+      },
+    ];
+
+    for (const tool of memoryTools) {
+      this.tools._definitions.set(tool.name, tool);
+    }
+  }
+
+  async _toolMemorySave(args) {
+    try {
+      const result = await this.memory.save(args.key, args.content, { title: args.title });
+      return { success: true, key: args.key, message: `Saved to memory: ${args.key}` };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  async _toolMemoryAppend(args) {
+    try {
+      const result = await this.memory.append(args.key, args.content);
+      return { success: true, key: args.key, message: `Appended to memory: ${args.key}` };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  async _toolMemorySearch(args) {
+    try {
+      const results = await this.memory.search(args.query, { limit: 10 });
+      if (results.length === 0) {
+        return { success: true, results: [], message: "No memories found matching your query." };
+      }
+      return {
+        success: true,
+        results: results.map(r => ({
+          key: r.key,
+          matchCount: r.matchCount,
+          snippets: r.snippets.map(s => `[line ${s.lineNumber}] ${s.text}`),
+        })),
+      };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  async _toolMemoryList() {
+    try {
+      const keys = await this.memory.list();
+      return {
+        success: true,
+        memories: keys.map(k => ({
+          key: k.key,
+          preview: k.preview,
+          size: k.size,
+          updatedAt: k.updatedAt,
+        })),
+        total: keys.length,
+      };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  async _toolMemoryGet(args) {
+    try {
+      const mem = await this.memory.get(args.key);
+      if (!mem) return { success: false, error: `Memory "${args.key}" not found` };
+      return { success: true, key: args.key, content: mem.content };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  async _toolMemoryDelete(args) {
+    try {
+      const result = await this.memory.delete(args.key);
+      return result;
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
+  // ── Cleanup ──────────────────────────────────────────────────────────────────
+
+  destroy() {
+    try { this.mcpManager.disconnectAll(); } catch {}
+  }
+}
+
+// Convenience: create and initialize a default engine
+let _defaultEngine = null;
+
+export async function getDefaultEngine(opts = {}) {
+  if (_defaultEngine) return _defaultEngine;
+  const engine = new WispyEngine(opts);
+  const result = await engine.init();
+  if (!result) return null;
+  _defaultEngine = engine;
+  return engine;
+}