joonecli 0.1.0 → 0.2.0

package/src/tools/webSearch.ts

@@ -1,142 +0,0 @@
-import { DynamicToolInterface, ToolResult } from "./index.js";
-
-/**
- * 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: string | undefined;
-
-/**
- * Bind the Valyu API key at session start.
- */
-export function bindValyuApiKey(key: string | undefined): void {
-  _valyuApiKey = key;
-}
-
-export const WebSearchTool: DynamicToolInterface = {
-  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: {
-    query: string;
-    source?: string;
-    maxResults?: number;
-  }): Promise<ToolResult> => {
-    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: any;
-
-      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: any, i: number) =>
-            `${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: any) {
-      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 };
-    }
-  },
-};

package/src/tracing/analyzer.ts

@@ -1,265 +0,0 @@
-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 class TraceAnalyzer {
-  private trace: SessionTrace;
-
-  constructor(trace: SessionTrace) {
-    this.trace = trace;
-  }
-
-  /**
-   * Run all analysis checks and produce a full report.
-   */
-  analyze(): AnalysisReport {
-    const issues: AnalysisIssue[] = [
-      ...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(): AnalysisIssue[] {
-    const issues: AnalysisIssue[] = [];
-    const toolCalls = this.trace.events.filter((e) => e.type === "tool_call");
-
-    let consecutiveCount = 1;
-    let loopToolName: string | null = 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(): AnalysisIssue[] {
-    const issues: AnalysisIssue[] = [];
-    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(): AnalysisIssue[] {
-    const issues: AnalysisIssue[] = [];
-    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(): AnalysisIssue[] {
-    const issues: AnalysisIssue[] = [];
-    const errors = this.trace.events.filter((e) => e.type === "error");
-
-    if (errors.length === 0) return issues;
-
-    const byTool = new Map<string, number>();
-    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: AnalysisIssue[]): string[] {
-    const recs: string[] = [];
-
-    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: AnalysisReport): string {
-    const lines: string[] = [];
-
-    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");
-  }
-}

package/src/tracing/langsmith.ts

@@ -1,63 +0,0 @@
-/**
- * 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 function enableLangSmith(config: LangSmithConfig): void {
-  process.env.LANGCHAIN_TRACING_V2 = "true";
-  process.env.LANGCHAIN_API_KEY = config.apiKey;
-  process.env.LANGCHAIN_PROJECT = config.project ?? "joone";
-}
-
-/**
- * Disables LangSmith tracing.
- */
-export function disableLangSmith(): void {
-  delete process.env.LANGCHAIN_TRACING_V2;
-  delete process.env.LANGCHAIN_API_KEY;
-  delete process.env.LANGCHAIN_PROJECT;
-}
-
-/**
- * Checks if LangSmith tracing is currently enabled.
- */
-export function isLangSmithEnabled(): boolean {
-  return (
-    process.env.LANGCHAIN_TRACING_V2 === "true" &&
-    !!process.env.LANGCHAIN_API_KEY
-  );
-}
-
-/**
- * Attempts to enable LangSmith from JooneConfig values.
- * Returns true if successfully enabled.
- */
-export function tryEnableLangSmithFromConfig(config: {
-  langsmithApiKey?: string;
-  langsmithProject?: string;
-}): boolean {
-  if (!config.langsmithApiKey) return false;
-
-  enableLangSmith({
-    apiKey: config.langsmithApiKey,
-    project: config.langsmithProject,
-  });
-  return true;
-}

package/src/tracing/sessionTracer.ts

@@ -1,202 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-import { TraceEvent, TraceSummary, SessionTrace } from "./types.js";
-
-/**
- * SessionTracer — records events during an agent session and computes metrics.
- *
- * Usage:
- *   const tracer = new SessionTracer();
- *   tracer.recordLLMCall({ promptTokens: 500, completionTokens: 100, cached: true, duration: 800 });
- *   tracer.recordToolCall({ name: "bash", args: { command: "ls" }, result: "...", duration: 50 });
- *   tracer.recordError({ message: "Timeout", tool: "bash" });
- *   const summary = tracer.getSummary();
- *   tracer.save(); // writes to ~/.joone/traces/{sessionId}.json
- */
-export class SessionTracer {
-  private sessionId: string;
-  private startedAt: number;
-  private events: TraceEvent[] = [];
-
-  constructor(sessionId?: string) {
-    this.sessionId = sessionId ?? crypto.randomUUID();
-    this.startedAt = Date.now();
-  }
-
-  // ─── Recording Methods ──────────────────────────────────────────────────────
-
-  /**
-   * Record an LLM call with token usage and cache information.
-   */
-  recordLLMCall(data: {
-    promptTokens: number;
-    completionTokens: number;
-    cached: boolean;
-    duration: number;
-    model?: string;
-  }): void {
-    this.events.push({
-      type: "llm_call",
-      timestamp: Date.now(),
-      duration: data.duration,
-      data,
-    });
-  }
-
-  /**
-   * Record a tool execution.
-   */
-  recordToolCall(data: {
-    name: string;
-    args: Record<string, any>;
-    result?: string;
-    duration: number;
-    success: boolean;
-  }): void {
-    this.events.push({
-      type: "tool_call",
-      timestamp: Date.now(),
-      duration: data.duration,
-      data,
-    });
-  }
-
-  /**
-   * Record an error.
-   */
-  recordError(data: {
-    message: string;
-    tool?: string;
-    stack?: string;
-  }): void {
-    this.events.push({
-      type: "error",
-      timestamp: Date.now(),
-      data,
-    });
-  }
-
-  /**
-   * Record a context compaction event.
-   */
-  recordCompaction(data: {
-    tokensBefore: number;
-    tokensAfter: number;
-    messagesSummarized: number;
-  }): void {
-    this.events.push({
-      type: "compaction",
-      timestamp: Date.now(),
-      data,
-    });
-  }
-
-  // ─── Summary Computation ────────────────────────────────────────────────────
-
-  /**
-   * Compute aggregated metrics from all recorded events.
-   */
-  getSummary(): TraceSummary {
-    let promptTokens = 0;
-    let completionTokens = 0;
-    let cachedPromptTokens = 0;
-    let toolCallCount = 0;
-    let errorCount = 0;
-    let turnCount = 0;
-
-    for (const event of this.events) {
-      switch (event.type) {
-        case "llm_call":
-          promptTokens += event.data.promptTokens || 0;
-          completionTokens += event.data.completionTokens || 0;
-          if (event.data.cached) {
-            cachedPromptTokens += event.data.promptTokens || 0;
-          }
-          turnCount++;
-          break;
-        case "tool_call":
-          toolCallCount++;
-          break;
-        case "error":
-          errorCount++;
-          break;
-      }
-    }
-
-    const totalTokens = promptTokens + completionTokens;
-    const cacheHitRate = promptTokens > 0 ? cachedPromptTokens / promptTokens : 0;
-
-    // Rough cost estimate: ~$3/1M input tokens, ~$15/1M output tokens (Claude Sonnet pricing)
-    const totalCost =
-      (promptTokens / 1_000_000) * 3 + (completionTokens / 1_000_000) * 15;
-
-    const totalDuration = Date.now() - this.startedAt;
-
-    return {
-      totalTokens,
-      promptTokens,
-      completionTokens,
-      totalCost,
-      cacheHitRate,
-      toolCallCount,
-      errorCount,
-      totalDuration,
-      turnCount,
-    };
-  }
-
-  // ─── Export & Persistence ───────────────────────────────────────────────────
-
-  /**
-   * Returns the full session trace as a serializable object.
-   */
-  export(): SessionTrace {
-    return {
-      sessionId: this.sessionId,
-      startedAt: this.startedAt,
-      endedAt: Date.now(),
-      events: this.events,
-      summary: this.getSummary(),
-    };
-  }
-
-  /**
-   * Saves the session trace to ~/.joone/traces/{sessionId}.json.
-   */
-  save(dir?: string): string {
-    const tracesDir = dir ?? path.join(os.homedir(), ".joone", "traces");
-
-    if (!fs.existsSync(tracesDir)) {
-      fs.mkdirSync(tracesDir, { recursive: true });
-    }
-
-    // Sanitize sessionId to prevent path traversal
-    const safeSessionId = path.basename(this.sessionId);
-    const filePath = path.join(tracesDir, `${safeSessionId}.json`);
-    fs.writeFileSync(filePath, JSON.stringify(this.export(), null, 2));
-
-    return filePath;
-  }
-  /**
-   * Loads a session trace from a JSON file.
-   */
-  static load(filePath: string): SessionTrace {
-    const raw = fs.readFileSync(filePath, "utf-8");
-    return JSON.parse(raw) as SessionTrace;
-  }
-
-  // ─── Accessors ─────────────────────────────────────────────────────────────
-
-  getSessionId(): string {
-    return this.sessionId;
-  }
-
-  getEvents(): readonly TraceEvent[] {
-    return this.events;
-  }
-
-  getEventCount(): number {
-    return this.events.length;
-  }
-}