joonecli 0.1.0

package/dist/tools/security.js

@@ -0,0 +1,183 @@
+// ─── Sandbox + Installer references (set at session start) ──────────────────
+let _sandboxManager = null;
+let _installer = null;
+/**
+ * Binds the security tools to the sandbox and installer.
+ * Must be called at session start.
+ */
+export function bindSecuritySandbox(sandbox, installer) {
+    _sandboxManager = sandbox;
+    _installer = installer;
+}
+// ─── Security Helpers ───────────────────────────────────────────────────────────
+/**
+ * Escapes a string so it can be safely used as an argument in a Bash shell command.
+ */
+function escapeBashArg(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Validates a file path to prevent directory traversal out of the workspace.
+ */
+function isSafePath(pathStr) {
+    if (!pathStr || pathStr.trim() === "")
+        return false;
+    if (pathStr.includes("..") || pathStr.startsWith("/"))
+        return false;
+    return true;
+}
+// ─── SecurityScanTool ───────────────────────────────────────────────────────────
+/**
+ * Scans code for security vulnerabilities using the Gemini CLI Security Extension.
+ *
+ * Execution flow:
+ * 1. LazyInstaller ensures Gemini CLI + security extension are in the sandbox.
+ * 2. Runs `gemini -x security:analyze` in the sandbox.
+ * 3. Returns the generated security report.
+ *
+ * If Gemini CLI installation fails, returns a descriptive fallback message
+ * suggesting manual review or alternative tools.
+ */
+export const SecurityScanTool = {
+    name: "security_scan",
+    description: "Scans code changes for security vulnerabilities using the Gemini CLI Security Extension. " +
+        "Analyzes the current branch diff for common vulnerabilities and generates a security report.",
+    schema: {
+        type: "object",
+        properties: {
+            target: {
+                type: "string",
+                enum: ["changes", "file", "deps"],
+                description: 'What to scan: "changes" (branch diff), "file" (specific file), "deps" (dependencies only)',
+            },
+            path: {
+                type: "string",
+                description: "File path for single-file scan (required when target is 'file')",
+            },
+        },
+        required: ["target"],
+    },
+    execute: async (args) => {
+        if (!_sandboxManager || !_sandboxManager.isActive()) {
+            return { content: "Sandbox is not active. Cannot run security scan.", isError: true };
+        }
+        if (!_installer) {
+            return { content: "LazyInstaller not initialized. Call bindSecuritySandbox() first.", isError: true };
+        }
+        // Ensure Gemini CLI is available
+        const cliReady = await _installer.ensureGeminiCli(_sandboxManager);
+        if (!cliReady) {
+            return {
+                content: ("⚠ Gemini CLI could not be installed in the sandbox.\n" +
+                    "Suggestions:\n" +
+                    '  - Use `dep_scan` tool for dependency vulnerability scanning (uses npm audit)\n' +
+                    "  - Manually review code for OWASP Top 10 vulnerabilities\n" +
+                    "  - Set sandboxTemplate to a pre-baked template with Gemini CLI installed"),
+                isError: true
+            };
+        }
+        // Build the command based on target
+        let command;
+        switch (args.target) {
+            case "changes":
+                command = "cd /workspace && gemini -x security:analyze 2>&1";
+                break;
+            case "file":
+                if (!args.path) {
+                    return { content: "Error: 'path' is required when target is 'file'.", isError: true };
+                }
+                if (!isSafePath(args.path)) {
+                    return { content: "Error: Invalid file path. Path must be relative and cannot contain traversal characters ('..').", isError: true };
+                }
+                command = `cd /workspace && gemini -x security:analyze --file ${escapeBashArg(args.path)} 2>&1`;
+                break;
+            case "deps":
+                command = "cd /workspace && gemini -x security:analyze --deps-only 2>&1";
+                break;
+            default:
+                return { content: `Error: Unknown target "${args.target}". Use "changes", "file", or "deps".`, isError: true };
+        }
+        const result = await _sandboxManager.exec(command);
+        if (result.exitCode !== 0) {
+            return {
+                content: `Security scan failed (exit code ${result.exitCode}):\n${result.stdout}\n${result.stderr}`,
+                metadata: { exitCode: result.exitCode },
+                isError: true
+            };
+        }
+        return {
+            content: result.stdout || "Security scan completed — no issues found.",
+            metadata: { exitCode: result.exitCode },
+            isError: false
+        };
+    },
+};
+// ─── DepScanTool ────────────────────────────────────────────────────────────────
+/**
+ * Scans project dependencies for known vulnerabilities.
+ *
+ * Execution flow:
+ * 1. Try OSV-Scanner (more comprehensive, covers multiple ecosystems).
+ * 2. Fall back to `npm audit --json` (always available in Node sandboxes).
+ */
+export const DepScanTool = {
+    name: "dep_scan",
+    description: "Scans project dependencies for known vulnerabilities (CVEs). " +
+        "Uses OSV-Scanner when available, falls back to npm audit.",
+    schema: {
+        type: "object",
+        properties: {
+            format: {
+                type: "string",
+                enum: ["summary", "json"],
+                description: 'Output format: "summary" (human readable) or "json" (raw)',
+            },
+        },
+    },
+    execute: async (args) => {
+        if (!_sandboxManager || !_sandboxManager.isActive()) {
+            return { content: "Sandbox is not active. Cannot run dependency scan.", isError: true };
+        }
+        if (!_installer) {
+            return { content: "LazyInstaller not initialized.", isError: true };
+        }
+        const format = args?.format ?? "summary";
+        // Try OSV-Scanner first
+        const osvReady = await _installer.ensureOsvScanner(_sandboxManager);
+        if (osvReady) {
+            const osvCmd = format === "json"
+                ? "cd /workspace && osv-scanner --json . 2>&1"
+                : "cd /workspace && osv-scanner . 2>&1";
+            const result = await _sandboxManager.exec(osvCmd);
+            if (result.exitCode === 0) {
+                return {
+                    content: result.stdout || "No known vulnerabilities found in dependencies.",
+                    metadata: { exitCode: result.exitCode },
+                    isError: false
+                };
+            }
+            // Exit code 1 from OSV-Scanner means vulnerabilities found — still valid output
+            if (result.exitCode === 1 && result.stdout) {
+                return {
+                    content: result.stdout,
+                    metadata: { exitCode: result.exitCode },
+                    isError: false
+                };
+            }
+            // If we reach here, OSV-Scanner failed for another reason (e.g. exit > 1)
+            console.warn(`⚠ OSV-Scanner failed (exit code ${result.exitCode}). Falling back to npm audit.\nDetails: ${result.stdout}\n${result.stderr}`);
+        }
+        // Fallback: npm audit
+        const auditCmd = format === "json"
+            ? "cd /workspace && npm audit --json 2>&1"
+            : "cd /workspace && npm audit 2>&1";
+        const auditResult = await _sandboxManager.exec(auditCmd);
+        // npm audit returns 1 when vulnerabilities are found — that's valid output
+        return {
+            content: auditResult.stdout || "No known vulnerabilities found in dependencies.",
+            metadata: { exitCode: auditResult.exitCode },
+            isError: false
+        };
+    },
+};
+//# sourceMappingURL=security.js.map

package/dist/tools/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/tools/security.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAE/E,IAAI,eAAe,GAA0B,IAAI,CAAC;AAClD,IAAI,UAAU,GAAyB,IAAI,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,SAAwB;IAExB,eAAe,GAAG,OAAO,CAAC;IAC1B,UAAU,GAAG,SAAS,CAAC;AACzB,CAAC;AAED,mFAAmF;AAEnF;;GAEG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,OAAe;IACjC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mFAAmF;AAEnF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAyB;IACpD,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,2FAA2F;QAC3F,8FAA8F;IAChG,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;gBACjC,WAAW,EACT,2FAA2F;aAC9F;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,iEAAiE;aACpE;SACF;QACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;KACrB;IACD,OAAO,EAAE,KAAK,EAAE,IAAuC,EAAuB,EAAE;QAC9E,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,EAAE,CAAC;YACpD,OAAO,EAAE,OAAO,EAAE,kDAAkD,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,OAAO,EAAE,kEAAkE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxG,CAAC;QAED,iCAAiC;QACjC,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;QAEnE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO;gBACL,OAAO,EAAE,CACP,uDAAuD;oBACvD,gBAAgB;oBAChB,kFAAkF;oBAClF,6DAA6D;oBAC7D,2EAA2E,CAC5E;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,oCAAoC;QACpC,IAAI,OAAe,CAAC;QACpB,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;YACpB,KAAK,SAAS;gBACZ,OAAO,GAAG,kDAAkD,CAAC;gBAC7D,MAAM;YACR,KAAK,MAAM;gBACT,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;oBACf,OAAO,EAAE,OAAO,EAAE,kDAAkD,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBACxF,CAAC;gBACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC3B,OAAO,EAAE,OAAO,EAAE,iGAAiG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;gBACvI,CAAC;gBACD,OAAO,GAAG,sDAAsD,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;gBAChG,MAAM;YACR,KAAK,MAAM;gBACT,OAAO,GAAG,8DAA8D,CAAC;gBACzE,MAAM;YACR;gBACE,OAAO,EAAE,OAAO,EAAE,0BAA0B,IAAI,CAAC,MAAM,sCAAsC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACnH,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEnD,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,mCAAmC,MAAM,CAAC,QAAQ,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE;gBACnG,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;gBACvC,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,MAAM,IAAI,4CAA4C;YACtE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;YACvC,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,mFAAmF;AAEnF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,IAAI,EAAE,UAAU;IAChB,WAAW,EACT,+DAA+D;QAC/D,2DAA2D;IAC7D,MAAM,EAAE;QACN,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;gBACzB,WAAW,EAAE,2DAA2D;aACzE;SACF;KACF;IACD,OAAO,EAAE,KAAK,EAAE,IAA0B,EAAuB,EAAE;QACjE,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,EAAE,CAAC;YACpD,OAAO,EAAE,OAAO,EAAE,oDAAoD,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC1F,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,OAAO,EAAE,gCAAgC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACtE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,SAAS,CAAC;QAEzC,wBAAwB;QACxB,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC;QAEpE,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GACV,MAAM,KAAK,MAAM;gBACf,CAAC,CAAC,4CAA4C;gBAC9C,CAAC,CAAC,qCAAqC,CAAC;YAE5C,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAElD,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;gBAC1B,OAAO;oBACL,OAAO,EAAE,MAAM,CAAC,MAAM,IAAI,iDAAiD;oBAC3E,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;oBACvC,OAAO,EAAE,KAAK;iBACf,CAAC;YACJ,CAAC;YAED,gFAAgF;YAChF,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC3C,OAAO;oBACL,OAAO,EAAE,MAAM,CAAC,MAAM;oBACtB,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE;oBACvC,OAAO,EAAE,KAAK;iBACf,CAAC;YACJ,CAAC;YAED,0EAA0E;YAC1E,OAAO,CAAC,IAAI,CAAC,mCAAmC,MAAM,CAAC,QAAQ,2CAA2C,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/I,CAAC;QAED,sBAAsB;QACtB,MAAM,QAAQ,GACZ,MAAM,KAAK,MAAM;YACf,CAAC,CAAC,wCAAwC;YAC1C,CAAC,CAAC,iCAAiC,CAAC;QAExC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAEzD,2EAA2E;QAC3E,OAAO;YACL,OAAO,EAAE,WAAW,CAAC,MAAM,IAAI,iDAAiD;YAChF,QAAQ,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAAE;YAC5C,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/tools/webSearch.d.ts

@@ -0,0 +1,6 @@
+import { DynamicToolInterface } from "./index.js";
+/**
+ * Bind the Valyu API key at session start.
+ */
+export declare function bindValyuApiKey(key: string | undefined): void;
+export declare const WebSearchTool: DynamicToolInterface;

package/dist/tools/webSearch.js

@@ -0,0 +1,120 @@
+/**
+ * Web Search Tool — wraps the Valyu AI Search SDK.
+ *
+ * Provides AI-optimized web search and domain-specific search
+ * (papers, finance, patents, SEC filings, etc.). Runs on the Host
+ * (API call, not a shell command).
+ *
+ * Requires a Valyu API key in config (`valyuApiKey`).
+ */
+let _valyuApiKey;
+/**
+ * Bind the Valyu API key at session start.
+ */
+export function bindValyuApiKey(key) {
+    _valyuApiKey = key;
+}
+export const WebSearchTool = {
+    name: "web_search",
+    description: "Search the web for information. Supports general web search and specialized sources: " +
+        "papers (arXiv/PubMed), finance, patents, SEC filings, companies. " +
+        "Returns AI-optimized structured results.",
+    schema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "The search query",
+            },
+            source: {
+                type: "string",
+                enum: ["web", "papers", "finance", "patents", "sec", "companies"],
+                description: 'Search source (default: "web"). Use "papers" for academic, "finance" for financial data, etc.',
+            },
+            maxResults: {
+                type: "number",
+                description: "Maximum number of results to return (default: 5)",
+            },
+        },
+        required: ["query"],
+    },
+    execute: async (args) => {
+        if (!_valyuApiKey) {
+            return {
+                content: "Error: Valyu API key not configured.\n" +
+                    'Run `joone config` and set your Valyu API key, or add "valyuApiKey" to ~/.joone/config.json.',
+                isError: true
+            };
+        }
+        const source = args.source ?? "web";
+        const maxResults = args.maxResults ?? 5;
+        try {
+            // Dynamic import to avoid requiring the dependency at startup
+            const { Valyu } = await import("@valyu/ai-sdk");
+            const valyu = new Valyu({ apiKey: _valyuApiKey });
+            let results;
+            switch (source) {
+                case "web":
+                    results = await valyu.search({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                case "papers":
+                    results = await valyu.paperSearch({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                case "finance":
+                    results = await valyu.financeSearch({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                case "patents":
+                    results = await valyu.patentSearch({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                case "sec":
+                    results = await valyu.secSearch({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                case "companies":
+                    results = await valyu.companyResearch({
+                        query: args.query,
+                        maxResults,
+                    });
+                    break;
+                default:
+                    return {
+                        content: `Error: Unknown source "${source}". Use: web, papers, finance, patents, sec, companies.`,
+                        isError: true
+                    };
+            }
+            // Format results for the LLM
+            if (!results || !results.results || results.results.length === 0) {
+                return { content: `No results found for "${args.query}" in ${source} source.` };
+            }
+            const formatted = results.results
+                .map((r, i) => `${i + 1}. **${r.title || "Untitled"}**\n   ${r.url || ""}\n   ${r.snippet || r.content || ""}`)
+                .join("\n\n");
+            return { content: `Search results for "${args.query}" (${source}):\n\n${formatted}` };
+        }
+        catch (error) {
+            if (error.code === "ERR_MODULE_NOT_FOUND" || error.code === "MODULE_NOT_FOUND") {
+                return {
+                    content: "Error: @valyu/ai-sdk is not installed.\n" +
+                        "Run: npm install @valyu/ai-sdk",
+                    isError: true
+                };
+            }
+            return { content: `Search error: ${error.message}`, isError: true };
+        }
+    },
+};
+//# sourceMappingURL=webSearch.js.map

package/dist/tools/webSearch.js.map

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

package/dist/tracing/analyzer.d.ts

@@ -0,0 +1,58 @@
+import { SessionTrace } from "./types.js";
+/**
+ * TraceAnalyzer — reads a SessionTrace and produces actionable insight reports.
+ *
+ * Analysis capabilities:
+ * - Loop detection: Identifies repeated tool call patterns
+ * - Cost hotspots: Flags turns that consumed >20% of total tokens
+ * - Error clustering: Groups errors by tool
+ * - Cache efficiency: Warns if cache hit rate < 70%
+ * - Recommendations: Human-readable suggestions for improvement
+ */
+export interface AnalysisReport {
+    /** Human-readable title. */
+    title: string;
+    /** Key metrics. */
+    metrics: Record<string, string | number>;
+    /** Detected issues. */
+    issues: AnalysisIssue[];
+    /** Actionable recommendations. */
+    recommendations: string[];
+}
+export interface AnalysisIssue {
+    severity: "info" | "warning" | "critical";
+    category: "loop" | "cost" | "error" | "cache" | "performance";
+    message: string;
+}
+export declare class TraceAnalyzer {
+    private trace;
+    constructor(trace: SessionTrace);
+    /**
+     * Run all analysis checks and produce a full report.
+     */
+    analyze(): AnalysisReport;
+    /**
+     * Detect repeated identical tool call patterns (potential doom-loops).
+     */
+    detectLoops(): AnalysisIssue[];
+    /**
+     * Find LLM calls that consumed >20% of total tokens (cost hotspots).
+     */
+    detectCostHotspots(): AnalysisIssue[];
+    /**
+     * Warn if cache hit rate is below 70%.
+     */
+    detectCacheIssues(): AnalysisIssue[];
+    /**
+     * Group errors by tool and report clusters.
+     */
+    clusterErrors(): AnalysisIssue[];
+    /**
+     * Generate actionable recommendations from detected issues.
+     */
+    generateRecommendations(issues: AnalysisIssue[]): string[];
+    /**
+     * Format the report as a human-readable string (for CLI output).
+     */
+    static formatReport(report: AnalysisReport): string;
+}

package/dist/tracing/analyzer.js

@@ -0,0 +1,190 @@
+export class TraceAnalyzer {
+    trace;
+    constructor(trace) {
+        this.trace = trace;
+    }
+    /**
+     * Run all analysis checks and produce a full report.
+     */
+    analyze() {
+        const issues = [
+            ...this.detectLoops(),
+            ...this.detectCostHotspots(),
+            ...this.detectCacheIssues(),
+            ...this.clusterErrors(),
+        ];
+        const recommendations = this.generateRecommendations(issues);
+        const { summary } = this.trace;
+        return {
+            title: `Session Analysis: ${this.trace.sessionId}`,
+            metrics: {
+                "Total Tokens": summary.totalTokens,
+                "Prompt Tokens": summary.promptTokens,
+                "Completion Tokens": summary.completionTokens,
+                "Estimated Cost": `$${summary.totalCost.toFixed(4)}`,
+                "Cache Hit Rate": `${(summary.cacheHitRate * 100).toFixed(1)}%`,
+                "Tool Calls": summary.toolCallCount,
+                "Errors": summary.errorCount,
+                "Turns": summary.turnCount,
+                "Duration": `${(summary.totalDuration / 1000).toFixed(1)}s`,
+            },
+            issues,
+            recommendations,
+        };
+    }
+    /**
+     * Detect repeated identical tool call patterns (potential doom-loops).
+     */
+    detectLoops() {
+        const issues = [];
+        const toolCalls = this.trace.events.filter((e) => e.type === "tool_call");
+        let consecutiveCount = 1;
+        let loopToolName = null;
+        for (let i = 1; i < toolCalls.length; i++) {
+            const prev = toolCalls[i - 1];
+            const curr = toolCalls[i];
+            if (prev.data.name === curr.data.name &&
+                JSON.stringify(prev.data.args) === JSON.stringify(curr.data.args)) {
+                consecutiveCount++;
+                loopToolName = curr.data.name;
+            }
+            else {
+                if (consecutiveCount >= 3 && loopToolName) {
+                    issues.push({
+                        severity: "critical",
+                        category: "loop",
+                        message: `Doom-loop detected: "${loopToolName}" called ${consecutiveCount} times consecutively with identical args.`,
+                    });
+                }
+                consecutiveCount = 1;
+                loopToolName = null;
+            }
+        }
+        // Handle loop at end of array
+        if (consecutiveCount >= 3 && loopToolName) {
+            issues.push({
+                severity: "critical",
+                category: "loop",
+                message: `Doom-loop detected: "${loopToolName}" called ${consecutiveCount} times consecutively with identical args.`,
+            });
+        }
+        return issues;
+    }
+    /**
+     * Find LLM calls that consumed >20% of total tokens (cost hotspots).
+     */
+    detectCostHotspots() {
+        const issues = [];
+        const { totalTokens } = this.trace.summary;
+        if (totalTokens === 0)
+            return issues;
+        const llmCalls = this.trace.events.filter((e) => e.type === "llm_call");
+        llmCalls.forEach((event, index) => {
+            const callTokens = (event.data.promptTokens || 0) + (event.data.completionTokens || 0);
+            const ratio = callTokens / totalTokens;
+            if (ratio > 0.2) {
+                issues.push({
+                    severity: "warning",
+                    category: "cost",
+                    message: `Turn ${index + 1} consumed ${(ratio * 100).toFixed(0)}% of total tokens (${callTokens} tokens).`,
+                });
+            }
+        });
+        return issues;
+    }
+    /**
+     * Warn if cache hit rate is below 70%.
+     */
+    detectCacheIssues() {
+        const issues = [];
+        const { cacheHitRate, turnCount } = this.trace.summary;
+        // Only relevant if we have enough turns
+        if (turnCount >= 3 && cacheHitRate < 0.7) {
+            issues.push({
+                severity: "warning",
+                category: "cache",
+                message: `Cache hit rate is ${(cacheHitRate * 100).toFixed(1)}% (below 70% target). This increases cost significantly.`,
+            });
+        }
+        return issues;
+    }
+    /**
+     * Group errors by tool and report clusters.
+     */
+    clusterErrors() {
+        const issues = [];
+        const errors = this.trace.events.filter((e) => e.type === "error");
+        if (errors.length === 0)
+            return issues;
+        const byTool = new Map();
+        for (const error of errors) {
+            const tool = error.data.tool || "unknown";
+            byTool.set(tool, (byTool.get(tool) || 0) + 1);
+        }
+        for (const [tool, count] of byTool) {
+            if (count >= 2) {
+                issues.push({
+                    severity: "warning",
+                    category: "error",
+                    message: `${count} errors from tool "${tool}" — may indicate a systemic issue.`,
+                });
+            }
+        }
+        return issues;
+    }
+    /**
+     * Generate actionable recommendations from detected issues.
+     */
+    generateRecommendations(issues) {
+        const recs = [];
+        const hasLoops = issues.some((i) => i.category === "loop");
+        const hasCostHotspots = issues.some((i) => i.category === "cost");
+        const hasCacheIssues = issues.some((i) => i.category === "cache");
+        const hasErrors = issues.some((i) => i.category === "error");
+        if (hasLoops) {
+            recs.push("Consider lowering the LoopDetectionMiddleware threshold or adding argument variation hints to the system prompt.");
+        }
+        if (hasCostHotspots) {
+            recs.push("Consider compacting context earlier — some turns consumed a large share of the token budget.");
+        }
+        if (hasCacheIssues) {
+            recs.push("Review the static system prompt prefix — cache misses often indicate the prompt prefix is being mutated between turns.");
+        }
+        if (hasErrors) {
+            recs.push("Investigate recurring tool errors — consider adding fallback strategies or better error messages in tool implementations.");
+        }
+        if (issues.length === 0) {
+            recs.push("Session looks healthy! No issues detected.");
+        }
+        return recs;
+    }
+    /**
+     * Format the report as a human-readable string (for CLI output).
+     */
+    static formatReport(report) {
+        const lines = [];
+        lines.push(`\n  ◆ ${report.title}`);
+        lines.push("  ─────────────────────────────────────");
+        // Metrics
+        lines.push("\n  📊 Metrics:");
+        for (const [key, value] of Object.entries(report.metrics)) {
+            lines.push(`     ${key.padEnd(20)} ${value}`);
+        }
+        // Issues
+        if (report.issues.length > 0) {
+            lines.push("\n  ⚠ Issues:");
+            for (const issue of report.issues) {
+                const icon = issue.severity === "critical" ? "🔴" : issue.severity === "warning" ? "🟡" : "🔵";
+                lines.push(`     ${icon} [${issue.category}] ${issue.message}`);
+            }
+        }
+        // Recommendations
+        lines.push("\n  💡 Recommendations:");
+        for (const rec of report.recommendations) {
+            lines.push(`     • ${rec}`);
+        }
+        lines.push("");
+        return lines.join("\n");
+    }
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/tracing/analyzer.js.map

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

package/dist/tracing/langsmith.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LangSmith Integration — thin configuration layer.
+ *
+ * LangChain has built-in LangSmith tracing via environment variables.
+ * This module reads from JooneConfig and sets the required env vars
+ * so LangChain auto-traces to LangSmith when enabled.
+ *
+ * Required env vars for LangSmith:
+ *   LANGCHAIN_TRACING_V2=true
+ *   LANGCHAIN_API_KEY=<key>
+ *   LANGCHAIN_PROJECT=<project>  (optional, defaults to "joone")
+ */
+interface LangSmithConfig {
+    apiKey: string;
+    project?: string;
+}
+/**
+ * Enables LangSmith tracing by setting the required environment variables.
+ * LangChain will automatically detect these and send traces.
+ */
+export declare function enableLangSmith(config: LangSmithConfig): void;
+/**
+ * Disables LangSmith tracing.
+ */
+export declare function disableLangSmith(): void;
+/**
+ * Checks if LangSmith tracing is currently enabled.
+ */
+export declare function isLangSmithEnabled(): boolean;
+/**
+ * Attempts to enable LangSmith from JooneConfig values.
+ * Returns true if successfully enabled.
+ */
+export declare function tryEnableLangSmithFromConfig(config: {
+    langsmithApiKey?: string;
+    langsmithProject?: string;
+}): boolean;
+export {};