kc-beta 0.3.2 → 0.5.3

package/src/agent/tools/agent-tool.js

@@ -3,27 +3,48 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { BaseTool, ToolResult } from "./base.js";
 
+// Mirrors VALID_ID in scheduler.js — alphanumeric + _- only, max 64 chars.
+// Sub-agent ids are used as path components under sub_agents/, so anything
+// permitting `..` or `/` is a path-traversal risk.
+const VALID_TASK_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+function _newAutoTaskId() {
+  return `task_${crypto.randomUUID().slice(0, 8)}`;
+}
+
 /**
  * Spawn a sub-agent for parallel work.
- * Creates a child AgentEngine sharing the workspace filesystem
- * but with independent conversation history.
- * Results arrive via workspace files.
+ * Creates a child AgentEngine that shares workspace files (rules/, rule_skills/,
+ * workflows/, etc.) but isolates its own persistence under
+ * `sub_agents/<taskId>/` — its own conversation history, event log, and
+ * session-state. Sub-agents inherit the parent's phase so they get the right
+ * tools registered. Results arrive via files written under sub_agents/<taskId>/.
  */
 export class AgentTool extends BaseTool {
-  constructor(workspace, engineFactory) {
+  /**
+   * @param {import('../workspace.js').Workspace} workspace
+   * @param {(opts: {sessionId: string, subagentScope: string, initialPhase: string}) => import('../engine.js').AgentEngine} engineFactory
+   * @param {() => string} getCurrentPhase  Callback returning the parent's current phase (so sub-agents get phase-appropriate tools)
+   */
+  constructor(workspace, engineFactory, getCurrentPhase = () => "bootstrap") {
     super();
     this._workspace = workspace;
     this._engineFactory = engineFactory;
+    this._getCurrentPhase = getCurrentPhase;
     this._runningTasks = new Map();
   }
 
   get name() { return "agent_tool"; }
   get description() {
     return (
-      "Spawn a sub-agent for an independent task. Give it a complete, " +
-      "self-contained task description. The sub-agent works in the same " +
-      "workspace and writes results to files. Use this for parallel rule " +
-      "processing, batch testing, or any work that can run independently."
+      "Spawn a sub-agent for an independent task. The sub-agent must own a " +
+      "non-overlapping unit of work — typically per-rule or per-document — " +
+      "so multiple sub-agents don't have to coordinate through shared mutable " +
+      "files. Do NOT build a lock mechanism inside the sub-agent's task body; " +
+      "concurrent peers + locks bottleneck and fail. The sub-agent's own " +
+      "persistence (history, event log, session-state) lives under " +
+      "sub_agents/<taskId>/; workspace artifacts (rules/, skills/, workflows/) " +
+      "are shared. Give the sub-agent a complete, self-contained task " +
+      "description — it has no conversation context."
     );
   }
 
@@ -35,7 +56,10 @@ export class AgentTool extends BaseTool {
           type: "string",
           description: "Complete task description for the sub-agent. Be specific — it has no conversation context.",
         },
-        task_id: { type: "string", description: "Optional task identifier (auto-generated if omitted)" },
+        task_id: {
+          type: "string",
+          description: "Optional task identifier — alphanumeric + _- only, max 64 chars. Used as a folder name under sub_agents/. If omitted or invalid, an auto-generated id is used.",
+        },
       },
       required: ["task_description"],
     };
@@ -43,19 +67,35 @@ export class AgentTool extends BaseTool {
 
   async execute(input) {
     const taskDesc = input.task_description || "";
-    const taskId = input.task_id || `task_${crypto.randomUUID().slice(0, 8)}`;
+    const requestedId = (input.task_id || "").trim();
+    // Sanitize: anything not matching VALID_TASK_ID is silently replaced with
+    // an auto-generated id. The label survives in result metadata so KC can
+    // still cross-reference, but the path component is always safe.
+    const taskId = requestedId && VALID_TASK_ID.test(requestedId)
+      ? requestedId
+      : _newAutoTaskId();
+    const labelOverridden = requestedId && taskId !== requestedId;
 
     if (!taskDesc) return new ToolResult("No task_description provided", true);
 
-    // Create sub-agent output directory
+    // Create sub-agent output directory (taskId is now sanitized)
     const taskDir = path.join(this._workspace.cwd, "sub_agents", taskId);
     fs.mkdirSync(taskDir, { recursive: true });
     fs.writeFileSync(path.join(taskDir, "task.md"), taskDesc, "utf-8");
+    if (labelOverridden) {
+      fs.writeFileSync(path.join(taskDir, "requested_id.txt"), requestedId, "utf-8");
+    }
 
-    // Create child engine sharing the same workspace
+    // Create child engine. Critical: pass subagentScope + initialPhase so the
+    // child's persistence is isolated to sub_agents/<taskId>/ AND it has the
+    // same tools registered as the parent (Bug 2 fix).
     let childEngine;
     try {
-      childEngine = this._engineFactory(this._workspace.sessionId);
+      childEngine = this._engineFactory({
+        sessionId: this._workspace.sessionId,
+        subagentScope: taskId,
+        initialPhase: this._getCurrentPhase(),
+      });
     } catch (e) {
       return new ToolResult(`Failed to create sub-agent: ${e.message}`, true);
     }
@@ -92,9 +132,12 @@ export class AgentTool extends BaseTool {
 
     return new ToolResult(JSON.stringify({
       task_id: taskId,
+      requested_id: labelOverridden ? requestedId : undefined,
       status: "started",
       output_dir: `sub_agents/${taskId}/`,
-      message: `Sub-agent started. Check sub_agents/${taskId}/status.txt for completion, output.md for text.`,
+      message: labelOverridden
+        ? `Sub-agent started under sanitized id '${taskId}' (your '${requestedId}' wasn't a valid path component). Check sub_agents/${taskId}/status.txt.`
+        : `Sub-agent started. Check sub_agents/${taskId}/status.txt for completion, output.md for text.`,
     }, null, 2));
   }
 }

package/src/agent/tools/archive-file.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * Move a workspace file into an archived/ subdirectory next to it.
+ * Use after a workflow consumes an input doc, or when an old result is no
+ * longer the primary view. If the file is git-tracked, uses `git mv` so
+ * history is preserved.
+ *
+ * Reverse moves (un-archive) are intentionally NOT exposed as a tool —
+ * KC can use sandbox_exec with `mv` for the rare reverse case.
+ */
+export class ArchiveFileTool extends BaseTool {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+  }
+
+  get name() { return "archive_file"; }
+
+  get description() {
+    return (
+      "Move a workspace file to an archived/ subdirectory next to it. " +
+      "Use after a workflow consumes an input doc, or when an old result is no longer primary. " +
+      "Preserves git history if the file is tracked."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Workspace-relative path of the file to archive (e.g. 'input/doc.pdf').",
+        },
+        target_subdir: {
+          type: "string",
+          description: "Subdirectory name (default: 'archived'). Created next to the file's parent.",
+        },
+      },
+      required: ["path"],
+    };
+  }
+
+  async execute(input) {
+    const relPath = input.path || "";
+    const subdir = (input.target_subdir || "archived").replace(/[/\\]/g, "_");
+    if (!relPath) return new ToolResult("path required", true);
+
+    let resolved;
+    try { resolved = this._workspace.resolvePath(relPath); }
+    catch (e) { return new ToolResult(e.message, true); }
+
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+      return new ToolResult(`File not found: ${relPath}`, true);
+    }
+
+    const parentRel = path.dirname(relPath);
+    const baseName = path.basename(relPath);
+    const targetRel = path.join(parentRel, subdir, baseName);
+    const targetAbs = this._workspace.resolvePath(targetRel);
+
+    if (fs.existsSync(targetAbs)) {
+      return new ToolResult(`Target already exists: ${targetRel}`, true);
+    }
+
+    fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+
+    // Try git mv first (preserves history). If it fails (file untracked or
+    // git unavailable), fall back to plain rename.
+    let usedGitMv = false;
+    if (this._workspace.gitAvailable) {
+      const r = spawnSync("git", ["mv", relPath, targetRel], {
+        cwd: this._workspace.cwd, stdio: "ignore",
+      });
+      usedGitMv = r.status === 0;
+    }
+    if (!usedGitMv) {
+      fs.renameSync(resolved, targetAbs);
+    }
+
+    // Auto-commit the move (no-op if both source and target are gitignored)
+    const traceId = this._workspace.autoCommit(targetRel, "archive");
+
+    return new ToolResult(
+      `Archived ${relPath} → ${targetRel}` +
+      (usedGitMv ? " (git history preserved)" : "") +
+      (traceId && this._workspace.gitAvailable ? ` [trace:${traceId}]` : "")
+    );
+  }
+}

package/src/agent/tools/copy-to-workspace.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BaseTool, ToolResult } from "./base.js";
+
+const MANIFEST_REL = "refs/manifest.json";
+const GITIGNORE_REL = ".gitignore";
+
+/**
+ * Copy a specific file from the user's project directory into the workspace
+ * (refs/) for KC to work on as a local copy. Default behavior remains:
+ * read project files in place via scope="project". Use this only when KC
+ * genuinely needs a working copy with provenance recorded.
+ *
+ * Files larger than `largeRefThresholdMB` (default 10 MB) are written but
+ * added to .gitignore so they don't bloat git history.
+ */
+export class CopyToWorkspaceTool extends BaseTool {
+  /**
+   * @param {import('../workspace.js').Workspace} workspace
+   * @param {object} [opts]
+   * @param {number} [opts.largeRefThresholdMB=10]
+   */
+  constructor(workspace, { largeRefThresholdMB = 10 } = {}) {
+    super();
+    this._workspace = workspace;
+    this._largeMB = largeRefThresholdMB;
+  }
+
+  get name() { return "copy_to_workspace"; }
+
+  get description() {
+    return (
+      "Copy a file from the user's project directory into the workspace (refs/) " +
+      "as a local working copy with provenance recorded. " +
+      "Default behavior is to read project files in place via scope='project'; " +
+      "only use this tool when you genuinely need a workspace-local copy " +
+      "(e.g. to modify it, or to feed a workflow that requires the file inside the workspace). " +
+      "Files larger than the configured threshold are written but excluded from git history."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        source_path: {
+          type: "string",
+          description: "Relative path within the project directory (e.g. 'samples/foo.pdf').",
+        },
+        target_name: {
+          type: "string",
+          description: "Optional file name under refs/. Defaults to the source basename.",
+        },
+        reason: {
+          type: "string",
+          description: "Optional reason for the copy, recorded in refs/manifest.json for provenance.",
+        },
+      },
+      required: ["source_path"],
+    };
+  }
+
+  async execute(input) {
+    const sourcePath = input.source_path || "";
+    const reason = input.reason || "";
+    if (!sourcePath) return new ToolResult("source_path required", true);
+    if (!this._workspace.projectDir) {
+      return new ToolResult("No project directory available — KC was launched without a project context.", true);
+    }
+
+    let resolvedSource;
+    try {
+      resolvedSource = this._workspace.resolveProjectPath(sourcePath);
+    } catch (e) {
+      return new ToolResult(e.message, true);
+    }
+
+    if (!fs.existsSync(resolvedSource) || !fs.statSync(resolvedSource).isFile()) {
+      return new ToolResult(`Source file not found: ${sourcePath}`, true);
+    }
+
+    const targetName = (input.target_name || path.basename(resolvedSource)).replace(/[/\\]/g, "_");
+    const targetRel = path.join("refs", targetName);
+    const targetAbs = this._workspace.resolvePath(targetRel);
+
+    fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+    fs.copyFileSync(resolvedSource, targetAbs);
+
+    const stat = fs.statSync(targetAbs);
+    const sizeMB = stat.size / (1024 * 1024);
+    const isLarge = sizeMB > this._largeMB;
+
+    if (isLarge) {
+      this._appendGitignore(`refs/${targetName}`);
+    }
+
+    this._appendManifest({
+      target: targetRel,
+      source: sourcePath,
+      size: stat.size,
+      copied_at: new Date().toISOString(),
+      large_excluded_from_git: isLarge,
+      reason: reason || null,
+    });
+
+    // Auto-commit refs/manifest.json (and the file itself, if small enough to track)
+    const traceId = this._workspace.autoCommit(MANIFEST_REL, "manifest");
+    if (!isLarge) this._workspace.autoCommit(targetRel, "copy");
+
+    return new ToolResult(
+      `Copied ${sourcePath} → ${targetRel} (${stat.size} bytes${isLarge ? ", excluded from git (large)" : ""}). ` +
+      `Provenance recorded${traceId ? ` [trace:${traceId}]` : ""}.`
+    );
+  }
+
+  _appendManifest(entry) {
+    const manifestAbs = this._workspace.resolvePath(MANIFEST_REL);
+    fs.mkdirSync(path.dirname(manifestAbs), { recursive: true });
+    let entries = [];
+    if (fs.existsSync(manifestAbs)) {
+      try { entries = JSON.parse(fs.readFileSync(manifestAbs, "utf-8")); }
+      catch { entries = []; }
+    }
+    if (!Array.isArray(entries)) entries = [];
+    entries.push(entry);
+    fs.writeFileSync(manifestAbs, JSON.stringify(entries, null, 2), "utf-8");
+  }
+
+  _appendGitignore(line) {
+    const giPath = this._workspace.resolvePath(GITIGNORE_REL);
+    let body = "";
+    if (fs.existsSync(giPath)) body = fs.readFileSync(giPath, "utf-8");
+    const lines = body.split("\n").map((l) => l.trim());
+    if (lines.includes(line.trim())) return;
+    if (body.length > 0 && !body.endsWith("\n")) body += "\n";
+    body += line + "\n";
+    fs.writeFileSync(giPath, body, "utf-8");
+    this._workspace.autoCommit(GITIGNORE_REL, "gitignore");
+  }
+}

package/src/agent/tools/phase-advance.js

@@ -0,0 +1,60 @@
+import { BaseTool, ToolResult } from "./base.js";
+import { Phase } from "../pipelines/index.js";
+
+const VALID_PHASES = new Set(Object.values(Phase));
+
+/**
+ * Advance the current phase to a target phase. Used when the user instructs
+ * KC to skip ahead, or when KC judges criteria are met but auto-detect
+ * doesn't see them. Most transitions happen automatically (exit criteria,
+ * task completion); this tool is the explicit-user-request path.
+ *
+ * Linear order is enforced by default — only forward-by-one is allowed.
+ * Pass force=true to skip phases or regress (e.g., when the user explicitly
+ * asks). Description kept short to minimize system-prompt budget cost.
+ */
+export class PhaseAdvanceTool extends BaseTool {
+  constructor(advanceFn) {
+    super();
+    this._advance = advanceFn;
+  }
+
+  get name() { return "phase_advance"; }
+
+  get description() {
+    return "Advance phase. Forward-by-one only unless force=true (use sparingly, e.g. when user asks to skip).";
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        to: {
+          type: "string",
+          enum: Array.from(VALID_PHASES),
+          description: "Target phase",
+        },
+        reason: { type: "string", description: "Why" },
+        force: {
+          type: "boolean",
+          description: "Allow non-adjacent or backward transitions. Default false.",
+        },
+      },
+      required: ["to"],
+    };
+  }
+
+  async execute(input) {
+    const to = input.to;
+    if (!VALID_PHASES.has(to)) return new ToolResult(`Unknown phase: ${to}`, true);
+    const advanced = this._advance(to, input.reason || "agent request", { force: !!input.force });
+    if (!advanced) {
+      // Either already in target phase, or non-adjacent without force
+      return new ToolResult(
+        `Did not advance to ${to}. Either you're already there, or the transition is non-adjacent (set force:true to override).`,
+        false,
+      );
+    }
+    return new ToolResult(`Advanced to ${to}${input.force ? " (forced)" : ""}`);
+  }
+}