error-trace-debugger 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,96 @@
+# error-trace-debugger
+
+CLI agent that ingests logs/stack traces, investigates a codebase, and outputs a report with a
+suggested fix and (when possible) a unified patch.
+
+## Install
+
+```bash
+npm install -g error-trace-debugger
+```
+
+Or run without installing:
+
+```bash
+npx error-trace-debugger analyze --help
+```
+
+## Usage
+
+### Analyze a logs file
+
+```bash
+error-trace-debugger analyze --logs ./error.log
+```
+
+### Analyze an inline stack trace
+
+```bash
+error-trace-debugger analyze --stack "TypeError: boom\n    at run (/repo/src/index.js:10:5)"
+```
+
+### Pipe logs over stdin
+
+```bash
+cat ./error.log | error-trace-debugger analyze --stdin
+```
+
+### Target a specific repo
+
+```bash
+error-trace-debugger analyze --logs ./error.log --repo ../my-repo
+```
+
+## Scope (single repo)
+
+`error-trace-debugger` analyzes **one repo/workspace at a time**.
+By default it uses the current working directory; you can override with `--repo <path>`.
+
+### Output formats
+
+```bash
+error-trace-debugger analyze --logs ./error.log --format md
+error-trace-debugger analyze --logs ./error.log --format text
+error-trace-debugger analyze --logs ./error.log --format json
+```
+
+If you keep the default `--format md` and do not pass `--out`, the CLI writes the full
+Markdown report to `error-trace-debugger-report.md` in the target repo root, and the terminal shows
+only a short “check out the file” message.
+
+### Write report + patch to files
+
+```bash
+error-trace-debugger analyze --logs ./error.log --out ./report.md --patch-out ./fix.diff
+git apply ./fix.diff
+```
+
+### Run tests (optional)
+
+```bash
+error-trace-debugger analyze --logs ./error.log --run-tests
+error-trace-debugger analyze --logs ./error.log --run-tests --test-command "npm test"
+```
+
+### Engine: v1 (default) vs v2 (LangGraph)
+
+- **v1** (default): heuristic loop (parse → search → diff → optional tests). No LLM.
+- **v2**: LangGraph state machine with the same tools plus LLM-backed patch proposal. Use `--engine v2` and set `OPENAI_API_KEY` (or `--api-key-env VAR`). Optional: `--provider openai`, `--model <name>`, `--max-tool-calls`, `--max-files-read`, `--max-bytes-read`.
+
+```bash
+error-trace-debugger analyze --engine v2 --logs ./error.log --repo .
+```
+
+## What it does (v1)
+- **Log analyzer**: parses common Node/Jest stack traces into structured frames.
+- **Code search**: uses ripgrep if available (otherwise scans within safe budgets).
+- **Diff generator**: emits a unified patch when it has concrete edits to apply.
+  If no edits are produced, the `Patch` section may be empty.
+- **Test runner**: runs tests (optional) and summarizes failing output.
+
+The orchestrator iteratively:
+`logs → hypothesis → code search → patch proposal → (optional) tests`.
+
+## Notes
+- v1 focuses on investigation + reporting. Patch generation is supported but requires a fix plan with edits (a future version can add an LLM-backed patch proposer).
+- PR creation is intentionally out of scope for v1.

package/bin/error-trace-debugger

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run_cli } from "../src/cli/deep_agent.js";
+
+await run_cli(process.argv);

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "error-trace-debugger",
+  "version": "0.1.0",
+  "description": "CLI agent that analyzes logs, investigates a repo, suggests fixes, and outputs a patch.",
+  "type": "module",
+  "bin": {
+    "error-trace-debugger": "bin/error-trace-debugger"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "node ./src/cli/deep_agent.js --help"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.34",
+    "@langchain/langgraph": "^0.2.74",
+    "@langchain/openai": "^0.3.5",
+    "commander": "^14.0.0",
+    "diff": "^8.0.0",
+    "execa": "^9.6.0",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5"
+  },
+  "license": "MIT"
+}

package/src/adapters/llm_client_langchain.js

@@ -0,0 +1,38 @@
+import { ChatOpenAI } from "@langchain/openai";
+
+const DEFAULT_PROVIDER = "openai";
+const DEFAULT_MODEL = "gpt-4.1-mini";
+
+export function createLlmClient({
+  provider = DEFAULT_PROVIDER,
+  model = DEFAULT_MODEL,
+  apiKeyEnv
+}) {
+  const provider_name = provider || DEFAULT_PROVIDER;
+  if (provider_name !== "openai") {
+    throw new Error(`Unsupported provider for v2 engine: ${provider_name}`);
+  }
+
+  const env_var_name = apiKeyEnv || "OPENAI_API_KEY";
+  const api_key = process.env[env_var_name];
+  if (!api_key) {
+    throw new Error(
+      `Missing API key: set ${env_var_name} in the environment to use --engine v2.`
+    );
+  }
+
+  const chat_model = new ChatOpenAI({
+    apiKey: api_key,
+    model: model || DEFAULT_MODEL,
+    temperature: 0
+  });
+
+  return {
+    async generateJson(prompt) {
+      const response = await chat_model.invoke(prompt);
+      const text = response.content?.[0]?.text ?? String(response.content ?? "");
+      return text;
+    }
+  };
+}
+

package/src/agents/agent_graph.js

@@ -0,0 +1,228 @@
+import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
+
+const investigationStepsReducer = (left, right) => {
+  const items = Array.isArray(right) ? right : right ? [right] : [];
+  return (left || []).concat(items);
+};
+
+export const DeepAgentState = Annotation.Root({
+  repo_path: Annotation(),
+  raw_logs: Annotation(),
+  log_artifact: Annotation(),
+  search_matches: Annotation(),
+  file_contexts: Annotation(),
+  hypothesis: Annotation(),
+  fix_plan: Annotation(),
+  patch_text: Annotation(),
+  validation_result: Annotation(),
+  iteration_index: Annotation(),
+  investigation_steps: Annotation({
+    reducer: investigationStepsReducer,
+    default: () => []
+  }),
+  run_tests: Annotation(),
+  test_command: Annotation(),
+  max_iterations: Annotation(),
+  budget_ms: Annotation(),
+  started_at_ms: Annotation(),
+  should_iterate: Annotation()
+});
+
+export function createAgentGraph({ tools, options }) {
+  const {
+    max_iterations = 5,
+    budget_ms,
+    run_tests = false,
+    test_command,
+    max_files_read = 32
+  } = options || {};
+
+  async function parseLogs(state) {
+    const log_artifact = await tools.log_analyzer.run({
+      raw_logs: state.raw_logs,
+      repo_path: state.repo_path
+    });
+    return {
+      log_artifact,
+      investigation_steps: [
+        { tool_name: "log_analyzer", summary: "Parsed logs.", output: log_artifact }
+      ]
+    };
+  }
+
+  function buildSearchQueries(log_artifact) {
+    const queries = new Set();
+    if (log_artifact?.error_name) queries.add(log_artifact.error_name);
+    if (log_artifact?.error_message) {
+      String(log_artifact.error_message)
+        .split(/[^a-zA-Z0-9_./-]+/g)
+        .map((t) => t.trim())
+        .filter(Boolean)
+        .slice(0, 20)
+        .forEach((t) => queries.add(t));
+    }
+    (log_artifact?.frames || []).slice(0, 10).forEach((frame) => {
+      if (frame.function_name) queries.add(frame.function_name);
+      if (frame.file_path) {
+        const basename = frame.file_path.split("/").pop();
+        if (basename) queries.add(basename);
+      }
+    });
+    return [...queries].filter((q) => q && q.trim().length >= 3).slice(0, 25);
+  }
+
+  async function searchCode(state) {
+    const queries = buildSearchQueries(state.log_artifact);
+    const search_result = await tools.code_search.run({
+      repo_path: state.repo_path,
+      queries
+    });
+    return {
+      search_matches: search_result.matches || [],
+      investigation_steps: [
+        {
+          tool_name: "code_search",
+          summary: "Searched codebase.",
+          output: { queries, match_count: (search_result.matches || []).length }
+        }
+      ]
+    };
+  }
+
+  function dedupeFilePaths(paths) {
+    const seen = new Set();
+    return (paths || []).filter((p) => p && !seen.has(p) && seen.add(p));
+  }
+
+  async function readFiles(state) {
+    const paths = dedupeFilePaths(
+      (state.search_matches || []).map((m) => m.file_path)
+    ).slice(0, max_files_read);
+    const file_contexts = [];
+    for (const file_path of paths) {
+      const result = await tools.read_file.run({
+        file_path,
+        start_line: 1,
+        end_line: 200
+      });
+      if (result.ok) file_contexts.push(result);
+    }
+    return {
+      file_contexts,
+      investigation_steps: [
+        {
+          tool_name: "read_file",
+          summary: "Read relevant files.",
+          output: { file_count: file_contexts.length }
+        }
+      ]
+    };
+  }
+
+  async function proposePatch(state) {
+    const fix_plan = await tools.patch_proposer.run({
+      log_artifact: state.log_artifact,
+      search_matches: state.search_matches || [],
+      file_contexts: state.file_contexts || []
+    });
+    const hypothesis = {
+      claim: fix_plan.summary || "LLM proposed fix.",
+      confidence: 0.7,
+      predicted_locations: (fix_plan.citations || []).slice(0, 5)
+    };
+    return {
+      fix_plan,
+      hypothesis,
+      investigation_steps: [
+        {
+          tool_name: "patch_proposer",
+          summary: "LLM proposed fix plan.",
+          output: { edit_count: (fix_plan.edits || []).length }
+        }
+      ]
+    };
+  }
+
+  async function generateDiff(state) {
+    const diff_result = await tools.diff_generator.run({
+      repo_path: state.repo_path,
+      log_artifact: state.log_artifact,
+      hypothesis: state.hypothesis,
+      search_matches: state.search_matches || [],
+      fix_plan_overrides: state.fix_plan
+    });
+    return {
+      patch_text: diff_result.patch_text || "",
+      investigation_steps: [
+        {
+          tool_name: "diff_generator",
+          summary: "Generated patch.",
+          output: { has_patch: Boolean(diff_result.patch_text) }
+        }
+      ]
+    };
+  }
+
+  async function runTests(state) {
+    const validation_result = await tools.test_runner.run({
+      repo_path: state.repo_path,
+      test_command: state.test_command
+    });
+    return {
+      validation_result,
+      investigation_steps: [
+        {
+          tool_name: "test_runner",
+          summary: "Ran tests.",
+          output: {
+            ok: validation_result.ok,
+            exit_code: validation_result.exit_code
+          }
+        }
+      ]
+    };
+  }
+
+  function assess(state) {
+    const iteration_index = (state.iteration_index ?? 0) + 1;
+    const tests_ok = state.validation_result?.ok === true;
+    const has_patch =
+      state.patch_text && String(state.patch_text).trim().length > 0;
+    const over_iterations = iteration_index >= (state.max_iterations ?? 5);
+    const over_budget =
+      Number.isFinite(state.budget_ms) &&
+      Date.now() - (state.started_at_ms ?? 0) >= state.budget_ms;
+    const should_iterate =
+      !tests_ok &&
+      !over_iterations &&
+      !over_budget &&
+      !has_patch;
+    return {
+      iteration_index,
+      should_iterate
+    };
+  }
+
+  const graph = new StateGraph(DeepAgentState)
+    .addNode("parseLogs", parseLogs)
+    .addNode("searchCode", searchCode)
+    .addNode("readFiles", readFiles)
+    .addNode("proposePatch", proposePatch)
+    .addNode("generateDiff", generateDiff)
+    .addNode("runTests", runTests)
+    .addNode("assess", assess)
+    .addEdge(START, "parseLogs")
+    .addEdge("parseLogs", "searchCode")
+    .addEdge("searchCode", "readFiles")
+    .addEdge("readFiles", "proposePatch")
+    .addEdge("proposePatch", "generateDiff")
+    .addConditionalEdges("generateDiff", (state) => {
+      return state.run_tests ? "runTests" : "assess";
+    })
+    .addEdge("runTests", "assess")
+    .addConditionalEdges("assess", (state) => {
+      return state.should_iterate ? "searchCode" : END;
+    });
+
+  return graph.compile();
+}

package/src/agents/deep_agent_v2.js

@@ -0,0 +1,74 @@
+import { LogAnalyzerTool } from "../tools/LogAnalyzerTool.js";
+import { CodeSearchTool } from "../tools/CodeSearchTool.js";
+import { GitDiffTool } from "../tools/GitDiffTool.js";
+import { TestRunnerTool } from "../tools/TestRunnerTool.js";
+import { ReadFileTool } from "../tools/ReadFileTool.js";
+import { PatchProposerTool } from "../tools/PatchProposerTool.js";
+import { createLlmClient } from "../adapters/llm_client_langchain.js";
+import { createAgentGraph } from "./agent_graph.js";
+
+export async function run_deep_agent_v2({ repo_path, raw_logs, cli_options }) {
+  const log_analyzer = new LogAnalyzerTool({ repo_path });
+  const code_search = new CodeSearchTool({ repo_path });
+  const diff_generator = new GitDiffTool({ repo_path });
+  const test_runner = new TestRunnerTool({ repo_path });
+
+  const read_file = new ReadFileTool({
+    repo_path,
+    max_bytes_per_file: cli_options.maxBytesRead || undefined,
+    max_total_bytes: cli_options.maxBytesRead || undefined
+  });
+
+  const llm_client = createLlmClient({
+    provider: cli_options.provider,
+    model: cli_options.model,
+    apiKeyEnv: cli_options.apiKeyEnv
+  });
+  const patch_proposer = new PatchProposerTool({ llm: llm_client });
+
+  const tools = {
+    log_analyzer,
+    code_search,
+    read_file,
+    patch_proposer,
+    diff_generator,
+    test_runner
+  };
+
+  const options = {
+    max_iterations: cli_options.maxIterations ?? 5,
+    budget_ms: cli_options.budgetMs,
+    run_tests: Boolean(cli_options.runTests),
+    test_command: cli_options.testCommand,
+    max_files_read: cli_options.maxFilesRead ?? 32
+  };
+
+  const graph = createAgentGraph({ tools, options });
+
+  const initial_state = {
+    repo_path,
+    raw_logs,
+    run_tests: options.run_tests,
+    test_command: options.test_command,
+    max_iterations: options.max_iterations,
+    budget_ms: options.budget_ms,
+    started_at_ms: Date.now(),
+    iteration_index: 0
+  };
+
+  const final_state = await graph.invoke(initial_state);
+
+  return {
+    repo_path: final_state.repo_path ?? repo_path,
+    raw_logs: final_state.raw_logs ?? raw_logs,
+    log_artifact: final_state.log_artifact,
+    hypotheses: final_state.hypothesis ? [final_state.hypothesis] : [],
+    investigation_steps: final_state.investigation_steps ?? [],
+    fix_plan: final_state.fix_plan,
+    patch_text: final_state.patch_text ?? "",
+    validation_result: final_state.validation_result ?? null,
+    has_error: Boolean(
+      final_state.validation_result && !final_state.validation_result.ok
+    )
+  };
+}

package/src/cli/deep_agent.js

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+import process from "node:process";
+import { run_analyze_command } from "./run_analyze_command.js";
+
+export async function run_cli(argv) {
+  const program = new Command();
+
+  program.name("error-trace-debugger");
+  program.description(
+    "Analyze logs/stack traces, investigate a repo, and output suggested fixes + a patch."
+  );
+  program.version("0.1.0");
+
+  program
+    .command("analyze")
+    .description("Analyze logs and propose a fix patch.")
+    .option("--logs <path>", "Path to a logs file")
+    .option("--stack <string>", "Inline stack trace / error text")
+    .option("--stdin", "Read logs from stdin")
+    .option("--repo <path>", "Repo path (default: cwd)")
+    .option("--max-iterations <n>", "Max investigation iterations", to_int, 5)
+    .option("--budget-ms <n>", "Time budget in ms", to_int)
+    .option("--engine <engine>", "Engine: v1|v2", "v1")
+    .option("--provider <provider>", "LLM provider for v2 (e.g. openai)")
+    .option("--model <model>", "LLM model name for v2")
+    .option(
+      "--api-key-env <name>",
+      "Environment variable name that holds the LLM API key"
+    )
+    .option("--max-tool-calls <n>", "Max tool calls for v2", to_int, 32)
+    .option("--max-files-read <n>", "Max files the agent may read", to_int, 64)
+    .option(
+      "--max-bytes-read <n>",
+      "Max total bytes the agent may read",
+      to_int,
+      5 * 1024 * 1024
+    )
+    .option("--format <format>", "Output format: md|json|text", "md")
+    .option("--out <path>", "Write report to path")
+    .option("--patch-out <path>", "Write patch (unified diff) to path")
+    .option("--run-tests", "Run tests after proposing a patch", false)
+    .option(
+      "--test-command <cmd>",
+      "Explicit test command (default: auto-detect)"
+    )
+    .action(async (options) => {
+      const exit_code = await run_analyze_command({
+        options,
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr
+      });
+      process.exitCode = exit_code;
+    });
+
+  program.showHelpAfterError(true);
+  await program.parseAsync(argv);
+}
+
+function to_int(value) {
+  const parsed_number = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed_number)) {
+    throw new Error(`Expected integer, got: ${value}`);
+  }
+  return parsed_number;
+}
+

package/src/cli/run_analyze_command.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import process from "node:process";
+import { read_logs_input } from "./stdin_logs.js";
+import { Orchestrator } from "../core/Orchestrator.js";
+import { create_default_tools } from "../tools/create_default_tools.js";
+import { write_report } from "../core/report_writer.js";
+import { write_text_file } from "../core/write_text_file.js";
+
+export async function run_analyze_command({ options, stdin, stdout, stderr }) {
+  const repo_path = options.repo ? path.resolve(options.repo) : process.cwd();
+  const logs_result = await read_logs_input({
+    logs_path: options.logs,
+    stack_text: options.stack,
+    use_stdin: Boolean(options.stdin),
+    stdin
+  });
+
+  if (!logs_result.ok) {
+    stderr.write(`${logs_result.error}\n`);
+    return 2;
+  }
+
+  const engine_name = options.engine || "v1";
+  const final_report =
+    engine_name === "v2"
+      ? await (await import("../agents/deep_agent_v2.js")).run_deep_agent_v2({
+          repo_path,
+          raw_logs: logs_result.value,
+          cli_options: options
+        })
+      : await run_v1_engine({
+          repo_path,
+          raw_logs: logs_result.value,
+          options
+        });
+
+  const report_text = write_report(final_report, { format: options.format });
+
+  const md_report_text = write_report(final_report, { format: "md" });
+  const should_suppress_stdout =
+    !options.out && options.format === "md" && md_report_text.length > 0;
+  const should_print_checkout_message =
+    (should_suppress_stdout || Boolean(options.out)) && !options.apply;
+
+  if (should_suppress_stdout) {
+    const default_md_path = path.join(repo_path, "error-trace-debugger-report.md");
+    await write_text_file(default_md_path, md_report_text);
+    stdout.write(
+      `Report written to: error-trace-debugger-report.md (${default_md_path})\n`
+    );
+    stdout.write("Please check out that file for the full output.\n");
+  } else if (options.out) {
+    const out_path = path.resolve(options.out);
+    await write_text_file(out_path, report_text);
+    if (should_print_checkout_message) {
+      const file_name = path.basename(out_path);
+      stdout.write(`Report written to: ${file_name} (${out_path})\n`);
+      stdout.write("Please check out that file for the full output.\n");
+    }
+  } else {
+    stdout.write(report_text);
+    if (!report_text.endsWith("\n")) stdout.write("\n");
+  }
+
+  if (options.patchOut && final_report.patch_text) {
+    await write_text_file(path.resolve(options.patchOut), final_report.patch_text);
+  }
+
+  return final_report.has_error ? 1 : 0;
+}
+
+async function run_v1_engine({ repo_path, raw_logs, options }) {
+  const tools = create_default_tools({ repo_path });
+  const orchestrator = new Orchestrator({
+    repo_path,
+    tools,
+    max_iterations: options.maxIterations,
+    budget_ms: options.budgetMs,
+    run_tests: Boolean(options.runTests),
+    test_command: options.testCommand
+  });
+
+  return await orchestrator.run({ raw_logs });
+}
+

package/src/cli/stdin_logs.js

@@ -0,0 +1,44 @@
+import fs from "node:fs/promises";
+
+export async function read_logs_input({
+  logs_path,
+  stack_text,
+  use_stdin,
+  stdin
+}) {
+  const has_logs_path = Boolean(logs_path);
+  const has_stack_text = typeof stack_text === "string" && stack_text.trim().length > 0;
+  const has_stdin = Boolean(use_stdin);
+
+  const selected_count = Number(has_logs_path) + Number(has_stack_text) + Number(has_stdin);
+  if (selected_count !== 1) {
+    return {
+      ok: false,
+      error: "Provide exactly one of --logs, --stack, or --stdin."
+    };
+  }
+
+  if (has_logs_path) {
+    const raw_text = await fs.readFile(logs_path, "utf8");
+    return { ok: true, value: raw_text };
+  }
+
+  if (has_stack_text) return { ok: true, value: stack_text };
+
+  const stdin_text = await read_all_stdin(stdin);
+  if (stdin_text.trim().length === 0) {
+    return { ok: false, error: "No input read from stdin." };
+  }
+  return { ok: true, value: stdin_text };
+}
+
+function read_all_stdin(stdin) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => chunks.push(chunk));
+    stdin.on("end", () => resolve(chunks.join("")));
+    stdin.on("error", (error) => reject(error));
+  });
+}
+