joonecli 0.1.0

package/src/tools/registry.ts

@@ -0,0 +1,198 @@
+import { DynamicToolInterface } from "./index.js";
+
+/**
+ * Lazy Tool Registry
+ *
+ * Instead of loading all complex tools into the System Prompt (which burns tokens
+ * and risks cache invalidation if changed), this registry maintains "stubs" —
+ * lightweight descriptors that let the agent discover tools on demand.
+ *
+ * Tools in DeferredToolsDB are NOT sent to the LLM by default. The agent can
+ * search for them via SearchToolsTool, then activate them via ActivateToolTool.
+ */
+
+// ─── Deferred (Lazy) Tools ─────────────────────────────────────────────────────
+
+export const DeferredToolsDB: Record<string, DynamicToolInterface> = {
+  git_commit: {
+    name: "git_commit",
+    description: "Creates a new git commit with staged changes.",
+    schema: {
+      type: "object",
+      properties: { message: { type: "string" } },
+      required: ["message"],
+    },
+    execute: async (args) => ({ content: `Committed with message: ${args.message}` }),
+  },
+  git_diff: {
+    name: "git_diff",
+    description:
+      "Shows the diff of uncommitted changes or between two branches/commits.",
+    schema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Branch, commit, or file path (optional)",
+        },
+      },
+    },
+    execute: async (args) => ({ content: `Diff for: ${args.target || "working directory"}` }),
+  },
+  git_log: {
+    name: "git_log",
+    description: "Shows recent commit history with messages and hashes.",
+    schema: {
+      type: "object",
+      properties: {
+        count: {
+          type: "number",
+          description: "Number of recent commits to show (default: 10)",
+        },
+      },
+    },
+    execute: async (args) => ({ content: `Showing last ${args.count || 10} commits.` }),
+  },
+  grep_search: {
+    name: "grep_search",
+    description:
+      "Searches for a text pattern across project files using ripgrep. Returns matching lines with filenames and line numbers.",
+    schema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search pattern (regex supported)" },
+        path: { type: "string", description: "Directory or file to search in (default: .)" },
+        includes: { type: "string", description: "File glob filter (e.g., '*.ts')" },
+      },
+      required: ["query"],
+    },
+    execute: async (args) => ({ content: `Search results for '${args.query}'` }),
+  },
+  list_dir: {
+    name: "list_dir",
+    description:
+      "Lists the contents of a directory — files and subdirectories with sizes.",
+    schema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path to list" },
+      },
+      required: ["path"],
+    },
+    execute: async (args) => ({ content: `Directory listing for: ${args.path}` }),
+  },
+};
+
+// ─── Active Tool Set (starts empty, filled by ActivateToolTool) ─────────────
+
+const activatedTools: Map<string, DynamicToolInterface> = new Map();
+
+/**
+ * Returns a tool that has been dynamically activated.
+ */
+export function getActivatedTool(name: string): DynamicToolInterface | undefined {
+  return activatedTools.get(name);
+}
+
+/**
+ * Returns all currently activated tools.
+ */
+export function getActivatedTools(): DynamicToolInterface[] {
+  return Array.from(activatedTools.values());
+}
+
+/**
+ * Activates a tool from the deferred registry, making it available for execution.
+ * Returns the activated tool, or undefined if not found.
+ */
+export function activateTool(name: string): DynamicToolInterface | undefined {
+  const tool = DeferredToolsDB[name];
+  if (!tool) return undefined;
+
+  activatedTools.set(name, tool);
+  return tool;
+}
+
+/**
+ * Resets all activated tools. For testing.
+ */
+export function resetActivatedTools(): void {
+  activatedTools.clear();
+}
+
+// ─── SearchToolsTool ────────────────────────────────────────────────────────────
+
+/**
+ * Fuzzy search: matches on tool name OR any word in the description.
+ */
+function fuzzyMatch(query: string, tool: DynamicToolInterface): boolean {
+  const q = query.toLowerCase();
+  const nameMatch = tool.name.toLowerCase().includes(q);
+  const descWords = tool.description.toLowerCase();
+  const descMatch = descWords.includes(q);
+  return nameMatch || descMatch;
+}
+
+export const SearchToolsTool: DynamicToolInterface = {
+  name: "search_tools",
+  description:
+    "Search for advanced tools available in the environment. Matches by tool name or description keywords.",
+  schema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Search query" },
+    },
+    required: ["query"],
+  },
+  execute: async (args: { query: string }) => {
+    const matches = Object.values(DeferredToolsDB).filter((tool) =>
+      fuzzyMatch(args.query, tool)
+    );
+
+    if (matches.length === 0) {
+      return { content: `No tools found matching '${args.query}'. Available categories: git, file, search.` };
+    }
+
+    const descriptions = matches.map(
+      (t) => `- **${t.name}**: ${t.description}`
+    );
+
+    return {
+      content:
+        `Found ${matches.length} tool(s):\n${descriptions.join("\n")}\n\n` +
+        `To use a tool, call activate_tool with its name.`
+    };
+  },
+};
+
+// ─── ActivateToolTool ───────────────────────────────────────────────────────────
+
+export const ActivateToolTool: DynamicToolInterface = {
+  name: "activate_tool",
+  description:
+    "Activates a discovered tool for use. Call search_tools first to find available tools.",
+  schema: {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "The tool name to activate" },
+    },
+    required: ["name"],
+  },
+  execute: async (args: { name: string }) => {
+    const tool = activateTool(args.name);
+
+    if (!tool) {
+      return {
+        content: `Error: Tool '${args.name}' not found in the registry. Use search_tools to see available tools.`,
+        isError: true
+      };
+    }
+
+    return {
+      content:
+        `✓ Tool '${args.name}' activated.\n` +
+        `Schema: ${JSON.stringify(tool.schema, null, 2)}\n` +
+        `You can now call it directly.`
+    };
+  },
+};

package/src/tools/router.ts

@@ -0,0 +1,78 @@
+/**
+ * Where a tool executes — on the host machine or in the sandbox.
+ */
+export enum ToolTarget {
+  /** Run on the host (Node.js process). User sees changes in IDE. */
+  HOST = "host",
+  /** Run inside the E2B sandbox. Commands are isolated. */
+  SANDBOX = "sandbox",
+}
+
+/**
+ * Tools that execute on the host machine (no code execution risk).
+ */
+const HOST_TOOLS = new Set([
+  "write_file",
+  "read_file",
+  "search_tools",
+  "activate_tool",
+  "list_files",
+  "search_files",
+  "web_search",
+  "search_skills",
+  "load_skill",
+  "spawn_agent",
+  "check_agent",
+]);
+
+/**
+ * Tools that execute inside the sandboxed environment.
+ */
+const SANDBOX_TOOLS = new Set([
+  "bash",
+  "run_tests",
+  "install_deps",
+  "run_command",
+  "python",
+  "security_scan",
+  "dep_scan",
+  "browser",
+]);
+
+/**
+ * Routes tool calls to either the host machine or the E2B sandbox.
+ *
+ * Design principle: File I/O runs on the host so the user sees changes
+ * in their IDE in real-time. Code execution runs in the sandbox for safety.
+ *
+ * Unknown tools default to SANDBOX (safe-by-default).
+ */
+export class ToolRouter {
+  /**
+   * Determines where a tool should execute.
+   *
+   * @param toolName The name of the tool being invoked.
+   * @returns ToolTarget.HOST or ToolTarget.SANDBOX
+   */
+  getTarget(toolName: string): ToolTarget {
+    if (HOST_TOOLS.has(toolName)) {
+      return ToolTarget.HOST;
+    }
+    // Default: sandbox (safe-by-default — never execute unknown tools on host)
+    return ToolTarget.SANDBOX;
+  }
+
+  /**
+   * Returns true if the tool should run on the host.
+   */
+  isHostTool(toolName: string): boolean {
+    return this.getTarget(toolName) === ToolTarget.HOST;
+  }
+
+  /**
+   * Returns true if the tool should run in the sandbox.
+   */
+  isSandboxTool(toolName: string): boolean {
+    return this.getTarget(toolName) === ToolTarget.SANDBOX;
+  }
+}

package/src/tools/security.ts

@@ -0,0 +1,220 @@
+import { SandboxManager } from "../sandbox/manager.js";
+import { LazyInstaller } from "../sandbox/bootstrap.js";
+import { DynamicToolInterface, ToolResult } from "./index.js";
+
+// ─── Sandbox + Installer references (set at session start) ──────────────────
+
+let _sandboxManager: SandboxManager | null = null;
+let _installer: LazyInstaller | null = null;
+
+/**
+ * Binds the security tools to the sandbox and installer.
+ * Must be called at session start.
+ */
+export function bindSecuritySandbox(
+  sandbox: SandboxManager,
+  installer: LazyInstaller
+): void {
+  _sandboxManager = sandbox;
+  _installer = installer;
+}
+
+// ─── Security Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Escapes a string so it can be safely used as an argument in a Bash shell command.
+ */
+function escapeBashArg(arg: string): string {
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Validates a file path to prevent directory traversal out of the workspace.
+ */
+function isSafePath(pathStr: string): boolean {
+  if (!pathStr || pathStr.trim() === "") return false;
+  if (pathStr.includes("..") || pathStr.startsWith("/")) return false;
+  return true;
+}
+
+// ─── SecurityScanTool ───────────────────────────────────────────────────────────
+
+/**
+ * Scans code for security vulnerabilities using the Gemini CLI Security Extension.
+ *
+ * Execution flow:
+ * 1. LazyInstaller ensures Gemini CLI + security extension are in the sandbox.
+ * 2. Runs `gemini -x security:analyze` in the sandbox.
+ * 3. Returns the generated security report.
+ *
+ * If Gemini CLI installation fails, returns a descriptive fallback message
+ * suggesting manual review or alternative tools.
+ */
+export const SecurityScanTool: DynamicToolInterface = {
+  name: "security_scan",
+  description:
+    "Scans code changes for security vulnerabilities using the Gemini CLI Security Extension. " +
+    "Analyzes the current branch diff for common vulnerabilities and generates a security report.",
+  schema: {
+    type: "object",
+    properties: {
+      target: {
+        type: "string",
+        enum: ["changes", "file", "deps"],
+        description:
+          'What to scan: "changes" (branch diff), "file" (specific file), "deps" (dependencies only)',
+      },
+      path: {
+        type: "string",
+        description:
+          "File path for single-file scan (required when target is 'file')",
+      },
+    },
+    required: ["target"],
+  },
+  execute: async (args: { target: string; path?: string }): Promise<ToolResult> => {
+    if (!_sandboxManager || !_sandboxManager.isActive()) {
+      return { content: "Sandbox is not active. Cannot run security scan.", isError: true };
+    }
+    if (!_installer) {
+      return { content: "LazyInstaller not initialized. Call bindSecuritySandbox() first.", isError: true };
+    }
+
+    // Ensure Gemini CLI is available
+    const cliReady = await _installer.ensureGeminiCli(_sandboxManager);
+
+    if (!cliReady) {
+      return {
+        content: (
+          "⚠ Gemini CLI could not be installed in the sandbox.\n" +
+          "Suggestions:\n" +
+          '  - Use `dep_scan` tool for dependency vulnerability scanning (uses npm audit)\n' +
+          "  - Manually review code for OWASP Top 10 vulnerabilities\n" +
+          "  - Set sandboxTemplate to a pre-baked template with Gemini CLI installed"
+        ),
+        isError: true
+      };
+    }
+
+    // Build the command based on target
+    let command: string;
+    switch (args.target) {
+      case "changes":
+        command = "cd /workspace && gemini -x security:analyze 2>&1";
+        break;
+      case "file":
+        if (!args.path) {
+          return { content: "Error: 'path' is required when target is 'file'.", isError: true };
+        }
+        if (!isSafePath(args.path)) {
+          return { content: "Error: Invalid file path. Path must be relative and cannot contain traversal characters ('..').", isError: true };
+        }
+        command = `cd /workspace && gemini -x security:analyze --file ${escapeBashArg(args.path)} 2>&1`;
+        break;
+      case "deps":
+        command = "cd /workspace && gemini -x security:analyze --deps-only 2>&1";
+        break;
+      default:
+        return { content: `Error: Unknown target "${args.target}". Use "changes", "file", or "deps".`, isError: true };
+    }
+
+    const result = await _sandboxManager.exec(command);
+
+    if (result.exitCode !== 0) {
+      return {
+        content: `Security scan failed (exit code ${result.exitCode}):\n${result.stdout}\n${result.stderr}`,
+        metadata: { exitCode: result.exitCode },
+        isError: true
+      };
+    }
+
+    return {
+      content: result.stdout || "Security scan completed — no issues found.",
+      metadata: { exitCode: result.exitCode },
+      isError: false
+    };
+  },
+};
+
+// ─── DepScanTool ────────────────────────────────────────────────────────────────
+
+/**
+ * Scans project dependencies for known vulnerabilities.
+ *
+ * Execution flow:
+ * 1. Try OSV-Scanner (more comprehensive, covers multiple ecosystems).
+ * 2. Fall back to `npm audit --json` (always available in Node sandboxes).
+ */
+export const DepScanTool: DynamicToolInterface = {
+  name: "dep_scan",
+  description:
+    "Scans project dependencies for known vulnerabilities (CVEs). " +
+    "Uses OSV-Scanner when available, falls back to npm audit.",
+  schema: {
+    type: "object",
+    properties: {
+      format: {
+        type: "string",
+        enum: ["summary", "json"],
+        description: 'Output format: "summary" (human readable) or "json" (raw)',
+      },
+    },
+  },
+  execute: async (args?: { format?: string }): Promise<ToolResult> => {
+    if (!_sandboxManager || !_sandboxManager.isActive()) {
+      return { content: "Sandbox is not active. Cannot run dependency scan.", isError: true };
+    }
+    if (!_installer) {
+      return { content: "LazyInstaller not initialized.", isError: true };
+    }
+
+    const format = args?.format ?? "summary";
+
+    // Try OSV-Scanner first
+    const osvReady = await _installer.ensureOsvScanner(_sandboxManager);
+
+    if (osvReady) {
+      const osvCmd =
+        format === "json"
+          ? "cd /workspace && osv-scanner --json . 2>&1"
+          : "cd /workspace && osv-scanner . 2>&1";
+
+      const result = await _sandboxManager.exec(osvCmd);
+
+      if (result.exitCode === 0) {
+        return {
+          content: result.stdout || "No known vulnerabilities found in dependencies.",
+          metadata: { exitCode: result.exitCode },
+          isError: false
+        };
+      }
+
+      // Exit code 1 from OSV-Scanner means vulnerabilities found — still valid output
+      if (result.exitCode === 1 && result.stdout) {
+        return {
+          content: result.stdout,
+          metadata: { exitCode: result.exitCode },
+          isError: false
+        };
+      }
+
+      // If we reach here, OSV-Scanner failed for another reason (e.g. exit > 1)
+      console.warn(`⚠ OSV-Scanner failed (exit code ${result.exitCode}). Falling back to npm audit.\nDetails: ${result.stdout}\n${result.stderr}`);
+    }
+
+    // Fallback: npm audit
+    const auditCmd =
+      format === "json"
+        ? "cd /workspace && npm audit --json 2>&1"
+        : "cd /workspace && npm audit 2>&1";
+
+    const auditResult = await _sandboxManager.exec(auditCmd);
+
+    // npm audit returns 1 when vulnerabilities are found — that's valid output
+    return {
+      content: auditResult.stdout || "No known vulnerabilities found in dependencies.",
+      metadata: { exitCode: auditResult.exitCode },
+      isError: false
+    };
+  },
+};

package/src/tools/spawnAgent.ts

@@ -0,0 +1,158 @@
+/**
+ * Spawn Agent Tools
+ *
+ * DynamicToolInterface implementations for spawning and checking sub-agents.
+ * These tools are registered with the main agent's tool set, allowing the
+ * LLM to delegate scoped tasks to isolated sub-agents.
+ *
+ * Safety: spawn_agent and check_agent are excluded from sub-agent tool sets
+ * to enforce the depth-1 nesting limit.
+ */
+
+import { DynamicToolInterface, ToolResult } from "./index.js";
+import { SubAgentManager } from "../core/subAgent.js";
+import { SubAgentResult } from "../agents/agentSpec.js";
+import { AgentRegistry } from "../agents/agentRegistry.js";
+
+// ─── Factory ────────────────────────────────────────────────────────────────────
+
+/**
+ * Creates the spawn_agent and check_agent tools bound to a SubAgentManager.
+ * The agent registry summary is injected into the spawn_agent description
+ * so the LLM knows which agents are available.
+ */
+export function createSpawnAgentTools(
+  manager: SubAgentManager,
+  registry: AgentRegistry
+): DynamicToolInterface[] {
+  const agentNames = registry.getNames();
+  const agentList = agentNames.join(", ");
+
+  // ─── spawn_agent ───────────────────────────────────────────────────────────
+
+  const SpawnAgentTool: DynamicToolInterface = {
+    name: "spawn_agent",
+    description:
+      `Spawn an isolated sub-agent to handle a scoped task. Available agents: ${agentList}. ` +
+      `The sub-agent runs independently with its own conversation and returns a structured result. ` +
+      `Use mode "async" for non-blocking execution — you can continue working and check results later with check_agent.`,
+    schema: {
+      type: "object",
+      properties: {
+        agent: {
+          type: "string",
+          description: `The agent name from the registry. Available: ${agentList}`,
+          enum: agentNames,
+        },
+        task: {
+          type: "string",
+          description: "Detailed description of the task for the sub-agent to complete",
+        },
+        mode: {
+          type: "string",
+          enum: ["sync", "async"],
+          description: "Execution mode: 'sync' (default, blocks until done) or 'async' (non-blocking, returns taskId)",
+        },
+      },
+      required: ["agent", "task"],
+    },
+    execute: async (args: {
+      agent: string;
+      task: string;
+      mode?: "sync" | "async";
+    }): Promise<ToolResult> => {
+      const mode = args.mode ?? "sync";
+
+      if (mode === "async") {
+        try {
+          const taskId = await manager.spawnAsync(args.agent, args.task);
+          return {
+            content: `Async sub-agent "${args.agent}" started. Task ID: ${taskId}\n` +
+              `Use check_agent with this taskId to get the result when ready.`,
+            metadata: { taskId, agentName: args.agent, mode: "async" },
+          };
+        } catch (err: any) {
+          return { content: `Spawn error: ${err.message}`, isError: true };
+        }
+      }
+
+      // Sync mode (default)
+      const result = await manager.spawn(args.agent, args.task);
+      return {
+        content: formatSubAgentResult(result),
+        metadata: {
+          agentName: result.agentName,
+          outcome: result.outcome,
+          toolCalls: result.toolCallCount,
+          turnsUsed: result.turnsUsed,
+          duration: result.duration,
+        },
+        isError: result.outcome === "failure",
+      };
+    },
+  };
+
+  // ─── check_agent ───────────────────────────────────────────────────────────
+
+  const CheckAgentTool: DynamicToolInterface = {
+    name: "check_agent",
+    description:
+      "Check the status or retrieve the result of an async sub-agent task. " +
+      "If the task is still running, returns a status update. If completed, returns the result.",
+    schema: {
+      type: "object",
+      properties: {
+        taskId: {
+          type: "string",
+          description: "The task ID returned by spawn_agent in async mode",
+        },
+      },
+      required: ["taskId"],
+    },
+    execute: async (args: { taskId: string }): Promise<ToolResult> => {
+      const result = await manager.getResult(args.taskId);
+
+      if (typeof result === "string") {
+        // Still running or unknown
+        return { content: result };
+      }
+
+      // Completed — return formatted result
+      return {
+        content: formatSubAgentResult(result),
+        metadata: {
+          agentName: result.agentName,
+          outcome: result.outcome,
+          toolCalls: result.toolCallCount,
+          turnsUsed: result.turnsUsed,
+          duration: result.duration,
+        },
+        isError: result.outcome === "failure",
+      };
+    },
+  };
+
+  return [SpawnAgentTool, CheckAgentTool];
+}
+
+// ─── Formatter ──────────────────────────────────────────────────────────────────
+
+/**
+ * Formats a SubAgentResult into a readable string for the main agent.
+ */
+function formatSubAgentResult(result: SubAgentResult): string {
+  const lines = [
+    `--- Sub-Agent Result: ${result.agentName} ---`,
+    `Outcome: ${result.outcome}`,
+    `Turns: ${result.turnsUsed} | Tool Calls: ${result.toolCallCount} | Duration: ${Math.round(result.duration / 1000)}s`,
+    `Tokens: ~${result.tokenUsage.prompt} prompt + ~${result.tokenUsage.completion} completion`,
+  ];
+
+  if (result.filesModified.length > 0) {
+    lines.push(`Files Modified: ${result.filesModified.join(", ")}`);
+  }
+
+  lines.push(`\nResult:\n${result.result}`);
+
+  return lines.join("\n");
+}