joonecli 0.1.0

package/src/hitl/bridge.ts

@@ -0,0 +1,160 @@
+import { EventEmitter } from "node:events";
+
+export interface HITLQuestion {
+    /** Unique ID for this question. */
+    id: string;
+    /** The question text to display to the user. */
+    question: string;
+    /** Optional predefined answer choices. */
+    options?: string[];
+    /** Timestamp when the question was posed. */
+    createdAt: number;
+}
+
+export interface HITLPermissionRequest {
+    /** Unique ID for this request. */
+    id: string;
+    /** The tool requesting permission. */
+    toolName: string;
+    /** The arguments the tool was called with. */
+    args: Record<string, unknown>;
+    /** Timestamp when the request was created. */
+    createdAt: number;
+}
+
+/**
+ * HITLBridge — Human-in-the-Loop communication bridge.
+ *
+ * Provides a typed event-based interface between the tool execution layer
+ * and the TUI rendering layer. When a tool needs user input, it emits
+ * a question event and awaits the response. The TUI listens, renders
+ * the prompt, and resolves the answer.
+ *
+ * Singleton pattern: one bridge per session.
+ */
+export class HITLBridge extends EventEmitter {
+    private static instance: HITLBridge | null = null;
+    private pendingResolvers = new Map<string, (answer: string) => void>();
+    private timeoutMs: number;
+    private questionCounter = 0;
+
+    constructor(timeoutMs: number = 5 * 60 * 1000) {
+        super();
+        this.timeoutMs = timeoutMs;
+    }
+
+    static getInstance(timeoutMs?: number): HITLBridge {
+        if (!HITLBridge.instance) {
+            HITLBridge.instance = new HITLBridge(timeoutMs);
+        }
+        return HITLBridge.instance;
+    }
+
+    static resetInstance(): void {
+        HITLBridge.instance = null;
+    }
+
+    /**
+     * Called by a tool to ask the user a free-form question.
+     * Blocks until the user responds (or times out).
+     *
+     * @returns The user's answer as a string.
+     */
+    async askUser(question: string, options?: string[]): Promise<string> {
+        const id = `hitl-q-${++this.questionCounter}-${Date.now()}`;
+
+        const payload: HITLQuestion = {
+            id,
+            question,
+            options,
+            createdAt: Date.now(),
+        };
+
+        return new Promise<string>((resolve, reject) => {
+            this.pendingResolvers.set(id, resolve);
+
+            // Emit the question so the TUI can render it
+            this.emit("question", payload);
+
+            // Timeout: auto-reject if user doesn't respond
+            const timer = setTimeout(() => {
+                if (this.pendingResolvers.has(id)) {
+                    this.pendingResolvers.delete(id);
+                    resolve("[No response — the user did not answer within the timeout period.]");
+                }
+            }, this.timeoutMs);
+
+            // Clean up timer if resolved before timeout
+            const originalResolve = this.pendingResolvers.get(id)!;
+            this.pendingResolvers.set(id, (answer: string) => {
+                clearTimeout(timer);
+                originalResolve(answer);
+            });
+        });
+    }
+
+    /**
+     * Called by the PermissionMiddleware to request tool execution approval.
+     * Blocks until the user responds [y/n] (or times out with denial).
+     *
+     * @returns true if approved, false if denied or timed out.
+     */
+    async requestPermission(toolName: string, args: Record<string, unknown>): Promise<boolean> {
+        const id = `hitl-perm-${++this.questionCounter}-${Date.now()}`;
+
+        const payload: HITLPermissionRequest = {
+            id,
+            toolName,
+            args,
+            createdAt: Date.now(),
+        };
+
+        return new Promise<boolean>((resolve) => {
+            const wrappedResolve = (answer: string) => {
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized === "y" || normalized === "yes" || normalized === "approve");
+            };
+
+            this.pendingResolvers.set(id, wrappedResolve as any);
+
+            // Emit so the TUI can render the permission prompt
+            this.emit("permission", payload);
+
+            // Timeout: auto-deny
+            const timer = setTimeout(() => {
+                if (this.pendingResolvers.has(id)) {
+                    this.pendingResolvers.delete(id);
+                    resolve(false); // Denied by timeout
+                }
+            }, this.timeoutMs);
+
+            // Clean up timer on resolve
+            const current = this.pendingResolvers.get(id)!;
+            this.pendingResolvers.set(id, (answer: string) => {
+                clearTimeout(timer);
+                (current as any)(answer);
+            });
+        });
+    }
+
+    /**
+     * Called by the TUI when the user submits an answer.
+     *
+     * @param id - The question/permission request ID.
+     * @param answer - The user's text response.
+     */
+    resolveAnswer(id: string, answer: string): void {
+        const resolver = this.pendingResolvers.get(id);
+        if (resolver) {
+            this.pendingResolvers.delete(id);
+            resolver(answer);
+        }
+    }
+
+    /**
+     * Returns true if there is an outstanding question awaiting an answer.
+     */
+    hasPendingQuestion(): boolean {
+        return this.pendingResolvers.size > 0;
+    }
+}

package/src/middleware/commandSanitizer.ts

@@ -0,0 +1,60 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+
+/**
+ * Intercepts bash tool calls to block dangerous or interactive commands.
+ *
+ * Categories of blocked commands:
+ * 1. Destructive: `rm -rf /`, `mkfs`, `dd if=`, fork bombs
+ * 2. Interactive/hanging: `vim`, `nano`, `less`, `top`, `htop`, `man`
+ * 3. Network abuse: `curl | sh`, `wget | bash`
+ */
+export class CommandSanitizerMiddleware implements ToolMiddleware {
+  readonly name = "CommandSanitizer";
+
+  /**
+   * Patterns that will cause a command to be blocked.
+   * Each entry is [regex, human-readable reason].
+   */
+  private readonly blockedPatterns: [RegExp, string][] = [
+    // Destructive
+    [/rm\s+(-\w*r\w*f\w*|-\w*f\w*r\w*)\s+\/(\*)?(?:\s|$)/, "destructive: rm -rf /"],
+    [/mkfs\b/, "destructive: filesystem format"],
+    [/\bdd\s+.*of=\/dev\//, "destructive: raw disk write"],
+    [/chmod\s+(-\w+\s+)*777\s+\//, "dangerous: chmod 777 on root"],
+
+    // Interactive / hanging
+    [/\b(vim|vi|nano|emacs|pico)\b/, "interactive: text editor (hangs the sandbox)"],
+    [/\b(less|more)\b/, "interactive: pager (hangs the sandbox)"],
+    [/\b(top|htop|glances)\b/, "interactive: process monitor (hangs the sandbox)"],
+    [/\bman\s+\w+/, "interactive: man page (hangs the sandbox)"],
+
+    // Network abuse: pipe-to-shell
+    [/curl\s+.*\|\s*(sh|bash|zsh)/, "unsafe: pipe remote script to shell"],
+    [/wget\s+.*\|\s*(sh|bash|zsh)/, "unsafe: pipe remote script to shell"],
+  ];
+
+  before(ctx: ToolCallContext): ToolCallContext | string {
+    // Only applies to bash/shell tool calls
+    if (ctx.toolName !== "bash") {
+      return ctx;
+    }
+
+    const command = ctx.args.command;
+    if (typeof command !== "string") {
+      return ctx;
+    }
+
+    for (const [pattern, reason] of this.blockedPatterns) {
+      if (pattern.test(command)) {
+        return (
+          `⚠ Blocked: Command rejected by sanitizer.\n` +
+          `Reason: ${reason}\n` +
+          `Command: ${command}\n` +
+          `Use a safer alternative or refine your approach.`
+        );
+      }
+    }
+
+    return ctx;
+  }
+}

package/src/middleware/loopDetection.ts

@@ -0,0 +1,63 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+
+/**
+ * Prevents the "Blind Retry" doom loop.
+ *
+ * Tracks a rolling window of recent tool call signatures. If the same
+ * tool + args combination appears N times consecutively, the call is
+ * rejected with an instruction to try a different approach.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Blind Retry Doom Loop"
+ */
+export class LoopDetectionMiddleware implements ToolMiddleware {
+  readonly name = "LoopDetection";
+
+  private history: string[] = [];
+  private readonly threshold: number;
+
+  /**
+   * @param threshold - Number of identical consecutive calls before blocking (default: 3).
+   */
+  constructor(threshold = 3) {
+    this.threshold = threshold;
+  }
+
+  /**
+   * Creates a signature string for a tool call (name + sorted args JSON).
+   */
+  private signature(ctx: ToolCallContext): string {
+    return `${ctx.toolName}:${JSON.stringify(ctx.args, Object.keys(ctx.args).sort())}`;
+  }
+
+  before(ctx: ToolCallContext): ToolCallContext | string {
+    const sig = this.signature(ctx);
+
+    this.history.push(sig);
+
+    // Keep only the last N entries to avoid unbounded growth
+    if (this.history.length > this.threshold * 2) {
+      this.history = this.history.slice(-this.threshold * 2);
+    }
+
+    // Check if the last `threshold` entries are all identical
+    const tail = this.history.slice(-this.threshold);
+    if (
+      tail.length >= this.threshold &&
+      tail.every((s) => s === sig)
+    ) {
+      return (
+        `⚠ Loop detected: You have called "${ctx.toolName}" with identical arguments ` +
+        `${this.threshold} times consecutively. Stop this approach and try a different strategy.`
+      );
+    }
+
+    return ctx;
+  }
+
+  /**
+   * Resets the history. Useful for testing or session boundaries.
+   */
+  reset(): void {
+    this.history = [];
+  }
+}

package/src/middleware/permission.ts

@@ -0,0 +1,72 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+import { HITLBridge } from "../hitl/bridge.js";
+import { ToolResult } from "../tools/index.js";
+
+export type PermissionMode = "auto" | "ask_dangerous" | "ask_all";
+
+/** Tools that are always safe and never need user approval. */
+const SAFE_TOOLS = new Set([
+    "read_file",
+    "view_file_outline",
+    "search_skills",
+    "load_skill",
+    "search_tools",
+    "ask_user_question", // Meta: the ask tool itself is always safe
+]);
+
+/** Tools that perform destructive or side-effect-heavy operations. */
+const DANGEROUS_TOOLS = new Set([
+    "bash",
+    "write_file",
+    "replace_file_content",
+    "multi_replace_file_content",
+    "install_deps",
+]);
+
+/**
+ * PermissionMiddleware — gates dangerous tool calls behind user approval.
+ *
+ * Behavior per mode:
+ * - `auto`: All tools execute without asking. (Default for power users.)
+ * - `ask_dangerous`: Only tools in DANGEROUS_TOOLS require approval.
+ * - `ask_all`: Every tool except SAFE_TOOLS requires approval.
+ */
+export class PermissionMiddleware implements ToolMiddleware {
+    name = "PermissionMiddleware";
+    private mode: PermissionMode;
+
+    constructor(mode: PermissionMode = "auto") {
+        this.mode = mode;
+    }
+
+    async before(ctx: ToolCallContext): Promise<ToolCallContext | string | void> {
+        if (this.mode === "auto") return ctx;
+
+        const toolName = ctx.toolName;
+        const needsApproval = this.requiresApproval(toolName);
+
+        if (!needsApproval) return ctx;
+
+        const bridge = HITLBridge.getInstance();
+        const approved = await bridge.requestPermission(toolName, ctx.args);
+
+        if (!approved) {
+            // Short-circuit: return a string to deny the tool call
+            return (
+                `Permission denied: The user declined to approve the execution of "${toolName}". ` +
+                `Try an alternative approach or ask the user for guidance using the ask_user_question tool.`
+            );
+        }
+
+        return ctx;
+    }
+
+    private requiresApproval(toolName: string): boolean {
+        if (SAFE_TOOLS.has(toolName)) return false;
+
+        if (this.mode === "ask_all") return true;
+        if (this.mode === "ask_dangerous") return DANGEROUS_TOOLS.has(toolName);
+
+        return false;
+    }
+}

package/src/middleware/pipeline.ts

@@ -0,0 +1,75 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+import { ToolResult } from "../tools/index.js";
+
+/**
+ * Executes tool calls through a chain of middleware hooks.
+ *
+ * Execution flow:
+ * 1. Run all `before()` hooks in registration order.
+ *    - If any returns a string → short-circuit (tool is NOT executed).
+ * 2. Execute the actual tool function.
+ * 3. Run all `after()` hooks in reverse registration order.
+ *    - Each can transform the result before it enters conversation history.
+ */
+export class MiddlewarePipeline {
+  private middlewares: ToolMiddleware[] = [];
+
+  /**
+   * Register a middleware. Middlewares run in the order they are added.
+   */
+  use(middleware: ToolMiddleware): void {
+    this.middlewares.push(middleware);
+  }
+
+  /**
+   * Returns the number of registered middlewares.
+   */
+  get length(): number {
+    return this.middlewares.length;
+  }
+
+  /**
+   * Execute a tool call through the middleware pipeline.
+   *
+   * @param ctx - The tool call context (name, args, callId).
+   * @param executeFn - The actual tool execution function.
+   * @returns The final result string (possibly transformed by after-hooks).
+   */
+  async run(
+    ctx: ToolCallContext,
+    executeFn: (ctx: ToolCallContext) => Promise<ToolResult> | ToolResult
+  ): Promise<string> {
+    // ── Before phase: run hooks in order ──
+    let currentCtx = ctx;
+
+    for (const mw of this.middlewares) {
+      if (mw.before) {
+        const result = await mw.before(currentCtx);
+
+        if (typeof result === "string") {
+          // Short-circuit: middleware rejected the call
+          return result;
+        }
+
+        if (result !== undefined) {
+          currentCtx = result;
+        }
+      }
+    }
+
+    // ── Execute the tool ──
+    let output: ToolResult = await executeFn(currentCtx);
+
+    // ── After phase: run hooks in reverse order ──
+    for (let i = this.middlewares.length - 1; i >= 0; i--) {
+      const mw = this.middlewares[i];
+      if (mw.after) {
+        const transformed = await mw.after(currentCtx, output);
+        if (transformed !== undefined) {
+          output = transformed;
+        }
+      }    }
+
+    return output.content;
+  }
+}

package/src/middleware/preCompletion.ts

@@ -0,0 +1,94 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+import { ToolResult } from "../tools/index.js";
+
+/**
+ * Prevents the agent from marking a task as "done" without running tests.
+ *
+ * Tracks whether any test command has been executed during the session.
+ * If the agent attempts to signal completion without running tests first,
+ * the middleware intercepts and forces verification.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Fake Success Verification"
+ */
+export class PreCompletionMiddleware implements ToolMiddleware {
+  readonly name = "PreCompletion";
+
+  private testsPassed = false;
+
+  /** Patterns in bash commands that count as "running tests". */
+  private readonly testPatterns = [
+    /\bvitest\b/,
+    /\bjest\b/,
+    /\bpytest\b/,
+    /\bmocha\b/,
+    /\bnpm\s+test\b/,
+    /\bnpm\s+run\s+test\b/,
+    /\byarn\s+test\b/,
+    /\bpnpm\s+test\b/,
+    /\bgo\s+test\b/,
+    /\bcargo\s+test\b/,
+  ];
+
+  /** Tool names that signal the agent is trying to complete the task. */
+  private readonly completionSignals = new Set([
+    "task_complete",
+    "attempt_completion",
+    "finish_task",
+    "submit_result",
+  ]);
+
+  before(ctx: ToolCallContext): ToolCallContext | string {
+    // When a test command is initiated, assume it hasn't passed yet
+    if (ctx.toolName === "bash" && typeof ctx.args.command === "string") {
+      for (const pattern of this.testPatterns) {
+        if (pattern.test(ctx.args.command)) {
+          this.testsPassed = false;
+          break;
+        }
+      }
+    }
+
+    // Intercept completion attempts
+    if (this.completionSignals.has(ctx.toolName)) {
+      if (!this.testsPassed) {
+        return (
+          "⚠ You must run tests before completing the task, AND they must pass.\n" +
+          "Use the bash tool to execute your test suite (e.g., `npm test`, `vitest`, `pytest`).\n" +
+          "If tests fail, fix the issues. Once tests pass cleanly, you may attempt completion again."
+        );
+      }
+    }
+
+    return ctx;
+  }
+
+  after(ctx: ToolCallContext, result: ToolResult): void {
+    if (ctx.toolName === "bash" && typeof ctx.args.command === "string") {
+      for (const pattern of this.testPatterns) {
+        if (pattern.test(ctx.args.command)) {
+          // Robustly check the exact exit code from the tool metadata
+          if (result.metadata?.exitCode === 0) {
+            this.testsPassed = true;
+          } else {
+            this.testsPassed = false;
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns whether tests have been run and passed in this session.
+   */
+  hasPassedTests(): boolean {
+    return this.testsPassed;
+  }
+
+  /**
+   * Resets state. Useful for testing or session boundaries.
+   */
+  reset(): void {
+    this.testsPassed = false;
+  }
+}

package/src/middleware/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Middleware types for the tool execution pipeline.
+ *
+ * Each middleware can hook into both the "before" and "after" phases
+ * of a tool call. The pipeline chains them in order.
+ */
+
+import { ToolResult } from "../tools/index.js";
+
+/**
+ * Context object passed through the middleware chain for each tool call.
+ */
+export interface ToolCallContext {
+  /** Name of the tool being called (e.g., "bash", "read_file"). */
+  toolName: string;
+  /** Arguments passed to the tool. */
+  args: Record<string, any>;
+  /** Unique ID of this tool call (from the LLM response). */
+  callId: string;
+}
+
+/**
+ * A middleware that can intercept tool calls before and after execution.
+ *
+ * - `before()`: Runs before the tool executes. Return the (possibly modified)
+ *   context to continue, or a `string` to short-circuit with an error/warning.
+ * - `after()`: Runs after the tool executes. Can transform the result before
+ *   it enters the conversation history.
+ */
+export interface ToolMiddleware {
+  /** Human-readable name for logging and debugging. */
+  name: string;
+
+  /**
+   * Pre-execution hook.
+   * @returns ToolCallContext to mutate, a string to short-circuit, or void to pass through unmodified.
+   */
+  before?(ctx: ToolCallContext): Promise<ToolCallContext | string | void> | ToolCallContext | string | void;
+
+  /**
+   * Post-execution hook.
+   * @returns The transformed tool result object, or void to pass through unmodified.
+   */
+  after?(ctx: ToolCallContext, result: ToolResult): Promise<ToolResult | void> | ToolResult | void;
+}

package/src/sandbox/bootstrap.ts

@@ -0,0 +1,121 @@
+import { SandboxManager } from "./manager.js";
+
+/**
+ * LazyInstaller handles on-demand tool installation inside the sandbox.
+ *
+ * - In DEV mode (no custom template), tools are installed lazily on first use.
+ * - In PROD mode (custom template like "joone-base"), tools are pre-baked —
+ *   the installer detects this and skips installation.
+ *
+ * Install state is cached per session so each tool is installed at most once.
+ */
+export class LazyInstaller {
+  private geminiCliInstalled = false;
+  private osvScannerInstalled = false;
+  private readonly usingCustomTemplate: boolean;
+
+  constructor(usingCustomTemplate: boolean) {
+    this.usingCustomTemplate = usingCustomTemplate;
+
+    // If using a custom template, assume all tools are pre-installed
+    if (usingCustomTemplate) {
+      this.geminiCliInstalled = true;
+      this.osvScannerInstalled = true;
+    }
+  }
+
+  /**
+   * Ensures Gemini CLI + security extension are available in the sandbox.
+   * Installs them if needed (dev mode). No-op if using a custom template.
+   *
+   * @returns true if Gemini CLI is now available.
+   */
+  async ensureGeminiCli(sandbox: SandboxManager): Promise<boolean> {
+    if (this.geminiCliInstalled) return true;
+
+    try {
+      // Check if already installed
+      const check = await sandbox.exec("gemini --version");
+      if (check.exitCode === 0) {
+        this.geminiCliInstalled = true;
+        return true;
+      }
+    } catch {
+      // Not installed — proceed to install
+    }
+
+    try {
+      // Install Gemini CLI globally
+      const install = await sandbox.exec(
+        "npm install -g @google/gemini-cli 2>&1"
+      );
+      if (install.exitCode !== 0) {
+        return false;
+      }
+
+      // Install security extension
+      const ext = await sandbox.exec(
+        "gemini extensions install https://github.com/gemini-cli-extensions/security 2>&1"
+      );
+      if (ext.exitCode !== 0) {
+        // CLI installed but extension failed — still partially useful
+        this.geminiCliInstalled = true;
+        return true;
+      }
+
+      this.geminiCliInstalled = true;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Ensures OSV-Scanner is available in the sandbox.
+   * Falls back gracefully — callers should use npm audit if this returns false.
+   *
+   * @returns true if osv-scanner is now available.
+   */
+  async ensureOsvScanner(sandbox: SandboxManager): Promise<boolean> {
+    if (this.osvScannerInstalled) return true;
+
+    try {
+      const check = await sandbox.exec("osv-scanner --version");
+      if (check.exitCode === 0) {
+        this.osvScannerInstalled = true;
+        return true;
+      }
+    } catch {
+      // Not installed
+    }
+
+    try {
+      // Try to install via go or download binary
+      const install = await sandbox.exec(
+        "curl -sSfL https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64 -o /usr/local/bin/osv-scanner && chmod +x /usr/local/bin/osv-scanner 2>&1"
+      );
+      if (install.exitCode === 0) {
+        this.osvScannerInstalled = true;
+        return true;
+      }
+    } catch {
+      // Install failed
+    }
+
+    return false;
+  }
+
+  /**
+   * Returns whether Gemini CLI is installed (cached state).
+   */
+  isGeminiCliReady(): boolean {
+    return this.geminiCliInstalled;
+  }
+
+  /**
+   * Returns whether OSV-Scanner is installed (cached state).
+   */
+  isOsvScannerReady(): boolean {
+    return this.osvScannerInstalled;
+  }
+}