joonecli 0.1.0 → 0.2.0

package/package.json

@@ -1,18 +1,17 @@
 {
   "name": "joonecli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An autonomous coding agent",
+  "files": ["dist"],
   "main": "dist/cli/index.js",
   "bin": {
-    "joone": "./dist/cli/index.js"
-  },
-  "directories": {
-    "doc": "docs"
+    "joone": "dist/cli/index.js"
   },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "postinstall": "node ./dist/cli/postinstall.js"
   },
   "repository": {
     "type": "git",

package/AGENTS.md

@@ -1,56 +0,0 @@
-# Welcome to the Agentic Coding Project
-
-You are an autonomous AI Agent contributing to this codebase. To ensure consistency with the established architectural patterns (Prompt Caching + Harness Engineering), you **MUST** review the foundational documents in the `docs/` directory before proposing new features or modifying the core loop.
-
-## Required Reading List
-
-Before tackling complex tasks related to the context engine, middleware, or tools, please reference:
-
-- `Handover.md`: **MUST READ FIRST if this is a new session.** Contains all key architectural decisions and current project state.
-- `docs/01_insights_and_patterns.md`: The core thesis of the project (Prefix caching rules, Middleware hooks).
-- `docs/02_edge_cases_and_mitigations.md`: What _not_ to do (e.g., Leaky timestamps, Mid-session model switches).
-- `docs/07_system_architecture.md`: The REPL execution graph.
-
-## Development Process: Red-Green-Refactor TDD
-
-> **CRITICAL:** This project follows a strict **Test-Driven Development (TDD)** workflow using the **Red-Green-Refactor** cycle.
-
-### TDD Skills (MUST READ)
-
-Before writing **any** production code, you **MUST** load and follow the TDD skill instructions:
-
-1. **Primary:** `C:\Users\Lenovo\.agents\skills\tdd\SKILL.md` — Covers vertical slicing (tracer bullets), behavior-driven testing, and anti-patterns.
-2. **Extended:** `C:\Users\Lenovo\.agents\skills\test-driven-development\SKILL.md` — The "Iron Law": no production code without a failing test first. Includes rationalizations to watch for and a verification checklist.
-
-### The Cycle
-
-1. **RED** — Write a failing test first. The test defines expected behavior.
-2. **GREEN** — Write the minimum production code to make the failing test pass.
-3. **REFACTOR** — Clean up both test and production code while keeping all tests green.
-
-### Rules
-
-- **Vertical slices only.** One test → one implementation → repeat. Never write all tests first.
-- **No production code without a failing test.** Code written before the test? Delete it. Start over.
-- **Never refactor while RED.** Get to GREEN first.
-
-**Test Runner:** Vitest (`npx vitest` or `npm test`).
-
-## Tracking Progress
-
-Any time you complete a significant milestone, you **must**:
-
-1. Append a summary of your actions and the current state of the project to `PROGRESS.md` in the project root.
-2. Update `Handover.md` to reflect any new architectural decisions, tool additions, or shifts in the project state.
-
-This ensures the next agent or human developer knows exactly where to pick up and why decisions were made.
-
-## API Key Management
-
-> **CRITICAL:** When implementing a **new tool** that requires an API key or token, you **must**:
->
-> 1. Add the key field to `JooneConfig` in `src/cli/config.ts`.
-> 2. Add a password prompt for it in the `joone config` onboarding flow in `src/cli/index.ts` (under the "Optional Service Keys" section).
-> 3. Ensure the key is included in the `newConfig` object that gets saved.
->
-> All service keys (except the primary LLM provider key) should be **optional** — the user can press Enter to skip. Tools should gracefully degrade when their API key is not configured.

package/Handover.md

@@ -1,115 +0,0 @@
-# Joone Agent: Handover & Architecture Document
-
-This document serves as a comprehensive handover note for future agents or engineering sessions. It captures the core architectural decisions, the current state of the project, and the rationale behind the implementation of the `joone` AI coding assistant.
-
-## 1. Project Overview & Tech Stack
-
-**Goal:** Build a secure, terminal-based AI coding assistant that executes code in an isolated sandbox while manipulating local project files, providing a premium developer experience.
-
-- **Runtime:** Node.js (v20+)
-- **Module System:** ESM (`"type": "module"`)
-- **Language:** TypeScript (`NodeNext` resolution)
-- **Terminal UI (TUI):** Ink v6 (React for CLI) + Clack (prompts/onboarding)
-- **Primary Sandbox:** E2B
-- **Fallback Sandbox:** OpenSandbox (Local Docker)
-- **AI SDKs:** `@langchain/anthropic`, `@langchain/openai`, `@google/genai` (planned/flexible via factory)
-- **Testing:** Vitest (TDD methodology strictly enforced)
-- **Testing:** Vitest (TDD methodology strictly enforced)
-
----
-
-## 2. Key Architectural Decisions
-
-### 2.1 The "Hybrid" Execution Model
-
-- **Decision:** Split tool execution between the **Host** machine and the **Sandbox**.
-- **Rationale:** We want the user to see file changes happen live in their IDE (Host), but we strictly do not want to run untrusted shell commands or install random dependencies on the user's machine (Sandbox).
-- **Implementation (`src/tools/router.ts` & `src/sandbox/manager.ts`):**
-  - **Host Routing (`HOST_TOOLS`):** `read_file`, `write_file`, `search_tools`.
-  - **Sandbox Routing (`SANDBOX_TOOLS`):** `bash`, `run_tests`, `install_deps`, `security_scan`, `dep_scan`.
-  - **Wrapper Architecture:** The `SandboxManager` uses an `ISandboxWrapper`. It attempts to connect to a primary **E2B** cloud sandbox. If initialization fails (e.g., API key error, network timeout), it gracefully defaults to a robust local **OpenSandbox** deployment (`localhost:8080`).
-  - _Safe-by-default logic:_ Any unknown tool request is routed to the sandbox.
-
-### 2.2 ESM Migration for the TUI
-
-- **Decision:** Migrated the entire codebase from CommonJS to ESM.
-- **Rationale:** The chosen TUI framework (Ink v6) and modern utility libraries (like Clack) are ESM-only. A premium UI requires modern tooling.
-- **Implementation:** Updated `package.json` (`type: module`), modified TSConfig (`module: NodeNext`), and enforced `.js` extensions on all relative local imports.
-
-### 2.3 Upload-on-Execute File Synchronization
-
-- **Decision:** Sync files from host to sandbox _just-in-time_ before command execution.
-- **Rationale:** Constant bidirectional syncing is slow and error-prone. Instead, when the agent uses `write_file` (on the host), the file is marked as "dirty".
-- **Implementation (`src/sandbox/sync.ts`):** Before `SandboxManager.exec()` runs a bash command, the `FileSync` layer checks the dirty queue and uploads only the modified files to the E2B sandbox.
-
-### 2.4 File Size & Context Guardrails
-
-- **Decision:** Prevent the LLM from reading massive files that would blow up the context window.
-- **Rationale:** Reading generic log files or compiled assets breaks token limits, leading to expensive failures.
-- **Implementation (`src/tools/index.ts` -> `ReadFileTool`):**
-  - Strict 512 KB file size hard-limit.
-  - Soft 2,000-line truncation limit.
-  - Added `startLine`/`endLine` arguments for specific chunk reading.
-  - Suggests `grep` or `head` via `bash` when limits are hit.
-
-### 2.5 Config-Driven Sandbox Strategy (Security Scanning)
-
-- **Decision:** Support both a zero-startup-cost Production environment and a flexible Development environment.
-- **Rationale:** Installing the Gemini CLI and OSV-Scanner inside the sandbox takes ~15 seconds, which ruins the UX if done on every session start.
-- **Implementation (`src/sandbox/bootstrap.ts`):**
-  - **Dev Mode (Default):** `LazyInstaller` installs tools on-demand _only_ when the user actually invokes `security_scan` or `dep_scan`. Install state is cached per session.
-  - **Prod Mode (`sandboxTemplate: "joone-base"`):** Uses a pre-baked E2B template defined in `e2b/Dockerfile`. The installer detects this and skips the install phase entirely (0s startup).
-
-### 2.6 Skills System (Multi-Directory Discovery)
-
-- **Decision:** Skills are discovered from multiple directories with project-level overriding user-level.
-- **Rationale:** Users may have personal skills (e.g., `~/.agents/skills/`) and project-specific skills. Project skills should take priority to allow per-project customization.
-- **Implementation (`src/skills/loader.ts`):**
-  - Discovery paths: `./skills/`, `./.agents/skills/`, `./.agent/skills/` (project), `~/.joone/skills/`, `~/.agents/skills/` (user)
-  - YAML frontmatter parsing for `name` and `description` fields
-  - Deduplication by name; project-level wins on conflict
-
----
-
-## 3. Current Project State
-
-All development follows strict TDD. Currently, **95 out of 95 tests are GREEN** across 13 test suites. TypeScript compiles cleanly.
-
-### Completed Milestones
-
-- ✅ **M1: Core Setup:** CLI scaffolding, config manager, dynamic Model Factory.
-- ✅ **M2: TUI & Core Loop:** Clack onboarding, Ink REPL interface, tool buffering.
-- ✅ **M3: Hybrid Sandbox:** E2B `SandboxManager`, `FileSync`, `ToolRouter`, core tools.
-- ✅ **M3.5: Security Tools:** `LazyInstaller`, `SecurityScanTool`, `DepScanTool`, E2B Dockerfile.
-- ✅ **M4: Harness Engineering:** `MiddlewarePipeline`, `LoopDetectionMiddleware`, `CommandSanitizerMiddleware`, `PreCompletionMiddleware`.
-- ✅ **M5: Advanced Optimizations:** Enhanced registry (fuzzy search + `activateTool`), `TokenCounter`, improved `compactHistory`, `ReasoningRouter`.
-- ✅ **M5.5: Browser, Search & Skills:** `BrowserTool` (agent-browser), `WebSearchTool` (@valyu/ai-sdk), `SkillLoader` + `search_skills`/`load_skill` tools.
-- ✅ **M6: Tracing & Refinement:** `SessionTracer` (metrics routing), `TraceAnalyzer` (offline insights), LangSmith env integration, `joone analyze` CLI command.
-- ✅ **M8: OpenSandbox Fallback:** `ISandboxWrapper`, local docker degradation at `localhost:8080`, and documented NFRs (Rate Limits & Budgets).
-- ✅ **M9: Persistent Sessions:** `SessionStore` (JSONL), `SessionResumer` (host drift detection), `joone sessions` dashboard, `joone start --resume <id>`.
-- ✅ **M10: Retry, HITL, Skills Sync:** `JooneError` hierarchy + `retryWithBackoff`, `HITLBridge` + `AskUserQuestionTool` + `PermissionMiddleware`, user-level skills sandbox sync.
-- ✅ **M11: Slash Command System:** `CommandRegistry` + 10 built-in `/commands` (`/help`, `/model`, `/clear`, `/compact`, `/tokens`, `/status`, `/exit`, `/history`, `/undo`) intercepted in TUI before agent loop (zero LLM cost).
-
-- ✅ **M12: LLM-Powered Compaction:** LLM-driven `ConversationCompactor`, fast model mapping (`FAST_MODEL_DEFAULTS`), and seamless handoff prompts post-compaction.
-- ✅ **M13: Sub-Agent Orchestration:** `AgentRegistry`, isolated sync/async `SubAgentManager`, and safe `spawn_agent` + `check_agent` tools (Depth-1 limits).
-- ✅ **M14: Stability & Reliability:** `ContextGuard` (80% auto-compact, 95% emergency truncation), `AutoSave` (debounced JSONL persistence), and atomic TUI `SIGINT/SIGTERM` handling.
-
-### Tool Routing Summary
-
-| HOST (safe, runs on user machine) | SANDBOX (isolated, runs in E2B)     |
-| --------------------------------- | ----------------------------------- |
-| `read_file`, `write_file`         | `bash`, `run_tests`, `install_deps` |
-| `search_tools`, `activate_tool`   | `security_scan`, `dep_scan`         |
-| `web_search` (API call)           | `browser` (agent-browser CLI)       |
-| `search_skills`, `load_skill`     | Unknown tools (safe-by-default)     |
-| `ask_user_question`               |                                     |
-| `/commands` (TUI-only, no LLM)    |                                     |
-| `spawn_agent`, `check_agent`      |                                     |
-
-### Pending Next Steps (Where to resume)
-
-**Continue with Milestone 15:**
-
-1.  **M15: MCP Client Integration** — `@modelcontextprotocol/sdk`, stdio/HTTP transport, namespaced MCP tools.
-
-_Reference `docs/08_roadmap.md` and the implementation plan artifact for the full checklist._

package/PROGRESS.md

@@ -1,160 +0,0 @@
-# Project Progress & Status
-
-_This document serves as a living changelog and status board. Any human or agent picking up this directory should read this first to understand the current state of the implementation._
-
----
-
-## Current Status
-
-- [x] Milestone 6: Tracing & Refinement
-- [x] Milestone 7: Testing & Evaluations (TDD - Ongoing)
-- [x] Milestone 8: OpenSandbox Fallback & NFRs
-- [x] Milestone 9: Persistent Sessions
-
-## Next Steps
-
-1.  **Milestone 7 Evals**: Hook LangSmith datasets to ExecutionHarness for regression testing.
-2.  **Dataset CI**: Build `joone eval` CLI command to assert Cache Hit Rate > 90% and Cost < $X.
-3.  **Security Tier 2 & 3 (Planned)**: OS Keychain and encrypted config.
-
----
-
-## Changelog
-
-### 2026-02-22: Project Initialization & Context Engine
-
-- **Docs Setup**: Extracted key insights from Harness Engineering and Prompt Caching research into the `docs/` folder (`01_insights...` through `08_roadmap...`).
-- **Tech Stack**: Finalized TypeScript + Node + LangChain + Zod + LangSmith architecture.
-- **Project Scaffold**: Initialized `package.json`, installed dependencies, configured strict `tsconfig.json`.
-- **Phase 1 Complete**: Implemented `CacheOptimizedPromptBuilder` (`src/core/promptBuilder.ts`) to strictly enforce the static-to-dynamic prefix caching rules via LangChain message formatting.
-- **Phase 1 Complete**: Implemented the base `ExecutionHarness` (`src/core/agentLoop.ts`) combining the LLM query and naive tool execution block.
-- **Phase 2 Started**: Created the `DeferredToolsDB` and mock `SearchToolsTool` (`src/tools/registry.ts`) to support lazy loading of tools for cache preservation.
-- **Testing & Sandbox Strategy**: Created `src/test_cache.ts` to empirically test Anthropic prompt caching locally. Outlined the architecture to use **E2B (e2b.dev)** or Docker for secure sandboxed code execution, isolating the agent's OS interactions from the host environment.
-- **Governance**: Created `AGENTS.md` and this `PROGRESS.md` file.
-
-### 2026-02-25: Architecture Refinements & Doc Overhaul
-
-- **Provider Abstraction**: Refactored `ExecutionHarness` to accept any LangChain `BaseChatModel | Runnable` instead of hardcoding `ChatAnthropic`. Model selection now happens at the call site (`src/index.ts`).
-- **AGENTS.md**: Added mandatory Red-Green-Refactor TDD workflow instructions; added reminder to use `tdd` skill if available.
-- **PRD**: Added CLI packaging (`npx joone`), provider/model selection feature, and E2B sandbox execution as core features.
-- **User Stories**: Added new Epics for CLI/Config (Epic 1) and E2B Sandbox Execution (Epic 3).
-- **System Architecture**: Updated mermaid diagram to show CLI config layer routing to provider selection and E2B sandbox replacing local OS execution.
-- **Roadmap**: Restructured milestones to include CLI Packaging (M2), E2B Sandbox Integration (M3), and made Testing & Evaluations an ongoing parallel milestone (M7) driven by TDD.
-
-### 2026-02-25: Milestone 7 — TDD Setup & First GREEN
-
-- **TDD Skills**: Located and verified both `tdd` and `test-driven-development` skills at `C:\Users\Lenovo\.agents\skills\`. Updated `AGENTS.md` with exact paths and instructions.
-- **Vitest Installed**: Added `vitest` as a dev dependency.
-- **PromptBuilder Tests (5/5 GREEN)**: Wrote 5 behavior-driven tests covering: strict prefix ordering, history appending after prefix, prefix stability across calls, `<system-reminder>` injection, and compaction. All passing.
-
-### 2026-02-26: Milestone 2 — Detailed Planning Complete
-
-- **PRD Updated**: Added streaming, expanded provider list (9+), tiered API key security (plain → keychain → encrypted), and dynamic provider loading.
-- **User Stories Updated**: Added Epic 2 (Streaming), expanded Epic 1 with masked input and planned keychain onboarding (US 1.6).
-- **System Architecture Updated**: Added Stream Handler component, Model Factory component, full provider table, and security tier roadmap.
-- **Roadmap Updated**: Detailed Milestone 2 into 5 sub-sections (2a–2e) with a 9-step TDD vertical slice test plan.
-- **Pending tracked items**: OS Keychain (Security Tier 2) and AES-256 encrypted config (Security Tier 3) tracked as planned items for future onboarding enhancement.
-
-### 2026-02-27: Milestone 2 — CLI Packaging & Provider Selection (COMPLETE)
-
-- **Config Manager** (`src/cli/config.ts`): `JooneConfig` interface, `loadConfig` (with env var fallback for 8 providers), `saveConfig` (with `chmod 600`), `DEFAULT_CONFIG`, `getProviderEnvVar`.
-- **Model Factory** (`src/cli/modelFactory.ts`): Dynamic `import()` for Anthropic and OpenAI. API key validation, missing package detection with install instructions. Support for 9+ providers planned.
-- **CLI Entry Point** (`src/cli/index.ts`): Commander.js with `joone` (default start) and `joone config` (interactive setup). Masked API key input via `@inquirer/prompts`. 9 provider choices + model lists.
-- **Streaming Support** (`src/core/agentLoop.ts`): `streamStep()` method on `ExecutionHarness` — text tokens emitted via `onToken` callback, tool call JSON chunks buffered until complete.
-- **Security Tier 1**: `saveConfig` writes with `mode: 0o600`, directory with `mode: 0o700`. Masked input in CLI. Env var fallback for API keys.
-- **Package.json**: Updated with `"bin"`, `"build"`, `"test"`, `"test:watch"` scripts. Version bumped to `0.1.0`.
-- **vitest.config.ts**: Created with test env vars to prevent Anthropic API key errors during testing.
-- **Bug fix**: Deleted stale compiled `.js`/`.d.ts` files that were shadowing `.ts` sources, causing `streamStep` not to be found at runtime.
-- **Tests**: 14/14 GREEN across 4 suites (config: 3, modelFactory: 4, promptBuilder: 5, streaming: 2).
-
-### 2026-02-28: Milestone 2.5 — Terminal UI (Ink + Clack) (COMPLETE)
-
-- **ESM Migration**: `package.json` → `"type": "module"`, `tsconfig.json` → `"module": "NodeNext"`, `"jsx": "react-jsx"`. All 17 relative imports updated with `.js` extensions. 14/14 tests GREEN after migration.
-- **Dependencies**: Added `ink`, `react`, `@types/react`, `@clack/prompts`, `chalk`, `ink-spinner`. Removed `@inquirer/prompts`.
-- **Clack Onboarding** (`src/cli/index.ts`): `joone config` rewritten with `intro()`, `outro()`, `spinner()`, `select()`, `password()`, `confirm()`, `cancel()`. Full cancellation handling with `isCancel()`. Chalk-styled terminal output for `joone start`.
-- **Ink Components** (`src/ui/`):
-  - `App.tsx`: Main REPL layout with header, message history, streaming text, tool call panel, status bar, keyboard input (Ctrl+C to exit), elapsed time timer.
-  - `Header.tsx`: Bordered box showing provider, model, streaming status with cyan accent.
-  - `MessageBubble.tsx`: Role-based styling (user=cyan, agent=green, system=yellow).
-  - `StreamingText.tsx`: Token-by-token rendering with blinking cursor during streaming.
-  - `ToolCallPanel.tsx`: Status-colored bordered box (yellow=running, green=success, red=error) with spinner, args display, truncated result.
-  - `StatusBar.tsx`: Persistent footer with token count, cache hit rate, tool calls, elapsed time.
-
-### 2026-02-28: Milestone 3 — Hybrid Sandbox Integration (COMPLETE)
-
-- **SandboxManager** (`src/sandbox/manager.ts`): E2B SDK wrapper with `create()`, `destroy()`, `exec(cmd)`, `uploadFile(path, content)`, and `isActive()` lifecycle management.
-- **FileSync** (`src/sandbox/sync.ts`): Host → sandbox file sync with `markDirty()`, `syncToSandbox()`, and `initialSync()`. Excludes `node_modules`, `.git`, `dist` on initial sync.
-- **ToolRouter** (`src/tools/router.ts`): Routes tools to HOST (`write_file`, `read_file`, `search_tools`) or SANDBOX (`bash`, `run_tests`, `install_deps`). Unknown tools default to sandbox for safety.
-- **Tests**: 26/26 GREEN across 6 suites (sandbox: 5, toolRouter: 7, plus existing 14).
-
-### 2026-02-28: Milestone 3.5 — Security Scanning Tool (COMPLETE)
-
-- **Config**: Added `sandboxTemplate?: string` to `JooneConfig` — config-driven switching between dev (lazy install) and prod (pre-baked template).
-- **LazyInstaller** (`src/sandbox/bootstrap.ts`): Handles on-demand tool installation inside the sandbox. Caches install state per session. Skips entirely when using a custom E2B template.
-- **SecurityScanTool** (`src/tools/security.ts`): Runs `gemini -x security:analyze` in sandbox. Supports targets: `"changes"`, `"file"`, `"deps"`. Handles CLI unavailability gracefully.
-- **DepScanTool** (`src/tools/security.ts`): Runs OSV-Scanner with `npm audit` fallback. Supports JSON and summary output.
-- **ToolRouter**: Added `security_scan` and `dep_scan` to `SANDBOX_TOOLS`.
-- **E2B Dockerfile** (`e2b/Dockerfile`): Pre-baked production template with Gemini CLI + security extension + OSV-Scanner.
-- **Tests**: 43/43 GREEN across 9 suites (bootstrap: 5, security: 5, plus existing 33).
-
-### 2026-02-28: Milestone 4 — Harness Engineering & Middlewares (COMPLETE)
-
-- **Middleware Types** (`src/middleware/types.ts`): `ToolCallContext` and `ToolMiddleware` interface with before/after hooks.
-- **MiddlewarePipeline** (`src/middleware/pipeline.ts`): Chains before-hooks in order, executes tool, chains after-hooks in reverse. Short-circuits on rejection.
-- **LoopDetectionMiddleware** (`src/middleware/loopDetection.ts`): Blocks after N identical consecutive tool calls (default: 3). Anti-doom-loop.
-- **CommandSanitizerMiddleware** (`src/middleware/commandSanitizer.ts`): Blocks destructive (`rm -rf /`, fork bombs), interactive (`vim`, `top`), and pipe-to-shell commands.
-- **PreCompletionMiddleware** (`src/middleware/preCompletion.ts`): Tracks test execution and blocks task completion until tests have been run.
-- **Integration**: `ExecutionHarness.executeToolCalls()` now routes through `MiddlewarePipeline`.
-- **Tests**: 55/55 GREEN across 10 suites (middleware: 12, plus existing 43).
-
-### 2026-02-28: Milestone 5 — Advanced Optimizations (COMPLETE)
-
-- **Enhanced Registry** (`src/tools/registry.ts`): Fuzzy search by name/description, `activateTool()` for dynamic mid-session tool loading, `ActivateToolTool`. Expanded stubs: git_diff, git_log, grep_search, list_dir.
-- **Token Counter** (`src/core/tokenCounter.ts`): Character-based heuristic (~4 chars/token). `estimateTokens()`, `countMessageTokens()`, `isNearCapacity()`.
-- **Context Compaction**: Enhanced `compactHistory()` with `keepLastN` parameter (preserves recent messages). Added `shouldCompact()` to `CacheOptimizedPromptBuilder`.
-- **Reasoning Router** (`src/core/reasoningRouter.ts`): HIGH/MEDIUM reasoning levels. HIGH for planning + error recovery, MEDIUM for tool-heavy turns. Temperature-only adjustment (preserves cache prefix).
-- **Tests**: 69/69 GREEN across 11 suites.
-
-### 2026-02-28: Milestone 5.5 — Browser, Web Search & Skills (COMPLETE)
-
-- **Browser Tool** (`src/tools/browser.ts`): Wraps `agent-browser` CLI. Actions: navigate, snapshot, click, type, screenshot, scroll. Runs in sandbox.
-- **Web Search Tool** (`src/tools/webSearch.ts`): Wraps `@valyu/ai-sdk`. Sources: web, papers, finance, patents, SEC, companies. Dynamic import, type stub in `src/types/valyu.d.ts`.
-- **Skills System**: `SkillLoader` (`src/skills/loader.ts`) discovers skills from project root (`./skills/`, `./.agents/skills/`) and user home (`~/.joone/skills/`, `~/.agents/skills/`). YAML frontmatter parsing, project-overrides-user deduplication.
-- **Skills Tools** (`src/skills/tools.ts`): `search_skills` + `load_skill` tools for agent runtime use.
-- **Config**: Added `valyuApiKey` to `JooneConfig`. Updated `ToolRouter` with browser/web_search/skills routing.
-
-### 2026-02-28: Milestone 6 — Tracing & Refinement (COMPLETE)
-
-- **SessionTracer** (`src/tracing/sessionTracer.ts`): Records LLM events (prompt/completion tokens), tool runs (name/args/duration/success), and errors. Saves traces to `~/.joone/traces/{id}.json`.
-- **Harness Integration** (`src/core/agentLoop.ts`): Wired `ExecutionHarness` to automatically emit tracing events natively through `SessionTracer` during `step()`, `streamStep()`, and `executeToolCalls()`.
-- **Trace Analyzer** (`src/tracing/analyzer.ts`): Analyzes a saved `SessionTrace` to detect doom-loops, cost hotspots (>20% total tokens), low cache efficiency (<70%), and error clusters. Generates actionable recommendations.
-- **LangSmith Integration** (`src/tracing/langsmith.ts`): Injects configured `LANGCHAIN_TRACING_V2` environment variables from `JooneConfig` natively on CLI startup.
-- **CLI Command** (`src/cli/index.ts`): Added `joone analyze [sessionId]` to read trace files and print the offline analysis report beautifully.
-- **Tests**: 91/91 GREEN across 13 suites.
-
-### 2026-03-01: Milestone 8 & Milestone 9 Completed!
-
-The agent now supports robust **Persistent Sessions** allowing users to pause/resume tasks. It uses highly optimized JSONL appending and automatically detects Host File System Drift when waking up. Furthermore, it supports automatic fallbacks to OpenSandbox when the primary cloud sandbox (E2B) is unavailable!
-
-- **SandboxManager (`ISandboxWrapper`)**: Refactored the core sandbox execution system to support multiple backends securely. Created `E2BSandboxWrapper` and `OpenSandboxWrapper`.
-- **Graceful Degradation**: If E2B fails to initialize (e.g. from a network error or bad API key), the agent automatically catches the error and degrades instantly to a local Docker `OpenSandbox` container on `localhost:8080`.
-- **SessionStore & SessionResumer**: Implemented a highly optimized JSONL-based `SessionStore` (`src/core/sessionStore.ts`) for persistent session logging and `SessionResumer` (`src/core/sessionResumer.ts`) for rehydrating agent state.
-- **Host File System Drift Detection**: `SessionResumer` now automatically detects changes in the host file system since the last session save and prompts the user for reconciliation.
-- **Config & CLI**: Updated `JooneConfig`, `loadConfig`/`saveConfig`, and the `joone config` Clack onboarding wizard to optionally prompt for `OpenSandbox API key` and `Domain`.
-- **NFRs Documented**: Formally established architectural standards in `docs/05_prd.md` for Error Handling (Fallback), Rate Limiting (Budgets & Loop Breakers), Authentication (CLI keys), and Telemetry Data Retention (Local JSONs rotated at 30 days — 100% private).
-- **Tests**: 95/95 GREEN tests ensuring the sandbox layer abstraction natively handles API mappings without breaking `BashTool`.
-
-### 2026-03-04: Milestone 10 — Retry, HITL, and Skills Sync (COMPLETE)
-
-- **Error Hierarchy** (`src/core/errors.ts`): `JooneError` base class with `LLMApiError`, `SandboxError`, `ToolExecutionError` subclasses. Each carries `category`, `retryable` flag, structured `context`, and `toRecoveryHint()` for self-healing. `wrapLLMError()` auto-classifies raw provider errors.
-- **Retry** (`src/core/retry.ts`): `retryWithBackoff<T>()` generic utility with exponential backoff (1s→2s→4s + jitter). Respects `JooneError.retryable` flag. Non-retryable errors (401/403) fail immediately.
-- **Self-Recovery** (`src/core/agentLoop.ts`): On exhausted retries, `ExecutionHarness` injects the error's `toRecoveryHint()` as a `SystemMessage` into conversation history instead of crashing. Tool errors now wrapped in `ToolExecutionError`.
-- **HITLBridge** (`src/hitl/bridge.ts`): EventEmitter-based singleton with `askUser()` and `requestPermission()`. Configurable timeout (default 5 min) with auto-deny/auto-no-response.
-- **AskUserQuestionTool** (`src/tools/askUser.ts`): Agent-callable tool for mid-turn clarification, preference gathering, and plan approval.
-- **PermissionMiddleware** (`src/middleware/permission.ts`): `ToolMiddleware` implementation with 3 modes (`auto`, `ask_dangerous`, `ask_all`). Hardcoded `SAFE_TOOLS` whitelist. Uses `HITLBridge.requestPermission()` for dangerous tools.
-- **HITLPrompt** (`src/ui/components/HITLPrompt.tsx`): Ink TUI component rendering question/permission prompts with `TextInput` capture.
-- **Skills Sync** (`src/sandbox/sync.ts`): `syncSkillsToSandbox()` uploads user-level skill directories into `/workspace/.joone/skills/` in the sandbox.
-- **System Prompt**: Updated `globalSystemInstructions` with `ask_user_question` awareness, permission system notice, and skills discovery instructions.
-- **Config**: Added `permissionMode` to `JooneConfig` (default: `"auto"`).
-- **Edge Cases**: Added 8 new scenarios covering retry/self-recovery, HITL timeouts, permission misconfiguration, and skills sync.
-- **Tests**: 24 new tests (14 retry/errors + 10 HITL/permission) all GREEN. TypeScript build clean.

package/docs/01_insights_and_patterns.md

@@ -1,27 +0,0 @@
-# Actionable Insights, Patterns, and Best Practices
-
-Derived from recent research on Harness Engineering and Prompt Caching for Agentic Coding.
-
-## 1. The Cache-Optimized Context Prefix (Prompt Caching)
-
-- **Prefix Matching Rule:** LLM APIs cache everything from the start of a prompt up to a `cache_control` breakpoint. Any dynamic change in the middle invalidates the rest of the cache.
-- **Order Matters (Static to Dynamic):**
-  1. Base System Instructions & Tool Definitions (Globally Cached)
-  2. Project/Workspace memory (e.g., `CLAUDE.md`) (Cached per project)
-  3. Session State (Environment variables, rules) (Cached per session)
-  4. Conversation Messages (Grows iteratively)
-- **Immutability within a Session:** Never add/remove tools mid-conversation, and never swap models (e.g., from Opus to Haiku) mid-session, as this breaks the cache prefix.
-- **The `<system-reminder>` Pattern:** If you need to update agent behavior or state, do **not** edit the system prompt. Instead, insert a `<system-reminder>` tag inside the next simulated User Message or Tool Result.
-
-## 2. Harness Engineering & Middleware
-
-- **Control via Harness, Not Just Prompts:** Mold the agent's behavior by building programmatic wrappers (middleware) around the LLM reasoning step rather than just asking the LLM nicely.
-- **Anti-Doom-Loop Middleware:** Track per-file edits in the harness. If an agent edits the same file N times without success, inject a message forcing it to reconsider its approach.
-- **Forced Self-Verification:** Agents tend to write code and immediately stop without testing. Implement a `PreCompletionChecklistMiddleware` that intercepts the agent's attempt to exit, forcing it to run local tests and read the full output before concluding.
-- **Local Context Injection:** Automatically discover and map the working directory and available binaries (e.g., Python, Node) into the prompt upon startup.
-
-## 3. Agent Execution Strategy
-
-- **The Reasoning Sandwich:** Adjust the amount of compute/reasoning dynamically. Use heavy reasoning for Planning, Discovery, and Final Verification, but use medium reasoning for straightforward code implementations to save time and tokens.
-- **Lazy Tool Loading (Searchable Tools):** Instead of stuffing every possible schema into the prompt, provide "stubs" (tool names and descriptions). Allow the agent to search for advanced tools, deferring the loading of full schemas to preserve prefix caching.
-- **Trace-Driven Improvement:** Treat tracing (e.g., LangSmith) as a first-class feature. Route raw text-space traces to a designated "Trace Analyzer Subagent" to find where the agent frequently fails, allowing you to patch the harness without blindly guessing.

package/docs/02_edge_cases_and_mitigations.md

@@ -1,143 +0,0 @@
-# Edge Cases & Mitigations
-
-When building a coding agent with Prompt Caching + Middlewares, these are the primary edge cases to design around:
-
-## 1. Prompt Caching Edge Cases (Cost & Latency Traps)
-
-- **The "Leaky Timestamp" Cache Breaker:**
-  - _The Edge Case:_ If you inject dynamic data (like the current time, memory usage, or random UUIDs) into your Base System Prompt, you will achieve a **0% cache hit rate**. The cache relies on exact prefix matching.
-  - _Mitigation:_ Put all static, immutable instructions at the top. Any dynamic state must be injected via a `<system-reminder>` inside the _Messages_ array (which sits at the end of the context).
-- **The Mid-Session Model Switch:**
-  - _The Edge Case:_ Switching models mid-thread (e.g., cheap model for summarizing, smart model for coding) means the new model has an empty cache and must re-process the entire prompt prefix from scratch.
-  - _Mitigation:_ Avoid swapping models in the same thread. Span a "Sub-agent" thread and only pass minimum necessary context.
-- **Context Window Compaction (Amnesia):**
-  - _The Edge Case:_ Summarizing a long conversation and starting a new prompt causes you to lose your cached prefix AND the agent forgets specific constraints.
-  - _Mitigation:_ Implement **Cache-Safe Forking**. Keep the exact same System Prompt and Tool definitions. Start a new thread by passing the summary of the previous history as the first few messages, followed by the new task.
-
-## 2. Harness & Middleware Edge Cases (Logic Traps)
-
-- **The "Massive File" Blunder:**
-  - _The Edge Case:_ The agent reads a 10,000-line minified file. This floods the context window, pushes out important instructions, and ruins the session cache.
-  - _Mitigation:_ Harness-level Guardrails. Restrict `read_file` to return chunks or force the agent to use `grep_search` / `view_file_outline`.
-- **The "Blind Retry" Doom Loop:**
-  - _The Edge Case:_ The agent misses a space in a search-and-replace, fails, and tries the exact same edit endlessly.
-  - _Mitigation:_ Use `LoopDetectionMiddleware`. If the agent emits identical tool calls 3 times, intercept and inject: _"You have failed this 3 times. Stop trying this approach."_
-- **The "Fake Success" Verification:**
-  - _The Edge Case:_ The agent runs tests, they fail, but the agent hallucinates that the failure is acceptable and marks the task as Done. Older approaches relied on fragile string parsing (e.g., matching "failed" in output), which could easily be bypassed or confused by test output.
-  - _Mitigation:_ The harness must programmatically parse terminal exit codes. By explicitly surfacing structured tool metadata (e.g., `ToolResult.metadata.exitCode`) from execution sandboxes, the `PreCompletionMiddleware` reliably blocks the agent from exiting if tests don't pass (`exitCode !== 0`).
-- **Tool Schema Amnesia (with Lazy Loading):**
-  - _The Edge Case:_ An agent loads a complex tool lazily, uses it once, and then later forgets how to format its JSON schema.
-  - _Mitigation:_ If a tool is "discovered", it must remain in the "Messages" context as a system reminder so the schema is preserved.
-- **The "Ghost Tool Call" (Context Desync):**
-  - _The Edge Case:_ A model emits a tool call but occasionally forgets to attach a internal `tool_call_id` (this breaks the strict `AIMessage[tool_calls] -> ToolMessage[tool_call_id]` sequencing rules required by modern LangChain/Anthropic/OpenAI APIs). If you forge a fake ID or cast it as a string, the LLM rejects the context on the next turn.
-  - _Mitigation:_ The "Soft Fail" approach. Intercept the malformed tool call in the `ExecutionHarness`. Do not execute the tool and do not emit a `ToolMessage`. Instead, emit a corrective `HumanMessage` stating: _"You attempted to call tool X, but didn't provide a tool_call_id. Please try again."_ This prevents context poisoning.
-
-## 3. Security & Execution Edge Cases (Tool Exploits)
-
-- **Command Injection via Malicious Interpolation:**
-  - _The Edge Case:_ Passing user-provided arguments directly into shell commands (e.g., `agent-browser --url "${args.url}"` or `gemini --file "${args.path}"`) allows attackers to escape quotes and execute arbitrary commands in the sandbox (e.g., `url = '"; cat /etc/passwd; "'`).
-  - _Mitigation:_ Use strict Bash parameter escaping. All dynamic strings passed to shell commands are wrapped in single quotes, and any internal single quotes are escaped (`'\\''`).
-- **Host Filesystem Path Traversal (The "Escaped Workspace" Vulnerability):**
-  - _The Edge Case:_ Because `read_file` and `write_file` execute on the host machine to support live IDE syncing, a malicious prompt could instruct the agent to write to `~/.bashrc`, `C:\Windows\System32`, or `/.ssh/id_rsa`, compromising the user's host machine.
-  - _Mitigation:_ Implement strict Workspace Jail boundaries. Before any host I/O operation, the resolved path is evaluated against `process.cwd()`. If the path attempts to escape the root workspace, the tool immediately rejects the call returning a permissions error.
-- **Silently Swallowed CLI Errors:**
-  - _The Edge Case:_ A CLI tool (like OSV-Scanner) crashes due to a configuration error (exit code > 1) and prints an error to `stderr`. If the orchestration layer only checks for `stdout` and swallows non-zero exit codes silently falling back to another tool, the critical error trace is lost.
-  - _Mitigation:_ Enforce strict exit code verification (e.g., `exitCode === 1` means vulnerabilities found) and emit clear warnings with the full `stderr` trace before attempting any fallback strategies.
-- **The "Over-Eager Doom Loop" Reporter:**
-  - _The Edge Case:_ When detecting a doom loop (calling the same tool with identical args continuously), firing an alert during the active iteration causes redundant, spammy issue reports (e.g., reporting loop counts 3, 4, and 5 as separate critical issues).
-  - _Mitigation:_ Track the loop state continuously but defer pushing the `AnalysisIssue` to the report array until the loop is visibly broken by a differing action, or the trace ends.
-- **The "Parallel Tool Expansion" Bug (TUI Memory Corruption):**
-  - _The Edge Case:_ In a Terminal UI rendering loop, executing an array of tool calls _inside_ the UI rendering iteration causes the generated `ToolMessage` array to be appended to the conversation history $N$ times (for $N$ tools), massively inflating context usage with duplicated data.
-
-## 4. Persistent Session Edge Cases (State Management)
-
-- **File System Drift (Host Desync):**
-  - _The Edge Case:_ The agent edits a file, the session is paused. A human edits the file externally before the session is resumed. The agent resumes, unaware of the external edits, and attempts a line-based replacement that corrupts the file.
-  - _Mitigation:_ `SessionResumer` explicitly logs `mtime` file stats. Upon resumption, it flags recently modified workspace files and injects a "Wakeup Prompt" forcing the LLM to diff or re-read the file before acting.
-- **Sandbox Ephemerality (The Amnesia Problem):**
-  - _The Edge Case:_ A session running a background Express server in a cloud sandbox on Friday is resumed on Monday. The cloud provider killed the idle VM. The new VM lacks the running server, but the LLM’s context history believes it is still running.
-  - _Mitigation:_ Sandboxes are treated strictly statelessly. Upon string resumption, the agent is injected with a system message that the sandbox was recycled and it must manually restart required daemons/dev-servers.
-- **"Mid-Breath" Interruption State (Corrupt Serialization):**
-  - _The Edge Case:_ A forced exit (`SIGINT`/Power Loss) occurs exactly while the agent stream is halfway through emitting a JSON tool call chunk, serializing a broken `AIMessage` into history.
-  - _Mitigation:_ The `SessionStore` must only trigger a `saveSession()` at strict execution boundaries (e.g. after a complete LLM generation cycle or successfully parsed CLI execution), guaranteeing invalid mid-stream JSON chunks never touch the disk.
-- **Context Overflow (The Infinite Chat Log):**
-  - _The Edge Case:_ A persistent session spanning weeks scales the context past 200k tokens, hitting API limits and exponentially inflating the per-turn token costs.
-  - _Mitigation:_ Compaction is forced _before_ disk serialization. The session stringizes and compresses turns older than $N$ iterations into a dense system summary block before writing to `.jsonl`.
-- **Provider/Model Switching Mid-Task:**
-  - _The Edge Case:_ Starting a complex reasoning loop with Opus, pausing, and resuming with a lightweight local model like Llama 3 8B. The history is filled with complex schema usages that confused the smaller model.
-  - _Mitigation:_ Serialize the `.jsonl` lines with `provider/model` metadata blocks. Upon resumption, the CLI explicitly warns if a provider downgrade is detected.
-
-## 5. Error Recovery & Retry Edge Cases
-
-- **Transient LLM API Failure (429/5xx):**
-  - _The Edge Case:_ The LLM provider returns a rate-limit (429) or server error (500/502/503) mid-turn, crashing the entire session.
-  - _Mitigation:_ `retryWithBackoff()` wraps all LLM calls with exponential backoff (1s→2s→4s + jitter). Only `JooneError` instances with `retryable === true` trigger retries; auth failures (401/403) propagate immediately.
-- **Exhausted Retries (Self-Recovery):**
-  - _The Edge Case:_ After 3 retry attempts, the LLM API is still down. The session crashes and the user loses all progress.
-  - _Mitigation:_ Instead of crashing, `ExecutionHarness` injects the error's `toRecoveryHint()` as a `SystemMessage` into the conversation, returning a synthetic `AIMessage`. The agent can observe the error context and adapt (e.g., wait, simplify, or ask the user).
-- **Unclassified Provider Errors:**
-  - _The Edge Case:_ A new LLM provider throws a non-standard error with no HTTP status code, bypassing the retry classification.
-  - _Mitigation:_ `wrapLLMError()` inspects `.status`, `.statusCode`, `.code`, and `.response.status` on raw errors, covering the common patterns of LangChain, Axios, and native `fetch` errors.
-
-## 6. Human-in-the-Loop Edge Cases
-
-- **Permission Timeout (User Away):**
-  - _The Edge Case:_ The agent calls a dangerous tool (`bash`, `write_file`) while the user is away from the terminal. The agent blocks indefinitely waiting for permission.
-  - _Mitigation:_ `HITLBridge.requestPermission()` has a configurable timeout (default 5 minutes) that auto-denies and returns a short-circuit string, letting the agent try an alternative.
-- **Ask Question Timeout:**
-  - _The Edge Case:_ The agent asks the user a clarifying question via `ask_user_question`, but the user doesn't respond.
-  - _Mitigation:_ `HITLBridge.askUser()` resolves with `"[No response]"` after timeout, so the agent can proceed with a default assumption.
-- **Permission Mode Misconfiguration:**
-  - _The Edge Case:_ The user sets `"permissionMode": "ask_all"` and then every tool call — including harmless reads — triggers a prompt, making the agent unusable.
-  - _Mitigation:_ `PermissionMiddleware` maintains a hardcoded `SAFE_TOOLS` whitelist (`read_file`, `search_skills`, `ask_user_question`, etc.) that bypasses approval even in `ask_all` mode.
-
-## 7. Skills Sync Edge Cases
-
-- **Missing User Skills Directory:**
-  - _The Edge Case:_ `~/.joone/skills/` doesn't exist on the user's machine. The sync crashes trying to walk a nonexistent path.
-  - _Mitigation:_ `syncSkillsToSandbox()` checks `fs.existsSync()` before walking each skill directory and silently skips missing paths.
-- **Skill Name Collision (Project vs. User):**
-  - _The Edge Case:_ A user-level skill and a project-level skill have the same name. Both get synced to the sandbox, creating confusion.
-  - _Mitigation:_ `SkillLoader.discoverSkills()` deduplicates by name with project-level priority. `syncSkillsToSandbox()` only uploads `source: "user"` skills since project-level skills are already inside `projectRoot`.
-
-## 8. Slash Command Edge Cases (M11)
-
-- **Command Typos & Frustration:**
-  - _The Edge Case:_ User types `/modle` instead of `/model` and the agent treats it as a prompt, wasting LLM tokens and failing to switch the model.
-  - _Mitigation:_ Levenshtein distance check in `CommandRegistry`. If an unknown command is `< 3` edits away from a known command, the TUI intercepts it and suggests the correct command without calling the LLM.
-- **State Mutation While Processing:**
-  - _The Edge Case:_ User runs `/exit` or `/clear` while the agent is midway through generating a sequence of ToolCalls.
-  - _Mitigation:_ App-level UI blocks input while `isProcessing === true`. The commands are disabled.
-- **Model Switch to Non-Existent Model:**
-  - _The Edge Case:_ User runs `/model nonexistent`.
-  - _Mitigation:_ The command validates the model string against `ConfigManager`'s available models and securely rejects it before updating internal state.
-
-## 9. LLM-Powered Compaction Edge Cases (M12)
-
-- **Compaction Data Loss (Amnesia 2.0):**
-  - _The Edge Case:_ The LLM summarizes a 50-turn conversation but drops explicit file paths or tool choices, leaving the main agent blind when resuming.
-  - _Mitigation:_ The built-in Compact Prompt explicitly mandates a structured format: `Files Modified`, `Decisions Made`, `Tools Used`. A handoff prompt (`[CONTEXT HANDOFF]`) is injected into the bottom of the history to glue the summary back to the agent's persona.
-- **Double Compaction Fidelity Loss:**
-  - _The Edge Case:_ A session exists so long it must be compacted twice. A "summary of a summary" loses critical resolution.
-  - _Mitigation:_ `ConversationCompactor` detects prior summaries and includes them entirely in the eviction block, prompting the LLM to unify the old summary with the new evicted messages.
-
-## 10. Sub-Agent Orchestration Edge Cases (M13)
-
-- **The Sub-Agent Recursion Bomb:**
-  - _The Edge Case:_ A sub-agent uses the `spawn_agent` tool to spawn another sub-agent, creating an infinite nesting loop.
-  - _Mitigation:_ Hardcoded Depth-1 limit. Pre-configured sub-agents in `AgentRegistry` never include `spawn_agent` or `check_agent` in their allowed toolsets.
-- **Async Resource Contention:**
-  - _The Edge Case:_ The main agent loops over a directory and spawns 50 async `test_runner` agents concurrently.
-  - _Mitigation:_ `SubAgentManager` maintains a hard cap of 3 concurrent async tasks. Further spawn requests are queued or rejected with a backpressure error tool response.
-- **Stale Files in Sandbox:**
-  - _The Edge Case:_ The main agent edits a file on the host, then immediately spawns a `bash` sub-agent. The sub-agent runs in the sandbox before the new host file is synced.
-  - _Mitigation:_ The `SubAgentManager` shares the main harness's `FileSync` instance and always forces a `syncToSandbox()` pass _before_ the sub-agent takes its first step.
-
-## 11. Stability & Reliability Edge Cases (M14)
-
-- **Context Window Overflows (Instant Death):**
-  - _The Edge Case:_ Despite compaction thresholds, a single `read_file` returns 120k tokens string, instantly blowing past the 100% capacity mark. Compaction fails because the context is already overflowing.
-  - _Mitigation:_ `ContextGuard` has a 95% "Emergency Truncation" threshold. Before hitting the API, if tokens > 95%, it _bypasses_ LLM compaction and brutally slices all but the last 4 messages, inserting a loud warning message directly into the stream, guaranteeing survival.
-- **Process Death Serialization Tearing:**
-  - _The Edge Case:_ The `AutoSave` triggers at the exact millisecond the user presses `Ctrl+C`. The Node process terminates while `fs.writeFileSync` is mid-chunk, corrupting the JSONL session file irreversibly.
-  - _Mitigation:_ Atomic saves. `SessionStore.saveSession()` writes to an intermediate staging stream. On `process.on('SIGINT')`, a synchronous `forceSave()` is fired to cleanly flush state _before_ `process.exit(0)`.

package/docs/03_initial_implementation_plan.md

@@ -1,66 +0,0 @@
-# Initial Implementation Plan
-
-## Phase 1: Context Engine & Caching Layer
-
-Build a structured Prompt Builder that strictly enforces the Prefix Matching patterns so every task in a session enjoys a >90% cache hit rate.
-
-```mermaid
-graph TD
-    A[Base System Prompt] -->|Static Prefix| B
-    B[Tool Schemas] -->|Static Prefix| C
-    C[Project Memory e.g., README] -->|Project Prefix| D
-    D[Session Context e.g., OS Info] -->|Session Prefix| E
-    E[Conversation History] -->|Dynamic Appends| F[New User/Tool Message]
-
-    style A fill:#1e4620,stroke:#2b662e,color:#fff
-    style B fill:#1e4620,stroke:#2b662e,color:#fff
-    style C fill:#1e4620,stroke:#2b662e,color:#fff
-    style D fill:#2b465e,stroke:#3b6282,color:#fff
-    style E fill:#4a3219,stroke:#664422,color:#fff
-
-    subgraph Fully Cached Prefix
-    A
-    B
-    C
-    end
-```
-
-## Phase 2: Interoperable Tooling & Lazy Loading
-
-Implement tools as immutable objects for the session. Implement "Plan Mode" to alter agent rules without unloading tool schemas.
-
-- Define core tools: `read_file`, `write_file`, `bash_command`.
-- Implement dummy/stub tools for complex integrations.
-- Implement "Cache-Safe Forking" for compaction.
-
-## Phase 3: The Middleware Harness
-
-Implement pre-completion checks and loop detection via a middleware pipeline.
-
-```mermaid
-sequenceDiagram
-    participant Agent as LLM Agent
-    participant Harness as Execution Harness
-    participant Middle as Middleware Pipeline
-    participant Env as Environment (Bash/FS)
-
-    Agent->>Harness: Request: Edit target_file.py
-    Harness->>Middle: Emit: 'pre_tool_call'
-    Middle-->>Harness: Check LoopDetection (Fail if > 4 tries)
-    Harness->>Env: Execute Edit
-    Env-->>Harness: Return File Diff
-    Harness->>Agent: Send Tool Result
-
-    Agent->>Harness: Request: Submit/Exit
-    Harness->>Middle: Emit: 'pre_submit'
-    Middle->>Harness: Inject 'PreCompletionChecklist' (Wait, did you run tests?)
-    Harness->>Agent: System Reminder: "Please run tests to verify."
-    Agent->>Harness: Request: Run `pytest`
-```
-
-## Phase 4: Tracing & Feedback Loop
-
-Build an automated pipeline that sends JSON traces of failed agent runs into an evaluation database.
-
-- Hook LLM API calls to save traces.
-- Implement `TraceAnalyzer` subagent to review failures.