joonecli 0.1.0

package/dist/ui/components/MessageBubble.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+type MessageRole = "user" | "agent" | "system";
+interface MessageBubbleProps {
+    role: MessageRole;
+    content: string;
+}
+/**
+ * Renders a single conversation message with role-based styling.
+ * - User messages: cyan accent, labeled "you"
+ * - Agent messages: green accent, labeled "joone"
+ * - System messages: centered, dim yellow
+ */ export declare const MessageBubble: React.FC<MessageBubbleProps>;
+export {};

package/dist/ui/components/MessageBubble.js

@@ -0,0 +1,17 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+/**
+ * Renders a single conversation message with role-based styling.
+ * - User messages: cyan accent, labeled "you"
+ * - Agent messages: green accent, labeled "joone"
+ * - System messages: centered, dim yellow
+ */ export const MessageBubble = ({ role, content, }) => {
+    if (role === "system") {
+        return (_jsx(Box, { paddingX: 1, justifyContent: "center", children: _jsxs(Text, { dimColor: true, italic: true, color: "yellow", children: ["\u2699 ", content] }) }));
+    }
+    const isUser = role === "user";
+    const accentColor = isUser ? "cyan" : "green";
+    const label = isUser ? "you" : "joone";
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { bold: true, color: accentColor, children: label }), _jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "white", wrap: "wrap", children: content }) })] }));
+};
+//# sourceMappingURL=MessageBubble.js.map

package/dist/ui/components/MessageBubble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MessageBubble.js","sourceRoot":"","sources":["../../../src/ui/components/MessageBubble.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAShC;;;;;GAKG,CAAC,MAAM,CAAC,MAAM,aAAa,GAAiC,CAAC,EAC9D,IAAI,EACJ,OAAO,GACR,EAAE,EAAE;IACH,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,CACL,KAAC,GAAG,IAAC,QAAQ,EAAE,CAAC,EAAE,cAAc,EAAC,QAAQ,YACvC,MAAC,IAAI,IAAC,QAAQ,QAAC,MAAM,QAAC,KAAK,EAAC,QAAQ,wBAC/B,OAAO,IACL,GACH,CACP,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,KAAK,MAAM,CAAC;IAC/B,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;IAEvC,OAAO,CACL,MAAC,GAAG,IAAC,aAAa,EAAC,QAAQ,EAAC,QAAQ,EAAE,CAAC,aACrC,KAAC,IAAI,IAAC,IAAI,QAAC,KAAK,EAAE,WAAW,YAC1B,KAAK,GACD,EACP,KAAC,GAAG,IAAC,UAAU,EAAE,CAAC,YAChB,KAAC,IAAI,IAAC,KAAK,EAAC,OAAO,EAAC,IAAI,EAAC,MAAM,YAC5B,OAAO,GACH,GACH,IACF,CACP,CAAC;AACJ,CAAC,CAAC"}

package/dist/ui/components/StatusBar.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+interface StatusBarProps {
+    /** Current tokens used in the context window (estimated). */
+    contextTokens?: number;
+    /** Maximum context window size for the model. */
+    maxContextTokens?: number;
+    /** Total tokens consumed across all LLM calls (prompt + completion). */
+    totalTokens?: number;
+    /** Cache hit rate (0–1). */
+    cacheHitRate?: number;
+    /** Elapsed session time. */
+    elapsed?: string;
+    /** Total tool calls executed. */
+    toolCalls?: number;
+    /** Number of LLM turns. */
+    turns?: number;
+    /** Estimated cost in USD. */
+    cost?: number;
+}
+export declare const StatusBar: React.FC<StatusBarProps>;
+export {};

package/dist/ui/components/StatusBar.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+/**
+ * Renders a visual capacity bar for the context window.
+ *
+ * Example: ▓▓▓▓▓▓▓▓░░░░░░░  52%
+ */
+function ContextBar({ used, max, width = 16, }) {
+    const ratio = max > 0 ? Math.min(used / max, 1) : 0;
+    const filled = Math.round(ratio * width);
+    const empty = width - filled;
+    const pct = Math.round(ratio * 100);
+    // Color: green < 60%, yellow 60-80%, red > 80%
+    const barColor = ratio < 0.6 ? "green" : ratio < 0.8 ? "yellow" : "red";
+    return (_jsxs(Text, { children: [_jsx(Text, { color: barColor, children: "▓".repeat(filled) }), _jsx(Text, { dimColor: true, children: "░".repeat(empty) }), _jsx(Text, { children: " " }), _jsxs(Text, { color: barColor, children: [pct, "%"] })] }));
+}
+/**
+ * Formats a token count for display (e.g., 3241 → "3.2K", 128000 → "128K").
+ */
+function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return `${n}`;
+}
+export const StatusBar = ({ contextTokens = 0, maxContextTokens = 200_000, totalTokens = 0, cacheHitRate, elapsed = "0s", toolCalls = 0, turns = 0, cost, }) => {
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "ctx " }), _jsx(ContextBar, { used: contextTokens, max: maxContextTokens }), _jsxs(Text, { dimColor: true, children: [" ", formatTokens(contextTokens), "/", formatTokens(maxContextTokens)] })] }), cacheHitRate !== undefined && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cache " }), _jsxs(Text, { color: cacheHitRate > 0.8
+                                    ? "green"
+                                    : cacheHitRate > 0.5
+                                        ? "yellow"
+                                        : "red", children: [(cacheHitRate * 100).toFixed(0), "%"] })] }))] }), _jsxs(Box, { justifyContent: "space-between", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "tokens " }), _jsx(Text, { color: "white", children: formatTokens(totalTokens) })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "turns " }), _jsx(Text, { color: "white", children: turns })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "tools " }), _jsx(Text, { color: "white", children: toolCalls })] }), cost !== undefined && cost > 0 && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cost " }), _jsxs(Text, { color: "white", children: ["$", cost < 0.01 ? cost.toFixed(4) : cost.toFixed(2)] })] })), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "elapsed " }), _jsx(Text, { color: "white", children: elapsed })] })] })] }));
+};
+//# sourceMappingURL=StatusBar.js.map

package/dist/ui/components/StatusBar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatusBar.js","sourceRoot":"","sources":["../../../src/ui/components/StatusBar.tsx"],"names":[],"mappings":"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"}

package/dist/ui/components/StreamingText.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+interface StreamingTextProps {
+    /** Array of tokens that have been received so far. */
+    tokens: string[];
+    /** Whether the stream is still active. */
+    isStreaming: boolean;
+}
+/**
+ * StreamingText renders incoming tokens with a blinking cursor
+ * while the stream is active. Once streaming stops, the cursor disappears.
+ */
+export declare const StreamingText: React.FC<StreamingTextProps>;
+export {};

package/dist/ui/components/StreamingText.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from "react";
+import { Text } from "ink";
+/**
+ * StreamingText renders incoming tokens with a blinking cursor
+ * while the stream is active. Once streaming stops, the cursor disappears.
+ */
+export const StreamingText = ({ tokens, isStreaming, }) => {
+    const [cursorVisible, setCursorVisible] = useState(true);
+    useEffect(() => {
+        if (!isStreaming) {
+            setCursorVisible(false);
+            return;
+        }
+        setCursorVisible(true);
+        const interval = setInterval(() => {
+            setCursorVisible((v) => !v);
+        }, 500);
+        return () => clearInterval(interval);
+    }, [isStreaming]);
+    const fullText = tokens.join("");
+    return (_jsxs(Text, { children: [_jsx(Text, { color: "white", children: fullText }), isStreaming && (_jsx(Text, { color: "cyan", bold: true, children: cursorVisible ? "▊" : " " }))] }));
+};
+//# sourceMappingURL=StreamingText.js.map

package/dist/ui/components/StreamingText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingText.js","sourceRoot":"","sources":["../../../src/ui/components/StreamingText.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAS3B;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiC,CAAC,EAC1D,MAAM,EACN,WAAW,GACZ,EAAE,EAAE;IACH,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEzD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACxB,OAAO;QACT,CAAC;QAED,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAEvB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAChC,gBAAgB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC,EAAE,GAAG,CAAC,CAAC;QAER,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEjC,OAAO,CACL,MAAC,IAAI,eACH,KAAC,IAAI,IAAC,KAAK,EAAC,OAAO,YAAE,QAAQ,GAAQ,EACpC,WAAW,IAAI,CACd,KAAC,IAAI,IAAC,KAAK,EAAC,MAAM,EAAC,IAAI,kBACpB,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GACrB,CACR,IACI,CACR,CAAC;AACJ,CAAC,CAAC"}

package/dist/ui/components/ToolCallPanel.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+export type ToolCallStatus = "running" | "success" | "error";
+interface ToolCallPanelProps {
+    toolName: string;
+    args?: Record<string, unknown>;
+    status: ToolCallStatus;
+    result?: string;
+}
+/**
+ * Styled panel that appears when the agent invokes a tool.
+ * Shows the tool name, arguments, a spinner while executing,
+ * and the result once complete.
+ */
+export declare const ToolCallPanel: React.FC<ToolCallPanelProps>;
+export {};

package/dist/ui/components/ToolCallPanel.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import Spinner from "ink-spinner";
+/**
+ * Styled panel that appears when the agent invokes a tool.
+ * Shows the tool name, arguments, a spinner while executing,
+ * and the result once complete.
+ */
+export const ToolCallPanel = ({ toolName, args, status, result, }) => {
+    const borderColor = status === "running" ? "yellow" : status === "success" ? "green" : "red";
+    const statusIcon = status === "running" ? (_jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) })) : status === "success" ? (_jsx(Text, { color: "green", children: "\u2713" })) : (_jsx(Text, { color: "red", children: "\u2717" }));
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: borderColor, paddingX: 1, marginY: 0, children: [_jsxs(Box, { gap: 1, children: [statusIcon, _jsx(Text, { bold: true, color: borderColor, children: toolName })] }), args && Object.keys(args).length > 0 && (_jsx(Box, { marginLeft: 2, flexDirection: "column", children: Object.entries(args).map(([key, value]) => (_jsxs(Text, { children: [_jsxs(Text, { dimColor: true, children: [key, ":"] }), " ", _jsx(Text, { color: "white", children: typeof value === "string"
+                                ? value.length > 80
+                                    ? value.slice(0, 77) + "..."
+                                    : value
+                                : JSON.stringify(value) })] }, key))) })), result && (_jsx(Box, { marginTop: 0, marginLeft: 2, children: _jsx(Text, { dimColor: true, children: result.length > 120 ? result.slice(0, 117) + "..." : result }) }))] }));
+};
+//# sourceMappingURL=ToolCallPanel.js.map

package/dist/ui/components/ToolCallPanel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolCallPanel.js","sourceRoot":"","sources":["../../../src/ui/components/ToolCallPanel.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,OAAO,MAAM,aAAa,CAAC;AAWlC;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiC,CAAC,EAC1D,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,MAAM,GACP,EAAE,EAAE;IACH,MAAM,WAAW,GACf,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC;IAE3E,MAAM,UAAU,GACd,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CACrB,KAAC,IAAI,IAAC,KAAK,EAAC,QAAQ,YAClB,KAAC,OAAO,IAAC,IAAI,EAAC,MAAM,GAAG,GAClB,CACR,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CACzB,KAAC,IAAI,IAAC,KAAK,EAAC,OAAO,uBAAS,CAC7B,CAAC,CAAC,CAAC,CACF,KAAC,IAAI,IAAC,KAAK,EAAC,KAAK,uBAAS,CAC3B,CAAC;IAEJ,OAAO,CACL,MAAC,GAAG,IACF,aAAa,EAAC,QAAQ,EACtB,WAAW,EAAC,OAAO,EACnB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,CAAC,aAEV,MAAC,GAAG,IAAC,GAAG,EAAE,CAAC,aACR,UAAU,EACX,KAAC,IAAI,IAAC,IAAI,QAAC,KAAK,EAAE,WAAW,YAC1B,QAAQ,GACJ,IACH,EAEL,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,CACvC,KAAC,GAAG,IAAC,UAAU,EAAE,CAAC,EAAE,aAAa,EAAC,QAAQ,YACvC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAC1C,MAAC,IAAI,eACH,MAAC,IAAI,IAAC,QAAQ,mBAAE,GAAG,SAAS,EAAC,GAAG,EAChC,KAAC,IAAI,IAAC,KAAK,EAAC,OAAO,YAChB,OAAO,KAAK,KAAK,QAAQ;gCACxB,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE;oCACjB,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK;oCAC5B,CAAC,CAAC,KAAK;gCACT,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GACpB,KARE,GAAG,CASP,CACR,CAAC,GACE,CACP,EAEA,MAAM,IAAI,CACT,KAAC,GAAG,IAAC,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,YAC9B,KAAC,IAAI,IAAC,QAAQ,kBACX,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,GACvD,GACH,CACP,IACG,CACP,CAAC;AACJ,CAAC,CAAC"}

package/docs/01_insights_and_patterns.md

@@ -0,0 +1,27 @@
+# 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

@@ -0,0 +1,143 @@
+# 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

@@ -0,0 +1,66 @@
+# 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.

package/docs/04_tech_stack_proposal.md

@@ -0,0 +1,20 @@
+# Tech Stack
+
+The technology stack has been finalized. We are moving forward with a combination of the strong typing of TypeScript and the robust AI orchestration ecosystem of LangChain.
+
+## The Final Stack
+
+- **Language:** TypeScript (Node.js)
+  - Provides end-to-end type safety, especially crucial for tool schemas (Zod) and avoiding runtime errors in the execution loop.
+- **Orchestration / LLM Framework:** LangChain.js / LangGraph.js
+  - Using the TypeScript SDK for LangChain allows us to build complex, cyclical agent workflows (like Middlewares and self-correction loops) via LangGraph.
+- **Typing / Tool Schemas:** Zod
+  - Seamless integration with LangChain for structural output parsing and strict tool definition.
+- **Tracing:** LangSmith
+  - First-party integration with LangChain, providing deep visibility into token usage, prompt construction, and latency. Essential for debugging cache hit rates.
+- **CLI Framework (Optional):** Commander.js / Ink
+  - To be used if we build a robust terminal interface for the agent.
+
+## Why this combination?
+
+This marries the best of both originally proposed worlds. It gives us the frontend/backend interoperability and strict compile-time checks of TypeScript, while retaining the mature, graph-based agent orchestration and high-fidelity trace analysis typically dominated by Python's LangChain ecosystem.

package/docs/05_prd.md

@@ -0,0 +1,87 @@
+# Product Requirements Document (PRD)
+
+## 1. Product Overview
+
+**Joone** is a CLI-based autonomous coding agent that leverages **Prompt Caching** and **Harness Engineering** to achieve high autonomy and robustness in complex coding tasks while minimizing token cost and latency. It executes all generated code inside **E2B sandboxed microVMs**, isolating the host machine from any destructive operations.
+
+## 2. Target Audience
+
+- Software Engineers looking for an autonomous pair-programmer.
+- DevOps engineers looking to automate script fixes and verifications.
+- AI Researchers running benchmarks (e.g., Terminal Bench 2.0).
+
+## 3. Core Features
+
+### 3.1. CLI Interface & Provider Selection
+
+- **Installable CLI**: Packaged as an npm global binary (`npx joone` or `npm i -g joone`).
+- **Provider/Model Selection**: On first run (or via `joone config`), the user interactively selects their LLM provider and model. Stored at `~/.joone/config.json`.
+- **Supported Providers**: Anthropic, OpenAI, Google, Mistral, Groq, DeepSeek, Fireworks, Together AI, Ollama (local).
+- **Dynamic Provider Loading**: Provider packages are loaded on demand. If a package isn't installed, the CLI prints a helpful install command.
+- **Streaming Output**: Token-by-token streaming enabled by default for all providers. Tool calls are buffered until complete before execution.
+
+### 3.2. API Key Security (Tiered)
+
+- **Tier 1 (Default)**: API keys stored in `~/.joone/config.json` with restrictive file permissions (`chmod 600`). Masked input during `joone config`.
+- **Tier 2 (Planned)**: OS Keychain integration (Windows Credential Manager / macOS Keychain) via `keytar`.
+- **Tier 3 (Planned)**: AES-256 encrypted config file with machine-derived key.
+- During onboarding, the user will eventually be able to choose their preferred security tier.
+
+### 3.3. Cache-Optimized Context Engine
+
+- **Strict Prefix Ordering**: Separates static system instructions, tool definitions, project memory, and conversation history to align with LLM `cache_control` behaviors.
+- **`<system-reminder>` Injection**: Updates agent state natively via standard messages rather than system prompt overwrites, preserving the cache.
+- **Cache-Safe Compaction**: Forks and summarizes contexts seamlessly without full cache eviction.
+
+### 3.4. Hybrid Sandbox Execution
+
+- **Architecture**: The agent uses a **Hybrid** model — file operations (`write_file`, `read_file`) run on the **host machine** so the user sees changes live in their IDE, while all **code execution** (`bash`, tests, scripts) runs inside an [E2B](https://e2b.dev) cloud microVM sandbox.
+- **File Sync Mechanism**: Before each sandbox execution, changed files are synced from host → sandbox.
+  - _Tracking:_ Modifications are tracked via a "dirty paths" memory array. The `write_file` host tool explicitly marks paths as dirty upon successful write.
+  - _Concurrency:_ Concurrent modifications are prevented by the `ExecutionHarness`, which executes agent tool calls sequentially and blocks the LLM loop until file I/O and sandbox syncs are fully complete.
+  - _Conflict Resolution:_ The Host machine is the absolute source of truth. The sandbox filesystem is ephemeral and overwritten by the Host's dirty files before any command runs. Modifications made manually in the sandbox bypass the host and are lost upon destroy.
+- **Security**: The host machine is never exposed to agent-executed commands. Only file read/write touches the host.
+
+### 3.5. Middleware Harness
+
+- **Loop Detection (Anti-Doom Loop)**: Tracks agent action duplication and injects corrective context to break the loop.
+- **Pre-Completion Checklist**: Intercepts task submission to force a self-verification/testing phase.
+- **Guardrails for Scale**: Prevents loading oversized files (>1MB) entirely into memory; enforces chunked reads.
+
+### 3.6. Lazy & Interoperable Tooling
+
+- **Immutable Tool Definition**: Prevents mid-session tool swapping to preserve cache.
+- **Tool Search**: Implements "stub" tools, allowing dynamic loading of complex tools only when actively requested.
+
+### 3.7. Trace Analytics (V2)
+
+- Logs reasoning loops and tool execution traces to analyze points of failure.
+- Trace analyzer sub-agent that periodically reviews failures to suggest harness improvements.
+
+## 4. Non-Functional Requirements
+
+- **Latency:** High cache hit rates (>80% for long sessions) leading to sub-second Time-To-First-Token.
+- **Cost:** Minimize redundant prefix token generation.
+- **Extensibility:** Middleware pipeline should make it trivial to add new guardrails.
+- **Development Process:** Strict Red-Green-Refactor TDD for all new features.
+
+### 4.1 Error Handling & Degraded Modes
+
+- **Sandbox Failures:** The `SandboxManager` is architected with an `ISandboxWrapper` interface. If the primary cloud **E2B** sandbox fails to initialize (e.g., due to network drops, API outages, or invalid keys), the manager will automatically print a warning and gracefully degrade to a local **OpenSandbox** deployment (`localhost:8080`) to ensure execution continuity.
+- **LLM Failures (Planned):** If the remote LLM provider API goes down, the Model Factory should seamlessly fallback to a local Ollama instance if available.
+
+### 4.2 Rate Limiting & Cost Controls (Planned)
+
+- **Session Budgets:** Users can configure a maximum token budget (e.g., $5.00) per session. The `ExecutionHarness` tracks usage via the `SessionTracer` and will forcefully halt the agent if the threshold is reached.
+- **Loop Circuit Breakers:** The `LoopDetectionMiddleware` acts as a behavioral rate limit, preventing the agent from infinitely burning tokens on failed bash commands.
+
+### 4.3 Sandbox Authentication Management
+
+- **E2B:** Authentication is managed via the `E2B_API_KEY` environment variable or securely stored in `~/.joone/config.json`.
+- **OpenSandbox (Fallback):** Handled via `OPENSANDBOX_API_KEY` and `OPENSANDBOX_DOMAIN` properties in the config, falling back to a local Docker `localhost:8080` endpoint.
+
+### 4.4 Telemetry, Privacy & Data Retention
+
+- **Local-First Tracing:** All session reasoning and tool execution traces are logged to `~/.joone/traces/` as local JSON files for offline analysis using `TraceAnalyzer`.
+- **Data Retention:** Local traces are automatically rotated/deleted after 30 days to prevent infinite disk bloat.
+- **Privacy:** Project source code is _never_ sent to third-party telemetry providers unless the user intentionally enables the optional `LANGSMITH_API_KEY` for advanced dashboard debugging.