joonecli 0.1.0

package/dist/core/agentLoop.js.map

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

package/dist/core/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 declare class JooneError extends Error {
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly context: Record<string, unknown>;
+    constructor(message: string, opts: {
+        category: ErrorCategory;
+        retryable: boolean;
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+    /**
+     * Returns a hint string that can be injected into the LLM's conversation
+     * so it can adapt its behavior instead of crashing.
+     */
+    toRecoveryHint(): string;
+}
+export declare class LLMApiError extends JooneError {
+    readonly statusCode: number | undefined;
+    readonly provider: string;
+    constructor(message: string, opts: {
+        statusCode?: number;
+        provider: string;
+        retryable: boolean;
+        headers?: Record<string, string>;
+        cause?: Error;
+    });
+    toRecoveryHint(): string;
+}
+export declare class SandboxError extends JooneError {
+    readonly sandboxProvider: string;
+    constructor(message: string, opts: {
+        sandboxProvider: string;
+        retryable: boolean;
+        cause?: Error;
+    });
+    toRecoveryHint(): string;
+}
+export declare class ToolExecutionError extends JooneError {
+    readonly toolName: string;
+    constructor(message: string, opts: {
+        toolName: string;
+        args?: Record<string, unknown>;
+        retryable: boolean;
+        cause?: Error;
+    });
+    toRecoveryHint(): string;
+}
+/**
+ * Wraps a raw provider error into a structured `LLMApiError`.
+ * Inspects the error for HTTP status codes, network error codes, etc.
+ */
+export declare function wrapLLMError(error: unknown, provider: string): LLMApiError;

package/dist/core/errors.js

@@ -0,0 +1,139 @@
+/**
+ * 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 class JooneError extends Error {
+    category;
+    retryable;
+    context;
+    constructor(message, opts) {
+        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() {
+        return `[SYSTEM ERROR — ${this.category.toUpperCase()}]: ${this.message}`;
+    }
+}
+// ─── LLM API Errors ─────────────────────────────────────────────────────────────
+export class LLMApiError extends JooneError {
+    statusCode;
+    provider;
+    constructor(message, opts) {
+        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() {
+        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 {
+    sandboxProvider;
+    constructor(message, opts) {
+        super(message, {
+            category: "sandbox",
+            retryable: opts.retryable,
+            context: { sandboxProvider: opts.sandboxProvider },
+            cause: opts.cause,
+        });
+        this.name = "SandboxError";
+        this.sandboxProvider = opts.sandboxProvider;
+    }
+    toRecoveryHint() {
+        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 {
+    toolName;
+    constructor(message, opts) {
+        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() {
+        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, provider) {
+    if (error instanceof LLMApiError)
+        return error;
+    const err = error instanceof Error ? error : new Error(String(error));
+    const statusCode = err.status ?? err.statusCode ?? err.response?.status;
+    const headers = err.response?.headers ?? {};
+    const code = err.code;
+    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,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/promptBuilder.d.ts

@@ -0,0 +1,49 @@
+import { BaseMessage } from "@langchain/core/messages";
+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 declare class CacheOptimizedPromptBuilder {
+    /**
+     * Compiles the full message array for the LLM request.
+     * The first messages are static, and subsequent ones are dynamic.
+     */
+    buildPrompt(state: ContextState): BaseMessage[];
+    /**
+     * The System Reminder Pattern
+     * Instead of replacing the System Prompt (which breaks cache),
+     * use this to inject state updates into the Conversation History.
+     */
+    injectSystemReminder(history: BaseMessage[], reminder: string): BaseMessage[];
+    /**
+     * Cache-Safe Compaction
+     * 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).
+     */
+    compactHistory(history: BaseMessage[], summary: string, keepLastN?: number): BaseMessage[];
+    /**
+     * 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).
+     */
+    shouldCompact(state: ContextState, maxTokens: number, threshold?: number): boolean;
+}

package/dist/core/promptBuilder.js

@@ -0,0 +1,84 @@
+import { SystemMessage, HumanMessage, } from "@langchain/core/messages";
+import { countMessageTokens } from "./tokenCounter.js";
+/**
+ * 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.
+     */
+    buildPrompt(state) {
+        // 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 systemMessages = [
+            new SystemMessage({
+                content: state.globalSystemInstructions,
+                name: "global_instructions",
+            }),
+            new SystemMessage({
+                content: `--- Project Context ---\n${state.projectMemory}`,
+                name: "project_context",
+            }),
+            new SystemMessage({
+                content: `--- Session Rules ---\n${state.sessionContext}`,
+                name: "session_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.
+     */
+    injectSystemReminder(history, reminder) {
+        const reminderMsg = new HumanMessage({
+            content: `<system-reminder>\n${reminder}\n</system-reminder>`,
+        });
+        return [...history, reminderMsg];
+    }
+    /**
+     * Cache-Safe Compaction
+     * 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).
+     */
+    compactHistory(history, summary, keepLastN = 6) {
+        if (history.length === 0) {
+            return history;
+        }
+        // Use SystemMessage (not AIMessage) to avoid breaking user/assistant
+        // alternation rules enforced by some providers (e.g. Anthropic).
+        const compactedMessage = new SystemMessage(`[The previous conversation history has been compacted.]\nSummary:\n${summary}`);
+        // Preserve recent messages for continuity
+        const recentMessages = history.slice(-keepLastN);
+        return [compactedMessage, ...recentMessages];
+    }
+    /**
+     * 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).
+     */
+    shouldCompact(state, maxTokens, threshold = 0.8) {
+        const allMessages = this.buildPrompt(state);
+        const usage = countMessageTokens(allMessages);
+        return usage >= maxTokens * threshold;
+    }
+}
+//# sourceMappingURL=promptBuilder.js.map

package/dist/core/promptBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptBuilder.js","sourceRoot":"","sources":["../../src/core/promptBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EACb,YAAY,GAEb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AASvD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,2BAA2B;IACtC;;;OAGG;IACI,WAAW,CAAC,KAAmB;QACpC,+CAA+C;QAC/C,iHAAiH;QACjH,gFAAgF;QAEhF,MAAM,cAAc,GAAkB;YACpC,IAAI,aAAa,CAAC;gBAChB,OAAO,EAAE,KAAK,CAAC,wBAAwB;gBACvC,IAAI,EAAE,qBAAqB;aAC5B,CAAC;YACF,IAAI,aAAa,CAAC;gBAChB,OAAO,EAAE,4BAA4B,KAAK,CAAC,aAAa,EAAE;gBAC1D,IAAI,EAAE,iBAAiB;aACxB,CAAC;YACF,IAAI,aAAa,CAAC;gBAChB,OAAO,EAAE,0BAA0B,KAAK,CAAC,cAAc,EAAE;gBACzD,IAAI,EAAE,iBAAiB;aACxB,CAAC;SACH,CAAC;QAEF,kEAAkE;QAClE,OAAO,CAAC,GAAG,cAAc,EAAE,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC3D,CAAC;IAED;;;;OAIG;IACI,oBAAoB,CACzB,OAAsB,EACtB,QAAgB;QAEhB,MAAM,WAAW,GAAG,IAAI,YAAY,CAAC;YACnC,OAAO,EAAE,sBAAsB,QAAQ,sBAAsB;SAC9D,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,OAAO,EAAE,WAAW,CAAC,CAAC;IACnC,CAAC;IAED;;;;;;;;OAQG;IACI,cAAc,CACnB,OAAsB,EACtB,OAAe,EACf,SAAS,GAAG,CAAC;QAEb,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,qEAAqE;QACrE,iEAAiE;QACjE,MAAM,gBAAgB,GAAG,IAAI,aAAa,CACxC,sEAAsE,OAAO,EAAE,CAChF,CAAC;QAEF,0CAA0C;QAC1C,MAAM,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;QAEjD,OAAO,CAAC,gBAAgB,EAAE,GAAG,cAAc,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACI,aAAa,CAClB,KAAmB,EACnB,SAAiB,EACjB,SAAS,GAAG,GAAG;QAEf,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,KAAK,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAC9C,OAAO,KAAK,IAAI,SAAS,GAAG,SAAS,CAAC;IACxC,CAAC;CACF"}

package/dist/core/reasoningRouter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 declare 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;
+}
+/**
+ * Tracks turn context and decides the reasoning level for each step.
+ */
+export declare class ReasoningRouter {
+    private config;
+    private turnCount;
+    private lastTurnHadError;
+    private consecutiveToolTurns;
+    constructor(config?: Partial<ReasoningConfig>);
+    /**
+     * 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?: boolean, hadError?: boolean): void;
+    /**
+     * Determines the reasoning level for the current turn based on state.
+     *
+     * @returns The recommended reasoning level.
+     */
+    getLevel(): ReasoningLevel;
+    /**
+     * Returns the temperature setting for a given reasoning level.
+     */
+    getTemperature(level: ReasoningLevel): number;
+    /**
+     * Convenience: get the recommended temperature for the current turn.
+     */
+    getRecommendedTemperature(): number;
+    /**
+     * Returns the current turn count.
+     */
+    getTurnCount(): number;
+    /**
+     * Resets state. For testing or new sessions.
+     */
+    reset(): void;
+}

package/dist/core/reasoningRouter.js

@@ -0,0 +1,102 @@
+/**
+ * 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 var ReasoningLevel;
+(function (ReasoningLevel) {
+    ReasoningLevel["HIGH"] = "high";
+    ReasoningLevel["MEDIUM"] = "medium";
+})(ReasoningLevel || (ReasoningLevel = {}));
+const DEFAULT_CONFIG = {
+    highTemp: 0,
+    mediumTemp: 0.2,
+    planningTurns: 2,
+};
+/**
+ * Tracks turn context and decides the reasoning level for each step.
+ */
+export class ReasoningRouter {
+    config;
+    turnCount = 0;
+    lastTurnHadError = false;
+    consecutiveToolTurns = 0;
+    constructor(config) {
+        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) {
+        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() {
+        // 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) {
+        return level === ReasoningLevel.HIGH
+            ? this.config.highTemp
+            : this.config.mediumTemp;
+    }
+    /**
+     * Convenience: get the recommended temperature for the current turn.
+     */
+    getRecommendedTemperature() {
+        return this.getTemperature(this.getLevel());
+    }
+    /**
+     * Returns the current turn count.
+     */
+    getTurnCount() {
+        return this.turnCount;
+    }
+    /**
+     * Resets state. For testing or new sessions.
+     */
+    reset() {
+        this.turnCount = 0;
+        this.lastTurnHadError = false;
+        this.consecutiveToolTurns = 0;
+    }
+}
+//# sourceMappingURL=reasoningRouter.js.map

package/dist/core/reasoningRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoningRouter.js","sourceRoot":"","sources":["../../src/core/reasoningRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,+BAAa,CAAA;IACb,mCAAiB,CAAA;AACnB,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAWD,MAAM,cAAc,GAAoB;IACtC,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,GAAG;IACf,aAAa,EAAE,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,eAAe;IAClB,MAAM,CAAkB;IACxB,SAAS,GAAG,CAAC,CAAC;IACd,gBAAgB,GAAG,KAAK,CAAC;IACzB,oBAAoB,GAAG,CAAC,CAAC;IAEjC,YAAY,MAAiC;QAC3C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAC,YAAY,GAAG,KAAK,EAAE,QAAQ,GAAG,KAAK;QAChD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;QAEjC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;QAChC,CAAC;aAAM,IAAI,YAAY,EAAE,CAAC;YACxB,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC9B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACN,+CAA+C;QAC/C,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAChD,OAAO,cAAc,CAAC,IAAI,CAAC;QAC7B,CAAC;QAED,+BAA+B;QAC/B,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,OAAO,cAAc,CAAC,IAAI,CAAC;QAC7B,CAAC;QAED,6CAA6C;QAC7C,IAAI,IAAI,CAAC,oBAAoB,GAAG,CAAC,EAAE,CAAC;YAClC,OAAO,cAAc,CAAC,MAAM,CAAC;QAC/B,CAAC;QAED,+DAA+D;QAC/D,OAAO,cAAc,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,KAAqB;QAClC,OAAO,KAAK,KAAK,cAAc,CAAC,IAAI;YAClC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ;YACtB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,yBAAyB;QACvB,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;QAC9B,IAAI,CAAC,oBAAoB,GAAG,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/core/retry.d.ts

@@ -0,0 +1,25 @@
+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 declare function retryWithBackoff<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/core/retry.js

@@ -0,0 +1,49 @@
+import { JooneError } from "./errors.js";
+/**
+ * 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(fn, opts = {}) {
+    const { maxRetries = 3, initialDelayMs = 1000, maxJitterMs = 500, onRetry, } = opts;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // 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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/core/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/core/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,EAAoB,EACpB,OAAqB,EAAE;IAEvB,MAAM,EACF,UAAU,GAAG,CAAC,EACd,cAAc,GAAG,IAAI,EACrB,WAAW,GAAG,GAAG,EACjB,OAAO,GACV,GAAG,IAAI,CAAC;IAET,IAAI,SAAiC,CAAC;IAEtC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC;YACD,OAAO,MAAM,EAAE,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,8DAA8D;YAC9D,IAAI,KAAK,YAAY,UAAU,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBACjD,SAAS,GAAG,KAAK,CAAC;gBAElB,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;oBACvB,MAAM,SAAS,GAAG,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;oBACxD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC;oBACzE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,CAAC;oBAE9C,IAAI,OAAO,EAAE,CAAC;wBACV,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;oBACvC,CAAC;oBAED,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;oBACnB,SAAS;gBACb,CAAC;YACL,CAAC;YAED,yDAAyD;YACzD,IAAI,CAAC,CAAC,KAAK,YAAY,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;gBACrD,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC;IACL,CAAC;IAED,wBAAwB;IACxB,MAAM,SAAU,CAAC;AACrB,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACrB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7D,CAAC"}

package/dist/core/sessionResumer.d.ts

@@ -0,0 +1,17 @@
+import { ContextState } from "./promptBuilder.js";
+import { SessionStatePayload } from "./sessionStore.js";
+export declare class SessionResumer {
+    private workspaceDir;
+    constructor(workspaceDir: string);
+    /**
+     * 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.
+     */
+    prepareForResume(payload: SessionStatePayload): ContextState;
+    /**
+     * 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.
+     */
+    detectFileDrift(state: ContextState, lastSavedAt: number): string[];
+}