joonecli 0.1.0

package/src/__tests__/toolRouter.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ToolRouter, ToolTarget } from "../tools/router.js";
+
+describe("Tool Router", () => {
+  let router: ToolRouter;
+
+  beforeEach(() => {
+    router = new ToolRouter();
+  });
+
+  // ─── Test #20: Routes write_file to host ───
+
+  it("routes write_file to the host", () => {
+    expect(router.getTarget("write_file")).toBe(ToolTarget.HOST);
+  });
+
+  // ─── Test #21: Routes read_file to host ───
+
+  it("routes read_file to the host", () => {
+    expect(router.getTarget("read_file")).toBe(ToolTarget.HOST);
+  });
+
+  // ─── Test #22: Routes bash to sandbox ───
+
+  it("routes bash to the sandbox", () => {
+    expect(router.getTarget("bash")).toBe(ToolTarget.SANDBOX);
+  });
+
+  // ─── Test #23: Routes run_tests to sandbox ───
+
+  it("routes run_tests to the sandbox", () => {
+    expect(router.getTarget("run_tests")).toBe(ToolTarget.SANDBOX);
+  });
+
+  // ─── Test #24: Routes install_deps to sandbox ───
+
+  it("routes install_deps to the sandbox", () => {
+    expect(router.getTarget("install_deps")).toBe(ToolTarget.SANDBOX);
+  });
+
+  // ─── Test #25: Routes search_tools to host ───
+
+  it("routes search_tools to the host", () => {
+    expect(router.getTarget("search_tools")).toBe(ToolTarget.HOST);
+  });
+
+  // ─── Test #26: Unknown tools default to sandbox (safe) ───
+
+  it("defaults unknown tools to sandbox for safety", () => {
+    expect(router.getTarget("unknown_tool")).toBe(ToolTarget.SANDBOX);
+  });
+});

package/src/__tests__/tools.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { ReadFileTool, WriteFileTool } from "../tools/index.js";
+
+describe("ReadFileTool", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(process.cwd(), ".joone-tools-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ─── Test #27: Reads a normal file ───
+
+  it("reads a small file and returns its content", async () => {
+    const filePath = path.join(tmpDir, "hello.txt");
+    fs.writeFileSync(filePath, "Hello, world!", "utf-8");
+
+    const result = await ReadFileTool.execute({ path: filePath });
+
+    expect(result.content).toBe("Hello, world!");
+  });
+
+  // ─── Test #28: Returns error for non-existent file ───
+
+  it("returns an error message for a non-existent file", async () => {
+    const result = await ReadFileTool.execute({
+      path: path.join(tmpDir, "nope.txt"),
+    });
+
+    expect(result.content).toMatch(/not found/i);
+  });
+
+  // ─── Test #29: File size guardrail rejects files over 512KB ───
+
+  it("rejects files larger than 512KB with a descriptive error", async () => {
+    const filePath = path.join(tmpDir, "big.txt");
+    // Create a 600KB file
+    const bigContent = "x".repeat(600 * 1024);
+    fs.writeFileSync(filePath, bigContent, "utf-8");
+
+    const result = await ReadFileTool.execute({ path: filePath });
+
+    expect(result.content).toMatch(/too large/i);
+    expect(result.content).toMatch(/512/);
+  });
+
+  // ─── Test #30: Line range slicing works ───
+
+  it("returns only the requested line range", async () => {
+    const filePath = path.join(tmpDir, "lines.txt");
+    const lines = Array.from({ length: 20 }, (_, i) => `Line ${i + 1}`);
+    fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
+
+    const result = await ReadFileTool.execute({
+      path: filePath,
+      startLine: 5,
+      endLine: 7,
+    });
+
+    expect(result.content).toContain("5: Line 5");
+    expect(result.content).toContain("6: Line 6");
+    expect(result.content).toContain("7: Line 7");
+    expect(result.content).not.toContain("4: Line 4");
+    expect(result.content).not.toContain("8: Line 8");
+  });
+
+  // ─── Test #31: Line count guardrail truncates long files ───
+
+  it("truncates files with more than 2000 lines", async () => {
+    const filePath = path.join(tmpDir, "long.txt");
+    // Create a file with 2500 short lines (under 512KB)
+    const lines = Array.from({ length: 2500 }, (_, i) => `L${i + 1}`);
+    fs.writeFileSync(filePath, lines.join("\n"), "utf-8");
+
+    const result = await ReadFileTool.execute({ path: filePath });
+
+    expect(result.content).toMatch(/truncated at 2000 lines/i);
+    expect(result.content).toContain("1: L1");
+    expect(result.content).toContain("2000: L2000");
+    expect(result.content).not.toContain("2001: L2001");
+  });
+
+  // ─── Test #X: Security Guardrail Blocks Outside Files ───
+
+  it("blocks reading files outside the project workspace", async () => {
+    // Create a file in the OS tmp directory (guaranteed outside project workspace)
+    const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), "joone-outside-"));
+    const filePath = path.join(outsideDir, "secret.txt");
+    fs.writeFileSync(filePath, "secret token", "utf-8");
+
+    try {
+      const result = await ReadFileTool.execute({ path: filePath });
+      expect(result.isError).toBe(true);
+      expect(result.content).toMatch(/Security Error: Access Denied/i);
+      expect(result.content).toMatch(/outside the current project workspace/i);
+    } finally {
+      fs.rmSync(outsideDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("WriteFileTool", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(process.cwd(), ".joone-write-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  // ─── Test #32: Writes a file to disk ───
+
+  it("writes content to a file and confirms", async () => {
+    const filePath = path.join(tmpDir, "output.ts");
+
+    const result = await WriteFileTool.execute({
+      path: filePath,
+      content: "const x = 42;",
+    });
+
+    expect(result.content).toMatch(/file written/i);
+    expect(fs.readFileSync(filePath, "utf-8")).toBe("const x = 42;");
+  });
+
+  // ─── Test #33: Creates parent directories if needed ───
+
+  it("creates parent directories if they do not exist", async () => {
+    const filePath = path.join(tmpDir, "nested", "deep", "file.ts");
+
+    const result = await WriteFileTool.execute({
+      path: filePath,
+      content: "export {}",
+    });
+
+    expect(result.content).toMatch(/file written/i);
+    expect(fs.existsSync(filePath)).toBe(true);
+  });
+});

package/src/__tests__/tracing.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { SessionTracer } from "../tracing/sessionTracer.js";
+import {
+  enableLangSmith,
+  disableLangSmith,
+  isLangSmithEnabled,
+} from "../tracing/langsmith.js";
+import { TraceAnalyzer } from "../tracing/analyzer.js";
+import type { SessionTrace } from "../tracing/types.js";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 6a: SessionTracer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("SessionTracer", () => {
+  // ─── Test #83: Records LLM calls and computes totals ───
+
+  it("records LLM calls and computes token totals", () => {
+    const tracer = new SessionTracer("test-session-1");
+
+    tracer.recordLLMCall({ promptTokens: 500, completionTokens: 100, cached: false, duration: 800 });
+    tracer.recordLLMCall({ promptTokens: 400, completionTokens: 150, cached: true, duration: 600 });
+
+    const summary = tracer.getSummary();
+
+    expect(summary.promptTokens).toBe(900);
+    expect(summary.completionTokens).toBe(250);
+    expect(summary.totalTokens).toBe(1150);
+    expect(summary.turnCount).toBe(2);
+  });
+
+  // ─── Test #84: Records tool calls and counts them ───
+
+  it("records tool calls and counts them", () => {
+    const tracer = new SessionTracer("test-session-2");
+
+    tracer.recordToolCall({ name: "bash", args: { command: "ls" }, duration: 50, success: true });
+    tracer.recordToolCall({ name: "write_file", args: { path: "a.ts" }, duration: 30, success: true });
+    tracer.recordToolCall({ name: "bash", args: { command: "npm test" }, duration: 200, success: false });
+
+    const summary = tracer.getSummary();
+
+    expect(summary.toolCallCount).toBe(3);
+  });
+
+  // ─── Test #85: Computes cache hit rate correctly ───
+
+  it("computes cache hit rate correctly", () => {
+    const tracer = new SessionTracer("test-session-3");
+
+    // 3 calls: 2 cached, 1 not
+    tracer.recordLLMCall({ promptTokens: 100, completionTokens: 50, cached: true, duration: 100 });
+    tracer.recordLLMCall({ promptTokens: 100, completionTokens: 50, cached: true, duration: 100 });
+    tracer.recordLLMCall({ promptTokens: 100, completionTokens: 50, cached: false, duration: 100 });
+
+    const summary = tracer.getSummary();
+
+    // 200 cached out of 300 total prompt tokens = 66.7%
+    expect(summary.cacheHitRate).toBeCloseTo(0.667, 2);
+  });
+
+  // ─── Test #86: export() returns valid SessionTrace ───
+
+  it("export() returns a valid SessionTrace", () => {
+    const tracer = new SessionTracer("export-test");
+
+    tracer.recordLLMCall({ promptTokens: 100, completionTokens: 50, cached: true, duration: 200 });
+    tracer.recordError({ message: "Timeout", tool: "bash" });
+
+    const trace = tracer.export();
+
+    expect(trace.sessionId).toBe("export-test");
+    expect(trace.startedAt).toBeGreaterThan(0);
+    expect(trace.endedAt).toBeGreaterThanOrEqual(trace.startedAt);
+    expect(trace.events).toHaveLength(2);
+    expect(trace.summary.turnCount).toBe(1);
+    expect(trace.summary.errorCount).toBe(1);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 6b: LangSmith Integration
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("LangSmith Integration", () => {
+  afterEach(() => {
+    disableLangSmith();
+  });
+
+  // ─── Test #87: enableLangSmith sets correct env vars ───
+
+  it("sets the correct environment variables", () => {
+    enableLangSmith({ apiKey: "test-key-123", project: "my-project" });
+
+    expect(process.env.LANGCHAIN_TRACING_V2).toBe("true");
+    expect(process.env.LANGCHAIN_API_KEY).toBe("test-key-123");
+    expect(process.env.LANGCHAIN_PROJECT).toBe("my-project");
+    expect(isLangSmithEnabled()).toBe(true);
+  });
+
+  // ─── Test #88: disableLangSmith clears env vars ───
+
+  it("disableLangSmith clears the environment variables", () => {
+    enableLangSmith({ apiKey: "test-key" });
+    disableLangSmith();
+
+    expect(process.env.LANGCHAIN_TRACING_V2).toBeUndefined();
+    expect(isLangSmithEnabled()).toBe(false);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 6c: TraceAnalyzer
+// ═══════════════════════════════════════════════════════════════════════════════
+
+describe("TraceAnalyzer", () => {
+  const createTrace = (overrides?: Partial<SessionTrace>): SessionTrace => ({
+    sessionId: "test",
+    startedAt: Date.now() - 10000,
+    endedAt: Date.now(),
+    events: [],
+    summary: {
+      totalTokens: 1000,
+      promptTokens: 700,
+      completionTokens: 300,
+      totalCost: 0.006,
+      cacheHitRate: 0.8,
+      toolCallCount: 5,
+      errorCount: 0,
+      totalDuration: 10000,
+      turnCount: 5,
+    },
+    ...overrides,
+  });
+  // ─── Test #89: Detects loop patterns ───
+
+  it("detects doom-loop patterns in tool calls", () => {
+    const trace = createTrace({
+      events: [
+        { type: "tool_call", timestamp: 1, data: { name: "bash", args: { command: "ls" } } },
+        { type: "tool_call", timestamp: 2, data: { name: "bash", args: { command: "ls" } } },
+        { type: "tool_call", timestamp: 3, data: { name: "bash", args: { command: "ls" } } },
+      ],
+    });
+
+    const analyzer = new TraceAnalyzer(trace);
+    const report = analyzer.analyze();
+
+    const loopIssues = report.issues.filter((i) => i.category === "loop");
+    expect(loopIssues.length).toBeGreaterThan(0);
+    expect(loopIssues[0].severity).toBe("critical");
+  });
+
+  // ─── Test #90: Detects cost hotspots ───
+
+  it("flags turns consuming >20% of total tokens", () => {
+    const trace = createTrace({
+      summary: {
+        ...createTrace().summary,
+        totalTokens: 1000,
+      },
+      events: [
+        { type: "llm_call", timestamp: 1, data: { promptTokens: 300, completionTokens: 100, cached: false } },
+        { type: "llm_call", timestamp: 2, data: { promptTokens: 100, completionTokens: 50, cached: true } },
+      ],
+    });
+
+    const analyzer = new TraceAnalyzer(trace);
+    const report = analyzer.analyze();
+
+    const costIssues = report.issues.filter((i) => i.category === "cost");
+    expect(costIssues.length).toBeGreaterThan(0);
+  });
+
+  // ─── Test #91: Warns on low cache hit rate ───
+
+  it("warns when cache hit rate is below 70%", () => {
+    const trace = createTrace({
+      summary: {
+        ...createTrace().summary,
+        cacheHitRate: 0.5,
+        turnCount: 5,
+      },
+    });
+
+    const analyzer = new TraceAnalyzer(trace);
+    const report = analyzer.analyze();
+
+    const cacheIssues = report.issues.filter((i) => i.category === "cache");
+    expect(cacheIssues.length).toBe(1);
+    expect(cacheIssues[0].message).toContain("50.0%");
+  });
+});

package/src/agents/agentRegistry.ts

@@ -0,0 +1,69 @@
+/**
+ * Agent Registry
+ *
+ * Central registry for named sub-agents. The registry enables:
+ * - Decoupled agent development (add agents without touching the main loop)
+ * - Prompt injection (registry summary included in the main agent's system prompt)
+ * - Lookup by name for the spawn_agent tool
+ */
+
+import { AgentSpec } from "./agentSpec.js";
+
+export class AgentRegistry {
+  private agents: Map<string, AgentSpec> = new Map();
+
+  /**
+   * Register a new agent spec. Overwrites if name already exists.
+   */
+  register(spec: AgentSpec): void {
+    this.agents.set(spec.name, spec);
+  }
+
+  /**
+   * Look up an agent by name.
+   */
+  get(name: string): AgentSpec | undefined {
+    return this.agents.get(name);
+  }
+
+  /**
+   * Returns all registered agent specs.
+   */
+  getAll(): AgentSpec[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * Returns all registered agent names.
+   */
+  getNames(): string[] {
+    return Array.from(this.agents.keys());
+  }
+
+  /**
+   * Returns true if an agent with the given name exists.
+   */
+  has(name: string): boolean {
+    return this.agents.has(name);
+  }
+
+  /**
+   * Generates a summary of all available agents, formatted for injection
+   * into the main agent's system prompt.
+   */
+  getSummary(): string {
+    if (this.agents.size === 0) {
+      return "No sub-agents are currently registered.";
+    }
+
+    const lines = ["Available sub-agents (use spawn_agent tool to invoke):\n"];
+
+    for (const spec of this.agents.values()) {
+      const tools = spec.tools ? ` [tools: ${spec.tools.join(", ")}]` : " [all tools]";
+      const turns = spec.maxTurns ?? 10;
+      lines.push(`  • ${spec.name}: ${spec.description}${tools} (max ${turns} turns)`);
+    }
+
+    return lines.join("\n");
+  }
+}

package/src/agents/agentSpec.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent Specification
+ *
+ * Defines the shape of a sub-agent: its identity, capabilities, constraints,
+ * and tools. This enables decoupled agent development — new agents can be
+ * added to the registry without modifying the main agent or harness.
+ */
+
+/**
+ * Describes a named sub-agent with a purpose-tuned configuration.
+ */
+export interface AgentSpec {
+  /** Unique name (e.g., "script_runner", "code_reviewer"). */
+  name: string;
+
+  /** Human-readable description included in the main agent's prompt. */
+  description: string;
+
+  /** Dedicated system prompt for this sub-agent. */
+  systemPrompt: string;
+
+  /** Restrict to specific tool names. If omitted, all main-agent tools are available. */
+  tools?: string[];
+
+  /** Maximum turns before the sub-agent is forcibly stopped (doom-loop protection). Default: 10. */
+  maxTurns?: number;
+
+  /** Override model for this agent (default: FAST_MODEL_DEFAULTS from same provider). */
+  model?: string;
+
+  /** Permission behavior for this agent. */
+  permissionMode?: "auto" | "ask_all";
+}
+
+/**
+ * Structured result returned by a sub-agent after completing (or failing) a task.
+ * Only this result is injected into the main agent's history — the sub-agent's
+ * full conversation is discarded to save context.
+ */
+export interface SubAgentResult {
+  /** The agent name from AgentSpec. */
+  agentName: string;
+
+  /** The original task description. */
+  taskDescription: string;
+
+  /** Outcome status. */
+  outcome: "success" | "failure" | "partial";
+
+  /** The final text output from the sub-agent. */
+  result: string;
+
+  /** Files created, modified, or deleted during the sub-task. */
+  filesModified: string[];
+
+  /** Total tool calls executed. */
+  toolCallCount: number;
+
+  /** Approximate token usage. */
+  tokenUsage: { prompt: number; completion: number };
+
+  /** Wall-clock duration in milliseconds. */
+  duration: number;
+
+  /** Number of turns the sub-agent ran. */
+  turnsUsed: number;
+}

package/src/agents/builtinAgents.ts

@@ -0,0 +1,142 @@
+/**
+ * Built-in Agent Specs
+ *
+ * Pre-configured sub-agents for common coding tasks. Each agent has a
+ * purpose-tuned system prompt and restricted tool access. This enables
+ * decoupled agent development — new agents are added here without
+ * touching the main agent or harness.
+ */
+
+import { AgentSpec } from "./agentSpec.js";
+import { AgentRegistry } from "./agentRegistry.js";
+
+// ─── Script Runner ──────────────────────────────────────────────────────────────
+
+export const ScriptRunnerAgent: AgentSpec = {
+  name: "script_runner",
+  description: "Execute and test scripts, return stdout/stderr and exit codes",
+  systemPrompt: `You are a script execution agent. Your task is to run scripts and commands, capturing their output.
+
+Rules:
+- Run the commands/scripts as specified in the task
+- Capture ALL stdout and stderr output
+- Report the exit code
+- If the script fails, analyze the error and report the likely cause
+- Do NOT modify any files unless explicitly asked
+- Summarize the results clearly at the end`,
+  tools: ["bash", "read_file"],
+  maxTurns: 8,
+  permissionMode: "auto",
+};
+
+// ─── Code Reviewer ──────────────────────────────────────────────────────────────
+
+export const CodeReviewerAgent: AgentSpec = {
+  name: "code_reviewer",
+  description: "Review code changes and suggest improvements",
+  systemPrompt: `You are a code review agent. Your task is to analyze code files and provide quality feedback.
+
+Rules:
+- Read the specified files and analyze them
+- Look for: bugs, security issues, code smells, missing error handling, performance issues
+- Check style consistency and naming conventions
+- Provide specific, actionable suggestions with line numbers
+- Rate overall quality: 1-5 stars
+- Be constructive and specific — avoid vague feedback`,
+  tools: ["read_file", "bash"],
+  maxTurns: 6,
+  permissionMode: "auto",
+};
+
+// ─── Test Runner ────────────────────────────────────────────────────────────────
+
+export const TestRunnerAgent: AgentSpec = {
+  name: "test_runner",
+  description: "Run test suites, diagnose failures, and suggest fixes",
+  systemPrompt: `You are a test execution agent. Your task is to run tests and analyze the results.
+
+Rules:
+- Execute the specified test command(s)
+- Parse test output to identify passing, failing, and skipped tests
+- For failures: read the relevant source files to diagnose the cause
+- Suggest specific fixes for failing tests
+- Report: total passes, failures, skips, and coverage if available
+- If asked to fix tests, you may write corrected test files`,
+  tools: ["bash", "read_file", "write_file"],
+  maxTurns: 10,
+  permissionMode: "auto",
+};
+
+// ─── File Analyst ───────────────────────────────────────────────────────────────
+
+export const FileAnalystAgent: AgentSpec = {
+  name: "file_analyst",
+  description: "Analyze project structure, find patterns, count metrics",
+  systemPrompt: `You are a file analysis agent. Your task is to analyze the project structure and report findings.
+
+Rules:
+- Use bash commands (find, grep, wc, etc.) to analyze the project
+- Report: file counts by type, line counts, directory structure
+- Identify patterns: naming conventions, common imports, dependency usage
+- Highlight anything unusual or noteworthy
+- Present results in a clear, structured format`,
+  tools: ["bash", "read_file"],
+  maxTurns: 6,
+  permissionMode: "auto",
+};
+
+// ─── Security Auditor ───────────────────────────────────────────────────────────
+
+export const SecurityAuditorAgent: AgentSpec = {
+  name: "security_auditor",
+  description: "Run security scans and report vulnerabilities",
+  systemPrompt: `You are a security audit agent. Your task is to check for security issues in the codebase.
+
+Rules:
+- Check for: hardcoded secrets, SQL injection, XSS, insecure dependencies
+- Run available security scanning tools
+- Read configuration files for security misconfigurations
+- Rate severity: Critical, High, Medium, Low, Info
+- Provide remediation steps for each finding
+- Do NOT expose actual secret values in your report`,
+  tools: ["bash", "read_file"],
+  maxTurns: 8,
+  permissionMode: "auto",
+};
+
+// ─── Browser Agent ──────────────────────────────────────────────────────────────
+
+export const BrowserAgent: AgentSpec = {
+  name: "browser_agent",
+  description: "Browse URLs, extract content, analyze web pages",
+  systemPrompt: `You are a web browsing agent. Your task is to access URLs and extract information.
+
+Rules:
+- Navigate to the specified URL(s)
+- Extract text content, titles, metadata as requested
+- Summarize the page content clearly
+- Report any errors (404, timeouts, etc.)
+- Do NOT submit forms or make purchases unless explicitly instructed
+- If the page requires authentication, report that you cannot access it`,
+  tools: ["bash"],
+  maxTurns: 6,
+  permissionMode: "auto",
+};
+
+// ─── Registry Factory ───────────────────────────────────────────────────────────
+
+/**
+ * Creates an AgentRegistry pre-loaded with all built-in agents.
+ */
+export function createDefaultAgentRegistry(): AgentRegistry {
+  const registry = new AgentRegistry();
+
+  registry.register(ScriptRunnerAgent);
+  registry.register(CodeReviewerAgent);
+  registry.register(TestRunnerAgent);
+  registry.register(FileAnalystAgent);
+  registry.register(SecurityAuditorAgent);
+  registry.register(BrowserAgent);
+
+  return registry;
+}