wispy-cli 0.1.0

package/lib/wispy-repl.mjs

@@ -0,0 +1,2105 @@
+#!/usr/bin/env node
+
+/**
+ * wispy — interactive AI assistant REPL
+ *
+ * Usage:
+ *   wispy                    Start interactive session
+ *   wispy "message"          One-shot message
+ *   wispy home <subcommand>  Operator commands (legacy CLI)
+ *
+ * Requires: OPENAI_API_KEY in env
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const WISPY_DIR = path.join(os.homedir(), ".wispy");
+const MEMORY_DIR = path.join(WISPY_DIR, "memory");
+
+// Workstream-aware conversation storage
+// wispy -w "project-name" → separate conversation per workstream
+const ACTIVE_WORKSTREAM = process.env.WISPY_WORKSTREAM ??
+  process.argv.find((a, i) => (process.argv[i-1] === "-w" || process.argv[i-1] === "--workstream")) ?? "default";
+const CONVERSATIONS_DIR = path.join(WISPY_DIR, "conversations");
+const HISTORY_FILE = path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.json`);
+
+// ---------------------------------------------------------------------------
+// Multi-provider config with auto-detection & setup guidance
+// ---------------------------------------------------------------------------
+
+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 },
+};
+
+// Also try macOS Keychain for keys
+async function tryKeychainKey(service) {
+  try {
+    const { execFile: ef } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const exec = promisify(ef);
+    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;
+}
+
+// Detect provider — env var, then config file, then keychain
+async function detectProvider() {
+  // 1. Check 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. Check config file
+  const configPath = path.join(WISPY_DIR, "config.json");
+  try {
+    const cfg = JSON.parse(await readFile(configPath, "utf8"));
+    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 };
+    }
+  } catch { /* no config */ }
+
+  // 3. Auto-detect from env vars (priority order)
+  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. Try macOS Keychain
+  const keychainMap = { "google-ai-key": "google", "anthropic-api-key": "anthropic", "openai-api-key": "openai" };
+  for (const [service, provider] of Object.entries(keychainMap)) {
+    const key = await tryKeychainKey(service);
+    if (key) {
+      // Set env for later use
+      process.env[PROVIDERS[provider].envKeys[0]] = key;
+      return { provider, key, model: process.env.WISPY_MODEL ?? PROVIDERS[provider].defaultModel };
+    }
+  }
+
+  return null;
+}
+
+function printSetupGuide() {
+  console.log(`
+${bold("🌿 Wispy — API key setup")}
+
+${bold("Supported providers:")}
+${Object.entries(PROVIDERS).map(([id, p]) => {
+  const envStr = p.envKeys.join(" or ");
+  const url = p.signupUrl ? dim(p.signupUrl) : dim("(local)");
+  return `  ${green(id.padEnd(12))} ${p.label}\n    env: ${envStr}\n    ${url}`;
+}).join("\n\n")}
+
+${bold("Quick start (pick one):")}
+  ${cyan("export GOOGLE_AI_KEY=your-key")}      ${dim("# free tier available")}
+  ${cyan("export ANTHROPIC_API_KEY=your-key")}   ${dim("# Claude")}
+  ${cyan("export OPENAI_API_KEY=your-key")}      ${dim("# GPT-4o")}
+  ${cyan("export OPENROUTER_API_KEY=your-key")}  ${dim("# any model")}
+
+${bold("Or save to config:")}
+  ${cyan('wispy config set provider google --global')}
+  ${cyan('wispy config set apiKey your-key --global')}
+
+${bold("macOS Keychain (auto-detected):")}
+  ${dim('security add-generic-password -s "google-ai-key" -a "poropo" -w "your-key"')}
+`);
+}
+
+const detected = await detectProvider();
+const PROVIDER = detected?.provider ?? "none";
+const API_KEY = detected?.key ?? null;
+const MODEL = detected?.model ?? "unknown";
+const MAX_CONTEXT_CHARS = 40_000;
+
+// ---------------------------------------------------------------------------
+// Colors (minimal, no deps)
+// ---------------------------------------------------------------------------
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+
+async function readFileOr(filePath, fallback = null) {
+  try { return await readFile(filePath, "utf8"); } catch { return fallback; }
+}
+
+async function loadWispyMd() {
+  const paths = [
+    path.resolve("WISPY.md"),
+    path.resolve(".wispy", "WISPY.md"),
+    path.join(WISPY_DIR, "WISPY.md"),
+  ];
+  for (const p of paths) {
+    const content = await readFileOr(p);
+    if (content) return content.slice(0, MAX_CONTEXT_CHARS);
+  }
+  return null;
+}
+
+async function loadMemories() {
+  const types = ["user", "feedback", "project", "references"];
+  const sections = [];
+  for (const type of types) {
+    const content = await readFileOr(path.join(MEMORY_DIR, `${type}.md`));
+    if (content?.trim()) {
+      sections.push(`## ${type} memory\n${content.trim()}`);
+    }
+  }
+  return sections.length ? sections.join("\n\n") : null;
+}
+
+async function loadConversation() {
+  const raw = await readFileOr(HISTORY_FILE);
+  if (!raw) return [];
+  try { return JSON.parse(raw); } catch { return []; }
+}
+
+async function saveConversation(messages) {
+  await mkdir(CONVERSATIONS_DIR, { recursive: true });
+  // Keep last 50 messages to prevent unbounded growth
+  const trimmed = messages.slice(-50);
+  await writeFile(HISTORY_FILE, JSON.stringify(trimmed, null, 2) + "\n", "utf8");
+}
+
+async function listWorkstreams() {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(CONVERSATIONS_DIR);
+    return files
+      .filter(f => f.endsWith(".json"))
+      .map(f => f.replace(".json", ""));
+  } catch { return []; }
+}
+
+async function loadWorkstreamConversation(wsName) {
+  try {
+    const wsPath = path.join(CONVERSATIONS_DIR, `${wsName}.json`);
+    const raw = await readFile(wsPath, "utf8");
+    return JSON.parse(raw);
+  } catch { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Director mode — overview across all workstreams
+// ---------------------------------------------------------------------------
+
+async function showOverview() {
+  const wsList = await listWorkstreams();
+  if (wsList.length === 0) {
+    console.log(dim("No workstreams yet. Start one: wispy -w <name> \"message\""));
+    return;
+  }
+
+  console.log(`\n${bold("🌿 Wispy Director — All Workstreams")}\n`);
+
+  let totalMsgs = 0;
+  let totalToolCalls = 0;
+  const summaries = [];
+
+  for (const ws of wsList) {
+    const conv = await loadWorkstreamConversation(ws);
+    const userMsgs = conv.filter(m => m.role === "user");
+    const assistantMsgs = conv.filter(m => m.role === "assistant");
+    const toolResults = conv.filter(m => m.role === "tool_result");
+    const lastUser = userMsgs[userMsgs.length - 1];
+    const lastAssistant = assistantMsgs[assistantMsgs.length - 1];
+
+    totalMsgs += userMsgs.length;
+    totalToolCalls += toolResults.length;
+
+    const isActive = ws === ACTIVE_WORKSTREAM;
+    const marker = isActive ? green("● ") : "  ";
+    const label = isActive ? green(ws) : ws;
+
+    console.log(`${marker}${bold(label)}`);
+    console.log(`    Messages: ${userMsgs.length} user / ${assistantMsgs.length} assistant / ${toolResults.length} tool calls`);
+    if (lastUser) {
+      console.log(`    Last request: ${dim(lastUser.content.slice(0, 60))}${lastUser.content.length > 60 ? "..." : ""}`);
+    }
+    if (lastAssistant) {
+      console.log(`    Last response: ${dim(lastAssistant.content.slice(0, 60))}${lastAssistant.content.length > 60 ? "..." : ""}`);
+    }
+    console.log("");
+
+    summaries.push({ ws, userCount: userMsgs.length, toolCount: toolResults.length, lastMsg: lastUser?.content ?? "" });
+  }
+
+  console.log(dim(`─────────────────────────────────`));
+  console.log(`  ${bold("Total")}: ${wsList.length} workstreams, ${totalMsgs} messages, ${totalToolCalls} tool calls`);
+  console.log(dim(`  Active: ${ACTIVE_WORKSTREAM}`));
+  console.log(dim(`  Switch: wispy -w <name>`));
+  console.log("");
+}
+
+async function searchAcrossWorkstreams(query) {
+  const wsList = await listWorkstreams();
+  const lowerQuery = query.toLowerCase();
+  let totalMatches = 0;
+
+  console.log(`\n${bold("🔍 Searching all workstreams for:")} ${cyan(query)}\n`);
+
+  for (const ws of wsList) {
+    const conv = await loadWorkstreamConversation(ws);
+    const matches = conv.filter(m =>
+      (m.role === "user" || m.role === "assistant") &&
+      m.content?.toLowerCase().includes(lowerQuery)
+    );
+
+    if (matches.length > 0) {
+      console.log(`  ${bold(ws)} (${matches.length} matches):`);
+      for (const m of matches.slice(-3)) { // Show last 3 matches
+        const role = m.role === "user" ? "👤" : "🌿";
+        const preview = m.content.slice(0, 80).replace(/\n/g, " ");
+        console.log(`    ${role} ${dim(preview)}${m.content.length > 80 ? "..." : ""}`);
+      }
+      console.log("");
+      totalMatches += matches.length;
+    }
+  }
+
+  if (totalMatches === 0) {
+    console.log(dim(`  No matches found for "${query}"`));
+  } else {
+    console.log(dim(`  ${totalMatches} total matches across ${wsList.length} workstreams`));
+  }
+  console.log("");
+}
+
+async function appendToMemory(type, entry) {
+  await mkdir(MEMORY_DIR, { recursive: true });
+  const ts = new Date().toISOString().slice(0, 16);
+  await appendFile(path.join(MEMORY_DIR, `${type}.md`), `\n- [${ts}] ${entry}\n`, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// System prompt builder
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Token / cost tracking
+// ---------------------------------------------------------------------------
+
+let sessionTokens = { input: 0, output: 0 };
+
+function estimateTokens(text) {
+  // Rough estimate: ~4 chars per token
+  return Math.ceil((text?.length ?? 0) / 4);
+}
+
+// Model pricing database (per 1M tokens)
+const MODEL_PRICING = {
+  // Google
+  "gemini-2.5-flash":   { input: 0.15,  output: 0.60,  tier: "cheap" },
+  "gemini-2.5-pro":     { input: 1.25,  output: 10.0,  tier: "mid" },
+  "gemini-2.0-flash":   { input: 0.10,  output: 0.40,  tier: "cheap" },
+  // Anthropic
+  "claude-sonnet-4-20250514": { input: 3.0, output: 15.0, tier: "mid" },
+  "claude-opus-4-6":    { input: 15.0,  output: 75.0,  tier: "expensive" },
+  "claude-haiku-3.5":   { input: 0.80,  output: 4.0,   tier: "cheap" },
+  // OpenAI
+  "gpt-4o":             { input: 2.50,  output: 10.0,  tier: "mid" },
+  "gpt-4o-mini":        { input: 0.15,  output: 0.60,  tier: "cheap" },
+  "gpt-4.1":            { input: 2.0,   output: 8.0,   tier: "mid" },
+  "gpt-4.1-mini":       { input: 0.40,  output: 1.60,  tier: "cheap" },
+  "gpt-4.1-nano":       { input: 0.10,  output: 0.40,  tier: "cheap" },
+  "o4-mini":            { input: 1.10,  output: 4.40,  tier: "mid" },
+  // OpenRouter (pass-through, estimate)
+  "anthropic/claude-sonnet-4-20250514": { input: 3.0, output: 15.0, tier: "mid" },
+  // Groq (fast, cheap)
+  "llama-3.3-70b-versatile": { input: 0.59, output: 0.79, tier: "cheap" },
+  // DeepSeek
+  "deepseek-chat":      { input: 0.27,  output: 1.10,  tier: "cheap" },
+  // Ollama (free)
+  "llama3.2":           { input: 0,     output: 0,     tier: "free" },
+};
+
+function getModelPricing(modelName) {
+  return MODEL_PRICING[modelName] ?? { input: 1.0, output: 3.0, tier: "unknown" };
+}
+
+function formatCost() {
+  const pricing = getModelPricing(MODEL);
+  const cost = (sessionTokens.input * pricing.input + sessionTokens.output * pricing.output) / 1_000_000;
+  return `${sessionTokens.input + sessionTokens.output} tokens (~$${cost.toFixed(4)})`;
+}
+
+// ---------------------------------------------------------------------------
+// Task-aware model routing — pick cheapest model for the job
+// ---------------------------------------------------------------------------
+
+const TASK_MODEL_MAP = {
+  // Simple tasks → cheapest model
+  simple:    { google: "gemini-2.5-flash", anthropic: "claude-haiku-3.5", openai: "gpt-4.1-nano", groq: "llama-3.3-70b-versatile" },
+  // Complex tasks → mid-tier
+  complex:   { google: "gemini-2.5-pro",   anthropic: "claude-sonnet-4-20250514", openai: "gpt-4o", groq: "llama-3.3-70b-versatile" },
+  // Critical tasks → best available
+  critical:  { google: "gemini-2.5-pro",   anthropic: "claude-opus-4-6", openai: "gpt-4o", groq: "llama-3.3-70b-versatile" },
+};
+
+function classifyTaskComplexity(prompt) {
+  const lower = prompt.toLowerCase();
+
+  // Critical: code review, architecture, security, debugging complex issues
+  if (/architect|security|review.*code|refactor|debug.*complex|design.*system/i.test(lower)) return "critical";
+
+  // Complex: code writing, analysis, multi-step reasoning
+  if (/write.*code|implement|analyze|compare|explain.*detail|create.*plan|build/i.test(lower)) return "complex";
+
+  // Simple: questions, formatting, translation, simple file ops
+  return "simple";
+}
+
+function getOptimalModel(prompt) {
+  // If user explicitly set a model, respect it
+  if (process.env.WISPY_MODEL) return process.env.WISPY_MODEL;
+
+  const complexity = classifyTaskComplexity(prompt);
+  const taskModels = TASK_MODEL_MAP[complexity];
+  return taskModels[PROVIDER] ?? MODEL;
+}
+
+// ---------------------------------------------------------------------------
+// Budget management (per-workstream)
+// ---------------------------------------------------------------------------
+
+const BUDGET_FILE = path.join(WISPY_DIR, "budgets.json");
+
+async function loadBudgets() {
+  try {
+    return JSON.parse(await readFile(BUDGET_FILE, "utf8"));
+  } catch { return {}; }
+}
+
+async function saveBudgets(budgets) {
+  await mkdir(WISPY_DIR, { recursive: true });
+  await writeFile(BUDGET_FILE, JSON.stringify(budgets, null, 2) + "\n", "utf8");
+}
+
+async function trackSpending(workstream, inputTokens, outputTokens, modelName) {
+  const budgets = await loadBudgets();
+  if (!budgets[workstream]) budgets[workstream] = { limitUsd: null, spentUsd: 0, totalTokens: 0 };
+
+  const pricing = getModelPricing(modelName);
+  const cost = (inputTokens * pricing.input + outputTokens * pricing.output) / 1_000_000;
+  budgets[workstream].spentUsd += cost;
+  budgets[workstream].totalTokens += inputTokens + outputTokens;
+  await saveBudgets(budgets);
+
+  // Check budget limit
+  if (budgets[workstream].limitUsd !== null && budgets[workstream].spentUsd > budgets[workstream].limitUsd) {
+    return { overBudget: true, spent: budgets[workstream].spentUsd, limit: budgets[workstream].limitUsd };
+  }
+  return { overBudget: false, spent: budgets[workstream].spentUsd };
+}
+
+// ---------------------------------------------------------------------------
+// Context window optimization — compact messages to fit token budget
+// ---------------------------------------------------------------------------
+
+function estimateMessagesTokens(messages) {
+  return messages.reduce((sum, m) => sum + estimateTokens(m.content ?? JSON.stringify(m)), 0);
+}
+
+function optimizeContext(messages, maxTokens = 30_000) {
+  const total = estimateMessagesTokens(messages);
+  if (total <= maxTokens) return messages; // fits, no optimization needed
+
+  // Strategy: keep system prompt + last N messages, summarize old ones
+  const system = messages.filter(m => m.role === "system");
+  const rest = messages.filter(m => m.role !== "system");
+
+  // Keep removing oldest messages until we fit
+  let optimized = [...rest];
+  while (estimateMessagesTokens([...system, ...optimized]) > maxTokens && optimized.length > 4) {
+    optimized.shift(); // remove oldest
+  }
+
+  // If still too big, truncate message contents
+  if (estimateMessagesTokens([...system, ...optimized]) > maxTokens) {
+    optimized = optimized.map(m => ({
+      ...m,
+      content: m.content ? m.content.slice(0, 2000) : m.content,
+    }));
+  }
+
+  return [...system, ...optimized];
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions (Gemini function calling format)
+// ---------------------------------------------------------------------------
+
+const TOOL_DEFINITIONS = [
+  {
+    name: "read_file",
+    description: "Read the contents of a file at the given path",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path to read" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "write_file",
+    description: "Write content to a file, creating it if it doesn't exist",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "File path to write" },
+        content: { type: "string", description: "Content to write" },
+      },
+      required: ["path", "content"],
+    },
+  },
+  {
+    name: "run_command",
+    description: "Execute a shell command and return stdout/stderr",
+    parameters: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "Shell command to execute" },
+      },
+      required: ["command"],
+    },
+  },
+  {
+    name: "list_directory",
+    description: "List files and directories at the given path",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path (default: current dir)" },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "web_search",
+    description: "Search the web and return results",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "spawn_agent",
+    description: "Spawn a sub-agent for a well-scoped task. Use for sidecar tasks that can run in parallel. Do NOT spawn for the immediate blocking step — do that yourself. Each agent gets its own context. Prefer concrete, bounded tasks with clear deliverables.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Concrete task description for the sub-agent" },
+        role: {
+          type: "string",
+          enum: ["explorer", "planner", "worker", "reviewer"],
+          description: "explorer=codebase search, planner=strategy design, worker=implementation, reviewer=code review/QA",
+        },
+        model_tier: {
+          type: "string",
+          enum: ["cheap", "mid", "expensive"],
+          description: "cheap for simple tasks, mid for coding, expensive for critical analysis. Default: auto based on role",
+        },
+        fork_context: { type: "boolean", description: "If true, copy current conversation context to the sub-agent" },
+      },
+      required: ["task", "role"],
+    },
+  },
+  {
+    name: "list_agents",
+    description: "List all running/completed sub-agents and their status",
+    parameters: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_agent_result",
+    description: "Get the result from a completed sub-agent",
+    parameters: {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "ID of the sub-agent" },
+      },
+      required: ["agent_id"],
+    },
+  },
+  {
+    name: "update_plan",
+    description: "Create or update a step-by-step plan for the current task. Use to track progress.",
+    parameters: {
+      type: "object",
+      properties: {
+        explanation: { type: "string", description: "Brief explanation of the plan" },
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              step: { type: "string" },
+              status: { type: "string", enum: ["pending", "in_progress", "completed", "skipped"] },
+            },
+          },
+          description: "List of plan steps with status",
+        },
+      },
+      required: ["steps"],
+    },
+  },
+  {
+    name: "pipeline",
+    description: "Run a sequential pipeline of agent roles. Each stage's output feeds into the next. Example: explore→planner→worker→reviewer. Use for complex multi-step tasks that need different specialists in sequence.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "The overall task to accomplish" },
+        stages: {
+          type: "array",
+          items: { type: "string", enum: ["explorer", "planner", "worker", "reviewer"] },
+          description: "Ordered list of agent roles to chain",
+        },
+      },
+      required: ["task", "stages"],
+    },
+  },
+  {
+    name: "spawn_async_agent",
+    description: "Spawn a sub-agent that runs in the background. Returns immediately with an agent_id. Check results later with get_agent_result. Use for sidecar tasks while you continue working on the main task.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task for the background agent" },
+        role: { type: "string", enum: ["explorer", "planner", "worker", "reviewer"], description: "Agent role" },
+      },
+      required: ["task", "role"],
+    },
+  },
+  {
+    name: "ralph_loop",
+    description: "Persistence mode — keep retrying a task until it's verified complete. The worker agent executes, then a reviewer verifies. If not done, worker tries again. Max 5 iterations. Use for tasks that MUST be completed correctly.",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "Task that must be completed" },
+        success_criteria: { type: "string", description: "How to verify the task is truly done" },
+      },
+      required: ["task"],
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Tool execution
+// ---------------------------------------------------------------------------
+
+// Try server API first, fallback to local execution
+async function executeToolViaServer(name, args) {
+  try {
+    const serverUrl = `http://127.0.0.1:${DEFAULT_SERVER_PORT}`;
+
+    if (name === "read_file") {
+      const resp = await fetch(`${serverUrl}/api/node-filesystem-actions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ subAction: "read_file", path: args.path }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      const data = await resp.json();
+      if (data.success) return { success: true, content: data.data?.slice(0, 10_000) ?? "" };
+      // Fallback to local if server rejects path
+      return null;
+    }
+
+    if (name === "write_file") {
+      const resp = await fetch(`${serverUrl}/api/node-filesystem-actions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ subAction: "write_file", path: args.path, content: args.content }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      const data = await resp.json();
+      if (data.success) return { success: true, message: `Written to ${args.path} (via server)` };
+      return null;
+    }
+
+    if (name === "list_directory") {
+      const resp = await fetch(`${serverUrl}/api/node-filesystem-actions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ subAction: "list_dir", path: args.path || "." }),
+        signal: AbortSignal.timeout(10_000),
+      });
+      const data = await resp.json();
+      if (data.success && data.entries) {
+        const listing = data.entries.map(e => `${e.isDir ? "📁" : "📄"} ${e.name}`).join("\n");
+        return { success: true, listing };
+      }
+      return null;
+    }
+  } catch {
+    // Server not available, fallback to local
+    return null;
+  }
+  return null; // Not handled by server
+}
+
+async function executeTool(name, args) {
+  // Try server first (sandboxed execution)
+  const serverResult = await executeToolViaServer(name, args);
+  if (serverResult) return serverResult;
+
+  const { execFile } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  const execAsync = promisify(execFile);
+
+  try {
+    switch (name) {
+      case "read_file": {
+        const filePath = args.path.replace(/^~/, os.homedir());
+        const content = await readFile(filePath, "utf8");
+        // Truncate large files
+        const truncated = content.length > 10_000
+          ? content.slice(0, 10_000) + `\n\n... (truncated, ${content.length} chars total)`
+          : content;
+        return { success: true, content: truncated };
+      }
+
+      case "write_file": {
+        args.path = args.path.replace(/^~/, os.homedir());
+        const dir = path.dirname(args.path);
+        await mkdir(dir, { recursive: true });
+        await writeFile(args.path, args.content, "utf8");
+        return { success: true, message: `Written ${args.content.length} chars to ${args.path}` };
+      }
+
+      case "run_command": {
+        console.log(dim(`  $ ${args.command}`));
+        const { stdout, stderr } = await execAsync("/bin/bash", ["-c", args.command], {
+          timeout: 30_000,
+          maxBuffer: 1024 * 1024,
+          cwd: process.cwd(),
+        });
+        const result = (stdout + (stderr ? `\nSTDERR: ${stderr}` : "")).trim();
+        const truncated = result.length > 5_000
+          ? result.slice(0, 5_000) + "\n... (truncated)"
+          : result;
+        return { success: true, output: truncated };
+      }
+
+      case "list_directory": {
+        const { readdir } = await import("node:fs/promises");
+        const targetPath = (args.path || ".").replace(/^~/, os.homedir());
+        const entries = await readdir(targetPath, { withFileTypes: true });
+        const list = entries.map(e => `${e.isDirectory() ? "📁" : "📄"} ${e.name}`).join("\n");
+        return { success: true, listing: list };
+      }
+
+      case "web_search": {
+        const { promisify } = await import("node:util");
+        const { execFile: ef } = await import("node:child_process");
+        const execP = promisify(ef);
+
+        // Try DuckDuckGo Lite first (lighter HTML, easier to parse)
+        const encoded = encodeURIComponent(args.query);
+        try {
+          const { stdout: html } = await execP("/usr/bin/curl", [
+            "-sL", "--max-time", "10",
+            "-H", "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+            `https://lite.duckduckgo.com/lite/?q=${encoded}`,
+          ], { timeout: 15_000 });
+
+          // Parse DuckDuckGo Lite results
+          const snippets = [];
+          // Match result links and snippets
+          const linkRegex = /<a[^>]*class="result-link"[^>]*>(.*?)<\/a>/gs;
+          const snippetRegex = /<td class="result-snippet">(.*?)<\/td>/gs;
+
+          const links = [];
+          let m;
+          while ((m = linkRegex.exec(html)) !== null) links.push(m[1].replace(/<[^>]+>/g, "").trim());
+
+          const snips = [];
+          while ((m = snippetRegex.exec(html)) !== null) snips.push(m[1].replace(/<[^>]+>/g, "").trim());
+
+          for (let i = 0; i < Math.min(links.length, 5); i++) {
+            const snippet = snips[i] ? `${links[i]}\n${snips[i]}` : links[i];
+            if (snippet) snippets.push(snippet);
+          }
+
+          if (snippets.length > 0) {
+            return { success: true, results: snippets.join("\n\n") };
+          }
+
+          // Fallback: extract any text content from result cells
+          const cellRegex = /<td[^>]*>(.*?)<\/td>/gs;
+          const cells = [];
+          while ((m = cellRegex.exec(html)) !== null && cells.length < 10) {
+            const text = m[1].replace(/<[^>]+>/g, "").trim();
+            if (text.length > 20) cells.push(text);
+          }
+          if (cells.length > 0) {
+            return { success: true, results: cells.slice(0, 5).join("\n\n") };
+          }
+        } catch { /* fallback below */ }
+
+        // Fallback: use run_command with curl to a simple search API
+        return {
+          success: true,
+          results: `Search for "${args.query}" — try using run_command with: curl -s "https://api.duckduckgo.com/?q=${encoded}&format=json&no_html=1"`,
+        };
+      }
+
+      case "spawn_agent": {
+        const role = args.role ?? "worker";
+        const tierMap = { explorer: "cheap", planner: "mid", worker: "mid", reviewer: "mid" };
+        const tier = args.model_tier ?? tierMap[role] ?? "mid";
+        const modelForTier = TASK_MODEL_MAP[tier === "cheap" ? "simple" : tier === "expensive" ? "critical" : "complex"];
+        const agentModel = modelForTier?.[PROVIDER] ?? MODEL;
+
+        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: agentModel,
+          status: "running", createdAt: new Date().toISOString(),
+          workstream: ACTIVE_WORKSTREAM, result: null,
+        };
+
+        console.log(dim(`  🤖 Spawning ${role} agent (${agentModel})...`));
+
+        // Run sub-agent — single-turn LLM call with the task
+        try {
+          const agentSystemPrompt = `You are a ${role} sub-agent for Wispy. Your role:
+${role === "explorer" ? "Search and analyze codebases, find relevant files and patterns." : ""}
+${role === "planner" ? "Design implementation strategies and create step-by-step plans." : ""}
+${role === "worker" ? "Implement code changes, write files, execute commands." : ""}
+${role === "reviewer" ? "Review code for bugs, security issues, and best practices." : ""}
+Be concise and deliver actionable results. Respond in the same language as the task.`;
+
+          const agentMessages = [
+            { role: "system", content: agentSystemPrompt },
+          ];
+
+          // Fork context if requested
+          if (args.fork_context) {
+            const parentContext = await loadConversation();
+            const recentContext = parentContext.filter(m => m.role === "user" || m.role === "assistant").slice(-6);
+            for (const m of recentContext) {
+              agentMessages.push({ role: m.role, content: m.content });
+            }
+          }
+
+          agentMessages.push({ role: "user", content: args.task });
+
+          const agentResult = await chatWithTools(agentMessages, null);
+          agent.result = agentResult.type === "text" ? agentResult.text : JSON.stringify(agentResult);
+          agent.status = "completed";
+          agent.completedAt = new Date().toISOString();
+        } catch (err) {
+          agent.result = `Error: ${err.message}`;
+          agent.status = "failed";
+        }
+
+        agents.push(agent);
+        // Keep last 50 agents
+        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,
+          model: agentModel,
+          status: agent.status,
+          result_preview: agent.result?.slice(0, 200),
+        };
+      }
+
+      case "list_agents": {
+        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 === ACTIVE_WORKSTREAM);
+        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,
+          })),
+        };
+      }
+
+      case "get_agent_result": {
+        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 };
+      }
+
+      case "update_plan": {
+        const planFile = path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.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");
+        // Pretty print plan
+        if (args.steps) {
+          for (const s of args.steps) {
+            const icon = s.status === "completed" ? "✅" : s.status === "in_progress" ? "🔄" : s.status === "skipped" ? "⏭️" : "⬜";
+            console.log(dim(`  ${icon} ${s.step}`));
+          }
+        }
+        return { success: true, message: "Plan updated" };
+      }
+
+      case "pipeline": {
+        const stages = args.stages ?? ["explorer", "planner", "worker"];
+        let stageInput = args.task;
+        const results = [];
+
+        console.log(dim(`  📋 Pipeline: ${stages.join(" → ")}`));
+
+        for (let i = 0; i < stages.length; i++) {
+          const role = stages[i];
+          const icon = { explorer: "🔍", planner: "📋", worker: "🔨", reviewer: "🔎" }[role] ?? "🤖";
+          console.log(dim(`\n  ${icon} Stage ${i + 1}/${stages.length}: ${role}`));
+
+          // Build stage prompt with previous stage output
+          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 stageSystem = `You are a ${role} agent in a pipeline. Stage ${i + 1} of ${stages.length}.
+${role === "explorer" ? "Find relevant files, patterns, and information." : ""}
+${role === "planner" ? "Design a concrete implementation plan based on the exploration results." : ""}
+${role === "worker" ? "Implement the plan. Write code, create files, run commands." : ""}
+${role === "reviewer" ? "Review the implementation. Check for bugs, security issues, completeness." : ""}
+Be concise. Your output feeds into the next stage.`;
+
+          const stageMessages = [
+            { role: "system", content: stageSystem },
+            { role: "user", content: stagePrompt },
+          ];
+
+          try {
+            const result = await chatWithTools(stageMessages, null);
+            const output = result.type === "text" ? result.text : JSON.stringify(result);
+            results.push(output);
+            console.log(dim(`     ✅ ${output.slice(0, 100)}...`));
+            stageInput = output;
+          } catch (err) {
+            results.push(`Error: ${err.message}`);
+            console.log(red(`     ❌ ${err.message.slice(0, 100)}`));
+            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),
+        };
+      }
+
+      case "spawn_async_agent": {
+        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: ACTIVE_WORKSTREAM, result: null,
+        };
+
+        // Save as "running" immediately
+        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");
+
+        console.log(dim(`  🤖 Async agent ${agentId} launched in background`));
+
+        // Fire and forget — run in background
+        (async () => {
+          const tierMap = { explorer: "cheap", planner: "mid", worker: "mid", reviewer: "mid" };
+          const tier = tierMap[role] ?? "mid";
+          const modelForTier = TASK_MODEL_MAP[tier === "cheap" ? "simple" : "complex"];
+          const agentModel = modelForTier?.[PROVIDER] ?? MODEL;
+
+          const agentSystem = `You are a ${role} sub-agent. Be concise and actionable.`;
+          const agentMessages = [
+            { role: "system", content: agentSystem },
+            { role: "user", content: args.task },
+          ];
+
+          try {
+            const result = await chatWithTools(agentMessages, null);
+            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();
+
+          // Update agents file
+          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.",
+        };
+      }
+
+      case "ralph_loop": {
+        const MAX_ITERATIONS = 5;
+        const criteria = args.success_criteria ?? "Task is fully completed and verified";
+        let lastResult = "";
+
+        console.log(dim(`  🪨 Ralph mode: will retry up to ${MAX_ITERATIONS} times until verified complete`));
+
+        for (let attempt = 1; attempt <= MAX_ITERATIONS; attempt++) {
+          // Worker attempt
+          console.log(dim(`\n  🔨 Attempt ${attempt}/${MAX_ITERATIONS}: worker executing...`));
+
+          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 chatWithTools(workerMessages, null);
+            lastResult = workerResult.type === "text" ? workerResult.text : JSON.stringify(workerResult);
+            console.log(dim(`     ✅ Worker output: ${lastResult.slice(0, 100)}...`));
+          } catch (err) {
+            console.log(red(`     ❌ Worker error: ${err.message.slice(0, 100)}`));
+            continue;
+          }
+
+          // Reviewer verification
+          console.log(dim(`  🔎 Reviewer verifying...`));
+
+          const reviewerMessages = [
+            { role: "system", content: "You are a reviewer agent. Your ONLY job is to determine if the task is TRULY complete. 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 chatWithTools(reviewerMessages, null);
+            const reviewText = reviewResult.type === "text" ? reviewResult.text : "";
+
+            // Try to parse JSON from review
+            const jsonMatch = reviewText.match(/\{[\s\S]*"complete"[\s\S]*\}/);
+            if (jsonMatch) {
+              try {
+                const verdict = JSON.parse(jsonMatch[0]);
+                if (verdict.complete) {
+                  console.log(green(`     ✅ Reviewer: COMPLETE — ${verdict.reason?.slice(0, 80) ?? "verified"}`));
+                  return { success: true, iterations: attempt, result: lastResult, verified: true };
+                }
+                console.log(yellow(`     ⏳ Reviewer: NOT COMPLETE — ${verdict.reason?.slice(0, 80) ?? "needs more work"}`));
+              } catch { /* parse failed, continue */ }
+            }
+          } catch (err) {
+            console.log(dim(`     ⚠️ Review error: ${err.message.slice(0, 80)}`));
+          }
+        }
+
+        // Max iterations reached
+        console.log(yellow(`  🪨 Ralph: max iterations (${MAX_ITERATIONS}) reached`));
+        return { success: true, iterations: MAX_ITERATIONS, result: lastResult, verified: false, message: "Max iterations reached" };
+      }
+
+      default:
+        return { success: false, error: `Unknown tool: ${name}` };
+    }
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// System prompt builder
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// work.md — per-workstream context file
+// ---------------------------------------------------------------------------
+
+async function loadWorkMd() {
+  const searchPaths = [
+    path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.work.md`),
+    path.resolve(`.wispy/${ACTIVE_WORKSTREAM}.work.md`),
+    path.resolve(`work.md`), // project root fallback
+  ];
+  for (const p of searchPaths) {
+    const content = await readFileOr(p);
+    if (content) return { path: p, content: content.slice(0, 20_000) };
+  }
+  return null;
+}
+
+async function buildSystemPrompt() {
+  const parts = [
+    "You are Wispy 🌿, a personal AI workspace assistant.",
+    "You are friendly, concise, and action-oriented.",
+    "Respond in the same language the user uses.",
+    "If the user speaks Korean, respond in Korean with casual tone (반말).",
+    "",
+    "You have access to tools: read_file, write_file, run_command, list_directory, web_search, spawn_agent, spawn_async_agent, pipeline, ralph_loop, update_plan, list_agents, get_agent_result.",
+    "Use them proactively when the user asks you to do something that requires file access, commands, or web info.",
+    "When using tools, briefly tell the user what you're doing.",
+    "",
+  ];
+
+  const wispyMd = await loadWispyMd();
+  if (wispyMd) {
+    parts.push("## Project Context (WISPY.md)");
+    parts.push(wispyMd);
+    parts.push("");
+  }
+
+  // Per-workstream context
+  const workMd = await loadWorkMd();
+  if (workMd) {
+    parts.push(`## Workstream Context (${ACTIVE_WORKSTREAM})`);
+    parts.push(workMd.content);
+    parts.push("");
+  }
+
+  const memories = await loadMemories();
+  if (memories) {
+    parts.push("## Persistent Memory");
+    parts.push(memories);
+    parts.push("");
+  }
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI API (streaming)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Gemini API with function calling (non-streaming for tool calls, streaming for text)
+// ---------------------------------------------------------------------------
+
+// OpenAI-compatible API endpoints for various providers
+const OPENAI_COMPAT_ENDPOINTS = {
+  openai:     "https://api.openai.com/v1/chat/completions",
+  openrouter: "https://openrouter.ai/api/v1/chat/completions",
+  groq:       "https://api.groq.com/openai/v1/chat/completions",
+  deepseek:   "https://api.deepseek.com/v1/chat/completions",
+  ollama:     `${process.env.OLLAMA_HOST ?? "http://localhost:11434"}/v1/chat/completions`,
+};
+
+async function chatWithTools(messages, onChunk) {
+  if (PROVIDER === "google") return chatGeminiWithTools(messages, onChunk);
+  if (PROVIDER === "anthropic") return chatAnthropicWithTools(messages, onChunk);
+  // All others use OpenAI-compatible API
+  return chatOpenAIWithTools(messages, onChunk);
+}
+
+async function chatGeminiWithTools(messages, onChunk) {
+  const systemInstruction = messages.find(m => m.role === "system")?.content ?? "";
+
+  // Build Gemini contents — handle tool results too
+  const contents = [];
+  for (const m of messages) {
+    if (m.role === "system") continue;
+    if (m.role === "tool_result") {
+      contents.push({
+        role: "user",
+        parts: [{ functionResponse: { name: m.toolName, response: m.result } }],
+      });
+    } else if (m.role === "assistant" && m.toolCalls) {
+      contents.push({
+        role: "model",
+        parts: m.toolCalls.map(tc => ({
+          functionCall: { name: tc.name, args: tc.args },
+        })),
+      });
+    } else {
+      contents.push({
+        role: m.role === "assistant" ? "model" : "user",
+        parts: [{ text: m.content }],
+      });
+    }
+  }
+
+  // Track input tokens
+  const inputText = contents.map(c => c.parts?.map(p => p.text ?? JSON.stringify(p)).join("")).join("");
+  sessionTokens.input += estimateTokens(systemInstruction + inputText);
+
+  const geminiTools = [{
+    functionDeclarations: TOOL_DEFINITIONS.map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    })),
+  }];
+
+  // Use streaming when no tool results in the conversation (pure text),
+  // non-streaming when tool results are present (function calling needs it)
+  const hasToolResults = messages.some(m => m.role === "tool_result");
+  const useStreaming = !hasToolResults;
+  const endpoint = useStreaming ? "streamGenerateContent" : "generateContent";
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:${endpoint}?${useStreaming ? "alt=sse&" : ""}key=${API_KEY}`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      system_instruction: systemInstruction ? { parts: [{ text: systemInstruction }] } : undefined,
+      contents,
+      tools: geminiTools,
+      generationConfig: { temperature: 0.7, maxOutputTokens: 4096 },
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Gemini API error ${response.status}: ${err.slice(0, 300)}`);
+  }
+
+  if (useStreaming) {
+    // SSE streaming response
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let fullText = "";
+    let sseBuffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      sseBuffer += decoder.decode(value, { stream: true });
+      const sseLines = sseBuffer.split("\n");
+      sseBuffer = sseLines.pop() ?? "";
+
+      for (const line of sseLines) {
+        if (!line.startsWith("data: ")) continue;
+        const ld = line.slice(6).trim();
+        if (!ld || ld === "[DONE]") continue;
+        try {
+          const parsed = JSON.parse(ld);
+          // Check for function calls in stream
+          const streamParts = parsed.candidates?.[0]?.content?.parts ?? [];
+          const streamFC = streamParts.filter(p => p.functionCall);
+          if (streamFC.length > 0) {
+            sessionTokens.output += estimateTokens(JSON.stringify(streamFC));
+            return { type: "tool_calls", calls: streamFC.map(p => ({ name: p.functionCall.name, args: p.functionCall.args })) };
+          }
+          const t = streamParts.map(p => p.text ?? "").join("");
+          if (t) { fullText += t; onChunk?.(t); }
+        } catch { /* skip */ }
+      }
+    }
+    sessionTokens.output += estimateTokens(fullText);
+    return { type: "text", text: fullText };
+  }
+
+  // Non-streaming response (when tool results present)
+  const data = await response.json();
+  const candidate = data.candidates?.[0];
+  if (!candidate) throw new Error("No response from Gemini");
+
+  const parts = candidate.content?.parts ?? [];
+  const functionCalls = parts.filter(p => p.functionCall);
+  if (functionCalls.length > 0) {
+    sessionTokens.output += estimateTokens(JSON.stringify(functionCalls));
+    return { type: "tool_calls", calls: functionCalls.map(p => ({ name: p.functionCall.name, args: p.functionCall.args })) };
+  }
+
+  const text = parts.map(p => p.text ?? "").join("");
+  sessionTokens.output += estimateTokens(text);
+  if (onChunk) onChunk(text);
+  return { type: "text", text };
+}
+
+async function chatOpenAIWithTools(messages, onChunk) {
+  const openaiMessages = messages.filter(m => m.role !== "tool_result").map(m => {
+    if (m.role === "tool_result") return { role: "tool", tool_call_id: m.toolCallId, content: JSON.stringify(m.result) };
+    return { role: m.role === "assistant" ? "assistant" : m.role, content: m.content };
+  });
+
+  const openaiTools = TOOL_DEFINITIONS.map(t => ({
+    type: "function",
+    function: { name: t.name, description: t.description, parameters: t.parameters },
+  }));
+
+  const inputText = openaiMessages.map(m => m.content ?? "").join("");
+  sessionTokens.input += estimateTokens(inputText);
+
+  const endpoint = OPENAI_COMPAT_ENDPOINTS[PROVIDER] ?? OPENAI_COMPAT_ENDPOINTS.openai;
+  const headers = { "Content-Type": "application/json" };
+  if (API_KEY) headers["Authorization"] = `Bearer ${API_KEY}`;
+  if (PROVIDER === "openrouter") headers["HTTP-Referer"] = "https://wispy.dev";
+
+  // Some providers don't support tools (Ollama, some Groq models)
+  const supportsTools = !["ollama"].includes(PROVIDER);
+  const body = { model: MODEL, messages: openaiMessages, temperature: 0.7, max_tokens: 4096 };
+  if (supportsTools) body.tools = openaiTools;
+
+  const response = await fetch(endpoint, { method: "POST", headers, body: JSON.stringify(body) });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`OpenAI API error ${response.status}: ${err.slice(0, 300)}`);
+  }
+
+  const data = await response.json();
+  const choice = data.choices?.[0];
+  if (!choice) throw new Error("No response from OpenAI");
+
+  if (choice.message?.tool_calls?.length > 0) {
+    const calls = choice.message.tool_calls.map(tc => ({
+      name: tc.function.name,
+      args: JSON.parse(tc.function.arguments),
+    }));
+    sessionTokens.output += estimateTokens(JSON.stringify(calls));
+    return { type: "tool_calls", calls };
+  }
+
+  const text = choice.message?.content ?? "";
+  sessionTokens.output += estimateTokens(text);
+  if (onChunk) onChunk(text);
+  return { type: "text", text };
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic API with tool use (streaming text + tool calls)
+// ---------------------------------------------------------------------------
+
+async function chatAnthropicWithTools(messages, onChunk) {
+  const systemPrompt = messages.find(m => m.role === "system")?.content ?? "";
+
+  // Build Anthropic messages
+  const anthropicMessages = [];
+  for (const m of messages) {
+    if (m.role === "system") continue;
+    if (m.role === "tool_result") {
+      anthropicMessages.push({
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: m.toolUseId ?? m.toolName, content: JSON.stringify(m.result) }],
+      });
+    } else if (m.role === "assistant" && m.toolCalls) {
+      anthropicMessages.push({
+        role: "assistant",
+        content: m.toolCalls.map(tc => ({
+          type: "tool_use", id: tc.id ?? tc.name, name: tc.name, input: tc.args,
+        })),
+      });
+    } else {
+      anthropicMessages.push({
+        role: m.role === "assistant" ? "assistant" : "user",
+        content: m.content,
+      });
+    }
+  }
+
+  const inputText = anthropicMessages.map(m => typeof m.content === "string" ? m.content : JSON.stringify(m.content)).join("");
+  sessionTokens.input += estimateTokens(systemPrompt + inputText);
+
+  const anthropicTools = TOOL_DEFINITIONS.map(t => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.parameters,
+  }));
+
+  const response = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": API_KEY,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model: MODEL,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages: anthropicMessages,
+      tools: anthropicTools,
+      stream: true,
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${err.slice(0, 300)}`);
+  }
+
+  // Parse SSE stream
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let fullText = "";
+  const toolCalls = [];
+  let currentToolCall = null;
+  let currentToolInput = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      if (!line.startsWith("data: ")) continue;
+      const data = line.slice(6).trim();
+      if (!data) continue;
+
+      try {
+        const event = JSON.parse(data);
+
+        if (event.type === "content_block_start") {
+          if (event.content_block?.type === "tool_use") {
+            currentToolCall = { id: event.content_block.id, name: event.content_block.name, args: {} };
+            currentToolInput = "";
+          }
+        } else if (event.type === "content_block_delta") {
+          if (event.delta?.type === "text_delta") {
+            fullText += event.delta.text;
+            onChunk?.(event.delta.text);
+          } else if (event.delta?.type === "input_json_delta") {
+            currentToolInput += event.delta.partial_json ?? "";
+          }
+        } else if (event.type === "content_block_stop") {
+          if (currentToolCall) {
+            try { currentToolCall.args = JSON.parse(currentToolInput); } catch { currentToolCall.args = {}; }
+            toolCalls.push(currentToolCall);
+            currentToolCall = null;
+            currentToolInput = "";
+          }
+        }
+      } catch { /* skip */ }
+    }
+  }
+
+  sessionTokens.output += estimateTokens(fullText + JSON.stringify(toolCalls));
+
+  if (toolCalls.length > 0) {
+    return { type: "tool_calls", calls: toolCalls };
+  }
+  return { type: "text", text: fullText };
+}
+
+// ---------------------------------------------------------------------------
+// Agentic loop — handles tool calls iteratively
+// ---------------------------------------------------------------------------
+
+async function agentLoop(messages, onChunk) {
+  const MAX_TOOL_ROUNDS = 10;
+
+  // Optimize context window before sending
+  const lastUserMsg = messages.filter(m => m.role === "user").pop();
+  const optimizedMessages = optimizeContext(messages);
+  if (optimizedMessages.length < messages.length) {
+    messages.length = 0;
+    messages.push(...optimizedMessages);
+  }
+
+  for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+    // Check budget before calling API
+    const budgetCheck = await loadBudgets();
+    const wsBudget = budgetCheck[ACTIVE_WORKSTREAM];
+    if (wsBudget?.limitUsd !== null && wsBudget?.spentUsd > wsBudget?.limitUsd) {
+      return `⚠️ Budget exceeded for workstream "${ACTIVE_WORKSTREAM}" ($${wsBudget.spentUsd.toFixed(4)} / $${wsBudget.limitUsd.toFixed(4)}). Use /budget to adjust.`;
+    }
+
+    const result = await chatWithTools(messages, onChunk);
+
+    if (result.type === "text") {
+      // Track spending for this workstream
+      await trackSpending(ACTIVE_WORKSTREAM, sessionTokens.input, sessionTokens.output, MODEL);
+      return result.text;
+    }
+
+    // Handle tool calls
+    console.log(""); // newline before tool output
+    const toolCallMsg = { role: "assistant", toolCalls: result.calls, content: "" };
+    messages.push(toolCallMsg);
+
+    for (const call of result.calls) {
+      console.log(dim(`  🔧 ${call.name}(${JSON.stringify(call.args).slice(0, 80)})`));
+      const toolResult = await executeTool(call.name, call.args);
+
+      if (toolResult.success) {
+        const preview = JSON.stringify(toolResult).slice(0, 100);
+        console.log(dim(`     ✅ ${preview}${preview.length >= 100 ? "..." : ""}`));
+      } else {
+        console.log(red(`     ❌ ${toolResult.error}`));
+      }
+
+      messages.push({
+        role: "tool_result",
+        toolName: call.name,
+        toolUseId: call.id ?? call.name,
+        result: toolResult,
+      });
+    }
+    console.log(""); // newline before next response
+  }
+
+  return "(tool call limit reached)";
+}
+
+// ---------------------------------------------------------------------------
+// Slash commands
+// ---------------------------------------------------------------------------
+
+async function handleSlashCommand(input, conversation) {
+  const parts = input.trim().split(/\s+/);
+  const cmd = parts[0].toLowerCase();
+
+  if (cmd === "/help") {
+    console.log(`
+${bold("Wispy Commands:")}
+  ${cyan("/help")}              Show this help
+  ${cyan("/compact")}           Summarize & compress conversation
+  ${cyan("/memory")} <type> <text>  Save to persistent memory (user|feedback|project|references)
+  ${cyan("/clear")}             Reset conversation
+  ${cyan("/history")}           Show conversation length
+  ${cyan("/model")} [name]      Show or change model
+  ${cyan("/quit")} or ${cyan("/exit")}    Exit
+`);
+    return true;
+  }
+
+  if (cmd === "/clear") {
+    conversation.length = 0;
+    await saveConversation([]);
+    console.log(green("🌿 Conversation cleared."));
+    return true;
+  }
+
+  if (cmd === "/history") {
+    console.log(dim(`${conversation.length} messages in current conversation.`));
+    return true;
+  }
+
+  if (cmd === "/model") {
+    if (parts[1]) {
+      process.env.WISPY_MODEL = parts[1];
+      console.log(green(`Model changed to: ${parts[1]}`));
+    } else {
+      console.log(dim(`Current model: ${MODEL}`));
+    }
+    return true;
+  }
+
+  if (cmd === "/memory") {
+    const type = parts[1];
+    const content = parts.slice(2).join(" ");
+    if (!type || !content) {
+      console.log(yellow("Usage: /memory <user|feedback|project|references> <content>"));
+      return true;
+    }
+    const validTypes = ["user", "feedback", "project", "references"];
+    if (!validTypes.includes(type)) {
+      console.log(yellow(`Invalid type. Use: ${validTypes.join(", ")}`));
+      return true;
+    }
+    await appendToMemory(type, content);
+    console.log(green(`✅ Saved to ${type} memory.`));
+    return true;
+  }
+
+  if (cmd === "/compact") {
+    // Ask the AI to summarize, then replace history with summary
+    const summaryMessages = [
+      { role: "system", content: "Summarize the following conversation in 3-5 bullet points. Be concise." },
+      ...conversation.filter(m => m.role !== "system").slice(-20),
+      { role: "user", content: "Summarize our conversation so far." },
+    ];
+
+    process.stdout.write(cyan("🌿 Compacting... "));
+    const summary = await chatStream(summaryMessages, (chunk) => process.stdout.write(chunk));
+    console.log("\n");
+
+    // Save summary to memory and reset conversation
+    await appendToMemory("project", `Session compact: ${summary.slice(0, 200)}`);
+    conversation.length = 0;
+    conversation.push({ role: "assistant", content: `[Previous session summary]\n${summary}` });
+    await saveConversation(conversation);
+    console.log(green("📦 Conversation compacted."));
+    return true;
+  }
+
+  if (cmd === "/cost" || cmd === "/tokens" || cmd === "/usage") {
+    console.log(dim(`📊 Session usage: ${formatCost()}`));
+    return true;
+  }
+
+  if (cmd === "/workstreams" || cmd === "/ws") {
+    const wsList = await listWorkstreams();
+    if (wsList.length === 0) {
+      console.log(dim("No workstreams yet."));
+    } else {
+      console.log(bold("\n📋 Workstreams:\n"));
+      for (const ws of wsList) {
+        const marker = ws === ACTIVE_WORKSTREAM ? green("● ") : "  ";
+        // Show last message preview
+        const wsConv = await loadWorkstreamConversation(ws);
+        const lastMsg = wsConv.filter(m => m.role === "user").pop();
+        const preview = lastMsg ? dim(` — "${lastMsg.content.slice(0, 40)}${lastMsg.content.length > 40 ? "..." : ""}"`) : "";
+        const msgCount = wsConv.filter(m => m.role === "user").length;
+        console.log(`${marker}${ws.padEnd(20)} ${dim(`${msgCount} msgs`)}${preview}`);
+      }
+      console.log(dim(`\nSwitch: wispy -w <name>`));
+    }
+    return true;
+  }
+
+  if (cmd === "/overview" || cmd === "/dashboard" || cmd === "/all") {
+    await showOverview();
+    return true;
+  }
+
+  if (cmd === "/search") {
+    const query = parts.slice(1).join(" ");
+    if (!query) {
+      console.log(yellow("Usage: /search <keyword>  — search across all workstreams"));
+      return true;
+    }
+    await searchAcrossWorkstreams(query);
+    return true;
+  }
+
+  if (cmd === "/work") {
+    const workMd = await loadWorkMd();
+    if (parts[1] === "edit" || parts[1] === "set") {
+      const content = parts.slice(2).join(" ");
+      if (!content) {
+        console.log(yellow("Usage: /work set <content>  or create file manually:"));
+        console.log(dim(`  ${path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.work.md`)}`));
+        return true;
+      }
+      const workPath = path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.work.md`);
+      await mkdir(CONVERSATIONS_DIR, { recursive: true });
+      await appendFile(workPath, `\n${content}\n`, "utf8");
+      console.log(green(`✅ Added to ${ACTIVE_WORKSTREAM} work.md`));
+      return true;
+    }
+    if (parts[1] === "init") {
+      const workPath = path.join(CONVERSATIONS_DIR, `${ACTIVE_WORKSTREAM}.work.md`);
+      if (workMd) {
+        console.log(dim(`work.md already exists at ${workMd.path}`));
+        return true;
+      }
+      await mkdir(CONVERSATIONS_DIR, { recursive: true });
+      await writeFile(workPath, `# ${ACTIVE_WORKSTREAM}\n\n## Goals\n\n## Context\n\n## Notes\n\n`, "utf8");
+      console.log(green(`✅ Created ${workPath}`));
+      return true;
+    }
+    // Show current work.md
+    if (workMd) {
+      console.log(`\n${bold(`📋 work.md (${ACTIVE_WORKSTREAM})`)}`);
+      console.log(dim(`   ${workMd.path}\n`));
+      console.log(workMd.content);
+    } else {
+      console.log(dim(`No work.md for "${ACTIVE_WORKSTREAM}". Create one:`));
+      console.log(dim(`  /work init`));
+      console.log(dim(`  /work set "project goals and context here"`));
+    }
+    return true;
+  }
+
+  if (cmd === "/budget") {
+    const budgets = await loadBudgets();
+    if (parts[1] === "set") {
+      const limit = parseFloat(parts[2]);
+      if (isNaN(limit)) {
+        console.log(yellow("Usage: /budget set <amount_usd>  — e.g., /budget set 1.00"));
+        return true;
+      }
+      if (!budgets[ACTIVE_WORKSTREAM]) budgets[ACTIVE_WORKSTREAM] = { limitUsd: null, spentUsd: 0, totalTokens: 0 };
+      budgets[ACTIVE_WORKSTREAM].limitUsd = limit;
+      await saveBudgets(budgets);
+      console.log(green(`💰 Budget set: $${limit.toFixed(2)} for "${ACTIVE_WORKSTREAM}"`));
+      return true;
+    }
+    if (parts[1] === "clear") {
+      if (budgets[ACTIVE_WORKSTREAM]) budgets[ACTIVE_WORKSTREAM].limitUsd = null;
+      await saveBudgets(budgets);
+      console.log(dim("Budget limit removed."));
+      return true;
+    }
+    // Show all budgets
+    const wsList = Object.keys(budgets);
+    if (wsList.length === 0) {
+      console.log(dim("No spending tracked yet."));
+      return true;
+    }
+    console.log(bold("\n💰 Budget Overview:\n"));
+    for (const ws of wsList) {
+      const b = budgets[ws];
+      const marker = ws === ACTIVE_WORKSTREAM ? green("● ") : "  ";
+      const limit = b.limitUsd !== null ? `/ $${b.limitUsd.toFixed(2)}` : dim("(no limit)");
+      const pct = b.limitUsd ? ` (${((b.spentUsd / b.limitUsd) * 100).toFixed(1)}%)` : "";
+      const warning = b.limitUsd && b.spentUsd > b.limitUsd ? red(" ⚠ OVER") : "";
+      console.log(`${marker}${ws.padEnd(20)} $${b.spentUsd.toFixed(4)} ${limit}${pct}${warning}  ${dim(`${b.totalTokens} tokens`)}`);
+    }
+    console.log(dim("\nSet limit: /budget set <usd>  |  Remove: /budget clear"));
+    console.log("");
+    return true;
+  }
+
+  if (cmd === "/provider") {
+    console.log(dim(`Provider: ${PROVIDERS[PROVIDER]?.label ?? PROVIDER}`));
+    console.log(dim(`Model: ${MODEL}`));
+    console.log(dim(`Workstream: ${ACTIVE_WORKSTREAM}`));
+    return true;
+  }
+
+  if (cmd === "/quit" || cmd === "/exit") {
+    console.log(dim(`🌿 Bye! (${formatCost()})`));
+    process.exit(0);
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Interactive REPL
+// ---------------------------------------------------------------------------
+
+async function runRepl() {
+  const wsLabel = ACTIVE_WORKSTREAM === "default" ? "" : ` [${cyan(ACTIVE_WORKSTREAM)}]`;
+  const providerLabel = PROVIDERS[PROVIDER]?.label ?? PROVIDER;
+  console.log(`
+${bold("🌿 Wispy")}${wsLabel} ${dim(`— ${providerLabel} (${MODEL})`)}
+${dim("Type a message to chat. /help for commands. Ctrl+C to exit.")}
+`);
+
+  const systemPrompt = await buildSystemPrompt();
+  const conversation = await loadConversation();
+
+  // Ensure system prompt is first
+  if (conversation.length === 0 || conversation[0].role !== "system") {
+    conversation.unshift({ role: "system", content: systemPrompt });
+  } else {
+    conversation[0].content = systemPrompt; // Refresh system prompt
+  }
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: green("› "),
+    historySize: 100,
+  });
+
+  rl.prompt();
+
+  rl.on("line", async (line) => {
+    const input = line.trim();
+    if (!input) { rl.prompt(); return; }
+
+    // Slash commands
+    if (input.startsWith("/")) {
+      const handled = await handleSlashCommand(input, conversation);
+      if (handled) { rl.prompt(); return; }
+    }
+
+    // Add user message
+    conversation.push({ role: "user", content: input });
+
+    // Agent loop with tool calls
+    process.stdout.write(cyan("🌿 "));
+    try {
+      const response = await agentLoop(conversation, (chunk) => {
+        process.stdout.write(chunk);
+      });
+      console.log("\n");
+
+      conversation.push({ role: "assistant", content: response });
+      await saveConversation(conversation);
+      console.log(dim(`  ${formatCost()}`));
+    } catch (err) {
+      // Friendly error handling
+      if (err.message.includes("429") || err.message.includes("rate")) {
+        console.log(yellow("\n\n⏳ Rate limited — wait a moment and try again."));
+      } else if (err.message.includes("401") || err.message.includes("403")) {
+        console.log(red("\n\n🔑 Authentication error — check your API key."));
+      } else if (err.message.includes("network") || err.message.includes("fetch")) {
+        console.log(red("\n\n🌐 Network error — check your connection."));
+      } else {
+        console.log(red(`\n\n❌ Error: ${err.message.slice(0, 200)}`));
+      }
+    }
+
+    rl.prompt();
+  });
+
+  rl.on("close", () => {
+    console.log(dim(`\n🌿 Bye! (${formatCost()})`));
+    process.exit(0);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// One-shot mode
+// ---------------------------------------------------------------------------
+
+async function runOneShot(message) {
+  const systemPrompt = await buildSystemPrompt();
+  const conversation = await loadConversation();
+
+  if (conversation.length === 0 || conversation[0].role !== "system") {
+    conversation.unshift({ role: "system", content: systemPrompt });
+  } else {
+    conversation[0].content = systemPrompt;
+  }
+
+  conversation.push({ role: "user", content: message });
+
+  try {
+    const response = await agentLoop(conversation, (chunk) => {
+      process.stdout.write(chunk);
+    });
+    console.log("");
+
+    conversation.push({ role: "assistant", content: response });
+    await saveConversation(conversation);
+    console.log(dim(`${formatCost()}`));
+  } catch (err) {
+    if (err.message.includes("429")) {
+      console.error(yellow("\n⏳ Rate limited — try again shortly."));
+    } else {
+      console.error(red(`\n❌ ${err.message.slice(0, 200)}`));
+    }
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto server management — start AWOS server if not running
+// ---------------------------------------------------------------------------
+
+import { spawn as spawnProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = process.env.WISPY_REPO_ROOT ?? path.resolve(SCRIPT_DIR, "..");
+// Server binary: check env → ~/.wispy/bin/ → repo build path
+import { statSync } from "node:fs";
+const SERVER_BINARY = process.env.WISPY_SERVER_BINARY
+  ?? (() => {
+    const candidates = [
+      path.join(os.homedir(), ".wispy", "bin", "awos-server"),
+      path.join(REPO_ROOT, "src-tauri", "target", "release", "awos-server"),
+      path.join(REPO_ROOT, "src-tauri", "target", "debug", "awos-server"),
+    ];
+    for (const c of candidates) {
+      try { if (statSync(c).isFile()) return c; } catch {}
+    }
+    return candidates[0];
+  })();
+const SERVER_PID_FILE = path.join(WISPY_DIR, "server.pid");
+const DEFAULT_SERVER_PORT = process.env.AWOS_PORT ?? "8090";
+
+async function isServerRunning() {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${DEFAULT_SERVER_PORT}/api/health`, {
+      signal: AbortSignal.timeout(2000),
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function startServerIfNeeded() {
+  if (await isServerRunning()) {
+    return { started: false, port: DEFAULT_SERVER_PORT };
+  }
+
+  // Check if binary exists
+  try {
+    const { stat } = await import("node:fs/promises");
+    await stat(SERVER_BINARY);
+  } catch {
+    // No binary — skip auto-start silently, CLI-only mode
+    return { started: false, port: DEFAULT_SERVER_PORT, noBinary: true };
+  }
+
+  // Start server in background
+  const logFile = path.join(WISPY_DIR, "server.log");
+  await mkdir(WISPY_DIR, { recursive: true });
+  const { openSync } = await import("node:fs");
+  const logFd = openSync(logFile, "a");
+
+  const child = spawnProcess(SERVER_BINARY, [], {
+    cwd: REPO_ROOT,
+    env: { ...process.env, AWOS_PORT: DEFAULT_SERVER_PORT },
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+  });
+
+  child.unref();
+
+  // Save PID for cleanup
+  await writeFile(SERVER_PID_FILE, String(child.pid), "utf8");
+
+  // Wait up to 5 seconds for server to be ready
+  for (let i = 0; i < 25; i++) {
+    await new Promise(r => setTimeout(r, 200));
+    if (await isServerRunning()) {
+      return { started: true, port: DEFAULT_SERVER_PORT, pid: child.pid };
+    }
+  }
+
+  return { started: true, port: DEFAULT_SERVER_PORT, pid: child.pid, slow: true };
+}
+
+async function stopServer() {
+  try {
+    const pidStr = await readFile(SERVER_PID_FILE, "utf8");
+    const pid = parseInt(pidStr.trim(), 10);
+    if (pid && !isNaN(pid)) {
+      process.kill(pid, "SIGTERM");
+      // Clean up PID file
+      const { unlink } = await import("node:fs/promises");
+      await unlink(SERVER_PID_FILE).catch(() => {});
+    }
+  } catch {
+    // No PID file or already stopped
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+// Filter out -w/--workstream flag from args
+const rawArgs = process.argv.slice(2);
+const args = [];
+for (let i = 0; i < rawArgs.length; i++) {
+  if (rawArgs[i] === "-w" || rawArgs[i] === "--workstream") { i++; continue; } // skip flag + value
+  args.push(rawArgs[i]);
+}
+
+// Route to legacy CLI for operator commands
+const operatorCommands = new Set([
+  "home", "node", "runtime", "agents", "agent",
+  "workstreams", "workstream", "doctor", "setup",
+  "package", "config", "server",
+]);
+
+// wispy server <start|stop|status>
+if (args[0] === "server") {
+  const sub = args[1] ?? "status";
+  if (sub === "status") {
+    const running = await isServerRunning();
+    if (running) {
+      console.log(green(`✅ Server running on port ${DEFAULT_SERVER_PORT}`));
+      const pidStr = await readFileOr(SERVER_PID_FILE);
+      if (pidStr) console.log(dim(`   PID: ${pidStr.trim()}`));
+    } else {
+      console.log(dim("Server not running."));
+    }
+    process.exit(0);
+  }
+  if (sub === "stop") {
+    await stopServer();
+    console.log(dim("🌿 Server stopped."));
+    process.exit(0);
+  }
+  if (sub === "start") {
+    const status = await startServerIfNeeded();
+    if (status.started) {
+      console.log(green(`🌿 Server started on port ${status.port} (PID: ${status.pid})`));
+    } else if (status.noBinary) {
+      console.log(red("Server binary not found. Run: cd agent-workstream-os && cargo build --manifest-path src-tauri/Cargo.toml --no-default-features --features server"));
+    } else {
+      console.log(dim(`Server already running on port ${status.port}`));
+    }
+    process.exit(0);
+  }
+  console.log("Usage: wispy server <start|stop|status>");
+  process.exit(1);
+}
+
+if (args[0] && operatorCommands.has(args[0])) {
+  // Delegate to the full CLI
+  const cliPath = process.env.WISPY_OPERATOR_CLI ?? path.join(SCRIPT_DIR, "awos-node-cli.mjs");
+  const { execFileSync } = await import("node:child_process");
+  try {
+    execFileSync(process.execPath, ["--experimental-strip-types", cliPath, ...args], {
+      stdio: "inherit",
+      env: process.env,
+    });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+  process.exit(0);
+}
+
+// Check API key
+if (!API_KEY && PROVIDER !== "ollama") {
+  printSetupGuide();
+  process.exit(1);
+}
+
+// Auto-start server before entering REPL or one-shot
+const serverStatus = await startServerIfNeeded();
+if (serverStatus.started) {
+  if (serverStatus.slow) {
+    console.log(yellow(`⚠ Server starting on port ${serverStatus.port} (may take a moment)...`));
+  } else {
+    console.log(dim(`🌿 Server started on port ${serverStatus.port}`));
+  }
+} else if (serverStatus.noBinary) {
+  // Silent — no binary built yet, that's fine for chat-only mode
+}
+
+// Server runs as a background daemon — survives CLI exit.
+// Use `wispy server stop` to stop it explicitly.
+
+if (args[0] === "overview" || args[0] === "dashboard") {
+  await showOverview();
+  process.exit(0);
+}
+
+if (args[0] === "search" && args[1]) {
+  await searchAcrossWorkstreams(args.slice(1).join(" "));
+  process.exit(0);
+}
+
+if (args[0] === "--continue" || args[0] === "-c") {
+  // Continue previous session with optional message
+  const message = args.slice(1).join(" ").trim();
+  if (message) {
+    await runOneShot(message);
+  } else {
+    await runRepl();
+  }
+} else if (args[0] === "--new" || args[0] === "-n") {
+  // Force new session
+  await saveConversation([]);
+  const message = args.slice(1).join(" ").trim();
+  if (message) {
+    await runOneShot(message);
+  } else {
+    console.log(dim("🌿 Starting fresh session."));
+    await runRepl();
+  }
+} else if (args.length > 0 && args[0] !== "--help" && args[0] !== "-h") {
+  // One-shot mode: wispy "message"
+  const message = args.join(" ");
+  await runOneShot(message);
+} else if (args[0] === "--help" || args[0] === "-h") {
+  console.log(`
+${bold("🌿 Wispy")} — AI workspace assistant
+
+${bold("Usage:")}
+  wispy                     Start interactive session
+  wispy "message"           One-shot message
+  wispy -w <name>           Use specific workstream
+  wispy -w <name> "msg"     Workstream + message
+  wispy --continue "msg"    Continue previous session
+  wispy --new "msg"         Start fresh session
+  wispy home <subcommand>   Operator commands
+  wispy config              Show/set config
+  wispy server status       Server management
+  wispy doctor              Diagnose environment
+
+${bold("Tools (AI can use):")}
+  read_file                 Read file contents
+  write_file                Write/create files
+  run_command               Execute shell commands
+  list_directory            List files in directory
+  web_search                Search the web
+
+${bold("In-session commands:")}
+  /help                     Show commands
+  /compact                  Compress conversation
+  /memory <type> <text>     Save to persistent memory
+  /clear                    Reset conversation
+  /model [name]             Show/change model
+  /cost                     Show session token usage
+  /work                     Show workstream context (work.md)
+  /work init                Create work.md for current workstream
+  /work set <text>          Append to work.md
+  /budget                   Show spending per workstream
+  /budget set <usd>         Set budget limit for current workstream
+  /workstreams              List all workstreams
+  /overview                 Director view — all workstreams at a glance
+  /search <keyword>         Search across all workstreams
+  /provider                 Show current provider info
+  /quit                     Exit
+
+${bold("Providers (auto-detected):")}
+  GOOGLE_AI_KEY             Google AI / Gemini ${dim("(free tier)")}
+  ANTHROPIC_API_KEY         Anthropic / Claude
+  OPENAI_API_KEY            OpenAI / GPT-4o
+  OPENROUTER_API_KEY        OpenRouter ${dim("(any model)")}
+  GROQ_API_KEY              Groq ${dim("(fast inference)")}
+  DEEPSEEK_API_KEY          DeepSeek
+  OLLAMA_HOST               Ollama ${dim("(local, no key needed)")}
+
+${bold("Options:")}
+  WISPY_PROVIDER            Force provider (google/anthropic/openai/openrouter/groq/deepseek/ollama)
+  WISPY_MODEL               Override model name
+  WISPY_WORKSTREAM          Set active workstream
+`);
+} else {
+  // Interactive REPL
+  await runRepl();
+}