kc-beta 0.1.2 → 0.3.0

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,
       });

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

@@ -0,0 +1,107 @@
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * Web search via Tavily API.
+ * Returns extracted text content from search results.
+ */
+export class WebSearchTool extends BaseTool {
+  /**
+   * @param {string} apiKey - Tavily API key
+   */
+  constructor(apiKey) {
+    super();
+    this._apiKey = apiKey;
+  }
+
+  get name() { return "web_search"; }
+
+  get description() {
+    return (
+      "Search the web for information using Tavily. Returns extracted text from top results. " +
+      "IMPORTANT: Always prioritize information from user-provided domain documents " +
+      "(uploaded regulations, sample files, workspace documents) over web search results. " +
+      "Use web search only when: (1) the needed information is not in provided documents, " +
+      "(2) you need to verify or supplement document content with external sources, or " +
+      "(3) the user explicitly asks for web information (e.g., latest LLM model info, API docs)."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "The search query",
+        },
+        search_depth: {
+          type: "string",
+          enum: ["basic", "advanced"],
+          description: "Search depth: 'basic' for fast results, 'advanced' for more thorough search (default: basic)",
+        },
+        max_results: {
+          type: "integer",
+          description: "Maximum number of results to return (default: 5, max: 10)",
+        },
+      },
+      required: ["query"],
+    };
+  }
+
+  async execute(input) {
+    const query = input.query || "";
+    if (!query.trim()) {
+      return new ToolResult("No query provided", true);
+    }
+
+    if (!this._apiKey) {
+      return new ToolResult(
+        "Web search is not configured. Set TAVILY_API_KEY in your .env file or global config.",
+        true,
+      );
+    }
+
+    const searchDepth = input.search_depth || "basic";
+    const maxResults = Math.min(input.max_results || 5, 10);
+
+    try {
+      const resp = await fetch("https://api.tavily.com/search", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          api_key: this._apiKey,
+          query,
+          search_depth: searchDepth,
+          max_results: maxResults,
+        }),
+        signal: AbortSignal.timeout(15000),
+      });
+
+      if (!resp.ok) {
+        const text = await resp.text();
+        return new ToolResult(`Tavily API error ${resp.status}: ${text}`, true);
+      }
+
+      const data = await resp.json();
+      const results = data.results || [];
+
+      if (results.length === 0) {
+        return new ToolResult(`No results found for: ${query}`);
+      }
+
+      const lines = [];
+      for (const r of results) {
+        lines.push(`--- ${r.title || "Untitled"} ---`);
+        lines.push(`URL: ${r.url || ""}`);
+        lines.push(r.content || "(no content)");
+        lines.push("");
+      }
+
+      return new ToolResult(
+        `Found ${results.length} result(s) for "${query}":\n\n${lines.join("\n")}`,
+      );
+    } catch (err) {
+      return new ToolResult(`Web search failed: ${err.message}`, true);
+    }
+  }
+}

package/src/agent/tools/worker-llm-call.js

@@ -8,15 +8,27 @@ import { BaseTool, ToolResult } from "./base.js";
  * the configured API provider.
  */
 export class WorkerLLMCallTool extends BaseTool {
-  constructor(workspace, { apiKey, baseUrl } = {}) {
+  constructor(workspace, { apiKey, baseUrl, authType = "bearer" } = {}) {
     super();
     this._workspace = workspace;
     this._apiKey = apiKey || "";
     this._baseUrl = (baseUrl || "https://api.siliconflow.cn/v1").replace(/\/+$/, "");
+    this._authType = authType;
     this._tierModels = {};
     this._loadTiers();
   }
 
+  _buildHeaders() {
+    const headers = { "Content-Type": "application/json" };
+    if (this._authType === "x-api-key") {
+      headers["x-api-key"] = this._apiKey;
+      headers["anthropic-version"] = "2023-06-01";
+    } else {
+      headers["Authorization"] = `Bearer ${this._apiKey}`;
+    }
+    return headers;
+  }
+
   _loadTiers() {
     const envPath = path.join(this._workspace.cwd, ".env");
     if (!fs.existsSync(envPath)) return;
@@ -78,10 +90,7 @@ export class WorkerLLMCallTool extends BaseTool {
       try {
         const resp = await fetch(`${this._baseUrl}/chat/completions`, {
           method: "POST",
-          headers: {
-            "Authorization": `Bearer ${this._apiKey}`,
-            "Content-Type": "application/json",
-          },
+          headers: this._buildHeaders(),
           body: JSON.stringify({ model, messages, max_tokens: maxTokens }),
           signal: AbortSignal.timeout(120000),
         });

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

@@ -5,9 +5,9 @@ import { BaseTool, ToolResult } from "./base.js";
 const MAX_READ = 50_000;
 
 /**
- * Read, write, or list files in the workspace directory.
- * All paths are resolved relative to the workspace root with
- * traversal protection. VersionManager hooks into writes for automatic versioning.
+ * Read, write, or list files in the workspace or project directory.
+ * All paths are resolved relative to the chosen scope with
+ * traversal protection. VersionManager hooks into workspace writes for automatic versioning.
  */
 export class WorkspaceFileTool extends BaseTool {
   /**
@@ -24,9 +24,10 @@ export class WorkspaceFileTool extends BaseTool {
 
   get description() {
     return (
-      "Read, write, or list files in the workspace directory. " +
-      "Operations: read (returns file content), write (creates/overwrites a file), " +
-      "list (shows directory contents)."
+      "Read, write, or list files. " +
+      "scope='workspace' (default): KC's working directory for rules, skills, workflows, results. " +
+      "scope='project': the user's project folder where KC was launched — source regulations and samples live here. " +
+      "Operations: read (returns file content), write (creates/overwrites a file), list (shows directory contents)."
     );
   }
 
@@ -41,34 +42,58 @@ export class WorkspaceFileTool extends BaseTool {
         },
         path: {
           type: "string",
-          description: "Relative path within the workspace. Defaults to '.' for list.",
+          description: "Relative path within the chosen scope. Defaults to '.' for list.",
         },
         content: {
           type: "string",
           description: "File content to write (required for write operation)",
         },
+        scope: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Which directory to operate in. 'workspace' (default) = KC's workspace. 'project' = user's project directory.",
+        },
       },
       required: ["operation"],
     };
   }
 
+  _resolveForScope(filePath, scope) {
+    if (scope === "project") {
+      return this._workspace.resolveProjectPath(filePath);
+    }
+    return this._workspace.resolvePath(filePath);
+  }
+
+  _baseForScope(scope) {
+    if (scope === "project") {
+      return this._workspace.projectDir;
+    }
+    return this._workspace.cwd;
+  }
+
   async execute(input) {
     const op = input.operation || "";
     const filePath = input.path || ".";
     const content = input.content || "";
+    const scope = input.scope || "workspace";
+
+    if (scope === "project" && !this._workspace.projectDir) {
+      return new ToolResult("No project directory available. KC was launched without a project context.", true);
+    }
 
     try {
-      if (op === "read") return this._read(filePath);
-      if (op === "write") return this._write(filePath, content);
-      if (op === "list") return this._list(filePath);
+      if (op === "read") return this._read(filePath, scope);
+      if (op === "write") return this._write(filePath, content, scope);
+      if (op === "list") return this._list(filePath, scope);
       return new ToolResult(`Unknown operation: ${op}`, true);
     } catch (err) {
       return new ToolResult(`File error: ${err.message}`, true);
     }
   }
 
-  _read(filePath) {
-    const resolved = this._workspace.resolvePath(filePath);
+  _read(filePath, scope) {
+    const resolved = this._resolveForScope(filePath, scope);
     if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
       return new ToolResult(`File not found: ${filePath}`, true);
     }
@@ -79,27 +104,28 @@ export class WorkspaceFileTool extends BaseTool {
     return new ToolResult(text);
   }
 
-  _write(filePath, content) {
+  _write(filePath, content, scope) {
     if (!filePath || filePath === ".") {
       return new ToolResult("Path required for write operation", true);
     }
-    const resolved = this._workspace.resolvePath(filePath);
+    const resolved = this._resolveForScope(filePath, scope);
     fs.mkdirSync(path.dirname(resolved), { recursive: true });
     fs.writeFileSync(resolved, content, "utf-8");
 
-    // Version tracking (structural — cannot be bypassed)
+    // Version tracking only for workspace writes
     let traceId = null;
-    if (this._versionManager) {
+    if (scope === "workspace" && this._versionManager) {
       traceId = this._versionManager.onWrite(filePath, content);
     }
 
-    let msg = `Wrote ${content.length} chars to ${filePath}`;
+    const label = scope === "project" ? `[project] ${filePath}` : filePath;
+    let msg = `Wrote ${content.length} chars to ${label}`;
     if (traceId) msg += ` [trace: ${traceId}]`;
     return new ToolResult(msg);
   }
 
-  _list(filePath) {
-    const resolved = this._workspace.resolvePath(filePath);
+  _list(filePath, scope) {
+    const resolved = this._resolveForScope(filePath, scope);
     if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
       return new ToolResult(`Not a directory: ${filePath}`, true);
     }
@@ -112,8 +138,9 @@ export class WorkspaceFileTool extends BaseTool {
     if (entries.length === 0) {
       return new ToolResult("(empty directory)");
     }
+    const base = this._baseForScope(scope);
     const lines = entries.map((e) => {
-      const rel = path.relative(this._workspace.cwd, path.join(resolved, e.name));
+      const rel = path.relative(base, path.join(resolved, e.name));
       const marker = e.isDirectory() ? "[dir] " : "      ";
       return `${marker}${rel}`;
     });

package/src/agent/workspace.js

@@ -11,11 +11,13 @@ export class Workspace {
   /**
    * @param {string} root - Workspace root directory
    * @param {string} [sessionId] - Session identifier (auto-generated if omitted)
+   * @param {string} [projectDir] - User's project directory (CWD at launch)
    */
-  constructor(root, sessionId) {
+  constructor(root, sessionId, projectDir) {
     this.root = path.resolve(root);
     this.sessionId = sessionId || crypto.randomUUID().replace(/-/g, "").slice(0, 12);
     this.path = path.resolve(this.root, this.sessionId);
+    this.projectDir = projectDir ? path.resolve(projectDir) : null;
     fs.mkdirSync(this.path, { recursive: true });
   }
 
@@ -42,6 +44,27 @@ export class Workspace {
     return resolved;
   }
 
+  /**
+   * Resolve a user-supplied relative path against the project directory.
+   * Same traversal protection as resolvePath() but for the project folder.
+   * @param {string} userPath
+   * @returns {string}
+   */
+  resolveProjectPath(userPath) {
+    if (!this.projectDir) {
+      throw new Error("No project directory available");
+    }
+    if (path.isAbsolute(userPath)) {
+      throw new Error(`Absolute paths not allowed: ${userPath}`);
+    }
+    const resolved = path.resolve(this.projectDir, userPath);
+    const base = path.resolve(this.projectDir);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      throw new Error(`Path escapes project directory: ${userPath}`);
+    }
+    return resolved;
+  }
+
   /**
    * Rename the workspace folder. Returns the new sessionId.
    * @param {string} newName

package/src/cli/components.js

@@ -12,7 +12,7 @@ const COOKING_WORDS = [
   "Stewing", "Tempering", "Whisking", "Zesting", "Garnishing", "Drizzling",
 ];
 
-export function CookingSpinner() {
+export function CookingSpinner({ status }) {
   const [idx, setIdx] = useState(Math.floor(Math.random() * COOKING_WORDS.length));
 
   useEffect(() => {
@@ -20,9 +20,11 @@ export function CookingSpinner() {
     return () => clearInterval(timer);
   }, []);
 
+  const displayText = status || `${COOKING_WORDS[idx]}...`;
+
   return h(Box, null,
     h(Text, { color: "yellow" }, "  * "),
-    h(Text, { dimColor: true }, `${COOKING_WORDS[idx]}...`),
+    h(Text, { dimColor: true }, displayText),
   );
 }
 
@@ -30,19 +32,29 @@ export function CookingSpinner() {
 
 const LENAT_QUOTE = "Intelligence is ten million rules.";
 
-export function StatusBar({ sessionId, phase }) {
+export function StatusBar({ sessionId, phase, contextTokens, contextLimit }) {
+  const pct = contextLimit ? Math.round((contextTokens / contextLimit) * 100) : 0;
+  const ctxColor = pct > 80 ? "red" : pct > 60 ? "yellow" : "green";
+  const ctxLabel = contextTokens >= 1000
+    ? `${(contextTokens / 1000).toFixed(1)}k`
+    : `${contextTokens || 0}`;
+  const limitLabel = contextLimit >= 1000
+    ? `${(contextLimit / 1000).toFixed(0)}k`
+    : `${contextLimit || 0}`;
+
   return h(Box, { marginTop: 0 },
     h(Text, { dimColor: true }, "  ⏵⏵  KC Agent CLI "),
     h(Text, { dimColor: true }, sessionId ? `[${sessionId}]` : ""),
     phase ? h(Text, { color: "cyan" }, ` ${phase.toUpperCase()}`) : null,
     h(Text, { color: "green" }, "  ●  "),
-    h(Text, { dimColor: true }, `· ${LENAT_QUOTE}`),
+    h(Text, { color: ctxColor }, `CTX: ${ctxLabel}/${limitLabel} (${pct}%)`),
+    h(Text, { dimColor: true }, `  · ${LENAT_QUOTE}`),
   );
 }
 
 // --- Welcome banner ---
 
-export function WelcomeBanner() {
+export function WelcomeBanner({ projectDir } = {}) {
   return h(Box, { flexDirection: "column", marginBottom: 1, borderStyle: "round", borderColor: "gray", paddingLeft: 1, paddingRight: 1 },
     h(Box, null,
       h(Text, { bold: true }, "KC AGENT CLI"),
@@ -50,6 +62,13 @@ export function WelcomeBanner() {
     ),
     h(Text, { dimColor: true }, "Hope you never know what KC was."),
     h(Text, null, ""),
+    projectDir
+      ? h(Box, { flexDirection: "column" },
+          h(Text, { dimColor: true }, `Project: ${projectDir}`),
+          h(Text, { color: "yellow", dimColor: true }, "KC has full read/write access to this directory. We recommend backing up important files."),
+        )
+      : null,
+    h(Text, null, ""),
     h(Text, { dimColor: true }, "Product of Memium / kitchen-engineer42"),
   );
 }