joonecli 0.1.1 → 0.2.0

package/src/core/compactor.ts

@@ -1,252 +0,0 @@
-/**
- * Conversation Compactor
- *
- * Replaces the simple string-based compaction with an LLM-powered summary.
- * Uses a dedicated compact prompt to produce a high-quality structured summary,
- * then injects a handoff prompt to orient the agent after compaction.
- *
- * Architecture:
- * 1. Evicted messages (all except keepLastN) are sent to a dedicated LLM call
- * 2. The LLM produces a structured markdown summary preserving critical context
- * 3. A handoff prompt is injected after the summary to guide the agent
- * 4. Falls back to string-based compaction if the LLM call fails
- */
-
-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, estimateTokens } from "./tokenCounter.js";
-
-// ─── Compact Prompt ─────────────────────────────────────────────────────────────
-
-export const COMPACT_SYSTEM_PROMPT = `You are a conversation summarizer. Your task is to produce a structured reference document from the conversation below.
-
-PRESERVE ALL of the following (do NOT omit):
-- File paths created, edited, or deleted
-- Tool calls made and their outcomes (success or failure)
-- Key decisions made and the rationale behind them
-- Current task state — what has been completed and what remains
-- Errors encountered and how they were resolved
-- Code snippets or configurations that are critical to the ongoing task
-
-FORMAT as structured markdown with clear sections:
-## Files Modified
-## Decisions Made
-## Current State
-## Errors & Resolutions
-
-Be thorough but concise. Do NOT include conversational filler or pleasantries.`;
-
-// ─── Handoff Prompt ─────────────────────────────────────────────────────────────
-
-export function createHandoffPrompt(compactionTimestamp: string): string {
-  return `[CONTEXT HANDOFF] Your earlier conversation has been compacted into the summary above.
-You are the same agent continuing the same task. Key points:
-- The summary preserves all file paths, decisions, tool outcomes, and errors
-- If you need details not included in the summary, re-read the relevant files using read_file
-- Continue from where the conversation left off — do NOT redo work described in the summary
-- Compacted at: ${compactionTimestamp}`;
-}
-
-// ─── Fast Model Defaults ────────────────────────────────────────────────────────
-
-/**
- * Maps each provider to its cheapest/fastest model for use in compaction
- * and sub-agent tasks. Users can override via config.compactModel.
- */
-export const FAST_MODEL_DEFAULTS: Record<string, string> = {
-  anthropic: "claude-3-haiku-20240307",
-  openai: "gpt-4o-mini",
-  google: "gemini-2.5-flash",
-  mistral: "mistral-small-latest",
-  groq: "mixtral-8x7b-32768",
-  deepseek: "deepseek-chat",
-  fireworks: "accounts/fireworks/models/llama-v3p1-70b-instruct",
-  together: "meta-llama/Llama-3.1-70B-Instruct-Turbo",
-  ollama: "mistral",
-};
-
-/**
- * Resolves the model to use for compaction/sub-agents.
- * Priority: explicit override > FAST_MODEL_DEFAULTS > main model (fallback)
- */
-export function resolveFastModel(
-  provider: string,
-  mainModel: string,
-  override?: string
-): string {
-  if (override) return override;
-  return FAST_MODEL_DEFAULTS[provider] ?? mainModel;
-}
-
-// ─── Compactor Options ──────────────────────────────────────────────────────────
-
-export interface CompactorOptions {
-  /** Number of recent messages to preserve (default: 8) */
-  keepLastN?: number;
-  /** Max tokens for the summary output (default: 2000) */
-  maxSummaryTokens?: number;
-}
-
-// ─── Compaction Result ──────────────────────────────────────────────────────────
-
-export interface CompactionResult {
-  /** The new compacted conversation history */
-  compactedHistory: BaseMessage[];
-  /** Number of messages evicted */
-  evictedCount: number;
-  /** Token count before compaction */
-  tokensBefore: number;
-  /** Token count after compaction */
-  tokensAfter: number;
-  /** Whether the LLM was used (true) or fallback was used (false) */
-  llmUsed: boolean;
-}
-
-// ─── ConversationCompactor ──────────────────────────────────────────────────────
-
-export class ConversationCompactor {
-
-  /**
-   * Compact a conversation history using an LLM to generate a structured summary.
-   *
-   * @param history — The full conversation history
-   * @param llm — The LLM to use for summarization (should be a fast/cheap model)
-   * @param options — Compaction options
-   * @returns CompactionResult with the new compacted history
-   */
-  async compact(
-    history: BaseMessage[],
-    llm: Runnable | BaseChatModel,
-    options: CompactorOptions = {}
-  ): Promise<CompactionResult> {
-    const keepLastN = options.keepLastN ?? 8;
-    const maxSummaryTokens = options.maxSummaryTokens ?? 2000;
-
-    if (history.length <= keepLastN) {
-      return {
-        compactedHistory: history,
-        evictedCount: 0,
-        tokensBefore: countMessageTokens(history),
-        tokensAfter: countMessageTokens(history),
-        llmUsed: false,
-      };
-    }
-
-    const tokensBefore = countMessageTokens(history);
-    const evictedMessages = history.slice(0, history.length - keepLastN);
-    const recentMessages = history.slice(-keepLastN);
-    const evictedCount = evictedMessages.length;
-
-    // Try LLM-powered compaction
-    try {
-      const summaryText = await this.generateLLMSummary(
-        evictedMessages,
-        llm,
-        maxSummaryTokens
-      );
-
-      const summaryMessage = new HumanMessage(
-        `<system-summary>\n[COMPACTED CONVERSATION SUMMARY]\n${summaryText}\n</system-summary>`
-      );
-
-      const handoffMessage = new HumanMessage(
-        `<system-handoff>\n${createHandoffPrompt(new Date().toISOString())}\n</system-handoff>`
-      );
-
-      const compactedHistory = [summaryMessage, handoffMessage, ...recentMessages];
-      const tokensAfter = countMessageTokens(compactedHistory);
-
-      return {
-        compactedHistory,
-        evictedCount,
-        tokensBefore,
-        tokensAfter,
-        llmUsed: true,
-      };
-    } catch (error) {
-      // Fallback to string-based compaction
-      return this.fallbackCompact(history, evictedMessages, recentMessages, tokensBefore);
-    }
-  }
-
-  /**
-   * Generates a structured summary using the LLM.
-   */
-  private async generateLLMSummary(
-    evictedMessages: BaseMessage[],
-    llm: Runnable | BaseChatModel,
-    maxSummaryTokens: number
-  ): Promise<string> {
-    // Construct the prompt for the compactor LLM
-    const compactPrompt = new HumanMessage(
-      `<system-directive>\n${COMPACT_SYSTEM_PROMPT}\n\nKeep your summary under ${maxSummaryTokens} tokens.\n</system-directive>`
-    );
-
-    // Convert evicted messages into a readable format for the summarizer
-    const conversationText = evictedMessages
-      .map((msg) => {
-        const role = msg._getType();
-        const content = typeof msg.content === "string"
-          ? msg.content
-          : JSON.stringify(msg.content);
-        return `[${role}]: ${content}`;
-      })
-      .join("\n\n");
-
-    const summaryRequest = new HumanMessage(
-      `Summarize this conversation:\n\n${conversationText}`
-    );
-
-    const response = await llm.invoke([compactPrompt, summaryRequest]);
-
-    // Extract text from response
-    if (typeof response === "string") return response;
-    if ("content" in response && typeof response.content === "string") {
-      return response.content;
-    }
-
-    throw new Error("Unexpected LLM response format during compaction");
-  }
-
-  /**
-   * Fallback compaction using a simple heuristic summary (no LLM call).
-   * Used when the LLM call fails.
-   */
-  private fallbackCompact(
-    _fullHistory: BaseMessage[],
-    evictedMessages: BaseMessage[],
-    recentMessages: BaseMessage[],
-    tokensBefore: number
-  ): CompactionResult {
-    // Build a basic summary from message roles and lengths
-    const humanMsgCount = evictedMessages.filter(m => m._getType() === "human").length;
-    const aiMsgCount = evictedMessages.filter(m => m._getType() === "ai").length;
-    const toolMsgCount = evictedMessages.filter(m => m._getType() === "tool").length;
-
-    const summaryText = [
-      `[Fallback Compaction — LLM summary unavailable]`,
-      `Evicted ${evictedMessages.length} messages:`,
-      `  - ${humanMsgCount} user messages`,
-      `  - ${aiMsgCount} agent responses`,
-      `  - ${toolMsgCount} tool results`,
-      `The conversation is continuing below.`,
-    ].join("\n");
-
-    const summaryMessage = new HumanMessage(`<system-summary>\n${summaryText}\n</system-summary>`);
-    const handoffMessage = new HumanMessage(
-      `<system-handoff>\n${createHandoffPrompt(new Date().toISOString())}\n</system-handoff>`
-    );
-
-    const compactedHistory = [summaryMessage, handoffMessage, ...recentMessages];
-    const tokensAfter = countMessageTokens(compactedHistory);
-
-    return {
-      compactedHistory,
-      evictedCount: evictedMessages.length,
-      tokensBefore,
-      tokensAfter,
-      llmUsed: false,
-    };
-  }
-}

package/src/core/contextGuard.ts

@@ -1,129 +0,0 @@
-/**
- * Context Guard
- *
- * Proactively monitors token usage during the agent loop and triggers auto-compaction
- * before the model's context window is exceeded.
- *
- * Thresholds:
- * - 80% (WARN): Triggers standard LLM-powered context compaction
- * - 95% (CRITICAL): Forces emergency truncation if compaction fails
- */
-
-import { BaseMessage, SystemMessage, HumanMessage } from "@langchain/core/messages";
-import { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { Runnable } from "@langchain/core/runnables";
-import { CacheOptimizedPromptBuilder, ContextState } from "./promptBuilder.js";
-import { countMessageTokens } from "./tokenCounter.js";
-import { createHandoffPrompt } from "./compactor.js";
-
-export interface ContextGuardMetrics {
-  originalTokens: number;
-  newTokens: number;
-  messagesEvicted: number;
-  actionTaken: "none" | "compacted" | "emergency_truncated";
-}
-
-export class ContextGuard {
-  private promptBuilder: CacheOptimizedPromptBuilder;
-  private llm: Runnable | BaseChatModel;
-  private maxTokens: number;
-
-  constructor(
-    llm: Runnable | BaseChatModel,
-    maxTokens: number,
-    promptBuilder: CacheOptimizedPromptBuilder = new CacheOptimizedPromptBuilder()
-  ) {
-    this.llm = llm;
-    this.maxTokens = maxTokens;
-    this.promptBuilder = promptBuilder;
-  }
-
-  /**
-   * Checks the token usage of the current state and compacts if necessary.
-   * Returns updated state and metrics about the action taken.
-   */
-  async ensureCapacity(
-    state: ContextState,
-    warnThreshold = 0.8,
-    criticalThreshold = 0.95
-  ): Promise<{ state: ContextState; metrics: ContextGuardMetrics }> {
-    const fullPrompt = this.promptBuilder.buildPrompt(state);
-    const tokenCount = countMessageTokens(fullPrompt);
-
-    // 1. Under limit — do nothing
-    if (tokenCount < this.maxTokens * warnThreshold) {
-      return {
-        state,
-        metrics: {
-          originalTokens: tokenCount,
-          newTokens: tokenCount,
-          messagesEvicted: 0,
-          actionTaken: "none",
-        },
-      };
-    }
-
-    // 2. Over WARN but below CRITICAL — try standard LLM compaction
-    if (tokenCount < this.maxTokens * criticalThreshold) {
-      const result = await this.promptBuilder.compactHistoryWithLLM(
-        state.conversationHistory,
-        this.llm,
-        8 // keep last 8 messages
-      );
-
-      return {
-        state: {
-          ...state,
-          conversationHistory: result.compactedHistory,
-        },
-        metrics: {
-          originalTokens: tokenCount,
-          newTokens: result.tokensAfter,
-          messagesEvicted: result.evictedCount,
-          actionTaken: "compacted",
-        },
-      };
-    }
-
-    // 3. CRITICAL overflow (or standard compaction didn't free enough space)
-    // Emergency truncation: drop everything except the last 4 messages and inject an emergency handoff
-    const keepLast = 4;
-    
-    // If we're already at or below 4 messages, we literally can't truncate more
-    if (state.conversationHistory.length <= keepLast) {
-       return {
-         state,
-         metrics: { originalTokens: tokenCount, newTokens: tokenCount, messagesEvicted: 0, actionTaken: "none" }
-       };
-    }
-
-    const recentMsgs = state.conversationHistory.slice(-keepLast);
-    const evictedCount = state.conversationHistory.length - keepLast;
-
-    const emergencySystemMsg = new HumanMessage(
-      `<system-alert>\n[EMERGENCY CONTEXT TRUNCATION]\n` +
-      `The conversation exceeded the maximum context window (${this.maxTokens} tokens). ` +
-      `Older messages were aggressively deleted without summarization to prevent an immediate crash.\n` +
-      `You are the same agent. ` + createHandoffPrompt(new Date().toISOString()) + `\n</system-alert>`
-    );
-
-    const newHistory = [emergencySystemMsg, ...recentMsgs];
-    const newTokens = countMessageTokens(this.promptBuilder.buildPrompt({
-       ...state,
-       conversationHistory: newHistory
-    }));
-
-    return {
-      state: {
-        ...state,
-        conversationHistory: newHistory,
-      },
-      metrics: {
-        originalTokens: tokenCount,
-        newTokens,
-        messagesEvicted: evictedCount,
-        actionTaken: "emergency_truncated",
-      },
-    };
-  }
-}

package/src/core/errors.ts

@@ -1,202 +0,0 @@
-/**
- * JooneError — Structured error hierarchy for the Joone agent.
- *
- * Every error in the system carries:
- * - `category`: A machine-readable classification (e.g., "llm_api", "sandbox", "tool").
- * - `retryable`: Whether the operation that caused this error is safe to retry.
- * - `context`: Arbitrary structured metadata for debugging.
- * - `toRecoveryHint()`: A human-readable string the LLM can use to self-correct.
- */
-
-export type ErrorCategory = "llm_api" | "sandbox" | "tool" | "config" | "network" | "unknown";
-
-export class JooneError extends Error {
-    public readonly category: ErrorCategory;
-    public readonly retryable: boolean;
-    public readonly context: Record<string, unknown>;
-
-    constructor(
-        message: string,
-        opts: {
-            category: ErrorCategory;
-            retryable: boolean;
-            context?: Record<string, unknown>;
-            cause?: Error;
-        }
-    ) {
-        super(message);
-        this.name = "JooneError";
-        this.category = opts.category;
-        this.retryable = opts.retryable;
-        this.context = opts.context ?? {};
-        if (opts.cause) {
-            this.cause = opts.cause;
-        }
-    }
-
-    /**
-     * Returns a hint string that can be injected into the LLM's conversation
-     * so it can adapt its behavior instead of crashing.
-     */
-    toRecoveryHint(): string {
-        return `[SYSTEM ERROR — ${this.category.toUpperCase()}]: ${this.message}`;
-    }
-}
-
-// ─── LLM API Errors ─────────────────────────────────────────────────────────────
-
-export class LLMApiError extends JooneError {
-    public readonly statusCode: number | undefined;
-    public readonly provider: string;
-
-    constructor(
-        message: string,
-        opts: {
-            statusCode?: number;
-            provider: string;
-            retryable: boolean;
-            headers?: Record<string, string>;
-            cause?: Error;
-        }
-    ) {
-        super(message, {
-            category: "llm_api",
-            retryable: opts.retryable,
-            context: {
-                statusCode: opts.statusCode,
-                provider: opts.provider,
-                retryAfter: opts.headers?.["retry-after"],
-            },
-            cause: opts.cause,
-        });
-        this.name = "LLMApiError";
-        this.statusCode = opts.statusCode;
-        this.provider = opts.provider;
-    }
-
-    toRecoveryHint(): string {
-        if (this.statusCode === 429) {
-            const retryAfter = this.context.retryAfter;
-            return (
-                `[SYSTEM ERROR — RATE LIMITED]: The ${this.provider} API returned a 429 rate limit error. ` +
-                (retryAfter
-                    ? `Retry after ${retryAfter} seconds. `
-                    : "Wait a moment before trying again. ") +
-                "Consider simplifying your request or reducing the number of tool calls per turn."
-            );
-        }
-        if (this.statusCode === 401 || this.statusCode === 403) {
-            return (
-                `[SYSTEM ERROR — AUTH FAILURE]: The ${this.provider} API rejected the credentials (HTTP ${this.statusCode}). ` +
-                "This is a fatal configuration error. Ask the user to verify their API key."
-            );
-        }
-        return (
-            `[SYSTEM ERROR — LLM API]: The ${this.provider} API returned an error` +
-            (this.statusCode ? ` (HTTP ${this.statusCode})` : "") +
-            `. ${this.message}`
-        );
-    }
-}
-
-// ─── Sandbox Errors ──────────────────────────────────────────────────────────────
-
-export class SandboxError extends JooneError {
-    public readonly sandboxProvider: string;
-
-    constructor(
-        message: string,
-        opts: {
-            sandboxProvider: string;
-            retryable: boolean;
-            cause?: Error;
-        }
-    ) {
-        super(message, {
-            category: "sandbox",
-            retryable: opts.retryable,
-            context: { sandboxProvider: opts.sandboxProvider },
-            cause: opts.cause,
-        });
-        this.name = "SandboxError";
-        this.sandboxProvider = opts.sandboxProvider;
-    }
-
-    toRecoveryHint(): string {
-        return (
-            `[SYSTEM ERROR — SANDBOX]: The ${this.sandboxProvider} sandbox encountered an error: ${this.message}. ` +
-            "The sandbox may have been recycled. Try running the command again."
-        );
-    }
-}
-
-// ─── Tool Execution Errors ───────────────────────────────────────────────────────
-
-export class ToolExecutionError extends JooneError {
-    public readonly toolName: string;
-
-    constructor(
-        message: string,
-        opts: {
-            toolName: string;
-            args?: Record<string, unknown>;
-            retryable: boolean;
-            cause?: Error;
-        }
-    ) {
-        super(message, {
-            category: "tool",
-            retryable: opts.retryable,
-            context: { toolName: opts.toolName, args: opts.args },
-            cause: opts.cause,
-        });
-        this.name = "ToolExecutionError";
-        this.toolName = opts.toolName;
-    }
-
-    toRecoveryHint(): string {
-        return (
-            `[SYSTEM ERROR — TOOL]: The tool "${this.toolName}" failed: ${this.message}. ` +
-            "Try a different approach or check the arguments you passed."
-        );
-    }
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────────
-
-const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503]);
-const RETRYABLE_ERROR_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ECONNREFUSED", "UND_ERR_CONNECT_TIMEOUT"]);
-const NON_RETRYABLE_STATUS_CODES = new Set([400, 401, 403, 404]);
-
-/**
- * Wraps a raw provider error into a structured `LLMApiError`.
- * Inspects the error for HTTP status codes, network error codes, etc.
- */
-export function wrapLLMError(error: unknown, provider: string): LLMApiError {
-    if (error instanceof LLMApiError) return error;
-
-    const err = error instanceof Error ? error : new Error(String(error));
-    const statusCode = (err as any).status ?? (err as any).statusCode ?? (err as any).response?.status;
-    const headers = (err as any).response?.headers ?? {};
-    const code = (err as any).code as string | undefined;
-
-    let retryable = false;
-    if (typeof statusCode === "number") {
-        retryable = RETRYABLE_STATUS_CODES.has(statusCode);
-    } else if (code && RETRYABLE_ERROR_CODES.has(code)) {
-        retryable = true;
-    }
-
-    // Non-retryable overrides
-    if (typeof statusCode === "number" && NON_RETRYABLE_STATUS_CODES.has(statusCode)) {
-        retryable = false;
-    }
-
-    return new LLMApiError(err.message, {
-        statusCode,
-        provider,
-        retryable,
-        headers,
-        cause: err,
-    });
-}

package/src/core/promptBuilder.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"promptBuilder.d.ts","sourceRoot":"","sources":["promptBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EAIZ,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,YAAY;IAC3B,wBAAwB,EAAE,MAAM,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,WAAW,EAAE,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,2BAA2B;IACtC;;;OAGG;IACI,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,EAAE;IAwBtD;;;;OAIG;IACI,oBAAoB,CACzB,OAAO,EAAE,WAAW,EAAE,EACtB,QAAQ,EAAE,MAAM,GACf,WAAW,EAAE;IAOhB;;;;;OAKG;IACI,cAAc,CACnB,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,EAAE,MAAM,GACd,WAAW,EAAE;CAWjB"}