kc-beta 0.2.1 → 0.3.1

package/src/agent/pipelines/initializer.js

@@ -1,9 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { Phase, PipelineEvent } from "./index.js";
 import { Pipeline } from "./base.js";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_MD_TEMPLATE = path.resolve(__dirname, "../../../template/AGENT.md");
+
 const REQUIRED_DIRS = ["rules", "samples", "input", "output", "logs", "workflows", "rule_skills"];
 
 const DEFAULT_ENV = `# === KC Agent Project Configuration ===
@@ -74,6 +78,12 @@ export class ProjectInitializer extends Pipeline {
       fs.writeFileSync(manifestPath, JSON.stringify({ version: "0.1.0", entries: [] }, null, 2), "utf-8");
     }
 
+    // AGENT.md — per-project context (agent can modify)
+    const agentMdPath = path.join(this._workspace.cwd, "AGENT.md");
+    if (!fs.existsSync(agentMdPath) && fs.existsSync(AGENT_MD_TEMPLATE)) {
+      fs.copyFileSync(AGENT_MD_TEMPLATE, agentMdPath);
+    }
+
     this.workspaceCreated = true;
     this._checkRegulations();
     this._checkSamples();
@@ -81,15 +91,41 @@ export class ProjectInitializer extends Pipeline {
   }
 
   _checkRegulations() {
+    // Check workspace rules/
     const dir = path.join(this._workspace.cwd, "rules");
-    if (!fs.existsSync(dir)) { this.hasRegulations = false; return; }
-    this.hasRegulations = fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile());
+    if (fs.existsSync(dir) && fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile())) {
+      this.hasRegulations = true; return;
+    }
+    // Check project dir rules/ (case-insensitive)
+    if (this._workspace.projectDir) {
+      for (const name of ["rules", "Rules", "RULES", "regulations", "Regulations"]) {
+        const pdir = path.join(this._workspace.projectDir, name);
+        if (fs.existsSync(pdir) && fs.statSync(pdir).isDirectory() &&
+            fs.readdirSync(pdir, { withFileTypes: true }).some((e) => e.isFile())) {
+          this.hasRegulations = true; return;
+        }
+      }
+    }
+    this.hasRegulations = false;
   }
 
   _checkSamples() {
+    // Check workspace samples/
     const dir = path.join(this._workspace.cwd, "samples");
-    if (!fs.existsSync(dir)) { this.hasSamples = false; return; }
-    this.hasSamples = fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile());
+    if (fs.existsSync(dir) && fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile())) {
+      this.hasSamples = true; return;
+    }
+    // Check project dir samples/ (case-insensitive)
+    if (this._workspace.projectDir) {
+      for (const name of ["samples", "Samples", "SAMPLES", "sample", "Sample"]) {
+        const pdir = path.join(this._workspace.projectDir, name);
+        if (fs.existsSync(pdir) && fs.statSync(pdir).isDirectory() &&
+            fs.readdirSync(pdir, { withFileTypes: true }).some((e) => e.isFile())) {
+          this.hasSamples = true; return;
+        }
+      }
+    }
+    this.hasSamples = false;
   }
 
   _checkConfig() {
@@ -115,10 +151,13 @@ export class ProjectInitializer extends Pipeline {
     const completed = [], pending = [];
     if (this.workspaceCreated) completed.push("Workspace structure created"); else pending.push("Workspace structure");
     if (this.configReady) completed.push("API keys configured"); else pending.push("API keys (check .env)");
-    if (this.hasRegulations) completed.push("Regulation documents in rules/"); else pending.push("Regulation documents in rules/");
-    if (this.hasSamples) completed.push("Sample documents in samples/"); else pending.push("Sample documents in samples/");
+    if (this.hasRegulations) completed.push("Regulation documents found"); else pending.push("Regulation documents (add to rules/ in workspace or project dir)");
+    if (this.hasSamples) completed.push("Sample documents found"); else pending.push("Sample documents (add to samples/ in workspace or project dir)");
 
     const parts = ["## Phase: BOOTSTRAP\nSet up the workspace and understand the developer user's verification scenario. Bundled methodology skills are available in the workspace skills/ directory."];
+    if (this._workspace.projectDir) {
+      parts.push(`**Project directory:** ${this._workspace.projectDir}\nUse scope="project" to read files from the user's project folder.`);
+    }
     if (completed.length) parts.push("### Done\n" + completed.map((c) => `- [x] ${c}`).join("\n"));
     if (pending.length) parts.push("### Needed\n" + pending.map((p) => `- [ ] ${p}`).join("\n"));
 
@@ -135,14 +174,20 @@ export class ProjectInitializer extends Pipeline {
     if (toolName === "workspace_file") {
       const op = toolInput.operation || "";
       const p = toolInput.path || "";
-      if (op === "write") {
+      const scope = toolInput.scope || "workspace";
+      if (op === "write" && scope === "workspace") {
         if (p.startsWith("rules/")) this.hasRegulations = true;
         else if (p.startsWith("samples/")) this.hasSamples = true;
         else if (p === ".env") this._checkConfig();
-      } else if (op === "list") {
+      } else if (op === "list" || op === "read") {
+        // Re-check after any list/read — project dir files may satisfy criteria
         this._checkRegulations();
         this._checkSamples();
       }
+    } else if (toolName === "document_parse") {
+      // Parsing a document from project dir counts as having files
+      this._checkRegulations();
+      this._checkSamples();
     }
 
     if (!wasReady && this.exitCriteriaMet()) {

package/src/agent/session-state.js

@@ -29,6 +29,7 @@ export class SessionState {
       version: 1,
       sessionId: engine.workspace.sessionId,
       currentPhase: engine.currentPhase,
+      projectDir: engine.workspace.projectDir || null,
       phaseSummaries: engine._phaseSummaries || [],
       lastEventSeq: engine.eventLog?.currentSeq || 0,
       createdAt: this._loadRaw()?.createdAt || new Date().toISOString(),

package/src/agent/skill-loader.js

@@ -130,7 +130,19 @@ export class SkillLoader {
 
       const frontmatter = match[1];
       const name = frontmatter.match(/^name:\s*(.+)$/m)?.[1]?.trim() || "";
-      const description = frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
+
+      // Handle both single-line and multi-line (YAML >) descriptions
+      let description = "";
+      const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+      if (descMatch && descMatch[1].trim() === ">") {
+        // Multi-line: capture indented lines after "description: >"
+        const multiMatch = frontmatter.match(/^description:\s*>\s*\n((?:[ \t]+.+\n?)*)/m);
+        if (multiMatch) {
+          description = multiMatch[1].replace(/^[ \t]+/gm, "").replace(/\n/g, " ").trim();
+        }
+      } else if (descMatch) {
+        description = descMatch[1].trim();
+      }
       return { name, description };
     } catch {
       return {};

package/src/agent/task-manager.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Manages a per-session task list for ralph-loop style autonomous execution.
+ * Tasks are generated from KC's rule catalog — each rule becomes a task.
+ * Persisted to workspace/tasks.json.
+ */
+export class TaskManager {
+  /**
+   * @param {string} workspacePath - Session workspace directory
+   */
+  constructor(workspacePath) {
+    this._path = path.join(workspacePath, "tasks.json");
+    this._tasks = [];
+    this._load();
+  }
+
+  // --- Task CRUD ---
+
+  /**
+   * Add a task to the list.
+   * @param {{ id: string, title: string, phase: string, ruleId?: string }} task
+   */
+  addTask({ id, title, phase, ruleId }) {
+    // Don't add duplicates
+    if (this._tasks.find((t) => t.id === id)) return;
+    this._tasks.push({
+      id,
+      title,
+      phase,
+      ruleId: ruleId || null,
+      status: "pending",
+      summary: null,
+      createdAt: new Date().toISOString(),
+      completedAt: null,
+    });
+    this.save();
+  }
+
+  /**
+   * Update a task's status and optional summary.
+   * @param {string} id
+   * @param {{ status?: string, summary?: string }} updates
+   */
+  updateTask(id, { status, summary } = {}) {
+    const task = this._tasks.find((t) => t.id === id);
+    if (!task) return;
+    if (status) {
+      task.status = status;
+      if (status === "completed" || status === "failed") {
+        task.completedAt = new Date().toISOString();
+      }
+    }
+    if (summary !== undefined) task.summary = summary;
+    this.save();
+  }
+
+  /**
+   * Get the next pending task.
+   * @returns {object|null}
+   */
+  getNextPending() {
+    return this._tasks.find((t) => t.status === "pending") || null;
+  }
+
+  /**
+   * Get all tasks.
+   * @returns {Array}
+   */
+  getAllTasks() {
+    return [...this._tasks];
+  }
+
+  /**
+   * Check if there are any tasks at all.
+   */
+  get hasTasks() {
+    return this._tasks.length > 0;
+  }
+
+  // --- Bulk creation from rule catalog ---
+
+  /**
+   * Create one task per rule for a given phase.
+   * Reads rules from the provided array (typically from rules/catalog.json).
+   * @param {Array<{id: string, title?: string, description?: string}>} rules
+   * @param {string} phase - The phase these tasks belong to
+   */
+  createRuleTasks(rules, phase) {
+    for (const rule of rules) {
+      const ruleId = rule.id || rule.rule_id;
+      const title = rule.title || rule.description || ruleId;
+      this.addTask({
+        id: `${ruleId}-${phase}`,
+        title: `${title}`,
+        phase,
+        ruleId,
+      });
+    }
+  }
+
+  // --- Progress ---
+
+  /**
+   * @returns {{ total: number, completed: number, inProgress: number, pending: number, failed: number }}
+   */
+  get progress() {
+    const total = this._tasks.length;
+    const completed = this._tasks.filter((t) => t.status === "completed").length;
+    const inProgress = this._tasks.filter((t) => t.status === "in_progress").length;
+    const failed = this._tasks.filter((t) => t.status === "failed").length;
+    const pending = this._tasks.filter((t) => t.status === "pending").length;
+    return { total, completed, inProgress, pending, failed };
+  }
+
+  /**
+   * Format task list for injection into system prompt context.
+   * Compact checklist — not conversation history.
+   * @returns {string}
+   */
+  describeForContext() {
+    if (this._tasks.length === 0) return "";
+
+    const { total, completed, inProgress } = this.progress;
+    const current = this._tasks.find((t) => t.status === "in_progress");
+    const currentPhase = current?.phase || this._tasks.find((t) => t.status === "pending")?.phase || "";
+
+    const lines = [
+      `## Task Progress`,
+      `${completed}/${total} completed${currentPhase ? ` | Phase: ${currentPhase}` : ""}${current ? ` | Current: ${current.ruleId} — ${current.title}` : ""}`,
+      "",
+    ];
+
+    for (const t of this._tasks) {
+      const mark = t.status === "completed" ? "[x]"
+        : t.status === "in_progress" ? "[>]"
+        : t.status === "failed" ? "[!]"
+        : "[ ]";
+      const arrow = t.status === "in_progress" ? " <-- current" : "";
+      lines.push(`- ${mark} ${t.ruleId || t.id}: ${t.title}${arrow}`);
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Format for /tasks slash command (more detailed than context injection).
+   * @returns {string}
+   */
+  formatForDisplay() {
+    if (this._tasks.length === 0) return "No tasks. Tasks are created when rules are extracted.";
+
+    const { total, completed, pending, failed } = this.progress;
+    const lines = [
+      `Tasks: ${completed}/${total} completed${failed ? `, ${failed} failed` : ""}, ${pending} pending`,
+      "",
+    ];
+
+    for (const t of this._tasks) {
+      const icon = t.status === "completed" ? "✓"
+        : t.status === "in_progress" ? "▸"
+        : t.status === "failed" ? "✗"
+        : "·";
+      lines.push(`  ${icon} ${t.ruleId || t.id}  ${t.title}  (${t.status})`);
+    }
+
+    return lines.join("\n");
+  }
+
+  // --- Persistence ---
+
+  save() {
+    fs.writeFileSync(this._path, JSON.stringify(this._tasks, null, 2), "utf-8");
+  }
+
+  _load() {
+    if (fs.existsSync(this._path)) {
+      try {
+        this._tasks = JSON.parse(fs.readFileSync(this._path, "utf-8"));
+      } catch {
+        this._tasks = [];
+      }
+    }
+  }
+}

package/src/agent/tools/document-parse.js

@@ -12,13 +12,13 @@ const MIN_CHARS_PER_PAGE = 50;
  * Level 3: OCR models via SiliconFlow — fallback via vision models
  */
 export class DocumentParseTool extends BaseTool {
-  constructor(workspace, { mineruApiUrl, mineruApiKey, llmApiKey, llmBaseUrl, siliconflowApiKey, siliconflowBaseUrl, ocrModel } = {}) {
+  constructor(workspace, { mineruApiUrl, mineruApiKey, llmApiKey, llmBaseUrl, ocrModel } = {}) {
     super();
     this._workspace = workspace;
     this._mineruApiUrl = mineruApiUrl || "";
     this._mineruApiKey = mineruApiKey || "";
-    this._sfApiKey = llmApiKey || siliconflowApiKey || "";
-    this._sfBaseUrl = llmBaseUrl || siliconflowBaseUrl || "https://api.siliconflow.cn/v1";
+    this._vlmApiKey = llmApiKey || "";
+    this._vlmBaseUrl = (llmBaseUrl || "").replace(/\/+$/, "");
     this._ocrModel = ocrModel || "";
   }
 
@@ -36,13 +36,18 @@ export class DocumentParseTool extends BaseTool {
     return {
       type: "object",
       properties: {
-        path: { type: "string", description: "Relative path to the document in the workspace" },
+        path: { type: "string", description: "Relative path to the document" },
         pages: { type: "string", description: "Page range to extract, e.g. '1-5', '3', '10-20'. Omit for all pages." },
         force_method: {
           type: "string",
-          enum: ["pdfjs", "mineru", "ocr"],
+          enum: ["pdfjs", "vlm", "mineru", "ocr"],
           description: "Force a specific parsing method, skipping the escalation chain.",
         },
+        scope: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Which directory to find the file in. 'workspace' (default) or 'project' (user's project folder).",
+        },
       },
       required: ["path"],
     };
@@ -52,11 +57,19 @@ export class DocumentParseTool extends BaseTool {
     const pathStr = input.path || "";
     const pages = input.pages;
     const force = input.force_method;
+    const scope = input.scope || "workspace";
 
     if (!pathStr) return new ToolResult("No path provided", true);
+    if (scope === "project" && !this._workspace.projectDir) {
+      return new ToolResult("No project directory available", true);
+    }
 
     let resolved;
-    try { resolved = this._workspace.resolvePath(pathStr); }
+    try {
+      resolved = scope === "project"
+        ? this._workspace.resolveProjectPath(pathStr)
+        : this._workspace.resolvePath(pathStr);
+    }
     catch (e) { return new ToolResult(e.message, true); }
 
     if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
@@ -76,13 +89,21 @@ export class DocumentParseTool extends BaseTool {
     if (force) return this._runMethod(force, resolved, pageRange);
 
     // Escalation chain
-    // Level 1: pdfjs-dist
+    // Level 1: pdfjs-dist (free, local text extraction)
     let result = await this._tryPdfjs(resolved, pageRange);
     if (result && this._qualityOk(result)) {
       return new ToolResult(this._formatOutput(result, "pdfjs", resolved));
     }
 
-    // Level 2: MineRU API
+    // Level 2: Provider VLM (vision model via API — more convenient than local OCR)
+    if (this._vlmApiKey && this._ocrModel) {
+      result = await this._tryVlm(resolved, pageRange);
+      if (result && this._qualityOk(result)) {
+        return new ToolResult(this._formatOutput(result, "vlm", resolved));
+      }
+    }
+
+    // Level 3: MineRU API (optional fallback)
     if (this._mineruApiUrl) {
       result = await this._tryMineru(resolved, pageRange);
       if (result && this._qualityOk(result)) {
@@ -90,12 +111,6 @@ export class DocumentParseTool extends BaseTool {
       }
     }
 
-    // Level 3: OCR via SiliconFlow
-    if (this._sfApiKey && this._ocrModel) {
-      result = await this._tryOcr(resolved, pageRange);
-      if (result) return new ToolResult(this._formatOutput(result, "ocr", resolved));
-    }
-
     if (result) return new ToolResult(this._formatOutput(result, "pdfjs (low quality)", resolved));
 
     return new ToolResult(
@@ -108,7 +123,7 @@ export class DocumentParseTool extends BaseTool {
     let result;
     if (method === "pdfjs") result = await this._tryPdfjs(filePath, pageRange);
     else if (method === "mineru") result = await this._tryMineru(filePath, pageRange);
-    else if (method === "ocr") result = await this._tryOcr(filePath, pageRange);
+    else if (method === "ocr" || method === "vlm") result = await this._tryVlm(filePath, pageRange);
     else return new ToolResult(`Unknown method: ${method}`, true);
 
     if (result) return new ToolResult(this._formatOutput(result, method, filePath));
@@ -145,12 +160,75 @@ export class DocumentParseTool extends BaseTool {
     return null;
   }
 
-  async _tryOcr(filePath, pageRange) {
-    // OCR requires sending page images to a vision model API.
-    // Without a native image renderer, we delegate to the agent
-    // to use sandbox_exec for custom OCR pipelines.
-    // For now, return null to signal OCR is not available natively.
-    return null;
+  async _tryVlm(filePath, pageRange) {
+    // Send page images to a VLM provider for OCR/interpretation.
+    // Renders PDF pages to PNG via pdfjs canvas, then sends base64 to VLM API.
+    if (!this._vlmApiKey || !this._ocrModel || !this._vlmBaseUrl) return null;
+
+    try {
+      const pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
+      const data = new Uint8Array(fs.readFileSync(filePath));
+      const doc = await pdfjsLib.getDocument({ data, useSystemFonts: true }).promise;
+
+      const start = pageRange ? pageRange[0] : 0;
+      const end = pageRange ? pageRange[1] : doc.numPages - 1;
+      const pages = [];
+
+      for (let i = Math.max(0, start); i <= Math.min(end, doc.numPages - 1); i++) {
+        const page = await doc.getPage(i + 1);
+        const viewport = page.getViewport({ scale: 2.0 }); // Higher res for OCR
+
+        // Render to PNG via node-canvas if available; otherwise skip VLM and let
+        // the escalation chain fall through to MineRU.
+        let imageBase64;
+        try {
+          const { createCanvas } = await import("canvas").catch(() => ({ createCanvas: null }));
+          if (!createCanvas) return null;
+          const canvas = createCanvas(viewport.width, viewport.height);
+          const ctx = canvas.getContext("2d");
+          await page.render({ canvasContext: ctx, viewport }).promise;
+          imageBase64 = canvas.toBuffer("image/png").toString("base64");
+        } catch {
+          continue;
+        }
+
+        if (!imageBase64) continue;
+
+        // Call VLM API with the page image
+        const baseUrl = this._vlmBaseUrl.replace(/\/+$/, "");
+        const resp = await fetch(`${baseUrl}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this._vlmApiKey}`,
+          },
+          body: JSON.stringify({
+            model: this._ocrModel,
+            messages: [
+              { role: "system", content: "Extract all text from this document page. Preserve structure: headings, paragraphs, tables (as markdown), lists. Output clean text only." },
+              { role: "user", content: [
+                { type: "image_url", image_url: { url: `data:image/png;base64,${imageBase64}` } },
+                { type: "text", text: "Extract all text from this page." },
+              ]},
+            ],
+            max_tokens: 4096,
+          }),
+          signal: AbortSignal.timeout(60000),
+        });
+
+        if (resp.ok) {
+          const result = await resp.json();
+          const text = result.choices?.[0]?.message?.content || "";
+          if (text.trim()) {
+            pages.push(`--- Page ${i + 1} ---\n${text.trim()}`);
+          }
+        }
+      }
+
+      return pages.length > 0 ? pages.join("\n\n") : null;
+    } catch {
+      return null;
+    }
   }
 
   _qualityOk(text) {

package/src/agent/tools/document-search.js

@@ -21,8 +21,10 @@ export class DocumentSearchTool extends BaseTool {
 
   get description() {
     return (
-      "Search for text across documents in the workspace. Returns matching " +
-      "passages with file path and context. Supports plain text and regex queries."
+      "Search for text across documents. " +
+      "scope='workspace' (default) searches KC's workspace. " +
+      "scope='project' searches the user's project directory. " +
+      "Returns matching passages with file path and context. Supports plain text and regex queries."
     );
   }
 
@@ -31,9 +33,14 @@ export class DocumentSearchTool extends BaseTool {
       type: "object",
       properties: {
         query: { type: "string", description: "Search query (plain text or regex pattern)" },
-        path: { type: "string", description: "Subdirectory to search in (default: entire workspace)" },
+        path: { type: "string", description: "Subdirectory to search in (default: entire scope root)" },
         max_results: { type: "integer", description: `Maximum results to return (default: ${MAX_RESULTS})` },
         regex: { type: "boolean", description: "Treat query as regex pattern (default: false)" },
+        scope: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Which directory to search. 'workspace' (default) or 'project'.",
+        },
       },
       required: ["query"],
     };
@@ -44,11 +51,19 @@ export class DocumentSearchTool extends BaseTool {
     const searchPath = input.path || ".";
     const maxResults = input.max_results || MAX_RESULTS;
     const useRegex = input.regex || false;
+    const scope = input.scope || "workspace";
 
     if (!query) return new ToolResult("No query provided", true);
+    if (scope === "project" && !this._workspace.projectDir) {
+      return new ToolResult("No project directory available", true);
+    }
 
     let searchDir;
-    try { searchDir = this._workspace.resolvePath(searchPath); }
+    try {
+      searchDir = scope === "project"
+        ? this._workspace.resolveProjectPath(searchPath)
+        : this._workspace.resolvePath(searchPath);
+    }
     catch (e) { return new ToolResult(e.message, true); }
 
     if (!fs.existsSync(searchDir) || !fs.statSync(searchDir).isDirectory()) {
@@ -62,8 +77,9 @@ export class DocumentSearchTool extends BaseTool {
       return new ToolResult(`Invalid regex: ${e.message}`, true);
     }
 
+    const baseDir = scope === "project" ? this._workspace.projectDir : this._workspace.cwd;
     const results = [];
-    this._searchDir(searchDir, pattern, results, maxResults);
+    this._searchDir(searchDir, pattern, results, maxResults, baseDir);
 
     if (results.length === 0) return new ToolResult(`No matches found for: ${query}`);
 
@@ -76,7 +92,7 @@ export class DocumentSearchTool extends BaseTool {
     return new ToolResult(`Found ${results.length} match(es):\n\n${lines.join("\n")}`);
   }
 
-  _searchDir(dir, pattern, results, maxResults) {
+  _searchDir(dir, pattern, results, maxResults, baseDir) {
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
     catch { return; }
@@ -87,7 +103,7 @@ export class DocumentSearchTool extends BaseTool {
 
       if (entry.isDirectory()) {
         if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "__pycache__") continue;
-        this._searchDir(fullPath, pattern, results, maxResults);
+        this._searchDir(fullPath, pattern, results, maxResults, baseDir);
       } else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
         let content;
         try { content = fs.readFileSync(fullPath, "utf-8"); }
@@ -100,7 +116,7 @@ export class DocumentSearchTool extends BaseTool {
           const end = Math.min(content.length, match.index + match[0].length + CONTEXT_CHARS);
           const context = content.slice(start, end).trim();
           const lineNum = content.slice(0, match.index).split("\n").length;
-          const relPath = path.relative(this._workspace.cwd, fullPath);
+          const relPath = path.relative(baseDir, fullPath);
 
           results.push({ file: relPath, line: lineNum, match: match[0], context });
           if (results.length >= maxResults) break;

package/src/agent/tools/sandbox-exec.js

@@ -23,8 +23,9 @@ export class SandboxExecTool extends BaseTool {
 
   get description() {
     return (
-      "Execute a shell command in the workspace directory. " +
-      "Use for running scripts, installing packages, listing files, etc. " +
+      "Execute a shell command. " +
+      "cwd='workspace' (default) runs in KC's workspace. " +
+      "cwd='project' runs in the user's project directory. " +
       "Pipes, redirects, and chained commands (&&) are supported."
     );
   }
@@ -37,6 +38,11 @@ export class SandboxExecTool extends BaseTool {
           type: "string",
           description: "The shell command to execute (e.g. 'python script.py', 'ls -la')",
         },
+        cwd: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Working directory. 'workspace' (default) = KC's workspace. 'project' = user's project directory.",
+        },
       },
       required: ["command"],
     };
@@ -44,12 +50,17 @@ export class SandboxExecTool extends BaseTool {
 
   async execute(input) {
     const command = input.command || "";
+    const cwdScope = input.cwd || "workspace";
     if (!command.trim()) {
       return new ToolResult("No command provided", true);
     }
 
+    const effectiveCwd = (cwdScope === "project" && this._workspace.projectDir)
+      ? this._workspace.projectDir
+      : this._workspace.cwd;
+
     try {
-      const { output, code } = await this._run(command);
+      const { output, code } = await this._run(command, effectiveCwd);
       let result = output;
       if (result.length > MAX_OUTPUT) {
         result = result.slice(0, MAX_OUTPUT) + "\n[truncated]";
@@ -70,11 +81,11 @@ export class SandboxExecTool extends BaseTool {
    * @param {string} command
    * @returns {Promise<{output: string, code: number}>}
    */
-  _run(command) {
+  _run(command, cwd) {
     return new Promise((resolve, reject) => {
       const controller = new AbortController();
       const proc = spawn("sh", ["-c", command], {
-        cwd: this._workspace.cwd,
+        cwd,
         stdio: ["ignore", "pipe", "pipe"],
         signal: controller.signal,
       });