wispy-cli 0.8.0 → 0.9.0

package/core/engine.mjs

@@ -20,6 +20,7 @@ import { ToolRegistry } from "./tools.mjs";
 import { SessionManager } from "./session.mjs";
 import { MCPManager, ensureDefaultMcpConfig } from "./mcp.mjs";
 import { MemoryManager } from "./memory.mjs";
+import { SubAgentManager } from "./subagents.mjs";
 
 const MAX_TOOL_ROUNDS = 10;
 const MAX_CONTEXT_CHARS = 40_000;
@@ -32,6 +33,7 @@ export class WispyEngine {
     this.sessions = new SessionManager();
     this.mcpManager = new MCPManager(config.mcpConfigPath ?? MCP_CONFIG_PATH);
     this.memory = new MemoryManager(WISPY_DIR);
+    this.subagents = new SubAgentManager(this, this.sessions);
     this._initialized = false;
     this._activeWorkstream = config.workstream
       ?? process.env.WISPY_WORKSTREAM
@@ -226,6 +228,17 @@ export class WispyEngine {
         return this._toolMemoryAppend(args);
       case "memory_delete":
         return this._toolMemoryDelete(args);
+      // Sub-agent tools (v0.9)
+      case "spawn_subagent":
+        return this._toolSpawnSubagent(args, opts);
+      case "list_subagents":
+        return this._toolListSubagents();
+      case "get_subagent_result":
+        return this._toolGetSubagentResult(args);
+      case "kill_subagent":
+        return this._toolKillSubagent(args);
+      case "steer_subagent":
+        return this._toolSteerSubagent(args);
       default:
         return this.tools.execute(name, args);
     }
@@ -438,6 +451,88 @@ export class WispyEngine {
     return { success: true, iterations: MAX_ITERATIONS, result: lastResult, verified: false, message: "Max iterations reached" };
   }
 
+  // ── Sub-agent tools (v0.9) ──────────────────────────────────────────────────
+
+  async _toolSpawnSubagent(args, parentOpts = {}) {
+    const agent = await this.subagents.spawn({
+      task: args.task,
+      label: args.label,
+      model: args.model ?? null,
+      timeout: args.timeout_seconds ?? 300,
+      workstream: this._activeWorkstream,
+      onNotify: parentOpts?.onSubagentNotify ?? null,
+    });
+
+    return {
+      success: true,
+      id: agent.id,
+      label: agent.label,
+      status: agent.status,
+      message: `Sub-agent '${agent.label}' spawned (id: ${agent.id}). Use get_subagent_result to check when done.`,
+    };
+  }
+
+  async _toolListSubagents() {
+    const inMemory = this.subagents.list();
+    const history = await this.subagents.listHistory(20);
+
+    // Merge: in-memory takes precedence
+    const inMemoryIds = new Set(inMemory.map(a => a.id));
+    const combined = [
+      ...inMemory.map(a => a.toJSON()),
+      ...history.filter(h => !inMemoryIds.has(h.id)),
+    ].slice(0, 30);
+
+    return {
+      success: true,
+      agents: combined.map(a => ({
+        id: a.id,
+        label: a.label,
+        status: a.status,
+        task: a.task?.slice(0, 80),
+        model: a.model,
+        createdAt: a.createdAt,
+        completedAt: a.completedAt,
+      })),
+      total: combined.length,
+    };
+  }
+
+  async _toolGetSubagentResult(args) {
+    const inMemory = this.subagents.get(args.id);
+    if (inMemory) {
+      return {
+        success: true,
+        ...inMemory.toJSON(),
+        result_preview: inMemory.result?.slice(0, 500),
+      };
+    }
+
+    // Try disk
+    const disk = await this.subagents.loadFromDisk(args.id);
+    if (disk) {
+      return { success: true, ...disk, result_preview: disk.result?.slice(0, 500) };
+    }
+
+    return { success: false, error: `Sub-agent not found: ${args.id}` };
+  }
+
+  _toolKillSubagent(args) {
+    const agent = this.subagents.get(args.id);
+    if (!agent) return { success: false, error: `Sub-agent not found: ${args.id}` };
+    this.subagents.kill(args.id);
+    return { success: true, id: args.id, message: `Sub-agent '${agent.label}' killed.` };
+  }
+
+  _toolSteerSubagent(args) {
+    try {
+      this.subagents.steer(args.id, args.message);
+      return { success: true, id: args.id, message: `Guidance sent to sub-agent.` };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+
   // ── Context optimization ─────────────────────────────────────────────────────
 
   _optimizeContext(messages, maxTokens = 30_000) {

package/core/index.mjs

@@ -12,3 +12,4 @@ 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";
 export { MemoryManager } from "./memory.mjs";
 export { CronManager } from "./cron.mjs";
+export { SubAgentManager, SubAgent } from "./subagents.mjs";

package/core/subagents.mjs

@@ -0,0 +1,343 @@
+/**
+ * core/subagents.mjs — Sub-agent orchestration for Wispy v0.9.0
+ *
+ * Class SubAgentManager:
+ *   - async spawn(opts) → SubAgent
+ *   - list() → SubAgent[]
+ *   - get(id) → SubAgent
+ *   - kill(id) → void
+ *   - steer(id, message) → void
+ *   - async waitFor(id, timeoutMs?) → Result
+ *   - async waitForAll(ids) → Result[]
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { WISPY_DIR } from "./config.mjs";
+
+const SUBAGENTS_DIR = path.join(WISPY_DIR, "subagents");
+
+function makeId() {
+  return `sa-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+export class SubAgent {
+  constructor({ id, task, label, model, timeout, workstream, status = "pending" }) {
+    this.id = id;
+    this.task = task;
+    this.label = label ?? `sub-agent-${id}`;
+    this.model = model ?? null;
+    this.timeout = timeout ?? 300_000; // ms
+    this.workstream = workstream ?? "default";
+    this.status = status; // pending → running → completed | failed | killed | timeout
+    this.result = null;
+    this.error = null;
+    this.createdAt = new Date().toISOString();
+    this.startedAt = null;
+    this.completedAt = null;
+    this._abortController = new AbortController();
+    this._steerMessages = []; // guidance queue
+    this._promise = null; // internal execution promise
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      task: this.task,
+      label: this.label,
+      model: this.model,
+      timeout: this.timeout,
+      workstream: this.workstream,
+      status: this.status,
+      result: this.result,
+      error: this.error,
+      createdAt: this.createdAt,
+      startedAt: this.startedAt,
+      completedAt: this.completedAt,
+    };
+  }
+}
+
+export class SubAgentManager {
+  /**
+   * @param {import('./engine.mjs').WispyEngine} engine
+   * @param {import('./session.mjs').SessionManager} sessionManager
+   */
+  constructor(engine, sessionManager) {
+    this._engine = engine;
+    this._sessions = sessionManager;
+    this._agents = new Map(); // id → SubAgent
+  }
+
+  /**
+   * Spawn a new sub-agent.
+   * @param {object} opts
+   * @param {string} opts.task
+   * @param {string} [opts.label]
+   * @param {string} [opts.model]
+   * @param {number} [opts.timeout] - milliseconds (default 300_000)
+   * @param {string} [opts.workstream]
+   * @param {Function} [opts.onComplete] - callback(result)
+   * @param {Function} [opts.onNotify] - channel notification callback(type, text)
+   * @returns {Promise<SubAgent>}
+   */
+  async spawn(opts) {
+    const agent = new SubAgent({
+      id: makeId(),
+      task: opts.task,
+      label: opts.label,
+      model: opts.model,
+      timeout: opts.timeout ? opts.timeout * 1000 : 300_000,
+      workstream: opts.workstream ?? this._engine._activeWorkstream,
+    });
+
+    this._agents.set(agent.id, agent);
+
+    // Run async without awaiting
+    agent._promise = this._run(agent, opts).catch((err) => {
+      if (agent.status === "running" || agent.status === "pending") {
+        agent.status = "failed";
+        agent.error = err.message;
+        agent.completedAt = new Date().toISOString();
+        this._persist(agent);
+        opts.onNotify?.("error", `❌ Sub-agent '${agent.label}' failed: ${err.message}`);
+      }
+    });
+
+    return agent;
+  }
+
+  /**
+   * Internal: run the sub-agent's agentic loop.
+   */
+  async _run(agent, opts) {
+    agent.status = "running";
+    agent.startedAt = new Date().toISOString();
+
+    // Create an isolated session for this sub-agent
+    const session = this._sessions.create({ workstream: agent.workstream });
+
+    // Build initial messages
+    const systemPrompt = `You are Wispy 🌿 — a sub-agent handling a delegated task.
+Be focused, thorough, and efficient. Complete the task fully.
+Reply in the same language as the task. Sign off with 🌿.`;
+
+    const messages = [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: agent.task },
+    ];
+
+    // Timeout logic
+    let timedOut = false;
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      agent._abortController.abort();
+    }, agent.timeout);
+
+    try {
+      const MAX_ROUNDS = 15;
+      let round = 0;
+
+      while (round < MAX_ROUNDS) {
+        // Check if killed
+        if (agent.status === "killed") break;
+        if (timedOut) {
+          agent.status = "timeout";
+          agent.error = "Timed out";
+          agent.completedAt = new Date().toISOString();
+          await this._persist(agent);
+          opts?.onNotify?.("error", `⏰ Sub-agent '${agent.label}' timed out.`);
+          return;
+        }
+
+        // Inject any steering messages
+        while (agent._steerMessages.length > 0) {
+          const steerMsg = agent._steerMessages.shift();
+          messages.push({ role: "user", content: `[Guidance from orchestrator]: ${steerMsg}` });
+        }
+
+        // Call provider
+        const result = await this._engine.providers.chat(
+          messages,
+          this._engine.tools.getDefinitions(),
+          { model: agent.model }
+        );
+
+        if (result.type === "text") {
+          // Final answer
+          agent.result = result.text;
+          agent.status = "completed";
+          agent.completedAt = new Date().toISOString();
+          await this._persist(agent);
+
+          const summary = result.text.slice(0, 200).replace(/\n/g, " ");
+          opts?.onNotify?.("success", `✅ Sub-agent '${agent.label}' completed: ${summary}`);
+          opts?.onComplete?.(agent);
+          clearTimeout(timeoutHandle);
+          return;
+        }
+
+        // Handle tool calls
+        messages.push({ role: "assistant", toolCalls: result.calls, content: "" });
+
+        for (const call of result.calls) {
+          const toolResult = await this._engine._executeTool(
+            call.name, call.args, messages, session, {}
+          );
+          messages.push({
+            role: "tool_result",
+            toolName: call.name,
+            toolUseId: call.id ?? call.name,
+            result: toolResult,
+          });
+        }
+
+        round++;
+      }
+
+      // Max rounds reached
+      agent.result = "(max rounds reached — partial work above)";
+      agent.status = "completed";
+      agent.completedAt = new Date().toISOString();
+      await this._persist(agent);
+      opts?.onNotify?.("success", `✅ Sub-agent '${agent.label}' completed (max rounds).`);
+    } catch (err) {
+      clearTimeout(timeoutHandle);
+      if (agent.status !== "killed") {
+        agent.status = "failed";
+        agent.error = err.message;
+        agent.completedAt = new Date().toISOString();
+        await this._persist(agent);
+        opts?.onNotify?.("error", `❌ Sub-agent '${agent.label}' failed: ${err.message}`);
+      }
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  /**
+   * List all sub-agents (active + recent in-memory).
+   */
+  list() {
+    return Array.from(this._agents.values());
+  }
+
+  /**
+   * Get a sub-agent by ID.
+   */
+  get(id) {
+    return this._agents.get(id) ?? null;
+  }
+
+  /**
+   * Kill (cancel) a running sub-agent.
+   */
+  kill(id) {
+    const agent = this._agents.get(id);
+    if (!agent) return;
+    if (agent.status === "running" || agent.status === "pending") {
+      agent.status = "killed";
+      agent.completedAt = new Date().toISOString();
+      agent._abortController.abort();
+      this._persist(agent).catch(() => {});
+    }
+  }
+
+  /**
+   * Send guidance/steering to a running sub-agent.
+   */
+  steer(id, message) {
+    const agent = this._agents.get(id);
+    if (!agent) throw new Error(`Sub-agent not found: ${id}`);
+    if (agent.status !== "running" && agent.status !== "pending") {
+      throw new Error(`Sub-agent ${id} is not running (status: ${agent.status})`);
+    }
+    agent._steerMessages.push(message);
+  }
+
+  /**
+   * Wait for a specific sub-agent to complete.
+   * @param {string} id
+   * @param {number} [timeoutMs]
+   * @returns {Promise<{id, status, result, error}>}
+   */
+  async waitFor(id, timeoutMs) {
+    const agent = this._agents.get(id);
+    if (!agent) throw new Error(`Sub-agent not found: ${id}`);
+
+    if (agent.status === "completed" || agent.status === "failed" ||
+        agent.status === "killed" || agent.status === "timeout") {
+      return agent.toJSON();
+    }
+
+    if (!agent._promise) throw new Error(`Sub-agent ${id} has no active promise`);
+
+    if (timeoutMs) {
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`waitFor timed out after ${timeoutMs}ms`)), timeoutMs)
+      );
+      await Promise.race([agent._promise, timeoutPromise]);
+    } else {
+      await agent._promise;
+    }
+
+    return agent.toJSON();
+  }
+
+  /**
+   * Wait for multiple sub-agents to complete.
+   * @param {string[]} ids
+   * @returns {Promise<Array>}
+   */
+  async waitForAll(ids) {
+    return Promise.all(ids.map(id => this.waitFor(id)));
+  }
+
+  /**
+   * Persist a sub-agent's result to disk.
+   */
+  async _persist(agent) {
+    try {
+      await mkdir(SUBAGENTS_DIR, { recursive: true });
+      const filePath = path.join(SUBAGENTS_DIR, `${agent.id}.json`);
+      await writeFile(filePath, JSON.stringify(agent.toJSON(), null, 2) + "\n", "utf8");
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  /**
+   * Load persisted sub-agent from disk (for history).
+   */
+  async loadFromDisk(id) {
+    try {
+      const filePath = path.join(SUBAGENTS_DIR, `${id}.json`);
+      const data = JSON.parse(await readFile(filePath, "utf8"));
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * List persisted sub-agent history from disk.
+   */
+  async listHistory(limit = 20) {
+    try {
+      const { readdir } = await import("node:fs/promises");
+      const files = await readdir(SUBAGENTS_DIR);
+      const jsonFiles = files.filter(f => f.endsWith(".json")).sort().reverse().slice(0, limit);
+      const results = [];
+      for (const f of jsonFiles) {
+        try {
+          const data = JSON.parse(await readFile(path.join(SUBAGENTS_DIR, f), "utf8"));
+          results.push(data);
+        } catch {}
+      }
+      return results;
+    } catch {
+      return [];
+    }
+  }
+}

package/core/tools.mjs

@@ -221,6 +221,60 @@ export class ToolRegistry {
           required: ["task"],
         },
       },
+      // ── Sub-agent tools (v0.9) ───────────────────────────────────────────────
+      {
+        name: "spawn_subagent",
+        description: "Spawn an isolated sub-agent to handle a task independently. Use for parallel work, long-running tasks, or delegating to specialized models.",
+        parameters: {
+          type: "object",
+          properties: {
+            task: { type: "string", description: "The task description/prompt for the sub-agent" },
+            label: { type: "string", description: "Human-readable label for the sub-agent" },
+            model: { type: "string", description: "Model override (e.g., 'flash' for cheap tasks, 'claude-opus-4-5' for complex)" },
+            timeout_seconds: { type: "number", description: "Max runtime in seconds (default 300)" },
+          },
+          required: ["task"],
+        },
+      },
+      {
+        name: "list_subagents",
+        description: "List all sub-agents (active and recent)",
+        parameters: { type: "object", properties: {}, required: [] },
+      },
+      {
+        name: "get_subagent_result",
+        description: "Get the result of a completed sub-agent",
+        parameters: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Sub-agent ID" },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "kill_subagent",
+        description: "Cancel a running sub-agent",
+        parameters: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Sub-agent ID" },
+          },
+          required: ["id"],
+        },
+      },
+      {
+        name: "steer_subagent",
+        description: "Send additional guidance to a running sub-agent",
+        parameters: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Sub-agent ID" },
+            message: { type: "string", description: "Guidance message" },
+          },
+          required: ["id", "message"],
+        },
+      },
     ];
 
     for (const def of builtins) {
@@ -514,6 +568,12 @@ export class ToolRegistry {
         case "pipeline":
         case "spawn_async_agent":
         case "ralph_loop":
+        // Sub-agent tools (v0.9) — handled at engine level
+        case "spawn_subagent":
+        case "list_subagents":
+        case "get_subagent_result":
+        case "kill_subagent":
+        case "steer_subagent":
           return { success: false, error: `Tool "${name}" requires engine context. Call via WispyEngine.processMessage().` };
 
         default:

package/lib/wispy-repl.mjs

@@ -330,6 +330,12 @@ ${bold("Wispy Commands:")}
   ${cyan("/forget")} <key>      Delete a memory file
   ${cyan("/memories")}          List all memory files
   ${cyan("/recall")} <query>    Search memories
+
+${bold("Sub-agent Commands (v0.9):")}
+  ${cyan("/agents")}            List active/recent sub-agents
+  ${cyan("/agent")} <id>        Show sub-agent details and result
+  ${cyan("/kill")} <id>         Cancel a running sub-agent
+
   ${cyan("/quit")} or ${cyan("/exit")}    Exit
 `);
     return true;
@@ -614,6 +620,72 @@ ${bold("Wispy Commands:")}
     return true;
   }
 
+  // ── Sub-agent commands (v0.9) ──────────────────────────────────────────────
+
+  if (cmd === "/agents") {
+    const inMemory = engine.subagents.list();
+    const history = await engine.subagents.listHistory(20);
+    const inMemoryIds = new Set(inMemory.map(a => a.id));
+    const all = [
+      ...inMemory.map(a => a.toJSON()),
+      ...history.filter(h => !inMemoryIds.has(h.id)),
+    ].slice(0, 30);
+
+    if (all.length === 0) {
+      console.log(dim("No sub-agents yet. Ask wispy to spawn one!"));
+    } else {
+      console.log(bold(`\n🤖 Sub-agents (${all.length}):\n`));
+      for (const a of all) {
+        const icon = { completed: green("✓"), failed: red("✗"), running: cyan("⟳"), killed: dim("✕"), timeout: yellow("⏰"), pending: dim("…") }[a.status] ?? "?";
+        const elapsed = a.completedAt ? "" : a.startedAt ? ` ${dim(`(running ${Math.round((Date.now() - new Date(a.startedAt)) / 1000)}s)`)}` : "";
+        console.log(`  ${icon} ${bold(a.id)} ${dim("·")} ${a.label}${elapsed}`);
+        console.log(`     ${dim(`task: ${(a.task ?? "").slice(0, 70)}${(a.task?.length ?? 0) > 70 ? "…" : ""}`)}`);
+        if (a.result) console.log(`     ${dim(`result: ${a.result.slice(0, 80)}${a.result.length > 80 ? "…" : ""}`)}`);
+        if (a.error) console.log(`     ${red(`error: ${a.error.slice(0, 80)}`)}`);
+        console.log("");
+      }
+    }
+    return true;
+  }
+
+  if (cmd === "/agent") {
+    const id = parts[1];
+    if (!id) { console.log(yellow("Usage: /agent <id>")); return true; }
+
+    let agent = engine.subagents.get(id)?.toJSON();
+    if (!agent) agent = await engine.subagents.loadFromDisk(id);
+
+    if (!agent) {
+      console.log(red(`Sub-agent not found: ${id}`));
+    } else {
+      console.log(bold(`\n🤖 Sub-agent: ${agent.id}\n`));
+      console.log(`  ${dim("Label:")}   ${agent.label}`);
+      console.log(`  ${dim("Status:")}  ${agent.status}`);
+      console.log(`  ${dim("Model:")}   ${agent.model ?? "(default)"}`);
+      console.log(`  ${dim("Created:")} ${agent.createdAt}`);
+      if (agent.startedAt) console.log(`  ${dim("Started:")} ${agent.startedAt}`);
+      if (agent.completedAt) console.log(`  ${dim("Done:")}    ${agent.completedAt}`);
+      console.log(`\n  ${bold("Task:")}\n  ${dim(agent.task)}\n`);
+      if (agent.result) {
+        console.log(`  ${bold("Result:")}\n  ${agent.result.slice(0, 2000)}`);
+      }
+      if (agent.error) {
+        console.log(`  ${bold("Error:")} ${red(agent.error)}`);
+      }
+    }
+    return true;
+  }
+
+  if (cmd === "/kill") {
+    const id = parts[1];
+    if (!id) { console.log(yellow("Usage: /kill <id>")); return true; }
+    const agent = engine.subagents.get(id);
+    if (!agent) { console.log(red(`Sub-agent not found: ${id}`)); return true; }
+    engine.subagents.kill(id);
+    console.log(green(`🛑 Sub-agent '${agent.label}' killed.`));
+    return true;
+  }
+
   if (cmd === "/quit" || cmd === "/exit") {
     console.log(dim(`🌿 Bye! (${engine.providers.formatCost()})`));
     engine.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wispy-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "🌿 Wispy — AI workspace assistant with multi-agent orchestration and multi-channel bot support",
   "license": "Apache-2.0",
   "author": "Minseo & Poropo",