chainlesschain 0.42.2 → 0.43.0

package/src/lib/sub-agent-context.js

@@ -0,0 +1,296 @@
+/**
+ * Sub-Agent Context — isolated execution context for child agents.
+ *
+ * Provides message isolation, independent context engineering, tool whitelisting,
+ * iteration limits, and result summarization. Sub-agents run in their own
+ * context and only return a summary to the parent agent.
+ *
+ * @module sub-agent-context
+ */
+
+import crypto from "crypto";
+import { CLIContextEngineering } from "./cli-context-engineering.js";
+import { agentLoop, buildSystemPrompt, AGENT_TOOLS } from "./agent-core.js";
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_ITERATIONS = 8;
+const SUMMARY_DIRECT_THRESHOLD = 500; // chars — below this, use result as-is
+const SUMMARY_SECTION_PATTERN =
+  /^##\s*(Summary|Result|Output|Conclusion|Answer)/im;
+const TRUNCATE_LENGTH = 500;
+
+// ─── SubAgentContext ────────────────────────────────────────────────────────
+
+export class SubAgentContext {
+  /**
+   * Factory method — creates an isolated sub-agent context.
+   *
+   * @param {object} options
+   * @param {string} options.role - Sub-agent role (e.g. "code-review", "summarizer")
+   * @param {string} options.task - Task description for the sub-agent
+   * @param {string} [options.parentId] - Parent context ID (null for root)
+   * @param {string|null} [options.inheritedContext] - Condensed context from parent
+   * @param {string[]} [options.allowedTools] - Tool whitelist (null = all tools)
+   * @param {number} [options.maxIterations] - Iteration limit
+   * @param {number} [options.tokenBudget] - Optional token budget
+   * @param {object} [options.db] - Database instance
+   * @param {object} [options.permanentMemory] - Permanent memory instance
+   * @param {object} [options.llmOptions] - LLM provider/model/key options
+   * @param {string} [options.cwd] - Working directory
+   * @returns {SubAgentContext}
+   */
+  static create(options = {}) {
+    return new SubAgentContext(options);
+  }
+
+  constructor(options = {}) {
+    this.id = `sub-${crypto.randomUUID().slice(0, 12)}`;
+    this.parentId = options.parentId || null;
+    this.role = options.role || "general";
+    this.task = options.task || "";
+    this.maxIterations = options.maxIterations || DEFAULT_MAX_ITERATIONS;
+    this.tokenBudget = options.tokenBudget || null;
+    this.inheritedContext = options.inheritedContext || null;
+    this.allowedTools = options.allowedTools || null; // null = all
+    this.cwd = options.cwd || process.cwd();
+    this.status = "active";
+    this.result = null;
+    this.createdAt = new Date().toISOString();
+    this.completedAt = null;
+
+    // ── Isolated state ──────────────────────────────────────────────
+    // Independent message history — never shared with parent
+    this.messages = [];
+
+    // Independent context engine — does not inherit parent's compaction/errors
+    this.contextEngine = new CLIContextEngineering({
+      db: options.db || null,
+      permanentMemory: options.permanentMemory || null,
+      scope: {
+        taskId: this.id,
+        role: this.role,
+        parentObjective: this.task,
+      },
+    });
+
+    // Track tool usage and token consumption
+    this._toolsUsed = [];
+    this._tokenCount = 0;
+    this._iterationCount = 0;
+
+    // LLM options for chatWithTools
+    this._llmOptions = options.llmOptions || {};
+
+    // Build isolated system prompt
+    const basePrompt = buildSystemPrompt(this.cwd);
+    const rolePrompt = `\n\n## Sub-Agent Role: ${this.role}\nYou are a focused sub-agent with the role "${this.role}". Your task is:\n${this.task}\n\nStay focused on this specific task. Be concise and return results directly.`;
+    const contextSection = this.inheritedContext
+      ? `\n\n## Parent Context\n${this.inheritedContext}`
+      : "";
+
+    this.messages.push({
+      role: "system",
+      content: basePrompt + rolePrompt + contextSection,
+    });
+  }
+
+  /**
+   * Run the sub-agent loop with the given user prompt.
+   * Collects events, enforces iteration limit, and returns a structured result.
+   *
+   * @param {string} userPrompt - The task prompt for this sub-agent
+   * @param {object} [loopOptions] - Additional options for agentLoop
+   * @returns {Promise<{ summary: string, artifacts: Array, tokenCount: number, toolsUsed: string[], iterationCount: number }>}
+   */
+  async run(userPrompt, loopOptions = {}) {
+    if (this.status !== "active") {
+      throw new Error(
+        `SubAgentContext ${this.id} is not active (status: ${this.status})`,
+      );
+    }
+
+    // Add user message
+    this.messages.push({ role: "user", content: userPrompt });
+
+    const artifacts = [];
+    let lastContent = "";
+
+    // Build filtered tool list
+    const tools = this._getFilteredTools();
+
+    // Merge LLM options
+    const options = {
+      ...this._llmOptions,
+      contextEngine: this.contextEngine,
+      cwd: this.cwd,
+      ...loopOptions,
+    };
+
+    try {
+      // Use a separate messages array for the agent loop
+      // The agentLoop will append to this.messages directly
+      const gen = agentLoop(this.messages, options);
+
+      for await (const event of gen) {
+        this._iterationCount++;
+
+        if (event.type === "tool-executing") {
+          this._toolsUsed.push(event.tool);
+        }
+
+        if (event.type === "tool-result") {
+          // Store large tool results as artifacts
+          const resultStr = JSON.stringify(event.result);
+          // Estimate token count from tool result (~4 chars per token)
+          this._tokenCount += Math.ceil(resultStr.length / 4);
+          if (resultStr.length > 2000) {
+            artifacts.push({
+              type: "tool-output",
+              tool: event.tool,
+              content: resultStr,
+              truncated: resultStr.length > 10000,
+            });
+          }
+        }
+
+        if (event.type === "response-complete") {
+          lastContent = event.content || "";
+          // Estimate token count from response content (~4 chars per token)
+          this._tokenCount += Math.ceil((lastContent.length || 0) / 4);
+        }
+
+        // Enforce token budget
+        if (this.tokenBudget && this._tokenCount >= this.tokenBudget) {
+          this.forceComplete("token-budget-exceeded");
+          break;
+        }
+
+        // Enforce iteration limit
+        if (this._iterationCount >= this.maxIterations * 3) {
+          // 3 events per iteration (executing + result + potential response)
+          break;
+        }
+      }
+    } catch (err) {
+      this.status = "failed";
+      this.completedAt = new Date().toISOString();
+      this.result = {
+        summary: `Sub-agent failed: ${err.message}`,
+        artifacts: [],
+        tokenCount: this._tokenCount,
+        toolsUsed: [...new Set(this._toolsUsed)],
+        iterationCount: this._iterationCount,
+      };
+      return this.result;
+    }
+
+    // Summarize the result
+    const summary = this.summarize(lastContent);
+
+    this.status = "completed";
+    this.completedAt = new Date().toISOString();
+    this.result = {
+      summary,
+      artifacts,
+      tokenCount: this._tokenCount,
+      toolsUsed: [...new Set(this._toolsUsed)],
+      iterationCount: this._iterationCount,
+    };
+
+    return this.result;
+  }
+
+  /**
+   * Three-level summarization strategy.
+   *
+   * 1. Direct use — result ≤ 500 chars → return as-is
+   * 2. Section extraction — if result contains ## Summary/Result → extract that section
+   * 3. Truncate + artifact — take first 500 chars, store full output as artifact
+   *
+   * @param {string} content - Raw result content
+   * @returns {string} Summarized content
+   */
+  summarize(content) {
+    if (!content || content.length === 0) {
+      return "(No output from sub-agent)";
+    }
+
+    // Strategy 1: Direct use for short content
+    if (content.length <= SUMMARY_DIRECT_THRESHOLD) {
+      return content;
+    }
+
+    // Strategy 2: Extract structured section
+    const match = content.match(SUMMARY_SECTION_PATTERN);
+    if (match) {
+      const sectionStart = match.index;
+      // Find end of section (next ## heading or end of string)
+      const rest = content.slice(sectionStart + match[0].length);
+      const nextHeading = rest.search(/^##\s/m);
+      const section =
+        nextHeading >= 0 ? rest.slice(0, nextHeading).trim() : rest.trim();
+      if (section.length > 0 && section.length <= 1000) {
+        return section;
+      }
+    }
+
+    // Strategy 3: Truncate + note
+    return (
+      content.substring(0, TRUNCATE_LENGTH) +
+      `\n...[truncated, full output: ${content.length} chars]`
+    );
+  }
+
+  /**
+   * Get filtered tools based on allowedTools whitelist.
+   * @returns {Array} Filtered AGENT_TOOLS
+   */
+  _getFilteredTools() {
+    if (!this.allowedTools || this.allowedTools.length === 0) {
+      return AGENT_TOOLS;
+    }
+    return AGENT_TOOLS.filter((t) =>
+      this.allowedTools.includes(t.function.name),
+    );
+  }
+
+  /**
+   * Force-complete this sub-agent (e.g. on timeout or parent cancellation).
+   * @param {string} [reason] - Reason for force-completion
+   */
+  forceComplete(reason = "forced") {
+    if (this.status === "active") {
+      this.status = "completed";
+      this.completedAt = new Date().toISOString();
+      if (!this.result) {
+        this.result = {
+          summary: `(Sub-agent force-completed: ${reason})`,
+          artifacts: [],
+          tokenCount: this._tokenCount,
+          toolsUsed: [...new Set(this._toolsUsed)],
+          iterationCount: this._iterationCount,
+        };
+      }
+    }
+  }
+
+  /**
+   * Get a serializable snapshot of this context (for debugging/logging).
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      parentId: this.parentId,
+      role: this.role,
+      task: this.task,
+      status: this.status,
+      messageCount: this.messages.length,
+      toolsUsed: [...new Set(this._toolsUsed)],
+      tokenCount: this._tokenCount,
+      iterationCount: this._iterationCount,
+      createdAt: this.createdAt,
+      completedAt: this.completedAt,
+    };
+  }
+}

package/src/lib/sub-agent-registry.js

@@ -0,0 +1,186 @@
+/**
+ * Sub-Agent Registry — lifecycle tracking for sub-agents.
+ *
+ * Tracks active sub-agents, maintains completion history (ring buffer),
+ * and provides statistics. Singleton pattern for process-wide access.
+ *
+ * @module sub-agent-registry
+ */
+
+// ─── Ring Buffer ────────────────────────────────────────────────────────────
+
+class RingBuffer {
+  constructor(capacity = 100) {
+    this._buffer = new Array(capacity);
+    this._capacity = capacity;
+    this._head = 0;
+    this._size = 0;
+  }
+
+  push(item) {
+    this._buffer[this._head] = item;
+    this._head = (this._head + 1) % this._capacity;
+    if (this._size < this._capacity) this._size++;
+  }
+
+  toArray() {
+    if (this._size === 0) return [];
+    if (this._size < this._capacity) {
+      return this._buffer.slice(0, this._size);
+    }
+    // Wrap around — oldest first
+    return [
+      ...this._buffer.slice(this._head),
+      ...this._buffer.slice(0, this._head),
+    ];
+  }
+
+  get size() {
+    return this._size;
+  }
+
+  clear() {
+    this._buffer = new Array(this._capacity);
+    this._head = 0;
+    this._size = 0;
+  }
+}
+
+// ─── SubAgentRegistry ───────────────────────────────────────────────────────
+
+export class SubAgentRegistry {
+  static _instance = null;
+
+  /**
+   * Get or create the singleton instance.
+   * @returns {SubAgentRegistry}
+   */
+  static getInstance() {
+    if (!SubAgentRegistry._instance) {
+      SubAgentRegistry._instance = new SubAgentRegistry();
+    }
+    return SubAgentRegistry._instance;
+  }
+
+  /**
+   * Reset singleton (for testing).
+   */
+  static resetInstance() {
+    SubAgentRegistry._instance = null;
+  }
+
+  constructor() {
+    /** @type {Map<string, import("./sub-agent-context.js").SubAgentContext>} */
+    this._active = new Map();
+
+    /** @type {RingBuffer} */
+    this._completed = new RingBuffer(100);
+
+    this._totalTokens = 0;
+    this._totalDurationMs = 0;
+    this._completedCount = 0;
+  }
+
+  /**
+   * Register an active sub-agent.
+   * @param {import("./sub-agent-context.js").SubAgentContext} subCtx
+   */
+  register(subCtx) {
+    this._active.set(subCtx.id, subCtx);
+  }
+
+  /**
+   * Mark a sub-agent as completed and move to history.
+   * @param {string} id - Sub-agent ID
+   * @param {object} result - { summary, artifacts, tokenCount, toolsUsed, iterationCount }
+   */
+  complete(id, result) {
+    const subCtx = this._active.get(id);
+    if (!subCtx) return;
+
+    this._active.delete(id);
+
+    const record = {
+      id: subCtx.id,
+      parentId: subCtx.parentId,
+      role: subCtx.role,
+      task: subCtx.task,
+      status: subCtx.status,
+      summary: result?.summary || "(no summary)",
+      toolsUsed: result?.toolsUsed || [],
+      tokenCount: result?.tokenCount || 0,
+      iterationCount: result?.iterationCount || 0,
+      createdAt: subCtx.createdAt,
+      completedAt: subCtx.completedAt || new Date().toISOString(),
+      durationMs: subCtx.completedAt
+        ? new Date(subCtx.completedAt) - new Date(subCtx.createdAt)
+        : Date.now() - new Date(subCtx.createdAt).getTime(),
+    };
+
+    this._completed.push(record);
+    this._totalTokens += record.tokenCount;
+    this._totalDurationMs += record.durationMs;
+    this._completedCount++;
+  }
+
+  /**
+   * Get all active sub-agents.
+   * @returns {Array<object>}
+   */
+  getActive() {
+    return [...this._active.values()].map((ctx) => ctx.toJSON());
+  }
+
+  /**
+   * Get completion history (most recent last).
+   * @returns {Array<object>}
+   */
+  getHistory() {
+    return this._completed.toArray();
+  }
+
+  /**
+   * Force-complete all sub-agents belonging to a session.
+   * Used by ws-session-manager on session close.
+   *
+   * @param {string} [sessionId] - If provided, only force-complete agents whose parentId matches
+   */
+  forceCompleteAll(sessionId) {
+    for (const [id, subCtx] of this._active) {
+      if (!sessionId || subCtx.parentId === sessionId) {
+        subCtx.forceComplete("session-closed");
+        this.complete(id, subCtx.result);
+      }
+    }
+  }
+
+  /**
+   * Clean up stale entries older than maxAgeMs.
+   * @param {number} [maxAgeMs=600000] - Max age in ms (default: 10 minutes)
+   */
+  cleanup(maxAgeMs = 600000) {
+    const cutoff = Date.now() - maxAgeMs;
+    for (const [id, subCtx] of this._active) {
+      if (new Date(subCtx.createdAt).getTime() < cutoff) {
+        subCtx.forceComplete("timeout");
+        this.complete(id, subCtx.result);
+      }
+    }
+  }
+
+  /**
+   * Get registry statistics.
+   */
+  getStats() {
+    return {
+      active: this._active.size,
+      completed: this._completedCount,
+      historySize: this._completed.size,
+      totalTokens: this._totalTokens,
+      avgDurationMs:
+        this._completedCount > 0
+          ? Math.round(this._totalDurationMs / this._completedCount)
+          : 0,
+    };
+  }
+}

package/src/lib/ws-session-manager.js

@@ -19,6 +19,7 @@ import {
   listSessions as dbListSessions,
 } from "./session-manager.js";
 import { buildSystemPrompt } from "./agent-core.js";
+import { SubAgentRegistry } from "./sub-agent-registry.js";
 
 /**
  * @typedef {object} Session
@@ -266,6 +267,13 @@ export class WSSessionManager {
       }
     }
 
+    // Force-complete any active sub-agents for this session
+    try {
+      SubAgentRegistry.getInstance().forceCompleteAll(sessionId);
+    } catch (_err) {
+      // Non-critical
+    }
+
     // Clean up plan manager listeners
     if (session.planManager) {
       session.planManager.removeAllListeners();

package/src/repl/agent-repl.js

@@ -262,6 +262,9 @@ export async function startAgentRepl(options = {}) {
         `  ${chalk.cyan("/plan approve")} Approve and execute the plan`,
       );
       logger.log(`  ${chalk.cyan("/plan reject")}  Reject the plan`);
+      logger.log(
+        `  ${chalk.cyan("/sub-agents")}  Show active/completed sub-agents`,
+      );
       logger.log(chalk.bold("\nCapabilities:"));
       logger.log("  Read, write, and edit files");
       logger.log("  Run shell commands (git, npm, etc.)");
@@ -275,6 +278,48 @@ export async function startAgentRepl(options = {}) {
       return;
     }
 
+    if (trimmed === "/sub-agents" || trimmed === "/subagents") {
+      try {
+        const { SubAgentRegistry } =
+          await import("../lib/sub-agent-registry.js");
+        const registry = SubAgentRegistry.getInstance();
+        const active = registry.getActive();
+        const history = registry.getHistory();
+        const stats = registry.getStats();
+
+        logger.log(chalk.bold("\nSub-Agent Registry:"));
+        logger.log(
+          `  Active: ${chalk.yellow(active.length)}  Completed: ${chalk.green(stats.completed)}  Tokens: ${stats.totalTokens}  Avg Duration: ${stats.avgDurationMs}ms`,
+        );
+
+        if (active.length > 0) {
+          logger.log(chalk.bold("\n  Active Sub-Agents:"));
+          for (const a of active) {
+            logger.log(
+              `    ${chalk.cyan(a.id)} [${a.role}] ${a.task.substring(0, 50)} (iter: ${a.iterationCount})`,
+            );
+          }
+        }
+
+        if (history.length > 0) {
+          logger.log(chalk.bold("\n  Recent History (last 10):"));
+          for (const h of history.slice(-10)) {
+            const status =
+              h.status === "completed" ? chalk.green("✓") : chalk.red("✗");
+            logger.log(
+              `    ${status} ${chalk.dim(h.id)} [${h.role}] ${(h.summary || "").substring(0, 60)}`,
+            );
+          }
+        }
+
+        logger.log("");
+      } catch (_err) {
+        logger.log(chalk.dim("Sub-agent registry not available."));
+      }
+      prompt();
+      return;
+    }
+
     if (trimmed.startsWith("/model")) {
       const arg = trimmed.slice(6).trim();
       if (arg) {