kc-beta 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
   "type": "module",
   "bin": {

package/src/agent/context.js

@@ -32,9 +32,11 @@ outcome. Handle ambiguity explicitly — note it, ask the developer user. After
 audit which regulation sections are not yet covered.
 
 ### Entity Extraction
-Prefer regex/Python for predictable formats. Use LLM only when semantic understanding \
-is required. Every extraction captures: value, evidence, source location, confidence, \
-method used.
+Choose the cheapest method that meets accuracy threshold. Regex is the smallest \
+"model" — zero cost, instant, deterministic. Worker LLM handles semantic tasks \
+regex cannot (contextual interpretation, misleading language, adequacy judgment). \
+Try different methods, find the cost-accuracy balance. Every extraction captures: \
+value, evidence, source location, confidence, method used.
 
 ### Skill Authoring
 Write each rule into a skill folder following the Anthropic skill-creator format. A \
@@ -79,13 +81,15 @@ unclear regulations with them. Present results and let them judge.`;
 export class ContextAssembler {
   /**
    * @param {object} [opts]
+   * @param {string} [opts.agentMd] - Content of workspace AGENT.md (per-project context)
    * @param {string} [opts.pipelineState]
    * @param {string} [opts.workspaceState]
    * @param {string} [opts.skillIndex] - Brief index of available meta skills
    * @returns {string}
    */
-  build({ pipelineState, workspaceState, skillIndex } = {}) {
+  build({ agentMd, pipelineState, workspaceState, skillIndex } = {}) {
     const parts = [AGENT_IDENTITY];
+    if (agentMd) parts.push(agentMd);
     if (skillIndex) parts.push(skillIndex);
     if (pipelineState) parts.push(pipelineState);
     if (workspaceState) parts.push(workspaceState);

package/src/agent/engine.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { AgentEvent } from "./events.js";
 import { ContextAssembler } from "./context.js";
 import { ConversationHistory } from "./history.js";
@@ -56,7 +58,7 @@ export class AgentEngine {
     this.context = new ContextAssembler();
 
     // Workspace + structural components
-    this.workspace = new Workspace(config.kcWorkspaceRoot, sessionId);
+    this.workspace = new Workspace(config.kcWorkspaceRoot, sessionId, config.projectDir);
     this.history = new ConversationHistory(this.workspace.cwd);
     this.versionManager = new VersionManager(this.workspace.cwd);
     this.cornerCases = new CornerCaseRegistry(this.workspace.cwd);
@@ -102,12 +104,20 @@ export class AgentEngine {
    * re-register per phase without recreating.
    */
   _createAllTools() {
+    // Worker LLM uses separate config if set, otherwise falls back to conductor
+    const workerApiKey = this.config.effectiveWorkerApiKey();
+    const workerBaseUrl = this.config.effectiveWorkerBaseUrl();
+    const workerAuthType = this.config.effectiveWorkerAuthType();
+
     const workerLlm = new WorkerLLMCallTool(this.workspace, {
-      apiKey: this.config.llmApiKey,
-      baseUrl: this.config.llmBaseUrl,
-      authType: this.config.authType,
+      apiKey: workerApiKey,
+      baseUrl: workerBaseUrl,
+      authType: workerAuthType,
     });
 
+    // OCR/VLM uses worker config (VLM is a type of worker LLM)
+    const vlmModel = this.config.vlmTier1 || "";
+
     return {
       // Always available (BUILD + DISTILL)
       core: [
@@ -116,9 +126,9 @@ export class AgentEngine {
         new DocumentParseTool(this.workspace, {
           mineruApiUrl: this.config.mineruApiUrl,
           mineruApiKey: this.config.mineruApiKey,
-          llmApiKey: this.config.llmApiKey,
-          llmBaseUrl: this.config.llmBaseUrl,
-          ocrModel: this.config.ocrModelTier1,
+          llmApiKey: workerApiKey,
+          llmBaseUrl: workerBaseUrl,
+          ocrModel: vlmModel,
         }),
         new DocumentSearchTool(this.workspace),
         new RuleCatalogTool(this.workspace),
@@ -156,15 +166,52 @@ export class AgentEngine {
     }
   }
 
+  /**
+   * Read AGENT.md from workspace (per-project context).
+   * Returns content string or empty string if not found.
+   */
+  _readAgentMd() {
+    const agentMdPath = path.join(this.workspace.cwd, "AGENT.md");
+    try {
+      if (fs.existsSync(agentMdPath)) {
+        return fs.readFileSync(agentMdPath, "utf-8");
+      }
+    } catch { /* ignore */ }
+    return "";
+  }
+
+  /**
+   * Build the workspace/project directory state string for the system prompt.
+   */
+  _buildWorkspaceState() {
+    const lines = [
+      `## Directory Layout`,
+      `**KC Workspace:** ${this.workspace.cwd}`,
+      `  Use scope="workspace" (default). Write all working files here (rules, skills, workflows, results, logs).`,
+    ];
+    if (this.workspace.projectDir) {
+      lines.push(
+        `**Project Directory:** ${this.workspace.projectDir}`,
+        `  Use scope="project" to read/write files in the user's project folder.`,
+        `  This is where the user's source regulations, samples, and reference documents are.`,
+        ``,
+        `Read source documents from the project directory. Write KC outputs to the workspace.`,
+        `Write user-facing exports (reports, results) to the project directory when the user asks.`,
+      );
+    }
+    return lines.join("\n");
+  }
+
   /**
    * Get current context usage statistics.
    * @returns {{ totalTokens: number, limit: number, percentage: number }}
    */
   getContextStats() {
     const systemPrompt = this.context.build({
+      agentMd: this._readAgentMd(),
       skillIndex: this._skillLoader.formatForContext(),
       pipelineState: this.pipelines[this.currentPhase]?.describeState?.() || null,
-      workspaceState: `Your workspace directory is: ${this.workspace.cwd}`,
+      workspaceState: this._buildWorkspaceState(),
     });
     const systemTokens = estimateTokens(systemPrompt);
     const messageTokens = estimateMessagesTokens(this.history.messages);
@@ -270,6 +317,14 @@ export class AgentEngine {
       engine._phaseSummaries = data.phaseSummaries || [];
       engine._registerToolsForPhase(engine.currentPhase);
 
+      // Restore project directory from saved state
+      if (data.projectDir) {
+        if (fs.existsSync(data.projectDir)) {
+          engine.workspace.projectDir = data.projectDir;
+        }
+        // If dir no longer exists, projectDir stays as whatever was passed at launch
+      }
+
       // Restore pipeline milestones
       const milestones = data.pipelineMilestones || {};
       for (const [phase, mData] of Object.entries(milestones)) {
@@ -309,9 +364,10 @@ export class AgentEngine {
     const pipelineState = pipeline?.describeState?.() || null;
 
     const systemPrompt = this.context.build({
+      agentMd: this._readAgentMd(),
       skillIndex: this._skillLoader.formatForContext(),
       pipelineState,
-      workspaceState: `Your workspace directory is: ${this.workspace.cwd}`,
+      workspaceState: this._buildWorkspaceState(),
     });
     const tools = this.toolRegistry.schemasOpenai();
 

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/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,80 @@ 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
+
+        // Use OffscreenCanvas or node-canvas if available, otherwise skip
+        let imageBase64;
+        try {
+          // In Node.js, pdfjs can render to a canvas-like object
+          // We'll use the simpler approach: convert page to image via the API
+          const { createCanvas } = await import("canvas").catch(() => ({ createCanvas: null }));
+          if (!createCanvas) {
+            // No canvas available — fall back to sending raw text content hint + page number
+            pages.push(`--- Page ${i + 1} (VLM) ---`);
+            continue;
+          }
+          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,
       });