joonecli 0.1.1 → 0.2.0

package/src/core/promptBuilder.ts

@@ -1,139 +0,0 @@
-import {
-  BaseMessage,
-  SystemMessage,
-  HumanMessage,
-  AIMessage,
-} from "@langchain/core/messages";
-import { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { Runnable } from "@langchain/core/runnables";
-import { countMessageTokens } from "./tokenCounter.js";
-import { ConversationCompactor, CompactionResult } from "./compactor.js";
-
-export interface ContextState {
-  globalSystemInstructions: string;
-  projectMemory: string;
-  sessionContext: string;
-  conversationHistory: BaseMessage[];
-}
-
-/**
- * CacheOptimizedPromptBuilder
- *
- * Enforces strict prefix ordering to maximize Claude's Prompt Caching.
- *
- * Order of Prefix (Static to Dynamic):
- * 1. Base System Instructions + Tool Definitions (Globally Cached)
- * 2. Project Memory (e.g., CLAUDE.md) (Cached per project)
- * 3. Session State (Environment variables) (Cached per session)
- * 4. Conversation Messages (Grows iteratively)
- */
-export class CacheOptimizedPromptBuilder {
-  /**
-   * Compiles the full message array for the LLM request.
-   * The first messages are static, and subsequent ones are dynamic.
-   */
-  public buildPrompt(state: ContextState): BaseMessage[] {
-    // We use SystemMessages for the static prefix.
-    // In @langchain/anthropic, to use cache_control, we can inject it into the final message of each tier if needed,
-    // but preserving the exact order of the system prompts is the main requirement.
-
-    const unifiedContent = [
-      state.globalSystemInstructions,
-      `--- Project Context ---\n${state.projectMemory}`,
-      `--- Session Rules ---\n${state.sessionContext}`,
-    ].join("\n\n");
-
-    const systemMessages: BaseMessage[] = [
-      new SystemMessage({
-        content: unifiedContent,
-        name: "global_context",
-      }),
-    ];
-
-    // Combine the static prefix with the dynamic conversation history
-    return [...systemMessages, ...state.conversationHistory];
-  }
-
-  /**
-   * The System Reminder Pattern
-   * Instead of replacing the System Prompt (which breaks cache),
-   * use this to inject state updates into the Conversation History.
-   */
-  public injectSystemReminder(
-    history: BaseMessage[],
-    reminder: string,
-  ): BaseMessage[] {
-    const reminderMsg = new HumanMessage({
-      content: `<system-reminder>\n${reminder}\n</system-reminder>`,
-    });
-    return [...history, reminderMsg];
-  }
-
-  /**
-   * Cache-Safe Compaction (string-based fallback)
-   * When history gets too long, we preserve the last N messages (recent context)
-   * and replace older messages with a summary. The static system prefix is untouched.
-   *
-   * @param history - The full conversation history.
-   * @param summary - A text summary of the older messages.
-   * @param keepLastN - Number of recent messages to preserve (default: 6).
-   */
-  public compactHistory(
-    history: BaseMessage[],
-    summary: string,
-    keepLastN = 6,
-  ): BaseMessage[] {
-    if (history.length === 0) {
-      return history;
-    }
-
-    // Use HumanMessage formatted as a system update to avoid breaking Google's validation
-    // and maintaining proper user/assistant flow.
-    const compactedMessage = new HumanMessage(
-      `<system-update>\n[The previous conversation history has been compacted.]\nSummary:\n${summary}\n</system-update>`,
-    );
-
-    // Preserve recent messages for continuity
-    const recentMessages = history.slice(-keepLastN);
-
-    return [compactedMessage, ...recentMessages];
-  }
-
-  /**
-   * LLM-Powered Compaction with Handoff
-   * Uses a dedicated LLM call to generate a structured summary, then injects
-   * a handoff prompt to orient the agent. Falls back to string-based compaction
-   * if the LLM call fails.
-   *
-   * @param history - The full conversation history.
-   * @param llm - The LLM to use for summarization (should be a fast/cheap model).
-   * @param keepLastN - Number of recent messages to preserve (default: 8).
-   * @returns CompactionResult with the new history and metrics.
-   */
-  public async compactHistoryWithLLM(
-    history: BaseMessage[],
-    llm: Runnable | BaseChatModel,
-    keepLastN = 8,
-  ): Promise<CompactionResult> {
-    const compactor = new ConversationCompactor();
-    return compactor.compact(history, llm, { keepLastN });
-  }
-
-  /**
-   * Checks if the conversation should be compacted based on token usage.
-   *
-   * @param state - The current context state.
-   * @param maxTokens - The model's context window.
-   * @param threshold - Fraction of capacity to trigger (default: 0.8).
-   */
-  public shouldCompact(
-    state: ContextState,
-    maxTokens: number,
-    threshold = 0.8,
-  ): boolean {
-    const allMessages = this.buildPrompt(state);
-    const usage = countMessageTokens(allMessages);
-    return usage >= maxTokens * threshold;
-  }
-}
-

package/src/core/reasoningRouter.ts

@@ -1,121 +0,0 @@
-/**
- * Reasoning Sandwich — Dynamic Reasoning Router
- *
- * Adjusts the reasoning intensity per turn:
- * - HIGH: Planning, recovery after errors, final verification
- * - MEDIUM: Mechanical code writing, tool-heavy turns
- *
- * We adjust temperature only (not model variant) to preserve prompt cache prefix.
- * See docs/02_edge_cases_and_mitigations.md — "The Mid-Session Model Switch."
- */
-
-export enum ReasoningLevel {
-  HIGH = "high",
-  MEDIUM = "medium",
-}
-
-export interface ReasoningConfig {
-  /** Temperature for HIGH reasoning (default: 0). */
-  highTemp: number;
-  /** Temperature for MEDIUM reasoning (default: 0.2). */
-  mediumTemp: number;
-  /** Number of initial turns that always use HIGH reasoning (default: 2). */
-  planningTurns: number;
-}
-
-const DEFAULT_CONFIG: ReasoningConfig = {
-  highTemp: 0,
-  mediumTemp: 0.2,
-  planningTurns: 2,
-};
-
-/**
- * Tracks turn context and decides the reasoning level for each step.
- */
-export class ReasoningRouter {
-  private config: ReasoningConfig;
-  private turnCount = 0;
-  private lastTurnHadError = false;
-  private consecutiveToolTurns = 0;
-
-  constructor(config?: Partial<ReasoningConfig>) {
-    this.config = { ...DEFAULT_CONFIG, ...config };
-  }
-
-  /**
-   * Advances to the next turn and records the outcome of the previous one.
-   * Call exactly once per turn BEFORE querying the level for the new turn.
-   *
-   * @param hasToolCalls - Whether the previous response contained tool calls.
-   * @param hadError - Whether the previous turn resulted in an error.
-   */
-  advanceTurn(hasToolCalls = false, hadError = false): void {
-    this.turnCount++;
-    this.lastTurnHadError = hadError;
-
-    if (hadError) {
-      this.consecutiveToolTurns = 0;
-    } else if (hasToolCalls) {
-      this.consecutiveToolTurns++;
-    } else {
-      this.consecutiveToolTurns = 0;
-    }
-  }
-
-  /**
-   * Determines the reasoning level for the current turn based on state.
-   *
-   * @returns The recommended reasoning level.
-   */
-  getLevel(): ReasoningLevel {
-    // First N turns → always HIGH (planning phase)
-    if (this.turnCount <= this.config.planningTurns) {
-      return ReasoningLevel.HIGH;
-    }
-
-    // Post-error → HIGH (recovery)
-    if (this.lastTurnHadError) {
-      return ReasoningLevel.HIGH;
-    }
-
-    // Tool-heavy turn → MEDIUM (mechanical work)
-    if (this.consecutiveToolTurns > 0) {
-      return ReasoningLevel.MEDIUM;
-    }
-
-    // No tool calls previously (agent is thinking/planning) → HIGH
-    return ReasoningLevel.HIGH;
-  }
-
-  /**
-   * Returns the temperature setting for a given reasoning level.
-   */
-  getTemperature(level: ReasoningLevel): number {
-    return level === ReasoningLevel.HIGH
-      ? this.config.highTemp
-      : this.config.mediumTemp;
-  }
-
-  /**
-   * Convenience: get the recommended temperature for the current turn.
-   */
-  getRecommendedTemperature(): number {
-    return this.getTemperature(this.getLevel());
-  }
-
-  /**
-   * Returns the current turn count.
-   */
-  getTurnCount(): number {
-    return this.turnCount;
-  }
-
-  /**
-   * Resets state. For testing or new sessions.
-   */
-  reset(): void {
-    this.turnCount = 0;
-    this.lastTurnHadError = false;
-    this.consecutiveToolTurns = 0;
-  }
-}

package/src/core/retry.ts

@@ -1,75 +0,0 @@
-import { JooneError } from "./errors.js";
-
-export interface RetryOptions {
-    /** Maximum number of retry attempts. Default: 3. */
-    maxRetries?: number;
-    /** Initial delay in milliseconds before the first retry. Default: 1000. */
-    initialDelayMs?: number;
-    /** Maximum jitter in milliseconds added/subtracted from each delay. Default: 500. */
-    maxJitterMs?: number;
-    /** Optional callback invoked before each retry. */
-    onRetry?: (attempt: number, error: JooneError, delayMs: number) => void;
-}
-
-/**
- * Executes an async function with exponential backoff retry logic.
- *
- * - Retries only if the caught error is a `JooneError` with `retryable === true`.
- * - Non-retryable errors are re-thrown immediately.
- * - Raw (non-JooneError) errors are re-thrown immediately.
- * - Delays double with each attempt: 1s → 2s → 4s (+ random jitter).
- *
- * @param fn - The async function to execute.
- * @param opts - Retry configuration.
- * @returns The result of `fn` on success.
- * @throws The last error encountered after all retries are exhausted, or any non-retryable error.
- */
-export async function retryWithBackoff<T>(
-    fn: () => Promise<T>,
-    opts: RetryOptions = {}
-): Promise<T> {
-    const {
-        maxRetries = 3,
-        initialDelayMs = 1000,
-        maxJitterMs = 500,
-        onRetry,
-    } = opts;
-
-    let lastError: JooneError | undefined;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            return await fn();
-        } catch (error: unknown) {
-            // Only retry JooneErrors that are explicitly marked retryable
-            if (error instanceof JooneError && error.retryable) {
-                lastError = error;
-
-                if (attempt < maxRetries) {
-                    const baseDelay = initialDelayMs * Math.pow(2, attempt);
-                    const jitter = Math.floor(Math.random() * maxJitterMs * 2) - maxJitterMs;
-                    const delay = Math.max(0, baseDelay + jitter);
-
-                    if (onRetry) {
-                        onRetry(attempt + 1, error, delay);
-                    }
-
-                    await sleep(delay);
-                    continue;
-                }
-            }
-
-            // Non-retryable or non-JooneError: propagate immediately
-            if (!(error instanceof JooneError) || !error.retryable) {
-                throw error;
-            }
-        }
-    }
-
-    // All retries exhausted
-    throw lastError!;
-}
-
-function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/core/sessionResumer.ts

@@ -1,90 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { ContextState } from "./promptBuilder.js";
-import { SessionStatePayload } from "./sessionStore.js";
-import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
-
-export class SessionResumer {
-    private workspaceDir: string;
-
-    constructor(workspaceDir: string) {
-        this.workspaceDir = workspaceDir;
-    }
-
-    /**
-     * Prepares a loaded session state for execution by detecting external drift
-     * and injecting the Wakeup prompt so the LLM knows it is inside a fresh sandbox.
-     */
-    public prepareForResume(payload: SessionStatePayload): ContextState {
-        const state = { ...payload.state };
-
-        // 1. Detect File Drift
-        const driftedFiles = this.detectFileDrift(state, payload.header.lastSavedAt);
-
-        // 2. Formulate the Sandbox Amnesia & Drift Wakeup prompt
-        let wakeupPrompt = `[SYSTEM NOTIFICATION: SESSION RESUMED]\n`;
-        wakeupPrompt += `You were paused and have just been loaded into a **NEW** execution session. \n`;
-        wakeupPrompt += `IMPORTANT CONTEXT:\n`;
-        wakeupPrompt += `- The execution Sandbox is completely fresh. Any background processes, dev servers, or in-memory databases you were running previously are GONE. You must restart them if needed.\n`;
-        
-        if (driftedFiles.length > 0) {
-            wakeupPrompt += `- The following files were mutated externally on the host machine while you were offline:\n`;
-            for (const file of driftedFiles) {
-                wakeupPrompt += `  - \`${file}\`\n`;
-            }
-            wakeupPrompt += `Before modifying these files using replace_file_content, you MUST re-read them using view_code_item or view_file to understand the external changes.\n`;
-        } else {
-            wakeupPrompt += `- No files in your active context appear to have been edited on the host while you were paused.\n`;
-        }
-
-        // Inject as a Human Message at the very end of the history
-        // so it acts as an immediate reminder before the next LLM generation.
-        state.conversationHistory.push(new HumanMessage(`<system-wakeup>\n${wakeupPrompt}\n</system-wakeup>`));
-
-        return state;
-    }
-
-    /**
-     * Analyzes the conversation history for any files the agent has interacted with.
-     * Checks their `mtime` against the session `lastSavedAt`.
-     * If the file on disk is newer, it has drifted.
-     */
-    public detectFileDrift(state: ContextState, lastSavedAt: number): string[] {
-        const interactedFiles = new Set<string>();
-
-        // We deduce file interaction by looking at what tools were called
-        for (const msg of state.conversationHistory) {
-            if (msg instanceof AIMessage && msg.tool_calls) {
-                for (const call of msg.tool_calls) {
-                    if (call.name === "read_file" || call.name === "write_file" || call.name === "replace_file_content" || call.name === "multi_replace_file_content" || call.name === "view_file") {
-                        let targetPath = "";
-                        if (call.args.path) targetPath = call.args.path;
-                        if (call.args.AbsolutePath) targetPath = call.args.AbsolutePath;
-                        if (call.args.TargetFile) targetPath = call.args.TargetFile;
-
-                        if (targetPath) {
-                            interactedFiles.add(targetPath);
-                        }
-                    }
-                }
-            }
-        }
-
-        const drifted: string[] = [];
-
-        for (const file of interactedFiles) {
-            // Because paths might be absolute or relative, attempt resolution
-            const absolutePath = path.isAbsolute(file) ? file : path.resolve(this.workspaceDir, file);
-            
-            if (fs.existsSync(absolutePath)) {
-                const stats = fs.statSync(absolutePath);
-                // If the file's modification time is STRICTLY greater than the save time, it drifted
-                if (stats.mtimeMs > lastSavedAt) {
-                    drifted.push(file);
-                }
-            }
-        }
-
-        return drifted;
-    }
-}

package/src/core/sessionStore.ts

@@ -1,216 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import * as readline from "node:readline";
-import { 
-    BaseMessage, 
-    HumanMessage, 
-    AIMessage, 
-    SystemMessage, 
-    ToolMessage 
-} from "@langchain/core/messages";
-import { ContextState } from "./promptBuilder.js";
-
-// Ensure the sessions directory exists
-const SESSIONS_DIR = path.join(os.homedir(), ".joone", "sessions");
-
-export interface SessionHeader {
-    sessionId: string;
-    startedAt: number;
-    lastSavedAt: number;
-    provider: string;
-    model: string;
-    description: string;
-}
-
-export interface SessionStatePayload {
-    header: SessionHeader;
-    state: ContextState;
-}
-
-/**
- * Serializes and deserializes agent conversation history to streaming JSONL files.
- */
-export class SessionStore {
-    constructor() {
-        if (!fs.existsSync(SESSIONS_DIR)) {
-            fs.mkdirSync(SESSIONS_DIR, { recursive: true, mode: 0o700 });
-        }
-    }
-
-    /**
-     * Serializes a LangChain BaseMessage instance into a raw JSON object.
-     */
-    private serializeMessage(msg: BaseMessage): any {
-        const base = {
-            type: msg._getType(),
-            content: msg.content,
-        };
-
-        if (msg instanceof AIMessage && msg.tool_calls && msg.tool_calls.length > 0) {
-            (base as any).tool_calls = msg.tool_calls;
-        }
-
-        if (msg instanceof ToolMessage) {
-            (base as any).tool_call_id = msg.tool_call_id;
-        }
-
-        return base;
-    }
-
-    /**
-     * Rehydrates a raw JSON object back into a LangChain BaseMessage class instance.
-     */
-    private deserializeMessage(raw: any): BaseMessage {
-        switch (raw.type) {
-            case "human":
-                return new HumanMessage(raw.content);
-            case "ai":
-                return new AIMessage({
-                    content: raw.content,
-                    tool_calls: raw.tool_calls || undefined,
-                });
-            case "system":
-                // Remap old saved SystemMessages to HumanMessages to prevent provider index errors
-                return new HumanMessage(`<system-reminder>\n${raw.content}\n</system-reminder>`);
-            case "tool":
-                return new ToolMessage({
-                    content: raw.content,
-                    tool_call_id: raw.tool_call_id,
-                });
-            default:
-                throw new Error(`Unknown message type in session history: ${raw.type}`);
-        }
-    }
-
-    /**
-     * Saves the entire session state cleanly to a .jsonl file, overwriting the previous save.
-     * We don't append to avoid partial mid-turn corruption. Since we compact the context,
-     * the file size remains extremely small.
-     */
-    public async saveSession(
-        sessionId: string, 
-        state: ContextState, 
-        provider: string, 
-        model: string
-    ): Promise<void> {
-        const filePath = path.join(SESSIONS_DIR, `${sessionId}.jsonl`);
-        
-        let description = "Empty session";
-        if (state.conversationHistory.length > 0) {
-            const firstMsg = state.conversationHistory.find(m => m instanceof HumanMessage);
-            if (firstMsg && typeof firstMsg.content === "string") {
-                description = firstMsg.content.substring(0, 100).replace(/\n/g, " ") + "...";
-            }
-        }
-
-        const header: SessionHeader = {
-            sessionId,
-            startedAt: fs.existsSync(filePath) ? (await this.loadHeader(sessionId))?.startedAt || Date.now() : Date.now(),
-            lastSavedAt: Date.now(),
-            provider,
-            model,
-            description,
-        };
-
-        const writeStream = fs.createWriteStream(filePath, { encoding: "utf8" });
-
-        // Line 1: Header + System State
-        const payload = {
-            header,
-            globalSystemInstructions: state.globalSystemInstructions,
-            projectMemory: state.projectMemory,
-            sessionContext: state.sessionContext,
-        };
-        writeStream.write(JSON.stringify({ __type: "header", ...payload }) + "\n");
-
-        // Line 2+: conversationHistory messages
-        for (const msg of state.conversationHistory) {
-            writeStream.write(JSON.stringify(this.serializeMessage(msg)) + "\n");
-        }
-
-        await new Promise((resolve) => writeStream.end(resolve));
-    }
-
-    /**
-     * Loads the session state from disk.
-     */
-    public async loadSession(sessionId: string): Promise<SessionStatePayload> {
-        const filePath = path.join(SESSIONS_DIR, `${sessionId}.jsonl`);
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Session not found: ${sessionId}`);
-        }
-
-        const readStream = fs.createReadStream(filePath, { encoding: "utf8" });
-        const rl = readline.createInterface({ input: readStream, crlfDelay: Infinity });
-
-        let headerData: any = null;
-        const conversationHistory: BaseMessage[] = [];
-
-        for await (const line of rl) {
-            if (!line.trim()) continue;
-            const parsed = JSON.parse(line);
-
-            if (parsed.__type === "header") {
-                headerData = parsed;
-            } else {
-                conversationHistory.push(this.deserializeMessage(parsed));
-            }
-        }
-
-        if (!headerData) {
-            throw new Error(`Malformed session file: Missing header block in ${sessionId}.jsonl`);
-        }
-
-        return {
-            header: headerData.header,
-            state: {
-                globalSystemInstructions: headerData.globalSystemInstructions,
-                projectMemory: headerData.projectMemory,
-                sessionContext: headerData.sessionContext,
-                conversationHistory,
-            }
-        };
-    }
-
-    /**
-     * Only reads the first line of the given session file to quickly extract the header.
-     */
-    private async loadHeader(sessionId: string): Promise<SessionHeader | null> {
-        const filePath = path.join(SESSIONS_DIR, `${sessionId}.jsonl`);
-        if (!fs.existsSync(filePath)) return null;
-
-        const readStream = fs.createReadStream(filePath, { encoding: "utf8" });
-        const rl = readline.createInterface({ input: readStream, crlfDelay: Infinity });
-
-        for await (const line of rl) {
-            if (!line.trim()) continue;
-            const parsed = JSON.parse(line);
-            if (parsed.__type === "header") {
-                readStream.close();
-                return parsed.header as SessionHeader;
-            }
-        }
-        return null;
-    }
-
-    /**
-     * Lists all saved sessions, sorted by most recently saved.
-     */
-    public async listSessions(): Promise<SessionHeader[]> {
-        if (!fs.existsSync(SESSIONS_DIR)) return [];
-
-        const files = fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith(".jsonl"));
-        const sessions: SessionHeader[] = [];
-
-        for (const file of files) {
-            const sessionId = file.replace(".jsonl", "");
-            const header = await this.loadHeader(sessionId);
-            if (header) {
-                sessions.push(header);
-            }
-        }
-
-        return sessions.sort((a, b) => b.lastSavedAt - a.lastSavedAt);
-    }
-}