joonecli 0.1.0

package/dist/core/sessionResumer.js

@@ -0,0 +1,78 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AIMessage, SystemMessage } from "@langchain/core/messages";
+export class SessionResumer {
+    workspaceDir;
+    constructor(workspaceDir) {
+        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.
+     */
+    prepareForResume(payload) {
+        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 System Message at the very end of the history
+        // so it acts as an immediate reminder before the next LLM generation.
+        state.conversationHistory.push(new SystemMessage(wakeupPrompt));
+        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.
+     */
+    detectFileDrift(state, lastSavedAt) {
+        const interactedFiles = new Set();
+        // 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 = [];
+        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;
+    }
+}
+//# sourceMappingURL=sessionResumer.js.map

package/dist/core/sessionResumer.js.map

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

package/dist/core/sessionStore.d.ts

@@ -0,0 +1,45 @@
+import { ContextState } from "./promptBuilder.js";
+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 declare class SessionStore {
+    constructor();
+    /**
+     * Serializes a LangChain BaseMessage instance into a raw JSON object.
+     */
+    private serializeMessage;
+    /**
+     * Rehydrates a raw JSON object back into a LangChain BaseMessage class instance.
+     */
+    private deserializeMessage;
+    /**
+     * 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.
+     */
+    saveSession(sessionId: string, state: ContextState, provider: string, model: string): Promise<void>;
+    /**
+     * Loads the session state from disk.
+     */
+    loadSession(sessionId: string): Promise<SessionStatePayload>;
+    /**
+     * Only reads the first line of the given session file to quickly extract the header.
+     */
+    private loadHeader;
+    /**
+     * Lists all saved sessions, sorted by most recently saved.
+     */
+    listSessions(): Promise<SessionHeader[]>;
+}

package/dist/core/sessionStore.js

@@ -0,0 +1,167 @@
+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 { HumanMessage, AIMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
+// Ensure the sessions directory exists
+const SESSIONS_DIR = path.join(os.homedir(), ".joone", "sessions");
+/**
+ * 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.
+     */
+    serializeMessage(msg) {
+        const base = {
+            type: msg._getType(),
+            content: msg.content,
+        };
+        if (msg instanceof AIMessage && msg.tool_calls && msg.tool_calls.length > 0) {
+            base.tool_calls = msg.tool_calls;
+        }
+        if (msg instanceof ToolMessage) {
+            base.tool_call_id = msg.tool_call_id;
+        }
+        return base;
+    }
+    /**
+     * Rehydrates a raw JSON object back into a LangChain BaseMessage class instance.
+     */
+    deserializeMessage(raw) {
+        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":
+                return new SystemMessage(raw.content);
+            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.
+     */
+    async saveSession(sessionId, state, provider, model) {
+        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 = {
+            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.
+     */
+    async loadSession(sessionId) {
+        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 = null;
+        const conversationHistory = [];
+        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.
+     */
+    async loadHeader(sessionId) {
+        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;
+            }
+        }
+        return null;
+    }
+    /**
+     * Lists all saved sessions, sorted by most recently saved.
+     */
+    async listSessions() {
+        if (!fs.existsSync(SESSIONS_DIR))
+            return [];
+        const files = fs.readdirSync(SESSIONS_DIR).filter(f => f.endsWith(".jsonl"));
+        const sessions = [];
+        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);
+    }
+}
+//# sourceMappingURL=sessionStore.js.map

package/dist/core/sessionStore.js.map

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

package/dist/core/tokenCounter.d.ts

@@ -0,0 +1,17 @@
+import { BaseMessage } from "@langchain/core/messages";
+/**
+ * Estimates the token count for a string.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimates the total token count across a list of messages.
+ */
+export declare function countMessageTokens(messages: BaseMessage[]): number;
+/**
+ * Checks if the message history is approaching the context window limit.
+ *
+ * @param messages - The current conversation messages.
+ * @param maxTokens - The model's context window size.
+ * @param threshold - Fraction of capacity to trigger compaction (default: 0.8 = 80%).
+ */
+export declare function isNearCapacity(messages: BaseMessage[], maxTokens: number, threshold?: number): boolean;

package/dist/core/tokenCounter.js

@@ -0,0 +1,54 @@
+/**
+ * Lightweight token counter using character-based heuristic.
+ *
+ * Approximation: ~4 characters per token for English text.
+ * This avoids a dependency on tiktoken while being accurate enough
+ * for capacity threshold decisions (~90% accuracy for English).
+ *
+ * For production accuracy, swap to tiktoken with the appropriate
+ * model-specific encoding.
+ */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Estimates the token count for a string.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+ * Estimates the total token count across a list of messages.
+ */
+export function countMessageTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            total += estimateTokens(msg.content);
+        }
+        else if (Array.isArray(msg.content)) {
+            // Handle multi-part messages (text + tool calls)
+            for (const part of msg.content) {
+                if (typeof part === "string") {
+                    total += estimateTokens(part);
+                }
+                else if ("text" in part && typeof part.text === "string") {
+                    total += estimateTokens(part.text);
+                }
+            }
+        }
+        // Account for role/name overhead (~4 tokens per message)
+        total += 4;
+    }
+    return total;
+}
+/**
+ * Checks if the message history is approaching the context window limit.
+ *
+ * @param messages - The current conversation messages.
+ * @param maxTokens - The model's context window size.
+ * @param threshold - Fraction of capacity to trigger compaction (default: 0.8 = 80%).
+ */
+export function isNearCapacity(messages, maxTokens, threshold = 0.8) {
+    const used = countMessageTokens(messages);
+    return used >= maxTokens * threshold;
+}
+//# sourceMappingURL=tokenCounter.js.map

package/dist/core/tokenCounter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenCounter.js","sourceRoot":"","sources":["../../src/core/tokenCounter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAuB;IACxD,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACpC,KAAK,IAAI,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,iDAAiD;YACjD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAC/B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC7B,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;gBAChC,CAAC;qBAAM,IAAI,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC3D,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;QACH,CAAC;QAED,yDAAyD;QACzD,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAuB,EACvB,SAAiB,EACjB,SAAS,GAAG,GAAG;IAEf,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC1C,OAAO,IAAI,IAAI,SAAS,GAAG,SAAS,CAAC;AACvC,CAAC"}

package/dist/evals/dataset.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Programmatically creates the baseline dataset in LangSmith if it doesn't already exist.
+ */
+export declare function ensureBaselineDataset(): Promise<string>;

package/dist/evals/dataset.js

@@ -0,0 +1,61 @@
+import { Client } from "langsmith";
+const client = new Client();
+const DATASET_NAME = "joone-baseline-v1";
+/**
+ * Definition of our baseline evaluation dataset.
+ */
+const BASELINE_EXAMPLES = [
+    {
+        inputs: {
+            instruction: "Write a python script that calculates the 10th fibonacci number and saves the result to /workspace/fib_result.txt",
+        },
+        outputs: {
+            expected_file: "/workspace/fib_result.txt",
+            expected_content: "55\n", // 0,1,1,2,3,5,8,13,21,34,55
+        },
+    },
+    {
+        inputs: {
+            instruction: `Create a TypeScript file at /workspace/math.ts with a function 'add(a: number, b: number)' that returns their sum. 
+Then write a test file at /workspace/math.test.ts using the 'node:assert' module.
+Finally, use the bash tool to run 'npx tsx math.test.ts' to verify it passes.`,
+        },
+        outputs: {
+            expected_file: "/workspace/math.ts",
+            expected_test_execution: true,
+        },
+    },
+    {
+        inputs: {
+            instruction: "List all files in the current project root directory and save the output to /workspace/ls.txt",
+        },
+        outputs: {
+            expected_file: "/workspace/ls.txt",
+        },
+    },
+];
+/**
+ * Programmatically creates the baseline dataset in LangSmith if it doesn't already exist.
+ */
+export async function ensureBaselineDataset() {
+    try {
+        const dataset = await client.readDataset({ datasetName: DATASET_NAME });
+        console.log(`[Eval] Dataset '${DATASET_NAME}' already exists (ID: ${dataset.id}).`);
+        return DATASET_NAME;
+    }
+    catch (error) {
+        if (error?.message?.includes("not found") || error?.status === 404) {
+            console.log(`[Eval] Creating dataset '${DATASET_NAME}' from scratch...`);
+            const dataset = await client.createDataset(DATASET_NAME, {
+                description: "Baseline tasks to evaluate Joone's core sandbox, tool routing, and reasoning precision.",
+            });
+            for (const example of BASELINE_EXAMPLES) {
+                await client.createExample(example.inputs, example.outputs, { datasetId: dataset.id });
+            }
+            console.log(`[Eval] Successfully seeded dataset '${DATASET_NAME}' with ${BASELINE_EXAMPLES.length} examples.`);
+            return DATASET_NAME;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=dataset.js.map

package/dist/evals/dataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset.js","sourceRoot":"","sources":["../../src/evals/dataset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;AAC5B,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAEzC;;GAEG;AACH,MAAM,iBAAiB,GAAG;IACxB;QACE,MAAM,EAAE;YACN,WAAW,EAAE,mHAAmH;SACjI;QACD,OAAO,EAAE;YACP,aAAa,EAAE,2BAA2B;YAC1C,gBAAgB,EAAE,MAAM,EAAE,4BAA4B;SACvD;KACF;IACD;QACE,MAAM,EAAE;YACN,WAAW,EAAE;;8EAE2D;SACzE;QACD,OAAO,EAAE;YACP,aAAa,EAAE,oBAAoB;YACnC,uBAAuB,EAAE,IAAI;SAC9B;KACF;IACD;QACE,MAAM,EAAE;YACN,WAAW,EAAE,+FAA+F;SAC7G;QACD,OAAO,EAAE;YACP,aAAa,EAAE,mBAAmB;SACnC;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,mBAAmB,YAAY,yBAAyB,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;QACpF,OAAO,YAAY,CAAC;IACtB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,IAAI,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,IAAI,KAAK,EAAE,MAAM,KAAK,GAAG,EAAE,CAAC;YACnE,OAAO,CAAC,GAAG,CAAC,4BAA4B,YAAY,mBAAmB,CAAC,CAAC;YACzE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,YAAY,EAAE;gBACvD,WAAW,EAAE,yFAAyF;aACvG,CAAC,CAAC;YAEH,KAAK,MAAM,OAAO,IAAI,iBAAiB,EAAE,CAAC;gBACxC,MAAM,MAAM,CAAC,aAAa,CACxB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,OAAO,EACf,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAC1B,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,uCAAuC,YAAY,UAAU,iBAAiB,CAAC,MAAM,YAAY,CAAC,CAAC;YAC/G,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/evals/evaluator.d.ts

@@ -0,0 +1,21 @@
+import { Run, Example } from "langsmith";
+import { EvaluationResult } from "langsmith/evaluation";
+/**
+ * Custom evaluator: Success Validator
+ * Checks if the agent crashed or returned a fatal error trace.
+ */
+export declare function successEvaluator(run: Run, example?: Example): Promise<EvaluationResult>;
+/**
+ * Custom evaluator: Cache Efficiency
+ * Checks if the run utilized Anthropic Prompt Caching efficiently (> 70%).
+ *
+ * Note: Requires the LLM to emit `cache_creation_input_tokens` and `cache_read_input_tokens`
+ * in its usage metadata payload, which is currently extracted by the SessionTracer.
+ */
+export declare function cacheEfficiencyEvaluator(run: Run, example?: Example): Promise<EvaluationResult>;
+/**
+ * Custom evaluator: Output Artifact Check
+ * Verifies if the file the agent was instructed to create actually exists
+ * in the Sandbox after execution.
+ */
+export declare function filePresenceEvaluator(run: Run, example?: Example): Promise<EvaluationResult>;

package/dist/evals/evaluator.js

@@ -0,0 +1,68 @@
+/**
+ * Custom evaluator: Success Validator
+ * Checks if the agent crashed or returned a fatal error trace.
+ */
+export async function successEvaluator(run, example) {
+    // If the trace has an error field, the harness threw an unhandled exception.
+    const isError = !!run.error;
+    return {
+        key: "execution_success",
+        score: isError ? 0 : 1,
+        comment: isError ? run.error : "Agent completed execution loop cleanly.",
+    };
+}
+/**
+ * Custom evaluator: Cache Efficiency
+ * Checks if the run utilized Anthropic Prompt Caching efficiently (> 70%).
+ *
+ * Note: Requires the LLM to emit `cache_creation_input_tokens` and `cache_read_input_tokens`
+ * in its usage metadata payload, which is currently extracted by the SessionTracer.
+ */
+export async function cacheEfficiencyEvaluator(run, example) {
+    const outputs = run.outputs || {};
+    const metrics = outputs.metrics; // We will attach metrics to the harness output
+    if (!metrics || !metrics.totalTokens) {
+        return {
+            key: "cache_hit_rate",
+            score: null, // N/A (e.g., OpenAI or missing data)
+            comment: "No token metrics found in run output.",
+        };
+    }
+    const creationTokens = metrics.cacheCreationTokens || 0;
+    const readTokens = metrics.cacheReadTokens || 0;
+    if (creationTokens === 0 && readTokens === 0) {
+        return {
+            key: "cache_hit_rate",
+            score: 0,
+            comment: "Prompt caching is not active or not supported by this provider.",
+        };
+    }
+    const totalInputTokens = metrics.promptTokens;
+    const hitRate = readTokens / totalInputTokens;
+    return {
+        key: "cache_hit_rate",
+        score: hitRate,
+        comment: `Cache Hit Rate: ${(hitRate * 100).toFixed(1)}% (${readTokens} / ${totalInputTokens} input tokens)`,
+    };
+}
+/**
+ * Custom evaluator: Output Artifact Check
+ * Verifies if the file the agent was instructed to create actually exists
+ * in the Sandbox after execution.
+ */
+export async function filePresenceEvaluator(run, example) {
+    if (!example?.outputs?.expected_file) {
+        return { key: "expected_file_created", score: null };
+    }
+    // The harnessed output should return a manifest or state snapshot we can verify
+    const outputs = run.outputs || {};
+    const fileManifest = outputs.fileManifest || [];
+    const expectedFile = example.outputs.expected_file;
+    const didCreate = fileManifest.includes(expectedFile);
+    return {
+        key: "expected_file_created",
+        score: didCreate ? 1 : 0,
+        comment: didCreate ? `File ${expectedFile} created successfully.` : `Failed to create expected file: ${expectedFile}`,
+    };
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evals/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/evals/evaluator.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAQ,EAAE,OAAiB;IAChE,6EAA6E;IAC7E,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IAE5B,OAAO;QACL,GAAG,EAAE,mBAAmB;QACxB,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,yCAAyC;KACzE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,GAAQ,EAAE,OAAiB;IACxE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,+CAA+C;IAEhF,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACrC,OAAO;YACL,GAAG,EAAE,gBAAgB;YACrB,KAAK,EAAE,IAAI,EAAE,qCAAqC;YAClD,OAAO,EAAE,uCAAuC;SACjD,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,CAAC;IAEhD,IAAI,cAAc,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO;YACL,GAAG,EAAE,gBAAgB;YACrB,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,iEAAiE;SAC3E,CAAC;IACJ,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,GAAG,gBAAgB,CAAC;IAE9C,OAAO;QACL,GAAG,EAAE,gBAAgB;QACrB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,mBAAmB,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,UAAU,MAAM,gBAAgB,gBAAgB;KAC7G,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAQ,EAAE,OAAiB;IACrE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QACrC,OAAO,EAAE,GAAG,EAAE,uBAAuB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,gFAAgF;IAChF,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAEhD,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC;IACnD,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IAEtD,OAAO;QACL,GAAG,EAAE,uBAAuB;QAC5B,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,YAAY,wBAAwB,CAAC,CAAC,CAAC,mCAAmC,YAAY,EAAE;KACtH,CAAC;AACJ,CAAC"}

package/dist/hitl/bridge.d.ts

@@ -0,0 +1,65 @@
+import { EventEmitter } from "node:events";
+export interface HITLQuestion {
+    /** Unique ID for this question. */
+    id: string;
+    /** The question text to display to the user. */
+    question: string;
+    /** Optional predefined answer choices. */
+    options?: string[];
+    /** Timestamp when the question was posed. */
+    createdAt: number;
+}
+export interface HITLPermissionRequest {
+    /** Unique ID for this request. */
+    id: string;
+    /** The tool requesting permission. */
+    toolName: string;
+    /** The arguments the tool was called with. */
+    args: Record<string, unknown>;
+    /** Timestamp when the request was created. */
+    createdAt: number;
+}
+/**
+ * HITLBridge — Human-in-the-Loop communication bridge.
+ *
+ * Provides a typed event-based interface between the tool execution layer
+ * and the TUI rendering layer. When a tool needs user input, it emits
+ * a question event and awaits the response. The TUI listens, renders
+ * the prompt, and resolves the answer.
+ *
+ * Singleton pattern: one bridge per session.
+ */
+export declare class HITLBridge extends EventEmitter {
+    private static instance;
+    private pendingResolvers;
+    private timeoutMs;
+    private questionCounter;
+    constructor(timeoutMs?: number);
+    static getInstance(timeoutMs?: number): HITLBridge;
+    static resetInstance(): void;
+    /**
+     * Called by a tool to ask the user a free-form question.
+     * Blocks until the user responds (or times out).
+     *
+     * @returns The user's answer as a string.
+     */
+    askUser(question: string, options?: string[]): Promise<string>;
+    /**
+     * Called by the PermissionMiddleware to request tool execution approval.
+     * Blocks until the user responds [y/n] (or times out with denial).
+     *
+     * @returns true if approved, false if denied or timed out.
+     */
+    requestPermission(toolName: string, args: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Called by the TUI when the user submits an answer.
+     *
+     * @param id - The question/permission request ID.
+     * @param answer - The user's text response.
+     */
+    resolveAnswer(id: string, answer: string): void;
+    /**
+     * Returns true if there is an outstanding question awaiting an answer.
+     */
+    hasPendingQuestion(): boolean;
+}