joonecli 0.1.0

package/docs/06_user_stories.md

@@ -0,0 +1,72 @@
+# User Stories
+
+This document contains the foundational user stories for the Joone agent, organized by Epic. It does not include exhaustive acceptance criteria, but rather serves as a high-level requirements tracker for the core features.
+
+## Epic 1: CLI & Configuration
+
+- **US 1.1**: As a user, I want to install joone globally via `npm i -g joone` and run it with `joone` in any project directory.
+- **US 1.2**: As a user, I want to select my preferred LLM provider and model on first run or via `joone config`, choosing from at least 9 providers (Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, Fireworks, Together AI, Ollama).
+- **US 1.3**: As a user, I want my API key collected via masked interactive input during `joone config`, so I never have to manually create `.env` files.
+- **US 1.4**: As a user, I want my preferences stored at `~/.joone/config.json` with restrictive file permissions, so I don't re-enter them every session.
+- **US 1.5**: As a user, I want the CLI to tell me which provider package to install if it's missing (e.g., `Run: npm install @langchain/groq`).
+- **US 1.6** _(Planned)_: As a security-conscious user, I want to choose during onboarding whether to store my API key in a plain config file, OS Keychain, or encrypted config.
+
+## Epic 2: Streaming & Output
+
+- **US 2.1**: As a user, I want to see the agent's response stream token-by-token in my terminal, not wait for the entire response to finish.
+- **US 2.2**: As the system, I want to buffer tool call JSON during streaming until the full call is received, then execute it.
+- **US 2.3**: As a user, I want the option to disable streaming via `joone config` or a CLI flag (`--no-stream`).
+
+## Epic 3: The Context & Prompt Layer
+
+- **US 3.1**: As a developer, I want the system prompt to be strictly divided into static and dynamic sections, so that I maximize prompt caching and reduce costs.
+- **US 3.2**: As the system, I need to inject state updates (like time or file changes) into the conversation history as simulated messages (`<system-reminder>`), so I avoid invalidating the static prefix cache.
+- **US 3.3**: As the system, when the context window reaches 90% capacity, I want to execute a cache-safe compaction that summarizes early history while keeping the system prompt matching the parent thread.
+
+## Epic 4: Hybrid Sandbox Execution
+
+- **US 4.1**: As a user, I want `write_file` and `read_file` to operate on my host filesystem, so I can see the agent's code changes in my IDE in real-time.
+- **US 4.4**: As the system, I want to create a new E2B sandbox at the start of each agent session and destroy it when the session ends or times out, so that each session has a clean isolated environment and resources are properly released.
+- **US 4.5**: As a developer, I want the tool router to automatically determine whether a tool runs on the host or in the sandbox based on tool type.
+
+## Epic 5: Tooling & Lazy Loading
+
+- **US 5.1**: As an agent, I want access to core tools (`read_file`, `write_file`, `run_bash_command`) defined statically at the beginning of the session.
+- **US 5.2**: As an agent, I want to use a "Search Tools" endpoint to learn about complex or specific tools, rather than having all 50+ tool schemas loaded simultaneously into my context window.
+- **US 5.3**: As a developer, I want guardrails on `read_file` so the agent cannot accidentally load a 10MB file into the context window and blind itself.
+
+## Epic 6: Middleware Guards & Execution Loops
+
+- **US 6.1**: As a developer, I want a `LoopDetectionMiddleware` that counts how many consecutive times an agent has failed a specific action.
+- **US 6.2**: As an agent stuck in a loop, I want the system to interrupt me and tell me to reconsider my approach, so I don't waste tokens repeating a failure.
+- **US 6.3**: As an agent trying to finish a task, I want a `PreCompletionMiddleware` to ask me if I have run tests. If I haven't, it should block completion and ask me to run verifications.
+- **US 6.4**: As the system, I want to parse test exit codes; if a test fails (`exit 1`), I want to block the agent from declaring the task "Done" unless a max retry limit is reached.
+
+- **US 7.1**: As an operator, I want every agent decision, tool call, and token metric logged to a standard trace format so I can monitor cache hit rates.
+- **US 7.2**: As an operator, I want a script that can read failed traces and use an LLM to automatically summarize _why_ the agent failed tasks, allowing me to refine the harness.
+
+## Epic 8: TUI Slash Commands (M11)
+
+- **US 8.1**: As a user, I want to type `/help` or `/?` to see a list of all available commands without making an LLM call.
+- **US 8.2**: As a user, I want to switch models mid-session securely by typing `/model <name>`.
+- **US 8.3**: As a user with a bloated history context, I want to type `/compact` to manually force a context summarization.
+- **US 8.4**: As an error-prone user, if I type `/cls` instead of `/clear`, I want the UI to suggest `/clear` via Levenshtein distance grouping instead of sending garbage tokens to the API.
+
+## Epic 9: LLM-Powered Compaction (M12)
+
+- **US 9.1**: As an agent managing a huge conversation history, I want to delegate summarization of my older messages to an LLM, so the resulting summary is precise, preserving file paths and tool outcomes perfectly.
+- **US 9.2**: As the system, I want to automatically select a cheaper, faster LLM model (like `gpt-4o-mini` instead of `gpt-4o`) to perform the background compaction, saving the user money.
+- **US 9.3**: As a resumed agent, I want a seamless Handoff Prompt injected directly beneath the compaction summary, so I instantly understand my persona and context haven't broken.
+
+## Epic 10: Sub-Agent Orchestration (M13)
+
+- **US 10.1**: As the main reasoning agent, I want the ability to spawn named "sub-agents" to handle specialized tasks (e.g., executing scripts, analyzing directories) so I don't clutter my own context overhead.
+- **US 10.2**: As the main agent, I want to spawn certain sub-agents asynchronously, allowing me to continue reasoning or writing files while the sub-agent scans tests in the background.
+- **US 10.3**: As an orchestrator, I want hard limitations (a Depth-1 limit) that strictly prevent a sub-agent from accidentally spawning another sub-agent ad infinitum.
+
+## Epic 11: Stability & Reliability (M14)
+
+- **US 11.1**: As the core engine, I want a proactive `ContextGuard` that estimates API token payloads before sending the request to the provider, automatically triggering compaction at 80% usage.
+- **US 11.2**: As the core engine, I want an absolute Emergency Truncation trap door at 95% capacity to prevent immediate process death when compaction isn't fast enough.
+- **US 11.3**: As a user working on a long-running complex task, I want the `AutoSave` feature to quietly save my `.jsonl` session file atomically in the background every few turns.
+- **US 11.4**: As a user, when I hit `Ctrl+C` in my terminal, I want the CLI to intercept the shutdown signal, force a final instantaneous save, and clean up the sandbox before exiting.

package/docs/07_system_architecture.md

@@ -0,0 +1,138 @@
+# System Architecture
+
+## High-Level Architecture Overview
+
+The system operates as a CLI-based REPL (Read-Eval-Print Loop) Agent Wrapper. The user runs `joone` in their project directory. The LLM is nested within an "Execution Harness" that mediates all inputs, actions, and memory. Responses are **streamed** token-by-token.
+
+### Hybrid Sandbox Model
+
+Joone uses a **Hybrid** architecture for safety and developer experience:
+
+- **File operations** (`write_file`, `read_file`) run on the **host machine**, so the user sees changes in real-time in their IDE.
+- **Code execution** (`bash`, `npm test`, scripts) runs inside an **E2B sandboxed microVM**, protecting the host from destructive commands.
+- A **File Sync** layer mirrors changed files from host → sandbox before each execution.
+
+```
+┌─────────────────────────┐          ┌──────────────────────────┐
+│     HOST MACHINE        │   sync   │      E2B SANDBOX         │
+│                         │ ───────► │                          │
+│  write_file ──► disk    │          │  /workspace/ (mirror)    │
+│  read_file  ◄── disk    │          │                          │
+│                         │          │  bash, npm test, scripts │
+│  User sees changes      │          │  run here (isolated)     │
+│  live in their IDE      │          │                          │
+└─────────────────────────┘          └──────────────────────────┘
+```
+
+## System Diagram
+
+```mermaid
+graph TD
+    Client["User CLI (joone)"] -->|Task Input| Config
+    Config["Config Manager (~/.joone/config.json)"] -->|Provider + Key| Factory
+    Factory[Model Factory] -->|BaseChatModel| MainLoop
+
+    subgraph Agent Execution Harness
+        MainLoop[Execution Engine]
+        State[Conversation State Manager]
+        PromptBuilder[Cache-Oriented Prompt Builder]
+        StreamHandler[Stream Handler]
+
+        State --> PromptBuilder
+        MainLoop --> PromptBuilder
+        PromptBuilder --> LLM((LLM API))
+        LLM -->|Streamed Chunks| StreamHandler
+        StreamHandler -->|Complete Tool Call| Middlewares
+        StreamHandler -->|Text Tokens| Terminal[Terminal Output]
+    end
+
+    subgraph Middleware Pipeline
+        Middlewares{Middleware Orchestrator}
+        LoopDet[Loop Detection]
+        PreComp[Pre-Completion Check]
+        Guard[File Size Guardrails]
+
+        Middlewares --> LoopDet
+        Middlewares --> PreComp
+        Middlewares --> Guard
+    end
+
+    subgraph "Tool Routing (Hybrid)"
+        Middlewares -->|Approved Tool Call| Router{Tool Router}
+        Router -->|"write_file, read_file"| HostFS["Host Filesystem (Node.js fs)"]
+        Router -->|"bash, test, install"| Sync[File Sync Layer]
+        Sync -->|Upload changed files| Sandbox["E2B MicroVM (Ubuntu)"]
+        Sandbox -->|stdout/stderr| MainLoop
+        HostFS -->|File content| MainLoop
+    end
+```
+
+## Component Breakdown
+
+1. **CLI & Config Layer** (`src/cli/`):
+   - `index.ts`: Parses user commands (`joone`, `joone config`) via Commander.js.
+   - `config.ts`: Reads/writes `~/.joone/config.json`. Stores provider, model, API key (plain text + `chmod 600`), streaming preference, and temperature.
+   - `modelFactory.ts`: Factory that dynamically imports the correct LangChain provider package and returns a `BaseChatModel`. Supports 9+ providers.
+
+2. **State Manager & Prompt Builder** (`src/core/promptBuilder.ts`):
+   - Maintains the "Prefix Match". Compiles the static system prompt, appends project variables once, and exclusively appends subsequent messages.
+
+3. **Execution Engine** (`src/core/agentLoop.ts`):
+   - Polls the LLM via `.stream()` (default) or `.invoke()`.
+   - The **Stream Handler** prints text tokens to stdout in real-time and buffers tool call JSON chunks until complete.
+   - Routes completed tool calls to the Middleware pipeline.
+
+4. **Middleware Orchestrator** (`src/middleware/`):
+   - Implements the Observer pattern over the `on_tool_call` and `on_submit` events.
+   - Operates on a structured `ToolResult` interface (`{ content, metadata, isError }`) to robustly pass execution metadata (like process exit codes) through the pipeline without brittle string parsing.
+   - Can _intercept_ or _modify_ a tool request before it hits the tools.
+   - Can _inject_ `<system-reminder>` messages back to the Execution Engine.
+
+5. **Tool Router & Hybrid Execution**:
+   - **Host tools** (`write_file`, `read_file`): Execute directly on the host via Node.js `fs`. Changes appear instantly in the user's IDE.
+   - **Sandbox tools** (`bash`, `run_tests`, `install_deps`): Route through the File Sync layer → E2B sandbox.
+   - The split is determined by tool type, not configuration.
+
+6. **File Sync Layer** (`src/sandbox/sync.ts`):
+   - Tracks which files have changed on the host since the last sandbox sync.
+   - Before each sandbox execution, uploads only the changed files to the sandbox's `/workspace/` directory.
+   - Strategies: **upload-on-execute** (default) or **watch & mirror** (future).
+
+7. **E2B Sandbox** (`src/sandbox/`):
+   - Each agent session initializes an E2B cloud sandbox via the `e2b` TypeScript SDK.
+   - All bash commands and code execution run via `sandbox.commands.run()`.
+   - The sandbox is destroyed on session end or timeout.
+   - The host machine is **never** exposed to agent-executed commands.
+
+## Tool Routing Table
+
+| Tool                   | Runs On     | Why                                       |
+| ---------------------- | ----------- | ----------------------------------------- |
+| `write_file`           | **Host**    | User sees changes in IDE instantly        |
+| `read_file`            | **Host**    | Reads the real project files              |
+| `run_bash_command`     | **Sandbox** | Protects host from destructive commands   |
+| `run_tests`            | **Sandbox** | Tests may have side-effects               |
+| `install_dependencies` | **Sandbox** | npm install can execute arbitrary scripts |
+| `search_tools`         | **Host**    | Registry lookup, no execution             |
+
+## Supported LLM Providers
+
+| Provider       | Package                   | Dynamic Import             |
+| -------------- | ------------------------- | -------------------------- |
+| Anthropic      | `@langchain/anthropic`    | `ChatAnthropic`            |
+| OpenAI         | `@langchain/openai`       | `ChatOpenAI`               |
+| Google         | `@langchain/google-genai` | `ChatGoogleGenerativeAI`   |
+| Mistral        | `@langchain/mistralai`    | `ChatMistralAI`            |
+| Groq           | `@langchain/groq`         | `ChatGroq`                 |
+| DeepSeek       | OpenAI-compatible         | `ChatOpenAI` with base URL |
+| Fireworks      | `@langchain/community`    | `ChatFireworks`            |
+| Together AI    | `@langchain/community`    | `ChatTogetherAI`           |
+| Ollama (Local) | `@langchain/ollama`       | `ChatOllama`               |
+
+## Security Roadmap
+
+| Tier | Method                     | Status               |
+| ---- | -------------------------- | -------------------- |
+| 1    | Plain config + `chmod 600` | **Active (Default)** |
+| 2    | OS Keychain (`keytar`)     | Planned              |
+| 3    | AES-256 encrypted config   | Planned              |

package/docs/08_roadmap.md

@@ -0,0 +1,200 @@
+# Implementation Roadmap
+
+We will tackle this project moving from the foundation outward.
+
+## Milestone 1: The Foundation (Core Execution & Caching) ✅
+
+**Goal:** Build a basic agent that successfully executes simple loops while maintaining a 100% cache prefix validity across turns.
+
+1. ~~**Setup Project**: Initialize the repository based on the chosen Tech Stack.~~
+2. ~~**The Prompt Builder Engine**: Build the class responsible for layering static instruction strings, tools, and message arrays cleanly.~~
+3. **Core Tooling**: Implement `bash_executor` and `file_reader` / `file_writer`.
+4. **Basic Event Loop**: Implement a while loop that queries the LLM and runs the exact tool.
+
+## Milestone 2: CLI Packaging & Provider Selection
+
+**Goal:** Package joone as an installable CLI tool with dynamic LLM provider configuration, streaming output, and secure API key management.
+
+### 2a. Config Manager (`src/cli/config.ts`)
+
+1. **`JooneConfig` interface**: Define shape: `provider`, `model`, `apiKey`, `maxTokens`, `temperature`, `streaming`.
+2. **`loadConfig()`**: Reads `~/.joone/config.json`. Returns sensible defaults if file doesn't exist.
+3. **`saveConfig(config)`**: Writes JSON to `~/.joone/config.json`. Sets file permissions to `600` (owner-only).
+4. **Env var fallback**: If `apiKey` is missing from config, check `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.
+
+### 2b. Model Factory (`src/cli/modelFactory.ts`)
+
+1. **`createModel(config)`**: Factory function that switches on `config.provider`.
+2. **Dynamic imports**: Uses `await import("@langchain/anthropic")` etc. to avoid bundling all providers.
+3. **Missing package detection**: If the import fails, print `"Provider X requires @langchain/X. Run: npm install @langchain/X"`.
+4. **API key validation**: Throws a descriptive error if the API key is missing for the selected provider.
+5. **Supported providers** (9+): Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, Fireworks, Together AI, Ollama.
+
+### 2c. CLI Entry Point (`src/cli/index.ts`)
+
+1. **Commander.js** for command parsing.
+2. **`joone` (default command)**: Loads config → creates model → starts execution harness REPL.
+3. **`joone config`**: Interactive prompts (via `@inquirer/prompts`) for provider, model, API key (masked), streaming toggle.
+4. **`package.json` `"bin"` field**: Maps `joone` → `./dist/cli/index.js`.
+
+### 2d. Streaming Support
+
+1. **`ExecutionHarness.streamStep()`**: New method using `this.llm.stream(messages)`.
+2. **Text chunks**: Printed to `process.stdout` in real-time.
+3. **Tool call chunks**: Buffered until the full tool call JSON is received, then executed via the middleware pipeline.
+4. **Config flag**: `streaming: true` (default). Disable via `joone config` or `--no-stream` flag.
+
+### 2e. Security Tiers (Phased)
+
+1. **Tier 1 (Now)**: Plain `config.json` + `chmod 600` + masked input.
+2. **Tier 2 (Planned)**: OS Keychain via `keytar` — user selects during onboarding.
+3. **Tier 3 (Planned)**: AES-256 encrypted config with machine-derived key — user selects during onboarding.
+
+### TDD Test Plan (Vertical Slices)
+
+| #   | RED Test                                                                   | GREEN Implementation                 |
+| --- | -------------------------------------------------------------------------- | ------------------------------------ |
+| 1   | `loadConfig` returns defaults when no file exists                          | `loadConfig()` with default fallback |
+| 2   | `saveConfig` writes JSON and `loadConfig` reads it back                    | `saveConfig()` implementation        |
+| 3   | `loadConfig` falls back to env var if `apiKey` is missing                  | Env var fallback logic               |
+| 4   | `createModel` returns `ChatAnthropic` when provider is `"anthropic"`       | Factory Anthropic branch             |
+| 5   | `createModel` returns `ChatOpenAI` when provider is `"openai"`             | Factory OpenAI branch                |
+| 6   | `createModel` throws descriptive error if API key missing                  | Key validation                       |
+| 7   | `createModel` throws with install instructions if provider package missing | Dynamic import error handling        |
+| 8   | `streamStep` emits text chunks to provided callback                        | Stream handler implementation        |
+| 9   | `streamStep` buffers tool call JSON and returns complete `AIMessage`       | Tool call buffering                  |
+
+---
+
+## Milestone 3: Hybrid Sandbox Integration
+
+**Goal:** Route all agent code execution through isolated E2B cloud microVMs while keeping file I/O on the host for real-time IDE visibility.
+
+### 3a. E2B Sandbox Lifecycle (`src/sandbox/manager.ts`)
+
+1. **Install E2B SDK**: Add `e2b` to dependencies.
+2. **`SandboxManager`**: Class that creates/destroys an E2B sandbox per session.
+3. **Timeout & Cleanup**: Auto-destroy sandbox after configurable idle timeout.
+
+### 3b. File Sync Layer (`src/sandbox/sync.ts`)
+
+1. **Change Tracker**: Track which host files have been modified since last sync using file mtimes or a dirty set.
+2. **`syncToSandbox()`**: Upload only changed files to `/workspace/` in the sandbox before each execution.
+3. **Initial Sync**: On session start, upload the full project directory.
+
+### 3c. Tool Router (`src/tools/router.ts`)
+
+1. **Host tools**: `write_file`, `read_file` → execute via Node.js `fs` on the host.
+2. **Sandbox tools**: `bash`, `run_tests`, `install_deps` → sync files, then execute via `sandbox.commands.run()`.
+3. **Automatic routing**: Tool router determines target based on tool type.
+
+### 3d. Rewire Existing Tools
+
+1. **`BashTool`**: Remove stub, connect to `sandbox.commands.run()`.
+2. **`ReadFileTool`**: Keep on host, add size guardrail.
+3. **`WriteFileTool`**: Keep on host, mark file as dirty for next sync.
+
+### TDD Test Plan
+
+| #   | Test                                             | Behavior          |
+| --- | ------------------------------------------------ | ----------------- |
+| 1   | `SandboxManager.create()` initializes a sandbox  | Session lifecycle |
+| 2   | `SandboxManager.destroy()` cleans up the sandbox | Teardown          |
+| 3   | `syncToSandbox()` uploads dirty files            | Change tracking   |
+| 4   | Tool router sends `write_file` to host           | Host routing      |
+| 5   | Tool router sends `bash` to sandbox              | Sandbox routing   |
+
+---
+
+## Milestone 3.5: Security Scanning Tool
+
+**Goal:** Give the agent the ability to scan code for security vulnerabilities using the Gemini CLI Security Extension, with a native LLM-powered fallback.
+
+### 3.5a. SecurityScanTool (`src/tools/security.ts`)
+
+1. **Gemini CLI path** (preferred): Shell out to `gemini -x security:analyze` via sandbox.
+2. **Native LLM fallback**: Use the agent's configured LLM with a security-focused prompt to analyze code diffs.
+3. Accepts `target`: `"changes"` | `"file"` | `"deps"`, optional `path`.
+
+### 3.5b. DepScanTool (`src/tools/depScan.ts`)
+
+1. **OSV-Scanner**: Run `osv-scanner --json .` in sandbox, parse JSON results.
+2. **Fallback**: Run `npm audit --json` if OSV-Scanner is not installed.
+
+### 3.5c. Tool Registration
+
+1. Add both tools to `CORE_TOOLS` in `tools/index.ts`.
+2. Add `security_scan` and `dep_scan` to `SANDBOX_TOOLS` in `tools/router.ts`.
+3. Add security scan stubs to `DeferredToolsDB` in `tools/registry.ts`.
+
+### TDD Test Plan
+
+| #   | Test                                                      | Behavior    |
+| --- | --------------------------------------------------------- | ----------- |
+| 1   | SecurityScanTool returns report when Gemini CLI available | Shell path  |
+| 2   | SecurityScanTool falls back to LLM analysis               | Native path |
+| 3   | DepScanTool parses OSV-Scanner JSON output                | Dep scan    |
+| 4   | DepScanTool falls back to `npm audit`                     | Fallback    |
+| 5   | ToolRouter routes both to sandbox                         | Routing     |
+
+## Milestone 4: Harness Engineering & Middlewares
+
+**Goal:** Make the agent resilient. Stop it from breaking itself.
+
+1. **Middleware Pipeline Pattern**: Implement a generic pre/post execution hook system for tool calls.
+2. **Build `LoopDetectionMiddleware`**: Track hashes or signatures of tool calls. Throw errors/warnings when duplicated explicitly.
+3. **Build `SafeguardMiddleware`**: Prevent massive file reads.
+4. **Build `PreCompletionMiddleware`**: Intercept task completion and require proof of verification (e.g. running tests).
+
+## Milestone 5: Advanced Optimizations
+
+**Goal:** Scale the agent for complex workspaces and heavy memory.
+
+1. **Tool Lazy Loading**: Implement the "Tool Search" mechanism for dynamic capabilities.
+2. **Context Compaction**: Implement Cache-Safe Forking. When tokens hit 80% capacity, summarize earlier messages, retaining the static prefix format.
+3. **Reasoning Sandwich**: Implement dynamic logic routing. Allow the agent to use `high-reasoning` mode for planning, and drop to `medium-reasoning` for mechanical typing.
+
+## Milestone 5.5: Browser, Web Search & Skills
+
+**Goal:** Give the agent internet access, browser interaction, and extensible skill loading.
+
+### 5.5a. Browser Tool (`agent-browser`)
+
+- Wrap Vercel Labs' `agent-browser` CLI via sandbox shell calls
+- Commands: `navigate`, `snapshot` (accessibility tree), `click`, `type`, `screenshot`, `scroll`
+- Lazy-installed in dev, pre-baked in prod template
+
+### 5.5b. Web Search Tool (`@valyu/ai-sdk`)
+
+- AI-native search via Valyu API (runs on Host)
+- Sources: web, papers (arXiv/PubMed), finance, patents, SEC filings, companies
+- API key stored in config (`valyuApiKey`)
+
+### 5.5c. Skills System
+
+- Discovery paths: `./skills/`, `./.agents/skills/`, `~/.joone/skills/`, `~/.agents/skills/`
+- SKILL.md format: YAML frontmatter (name, description) + markdown instructions
+- Tools: `search_skills`, `load_skill` (injects into conversation as system-reminder)
+- Project skills override user skills with same name
+
+## Milestone 6: Tracing & Refinement
+
+**Goal:** Monitor performance and improve via feedback.
+
+1. **Integrate Tracing**: (LangSmith / LangFuse / OpenTelemetry) to track exact costs, cache hit rates, and execution paths.
+2. **Trace Analyzer Subagent**: Build the offline script that reads failed traces and outputs summaries for human harness engineers.
+
+## Milestone 7: Testing & Evaluations (TDD - Ongoing)
+
+**Goal:** Ensure the context boundaries, middlewares, and tools function flawlessly before production. This milestone runs **in parallel** with all others via TDD.
+
+1. ~~**Setup Vitest**~~
+2. **Unit Testing (Red-Green-Refactor)**:
+   - ~~`CacheOptimizedPromptBuilder` (5/5 GREEN)~~
+   - `ConfigManager`: loadConfig, saveConfig, env fallback
+   - `ModelFactory`: provider switching, error handling
+   - `MiddlewarePipeline`: Loop detection, pre-completion interception
+   - `SandboxLifecycleManager`: create/destroy lifecycle hooks
+3. **E2E Evaluations (Evals)**:
+   - Hook LangSmith datasets up to the `ExecutionHarness` to run regression tests against known code tasks.
+   - Measure **Cache Hit Rate** assertions (e.g., Assert CacheHit > 90% over a 10-turn conversation).

package/e2b/Dockerfile

@@ -0,0 +1,26 @@
+# joone-base: Pre-baked E2B sandbox template for production.
+# All security and development tools are pre-installed for zero startup cost.
+#
+# Build command:
+#   e2b template create --name joone-base --dockerfile ./e2b/Dockerfile
+#
+# Usage in config (~/.joone/config.json):
+#   { "sandboxTemplate": "joone-base" }
+
+FROM e2b/base
+
+# Install Node.js tooling
+RUN npm install -g @google/gemini-cli
+
+# Install Gemini CLI security extension
+RUN gemini extensions install https://github.com/gemini-cli-extensions/security
+
+# Install OSV-Scanner for dependency vulnerability scanning
+RUN 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
+
+# Verify installations
+RUN gemini --version && osv-scanner --version
+
+WORKDIR /workspace

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "joonecli",
+  "version": "0.1.0",
+  "description": "An autonomous coding agent",
+  "main": "dist/cli/index.js",
+  "bin": {
+    "joone": "./dist/cli/index.js"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuzzy08/joone.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/tuzzy08/joone/issues"
+  },
+  "homepage": "https://github.com/tuzzy08/joone#readme",
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@alibaba-group/opensandbox": "^0.1.4",
+    "@alibaba-group/opensandbox-code-interpreter": "^0.1.3-dev1",
+    "@clack/prompts": "^1.0.1",
+    "@langchain/anthropic": "^1.3.19",
+    "@langchain/core": "^1.1.27",
+    "@langchain/openai": "^1.2.11",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "cross-spawn": "^7.0.6",
+    "dotenv": "^17.3.1",
+    "e2b": "^2.13.0",
+    "ink": "^6.8.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "langchain": "^1.2.25",
+    "langsmith": "^0.5.7",
+    "react": "^19.2.4",
+    "zod": "^4.3.6"
+  }
+}

package/src/__tests__/bootstrap.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { LazyInstaller } from "../sandbox/bootstrap.js";
+import { SandboxManager } from "../sandbox/manager.js";
+
+// Mock SandboxManager
+const createMockSandbox = () => ({
+  exec: vi.fn(),
+  isActive: vi.fn().mockReturnValue(true),
+  create: vi.fn(),
+  destroy: vi.fn(),
+  uploadFile: vi.fn(),
+  getSandbox: vi.fn(),
+});
+
+describe("LazyInstaller", () => {
+  let mockSandbox: ReturnType<typeof createMockSandbox>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSandbox = createMockSandbox();
+  });
+
+  // ─── Test #34: Custom template skips all installs ───
+
+  it("skips installation when using a custom template", async () => {
+    const installer = new LazyInstaller(true);
+
+    expect(installer.isGeminiCliReady()).toBe(true);
+    expect(installer.isOsvScannerReady()).toBe(true);
+
+    // Should not call exec at all
+    const result = await installer.ensureGeminiCli(
+      mockSandbox as unknown as SandboxManager
+    );
+    expect(result).toBe(true);
+    expect(mockSandbox.exec).not.toHaveBeenCalled();
+  });
+
+  // ─── Test #35: Dev mode installs Gemini CLI on first use ───
+
+  it("installs Gemini CLI on first call in dev mode", async () => {
+    const installer = new LazyInstaller(false);
+
+    // First check fails (not installed), then install succeeds, then extension succeeds
+    mockSandbox.exec
+      .mockRejectedValueOnce(new Error("not found")) // version check
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "installed", stderr: "" }) // npm install
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "ok", stderr: "" }); // extension install
+
+    const result = await installer.ensureGeminiCli(
+      mockSandbox as unknown as SandboxManager
+    );
+
+    expect(result).toBe(true);
+    expect(installer.isGeminiCliReady()).toBe(true);
+  });
+
+  // ─── Test #36: Caches install state — second call is a no-op ───
+
+  it("does not re-install on second call (cached)", async () => {
+    const installer = new LazyInstaller(false);
+
+    // First: fails check, succeeds install + extension
+    mockSandbox.exec
+      .mockRejectedValueOnce(new Error("not found"))
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "" })
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "" });
+
+    await installer.ensureGeminiCli(mockSandbox as unknown as SandboxManager);
+    mockSandbox.exec.mockClear();
+
+    // Second call — should return immediately
+    const result = await installer.ensureGeminiCli(
+      mockSandbox as unknown as SandboxManager
+    );
+    expect(result).toBe(true);
+    expect(mockSandbox.exec).not.toHaveBeenCalled();
+  });
+
+  // ─── Test #37: Returns false if install fails ───
+
+  it("returns false if Gemini CLI installation fails", async () => {
+    const installer = new LazyInstaller(false);
+
+    mockSandbox.exec
+      .mockRejectedValueOnce(new Error("not found")) // version check
+      .mockResolvedValueOnce({ exitCode: 1, stdout: "", stderr: "error" }); // install fails
+
+    const result = await installer.ensureGeminiCli(
+      mockSandbox as unknown as SandboxManager
+    );
+    expect(result).toBe(false);
+    expect(installer.isGeminiCliReady()).toBe(false);
+  });
+
+  // ─── Test #38: OSV-Scanner install attempt ───
+
+  it("installs OSV-Scanner via curl when not available", async () => {
+    const installer = new LazyInstaller(false);
+
+    mockSandbox.exec
+      .mockRejectedValueOnce(new Error("not found")) // version check
+      .mockResolvedValueOnce({ exitCode: 0, stdout: "", stderr: "" }); // curl install
+
+    const result = await installer.ensureOsvScanner(
+      mockSandbox as unknown as SandboxManager
+    );
+    expect(result).toBe(true);
+    expect(installer.isOsvScannerReady()).toBe(true);
+  });
+});