wispy-cli 0.6.0 → 0.7.0

package/bin/wispy.mjs

@@ -81,11 +81,10 @@ if (serveMode || telegramMode || discordMode || slackMode) {
   process.on("SIGINT",  async () => { await manager.stopAll(); process.exit(0); });
   process.on("SIGTERM", async () => { await manager.stopAll(); process.exit(0); });
 
-  // Prevent Node from exiting (adapters keep their own event loops)
-  // but we still need something to hold the process open in case adapters
-  // don't (e.g. Telegram stops after connection error).
+  // Prevent Node from exiting
   setInterval(() => {}, 60_000);
-  return;
+  // eslint-disable-next-line no-constant-condition
+  await new Promise(() => {}); // keep alive
 }
 
 // ── TUI mode ──────────────────────────────────────────────────────────────────

package/core/config.mjs

@@ -0,0 +1,104 @@
+/**
+ * core/config.mjs — Centralized config loader for Wispy
+ *
+ * Loads ~/.wispy/config.json, ~/.wispy/channels.json
+ * Handles provider API key detection from env + macOS Keychain
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+
+export const WISPY_DIR = path.join(os.homedir(), ".wispy");
+export const CONFIG_PATH = path.join(WISPY_DIR, "config.json");
+export const CHANNELS_CONFIG_PATH = path.join(WISPY_DIR, "channels.json");
+export const MCP_CONFIG_PATH = path.join(WISPY_DIR, "mcp.json");
+export const SESSIONS_DIR = path.join(WISPY_DIR, "sessions");
+export const CONVERSATIONS_DIR = path.join(WISPY_DIR, "conversations");
+export const MEMORY_DIR = path.join(WISPY_DIR, "memory");
+
+export const PROVIDERS = {
+  google:    { envKeys: ["GOOGLE_AI_KEY", "GEMINI_API_KEY"], defaultModel: "gemini-2.5-flash", label: "Google AI (Gemini)", signupUrl: "https://aistudio.google.com/apikey" },
+  anthropic: { envKeys: ["ANTHROPIC_API_KEY"], defaultModel: "claude-sonnet-4-20250514", label: "Anthropic (Claude)", signupUrl: "https://console.anthropic.com/settings/keys" },
+  openai:    { envKeys: ["OPENAI_API_KEY"], defaultModel: "gpt-4o", label: "OpenAI", signupUrl: "https://platform.openai.com/api-keys" },
+  openrouter:{ envKeys: ["OPENROUTER_API_KEY"], defaultModel: "anthropic/claude-sonnet-4-20250514", label: "OpenRouter (multi-model)", signupUrl: "https://openrouter.ai/keys" },
+  groq:      { envKeys: ["GROQ_API_KEY"], defaultModel: "llama-3.3-70b-versatile", label: "Groq (fast inference)", signupUrl: "https://console.groq.com/keys" },
+  deepseek:  { envKeys: ["DEEPSEEK_API_KEY"], defaultModel: "deepseek-chat", label: "DeepSeek", signupUrl: "https://platform.deepseek.com/api_keys" },
+  ollama:    { envKeys: ["OLLAMA_HOST"], defaultModel: "llama3.2", label: "Ollama (local)", signupUrl: null, local: true },
+};
+
+async function tryKeychainKey(service) {
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const exec = promisify(execFile);
+    const { stdout } = await exec("security", ["find-generic-password", "-s", service, "-a", "poropo", "-w"], { timeout: 3000 });
+    return stdout.trim() || null;
+  } catch { return null; }
+}
+
+function getEnvKey(envKeys) {
+  for (const k of envKeys) {
+    if (process.env[k]) return process.env[k];
+  }
+  return null;
+}
+
+export async function loadConfig() {
+  await mkdir(WISPY_DIR, { recursive: true });
+  let fileConfig = {};
+  try {
+    fileConfig = JSON.parse(await readFile(CONFIG_PATH, "utf8"));
+  } catch { /* no config */ }
+  return fileConfig;
+}
+
+export async function saveConfig(config) {
+  await mkdir(WISPY_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+export async function detectProvider() {
+  // 1. WISPY_PROVIDER env override
+  const forced = process.env.WISPY_PROVIDER;
+  if (forced && PROVIDERS[forced]) {
+    const key = getEnvKey(PROVIDERS[forced].envKeys);
+    if (key || PROVIDERS[forced].local) {
+      return { provider: forced, key, model: process.env.WISPY_MODEL ?? PROVIDERS[forced].defaultModel };
+    }
+  }
+
+  // 2. Config file
+  const cfg = await loadConfig();
+  if (cfg.provider && PROVIDERS[cfg.provider]) {
+    const key = getEnvKey(PROVIDERS[cfg.provider].envKeys) ?? cfg.apiKey;
+    if (key || PROVIDERS[cfg.provider].local) {
+      return { provider: cfg.provider, key, model: cfg.model ?? PROVIDERS[cfg.provider].defaultModel };
+    }
+  }
+
+  // 3. Auto-detect from env vars
+  const order = ["google", "anthropic", "openai", "openrouter", "groq", "deepseek", "ollama"];
+  for (const p of order) {
+    const key = getEnvKey(PROVIDERS[p].envKeys);
+    if (key || (p === "ollama" && process.env.OLLAMA_HOST)) {
+      return { provider: p, key, model: process.env.WISPY_MODEL ?? PROVIDERS[p].defaultModel };
+    }
+  }
+
+  // 4. macOS Keychain
+  const keychainMap = [
+    ["google-ai-key", "google"],
+    ["anthropic-api-key", "anthropic"],
+    ["openai-api-key", "openai"],
+  ];
+  for (const [service, provider] of keychainMap) {
+    const key = await tryKeychainKey(service);
+    if (key) {
+      process.env[PROVIDERS[provider].envKeys[0]] = key;
+      return { provider, key, model: process.env.WISPY_MODEL ?? PROVIDERS[provider].defaultModel };
+    }
+  }
+
+  return null;
+}

package/core/engine.mjs

@@ -0,0 +1,532 @@
+/**
+ * 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";
+
+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._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();
+
+    // 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);
+      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
+    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;
+  }
+
+  // ── 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;
+}

package/core/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * core/index.mjs — Public API for wispy-core
+ *
+ * All surfaces (CLI, TUI, channels) import from here.
+ */
+
+export { WispyEngine, getDefaultEngine } from "./engine.mjs";
+export { SessionManager, Session, sessionManager } from "./session.mjs";
+export { ProviderRegistry } from "./providers.mjs";
+export { ToolRegistry } from "./tools.mjs";
+export { MCPClient, MCPManager, ensureDefaultMcpConfig } from "./mcp.mjs";
+export { loadConfig, saveConfig, detectProvider, PROVIDERS, WISPY_DIR, MCP_CONFIG_PATH, SESSIONS_DIR, CONVERSATIONS_DIR, MEMORY_DIR } from "./config.mjs";

package/core/mcp.mjs

@@ -0,0 +1,8 @@
+/**
+ * core/mcp.mjs — MCP client (re-export from lib/mcp-client.mjs)
+ *
+ * MCPClient and MCPManager are moved here as the canonical location.
+ * lib/mcp-client.mjs remains as a backward-compatible re-export.
+ */
+
+export { MCPClient, MCPManager, ensureDefaultMcpConfig } from "../lib/mcp-client.mjs";