chainlesschain 0.42.3 → 0.43.1

package/README.md

@@ -200,7 +200,9 @@ chainlesschain agent --provider openai --api-key sk-...
 
 Built-in tools: `read_file`, `write_file`, `edit_file`, `run_shell`, `search_files`, `list_dir`, `run_skill`, `list_skills`, `run_code`
 
-Agent slash commands: `/plan` (plan mode), `/plan interactive <request>` (LLM-driven planning with skill recommendations), `/model`, `/provider`, `/clear`, `/compact`, `/task`, `/session`, `/stats`, `/auto` (autonomous agent), `/cowork` (multi-agent collaboration)
+Agent slash commands: `/plan` (plan mode), `/plan interactive <request>` (LLM-driven planning with skill recommendations), `/model`, `/provider`, `/clear`, `/compact`, `/task`, `/session`, `/stats`, `/auto` (autonomous agent), `/cowork` (multi-agent collaboration), `/sub-agents` (show active/completed sub-agents)
+
+**Sub-Agent Isolation v2** (v0.43.0): Complex tasks are automatically decomposed into isolated sub-agents, each with its own namespaced memory, scoped context, and lifecycle tracking. Use `/sub-agents` inside an agent session to inspect active and completed sub-agents, token usage, and average durations.
 
 ### `chainlesschain skill <action>`
 
@@ -845,7 +847,7 @@ chainlesschain serve --allow-remote --token <secret>    # Allow remote + auth
 chainlesschain serve --project /path/to/project         # Default project root for sessions
 ```
 
-**Session Protocol** (v0.41.0): WebSocket clients can create stateful agent/chat sessions via `session-create`, send messages via `session-message`, resume previous sessions via `session-resume`, and manage sessions via `session-list`/`session-close`. Supports `slash-command` for in-session commands and `session-answer` for interactive Q&A (SlotFiller/Planner).
+**Session Protocol** (v0.43.0): WebSocket clients can create stateful agent/chat sessions via `session-create`, send messages via `session-message`, resume previous sessions via `session-resume`, and manage sessions via `session-list`/`session-close`. Supports `slash-command` for in-session commands and `session-answer` for interactive Q&A (SlotFiller/Planner).
 
 ---
 
@@ -922,7 +924,7 @@ Configuration is stored at `~/.chainlesschain/config.json`. The CLI creates and
 ```bash
 cd packages/cli
 npm install
-npm test                # Run all tests (2503 tests across 113 files)
+npm test                # Run all tests (2748 tests across 124 files)
 npm run test:unit       # Unit tests only
 npm run test:integration # Integration tests
 npm run test:e2e        # End-to-end tests
@@ -932,15 +934,15 @@ npm run test:e2e        # End-to-end tests
 
 | Category                 | Files   | Tests    | Status          |
 | ------------------------ | ------- | -------- | --------------- |
-| Unit — lib modules       | 56      | 1200+    | All passing     |
+| Unit — lib modules       | 63      | 1380+    | All passing     |
 | Unit — commands          | 15      | 350+     | All passing     |
 | Unit — runtime           | 1       | 6        | All passing     |
-| Integration              | 5       | 30+      | All passing     |
-| E2E                      | 14      | 150+     | All passing     |
+| Integration              | 6       | 40+      | All passing     |
+| E2E                      | 15      | 160+     | All passing     |
 | Core packages (external) | —       | 118      | All passing     |
 | Unit — WS sessions       | 9       | 156      | All passing     |
 | Integration — WS session | 1       | 12       | All passing     |
-| **CLI Total**            | **113** | **2503** | **All passing** |
+| **CLI Total**            | **124** | **2748** | **All passing** |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chainlesschain",
-  "version": "0.42.3",
+  "version": "0.43.1",
   "description": "CLI for ChainlessChain - install, configure, and manage your personal AI management system",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -82,7 +82,7 @@ const TEMPLATES = {
     skills: ["summarize"],
     persona: {
       name: "智能分诊助手",
-      role: "你是一个医疗分诊AI助手，帮助诊所工作人员根据症状和紧急��度对患者进行优先级分类。",
+      role: "你是一个医疗分诊AI助手，帮助诊所工作人员根据症状和紧急程度对患者进行优先级分类。",
       behaviors: [
         "始终先询问患者症状再给出建议",
         "使用标准分诊分类 (ESI 1-5)",

package/src/lib/agent-coordinator.js

@@ -6,6 +6,7 @@
  */
 
 import crypto from "crypto";
+import { SubAgentContext } from "./sub-agent-context.js";
 
 /**
  * Keyword map for agent type detection.
@@ -271,3 +272,113 @@ export function estimateComplexity(task) {
     estimatedSubtasks: Math.max(1, matchedTypes),
   };
 }
+
+// ─── Role-based tool whitelist ──────────────────────────────────────────
+
+export const ROLE_TOOL_WHITELIST = {
+  "code-review": ["read_file", "search_files", "list_dir"],
+  "code-generation": [
+    "read_file",
+    "write_file",
+    "edit_file",
+    "run_shell",
+    "search_files",
+    "list_dir",
+  ],
+  "data-analysis": [
+    "read_file",
+    "search_files",
+    "list_dir",
+    "run_code",
+    "run_shell",
+  ],
+  document: ["read_file", "write_file", "search_files", "list_dir"],
+  testing: [
+    "read_file",
+    "write_file",
+    "edit_file",
+    "run_shell",
+    "search_files",
+    "list_dir",
+    "run_code",
+  ],
+  general: null, // all tools
+};
+
+/**
+ * Execute a decomposed task using isolated sub-agent contexts.
+ * Each subtask gets its own SubAgentContext with role-appropriate tool whitelist.
+ *
+ * @param {{ taskId: string, subtasks: Array }} decomposition - From decomposeTask()
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Working directory
+ * @param {object} [options.db] - Database instance
+ * @param {object} [options.llmOptions] - LLM provider options
+ * @param {string} [options.parentContext] - Condensed context from parent
+ * @returns {Promise<{ taskId: string, status: string, results: Array, summary: string }>}
+ */
+export async function executeDecomposedTask(decomposition, options = {}) {
+  const { subtasks } = decomposition;
+  if (!subtasks || subtasks.length === 0) {
+    return {
+      taskId: decomposition.taskId,
+      status: "empty",
+      results: [],
+      summary: "No subtasks to execute",
+    };
+  }
+
+  const maxConcurrency = options.maxConcurrency || 3;
+
+  // Run subtasks in parallel batches with concurrency limit
+  const results = [];
+  for (let i = 0; i < subtasks.length; i += maxConcurrency) {
+    const batch = subtasks.slice(i, i + maxConcurrency);
+    const batchPromises = batch.map(async (subtask) => {
+      const allowedTools = ROLE_TOOL_WHITELIST[subtask.agentType] || null;
+
+      const subCtx = SubAgentContext.create({
+        role: subtask.agentType,
+        task: subtask.description,
+        inheritedContext: options.parentContext || null,
+        allowedTools,
+        cwd: options.cwd || process.cwd(),
+        db: options.db || null,
+        llmOptions: options.llmOptions || {},
+      });
+
+      try {
+        const result = await subCtx.run(subtask.description);
+        subtask.status = "completed";
+        subtask.result = result.summary;
+        return {
+          id: subtask.id,
+          agentType: subtask.agentType,
+          status: "completed",
+          summary: result.summary,
+          toolsUsed: result.toolsUsed,
+        };
+      } catch (err) {
+        subtask.status = "failed";
+        subtask.result = err.message;
+        return {
+          id: subtask.id,
+          agentType: subtask.agentType,
+          status: "failed",
+          error: err.message,
+        };
+      }
+    });
+
+    const batchResults = await Promise.all(batchPromises);
+    results.push(...batchResults);
+  }
+
+  const aggregated = aggregateResults(subtasks);
+  return {
+    taskId: decomposition.taskId,
+    status: aggregated.status,
+    results,
+    summary: aggregated.summary,
+  };
+}

package/src/lib/agent-core.js

@@ -23,6 +23,7 @@ import { CLISkillLoader } from "./skill-loader.js";
 import { executeHooks, HookEvents } from "./hook-manager.js";
 import { detectPython } from "./cli-anything-bridge.js";
 import { findProjectRoot, loadProjectConfig } from "./project-detector.js";
+import { SubAgentContext } from "./sub-agent-context.js";
 
 // ─── Tool definitions ────────────────────────────────────────────────────
 
@@ -212,6 +213,40 @@ export const AGENT_TOOLS = [
       },
     },
   },
+  {
+    type: "function",
+    function: {
+      name: "spawn_sub_agent",
+      description:
+        "Spawn an isolated sub-agent to handle a subtask. The sub-agent has its own context and message history, and only returns a summary result. Use this for tasks that benefit from focused, independent execution (e.g. code review, summarization, translation).",
+      parameters: {
+        type: "object",
+        properties: {
+          role: {
+            type: "string",
+            description:
+              "Sub-agent role (e.g. code-review, summarizer, translator, debugger)",
+          },
+          task: {
+            type: "string",
+            description: "Task description for the sub-agent",
+          },
+          context: {
+            type: "string",
+            description:
+              "Optional condensed context from the parent agent to pass to the sub-agent",
+          },
+          tools: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              'Optional tool whitelist for the sub-agent (e.g. ["read_file", "search_files"]). If omitted, all tools are available.',
+          },
+        },
+        required: ["role", "task"],
+      },
+    },
+  },
 ];
 
 // ─── Shared skill loader ──────────────────────────────────────────────────
@@ -326,6 +361,16 @@ When the user's problem involves data processing, calculations, file operations,
 
 You are not just a chatbot — you are a capable coding agent. Think step by step, write code when needed, and deliver real results.
 
+## Sub-Agent Isolation
+When a task involves multiple distinct roles (e.g. code review + code generation), or when you need
+focused analysis without polluting your current context, use the spawn_sub_agent tool. Examples:
+- Code review as a separate perspective while you're implementing
+- Summarizing a large file before incorporating it into your response
+- Running a focused analysis (security, performance) on specific code
+- Translating or reformatting content independently
+The sub-agent has its own message history and only returns a summary — your context stays clean.
+Do NOT spawn sub-agents for trivial tasks that you can handle directly.
+
 ## Environment
 ${envLines.join("\n")}
 
@@ -512,7 +557,11 @@ export async function executeTool(name, args, context = {}) {
 
   let toolResult;
   try {
-    toolResult = await executeToolInner(name, args, { skillLoader, cwd });
+    toolResult = await executeToolInner(name, args, {
+      skillLoader,
+      cwd,
+      parentMessages: context.parentMessages,
+    });
   } catch (err) {
     if (hookDb) {
       try {
@@ -550,7 +599,11 @@ export async function executeTool(name, args, context = {}) {
 /**
  * Inner tool execution — no hooks, no plan-mode checks.
  */
-async function executeToolInner(name, args, { skillLoader, cwd }) {
+async function executeToolInner(
+  name,
+  args,
+  { skillLoader, cwd, parentMessages },
+) {
   switch (name) {
     case "read_file": {
       const filePath = path.resolve(cwd, args.path);
@@ -613,6 +666,10 @@ async function executeToolInner(name, args, { skillLoader, cwd }) {
       return _executeRunCode(args, cwd);
     }
 
+    case "spawn_sub_agent": {
+      return _executeSpawnSubAgent(args, { skillLoader, cwd, parentMessages });
+    }
+
     case "search_files": {
       const dir = args.directory ? path.resolve(cwd, args.directory) : cwd;
       try {
@@ -676,6 +733,31 @@ async function executeToolInner(name, args, { skillLoader, cwd }) {
           error: `Skill "${args.skill_name}" not found or has no handler. Use list_skills to see available skills.`,
         };
       }
+
+      // Check if skill requests isolation (via SKILL.md frontmatter)
+      const skillIsolation = match.isolation === true;
+      if (skillIsolation) {
+        // Run skill through isolated sub-agent context
+        const subCtx = SubAgentContext.create({
+          role: `skill-${args.skill_name}`,
+          task: `Execute the "${args.skill_name}" skill with input: ${(args.input || "").substring(0, 200)}`,
+          allowedTools: ["read_file", "search_files", "list_dir"],
+          cwd,
+        });
+        try {
+          const result = await subCtx.run(args.input);
+          return {
+            success: true,
+            isolated: true,
+            skill: args.skill_name,
+            summary: result.summary,
+            toolsUsed: result.toolsUsed,
+          };
+        } catch (err) {
+          return { error: `Isolated skill execution failed: ${err.message}` };
+        }
+      }
+
       try {
         const handlerPath = path.join(match.skillDir, "handler.js");
         const imported = await import(
@@ -953,6 +1035,86 @@ async function _executeRunCode(args, cwd) {
   }
 }
 
+// ─── spawn_sub_agent implementation ──────────────────────────────────────
+
+/**
+ * Execute a spawn_sub_agent tool call.
+ * Creates an isolated SubAgentContext, runs it, and returns only the summary.
+ *
+ * @param {object} args - { role, task, context?, tools? }
+ * @param {object} ctx - { skillLoader, cwd }
+ * @returns {Promise<object>}
+ */
+async function _executeSpawnSubAgent(args, ctx) {
+  const { role, task, context: inheritedContext, tools: allowedTools } = args;
+
+  if (!role || !task) {
+    return { error: "Both 'role' and 'task' are required for spawn_sub_agent" };
+  }
+
+  // Auto-condense parent context if caller didn't provide explicit context
+  let resolvedContext = inheritedContext || null;
+  if (!resolvedContext && Array.isArray(ctx.parentMessages)) {
+    const recentMsgs = ctx.parentMessages
+      .filter((m) => m.role === "assistant" && typeof m.content === "string")
+      .slice(-3)
+      .map((m) => m.content.substring(0, 200));
+    if (recentMsgs.length > 0) {
+      resolvedContext = recentMsgs.join("\n---\n");
+    }
+  }
+
+  const subCtx = SubAgentContext.create({
+    role,
+    task,
+    inheritedContext: resolvedContext,
+    allowedTools: allowedTools || null,
+    cwd: ctx.cwd,
+  });
+
+  try {
+    // Notify registry if available
+    const { SubAgentRegistry } = await import("./sub-agent-registry.js").catch(
+      () => ({ SubAgentRegistry: null }),
+    );
+    if (SubAgentRegistry) {
+      try {
+        SubAgentRegistry.getInstance().register(subCtx);
+      } catch (_err) {
+        // Registry not available — non-critical
+      }
+    }
+
+    const result = await subCtx.run(task);
+
+    // Complete in registry
+    if (SubAgentRegistry) {
+      try {
+        SubAgentRegistry.getInstance().complete(subCtx.id, result);
+      } catch (_err) {
+        // Non-critical
+      }
+    }
+
+    return {
+      success: true,
+      subAgentId: subCtx.id,
+      role: subCtx.role,
+      summary: result.summary,
+      toolsUsed: result.toolsUsed,
+      iterationCount: result.iterationCount,
+      artifactCount: result.artifacts.length,
+    };
+  } catch (err) {
+    subCtx.forceComplete(err.message);
+    return {
+      error: `Sub-agent failed: ${err.message}`,
+      subAgentId: subCtx.id,
+      role: subCtx.role,
+    };
+  }
+}
+
 // ─── LLM chat with tools ─────────────────────────────────────────────────
 
 /**
@@ -1157,6 +1319,7 @@ export async function* agentLoop(messages, options) {
     hookDb: options.hookDb || null,
     skillLoader: options.skillLoader || _defaultSkillLoader,
     cwd: options.cwd || process.cwd(),
+    parentMessages: messages, // pass parent messages for sub-agent auto-condensation
   };
 
   // ── Slot-filling phase ──────────────────────────────────────────────
@@ -1292,6 +1455,8 @@ export function formatToolArgs(name, args) {
       return args.category || args.query || "all";
     case "run_code":
       return `${args.language} (${(args.code || "").length} chars)`;
+    case "spawn_sub_agent":
+      return `[${args.role}] ${(args.task || "").substring(0, 60)}`;
     default:
       return JSON.stringify(args).substring(0, 60);
   }

package/src/lib/cli-context-engineering.js

@@ -40,10 +40,15 @@ export class CLIContextEngineering {
    * @param {object} options
    * @param {object|null} options.db - Database instance (null for graceful degradation)
    * @param {object|null} options.permanentMemory - CLIPermanentMemory instance (optional)
+   * @param {object|null} options.scope - Scoping options for sub-agent isolation
+   * @param {string} [options.scope.taskId] - Task/sub-agent ID
+   * @param {string} [options.scope.role] - Sub-agent role
+   * @param {string} [options.scope.parentObjective] - Parent task objective
    */
-  constructor({ db, permanentMemory } = {}) {
+  constructor({ db, permanentMemory, scope } = {}) {
     this.db = db || null;
     this.permanentMemory = permanentMemory || null;
+    this.scope = scope || null;
     this.errorHistory = [];
     this.taskContext = null;
     this._bm25 = null;
@@ -52,6 +57,15 @@ export class CLIContextEngineering {
     this._compactionSummaries = [];
     // Stable prefix cache: { hash, cleanedPrefix }
     this._prefixCache = null;
+
+    // When scoped, auto-set task context from scope
+    if (this.scope && this.scope.parentObjective) {
+      this.taskContext = {
+        objective: this.scope.parentObjective,
+        steps: [],
+        currentStep: 0,
+      };
+    }
   }
 
   /**
@@ -91,31 +105,46 @@ export class CLIContextEngineering {
       }
     }
 
-    // 3. Memory injection
+    // 3. Memory injection (scoped: higher threshold, namespace-aware)
     if (this.db && userQuery) {
       try {
-        const memories = _deps.recallMemory(this.db, userQuery, { limit: 5 });
+        const memoryQuery = this.scope
+          ? `[${this.scope.role}] ${userQuery}`
+          : userQuery;
+        const memoryOpts = { limit: 5 };
+        if (this.scope) {
+          memoryOpts.namespace = this.scope.taskId;
+        }
+        const memories = _deps.recallMemory(this.db, memoryQuery, memoryOpts);
         if (memories && memories.length > 0) {
-          const lines = memories.map(
-            (m) =>
-              `- [${m.layer}] ${m.content} (retention: ${(m.retention * 100).toFixed(0)}%)`,
-          );
-          result.push({
-            role: "system",
-            content: `## Relevant Memories\n${lines.join("\n")}`,
-          });
+          // When scoped, apply higher relevance threshold to reduce noise
+          const threshold = this.scope ? 0.6 : 0.3;
+          const filtered = memories.filter((m) => m.retention >= threshold);
+          if (filtered.length > 0) {
+            const lines = filtered.map(
+              (m) =>
+                `- [${m.layer}] ${m.content} (retention: ${(m.retention * 100).toFixed(0)}%)`,
+            );
+            result.push({
+              role: "system",
+              content: `## Relevant Memories\n${lines.join("\n")}`,
+            });
+          }
         }
       } catch (_err) {
         // Memory injection failed — skip silently
       }
     }
 
-    // 4. Notes injection (BM25 search)
+    // 4. Notes injection (BM25 search — scoped: role-prefixed query)
     if (this.db && userQuery) {
       try {
         this._ensureNotesIndex();
         if (this._bm25 && this._bm25.totalDocs > 0) {
-          const hits = this._bm25.search(userQuery, {
+          const notesQuery = this.scope
+            ? `[${this.scope.role}] ${userQuery}`
+            : userQuery;
+          const hits = this._bm25.search(notesQuery, {
             topK: 3,
             threshold: 0.5,
           });
@@ -135,10 +164,14 @@ export class CLIContextEngineering {
       }
     }
 
-    // 5. Permanent memory injection
+    // 5. Permanent memory injection (scoped: reduced results)
     if (this.permanentMemory && userQuery) {
       try {
-        const pmResults = this.permanentMemory.getRelevantContext(userQuery, 3);
+        const pmLimit = this.scope ? 2 : 3;
+        const pmResults = this.permanentMemory.getRelevantContext(
+          userQuery,
+          pmLimit,
+        );
         if (pmResults && pmResults.length > 0) {
           const lines = pmResults.map(
             (r) => `- [${r.source || "memory"}] ${r.content}`,

package/src/lib/cowork/debate-review-cli.js

@@ -91,6 +91,16 @@ export async function startDebate({
   }
 
   // Phase 2: Moderator synthesizes final verdict
+  // Summarize each reviewer's output to reduce context pollution for the moderator
+  const REVIEW_SUMMARY_MAX = 300;
+  const reviewSummaries = reviews.map((r) => {
+    const summarized =
+      r.review.length <= REVIEW_SUMMARY_MAX
+        ? r.review
+        : r.review.substring(0, REVIEW_SUMMARY_MAX) + "... [truncated]";
+    return { ...r, reviewSummary: summarized };
+  });
+
   const moderatorMessages = [
     {
       role: "system",
@@ -99,8 +109,8 @@ export async function startDebate({
     },
     {
       role: "user",
-      content: `Multiple reviewers analyzed this code. Synthesize their findings into a final verdict.\n\nTarget: ${target}\n\n${reviews
-        .map((r) => `### ${r.role} (${r.verdict})\n${r.review}`)
+      content: `Multiple reviewers analyzed this code. Synthesize their findings into a final verdict.\n\nTarget: ${target}\n\n${reviewSummaries
+        .map((r) => `### ${r.role} (${r.verdict})\n${r.reviewSummary}`)
         .join(
           "\n\n---\n\n",
         )}\n\nProvide:\n1. Final Verdict: APPROVE / NEEDS_WORK / REJECT\n2. Consensus Score: 0-100 (how much the reviewers agree)\n3. Summary of key findings across all perspectives\n4. Priority action items (if any)`,