Krometrail

Appearance

Changelog ​

v0.2.20 ​

Fixes ​

  • Chrome no longer opens two tabs on launch — startMcpServer() was called unconditionally on module import, creating two MCP servers on the same stdio transport; every tool call was dispatched twice, causing Chrome to spawn twice. Fixed with import.meta.main guard.
  • Chrome launch no longer fails with false "exited immediately" error — on Linux, Chrome forks and the original PID exits while Chrome continues under a new PID; waitForChrome now checks CDP availability before throwing ChromeEarlyExitError
  • browser.start is now idempotent — concurrent or duplicate calls return the existing session info instead of erroring; in-flight starts are coalesced onto the same promise
  • Binary fallback chain prefers direct Chrome binary — /opt/google/chrome/chrome is now tried before wrapper scripts that may delegate to an existing instance and exit immediately
  • Error-specific recovery guidance for Chrome launch failures — ChromeEarlyExitError, CDPConnectionError, and ChromeNotFoundError now produce targeted messages instead of a generic 3-option hint; removed dangerous pkill -f chrome suggestion
  • consoleLevels filter no longer excludes page_error events — the filter now applies only to console-type events; page_error events pass through when included in event_types
  • Stale recorder cleaned up on retry — a failed browser.start no longer leaves a broken recorder in daemon state; subsequent starts clean up before creating a new session

Internal ​

  • Added 10 unit tests covering Chrome launch resilience behavioral contracts
  • Design doc: docs/designs/chrome-launch-resilience.md

v0.2.19 ​

Fixes ​

  • session_overview(around_marker:) marker lookup fixed — extractMarkerId was matching the session UUID instead of the label-based marker ID (e.g., "form-validation-failed-a1b2c3d4"); now extracts from the rendered (id: ...) pattern
  • chrome status --json CLI fix — test was calling browser status instead of chrome status; the command is registered as chrome, not browser

Internal ​

  • Stylistic refactors: renamed abbreviated variables (proc→child, res→response, buf→buffer, msg→errorMessage, desc→description, val→envValue) across 9 files; refactored launch command to use guard clause
  • Structural refactors: split session-manager.ts (1365→1061 lines) into breakpoint-manager.ts, execution-controller.ts, state-inspector.ts, session-output.ts; split daemon/server.ts (710→409 lines) into session-handlers.ts, browser-handlers.ts
  • Consolidated docs/guides/ into docs/guide/ with VitePress sidebar update
  • Added stylistic-refactor and structural-refactor agent skills

v0.2.18 ​

Fixes ​

  • Binary network bodies no longer corrupt MCP responses — request/response bodies are now read with content-type awareness; binary types (image/*, multipart/form-data, application/octet-stream, etc.) return a <binary: type, size> placeholder instead of attempting UTF-8 decode and corrupting the JSON response
  • Session overview now includes marker IDs — each marker line in session_overview output now shows its ID ((id: ...)) so agents can directly reference it in session_inspect and session_search
  • Wall-clock timestamps accepted as input — session_inspect, session_diff, and related tools now accept HH:mm:ss.SSS format copied directly from overview output, resolved relative to the session's start date
  • Marker lookup by label unified across tools — session_inspect(marker_id:) and session_overview(around_marker:) now accept a marker label as well as an ID, matching the existing behavior of session_search
  • Response content type was always null — network_response events were storing contentType from a non-existent field; now correctly reads mimeType from the event data
  • Request content type now stored — network_request bodies now store the Content-Type header alongside the body file, enabling accurate binary detection for uploads

v0.2.17 ​

Features ​

  • Inline screenshots in chrome_run_steps — screenshots are now embedded directly in the MCP tool response as base64 image content blocks, so agents can see them immediately without a separate file-read step

v0.2.16 ​

Fixes ​

  • Double tab on startup (macOS) — deleting Chrome session restore files (Current Session, Current Tabs, Last Session, Last Tabs) before launch now reliably prevents old tabs from reopening; patching Preferences alone was insufficient on macOS due to Secure Preferences HMAC validation silently ignoring the change

v0.2.15 ​

Features ​

  • Auto-stop on Chrome disconnect — when an attached Chrome window closes, the recording session now automatically stops after reconnection attempts are exhausted, instead of hanging as "recording" forever; the daemon cleans up its reference and resets the idle timer
  • Configurable CDP reconnect settings — maxReconnectAttempts and reconnectDelayMs options on BrowserRecorderConfig allow tuning reconnection behavior (defaults unchanged: 10 attempts, 1s delay)

v0.2.14 ​

Fixes ​

  • GitHub Pages build fixed — reverted Vue theme files that were broken by Biome's unsafe auto-fix (removed <script setup> imports used by templates); excluded docs/.vitepress/theme from Biome to prevent recurrence
  • Removed vitepress cache from git — build artifacts (docs/.vitepress/cache/, docs/.vitepress/dist/) are now gitignored

v0.2.13 ​

Features ​

  • chrome_refresh / chrome refresh — new tool and CLI command that reloads the current page and clears the event buffer in one call, giving the agent a clean slate without stop/start cycling
  • press_key step action — new action for chrome_run_steps that dispatches keyboard events (Enter, Tab, Escape, arrow keys, etc.) with optional element focus and modifier keys; solves form submission when no <button type="submit"> exists

Fixes ​

  • Double tab on startup — Chrome was restoring a previous crashed session alongside the new URL on every launch; fixed by patching the profile Preferences to clear crashed-session state before launch
  • Event listener leak in tab discovery — TabManager.discoverTabs() registered a new CDP listener on every poll iteration; now registers once

Internal ​

  • Fixed all lint errors: excluded generated/archive/fixture dirs from Biome, auto-fixed unused imports and template literals across 28 files
  • Improved navigate/reload action descriptions to clarify SPA cache behavior
  • Added screenshot-first tip and press_key guidance to chrome_run_steps tool description
  • Updated all agent skills with reload-vs-navigate guidance and "200 but empty page → check response body" investigation pattern

v0.2.12 ​

Fixes ​

  • Tab discovery polls for the requested URL — when chrome_start is called with a url, tab discovery now waits specifically for that URL to appear rather than any non-internal tab
  • Exponential backoff for tab discovery — polling starts at 50ms and doubles each iteration (capped at 1s), attaching as early as possible to beat framework initialization
  • Injection scripts evaluated on current page — framework detection hooks, annotation API, and input tracker are now evaluated via Runtime.evaluate on the current page in addition to addScriptToEvaluateOnNewDocument, ensuring hooks install even when the page is already loading on attach

v0.2.11 ​

Fixes ​

  • chrome_start race condition — tab discovery now retries with 500ms backoff for up to 10s instead of failing immediately; on macOS, Chrome's CDP endpoint becomes available before page targets are created
  • Orphaned Chrome processes — if chrome_start fails after launching Chrome, the process is now killed instead of left running as an orphan
  • Fresh profile extra tabs — added --disable-features=ChromeWhatsNewUI, --disable-default-apps, and --disable-session-crashed-bubble flags; Chrome now always receives a URL (defaulting to about:blank) to prevent the default new-tab page opening alongside the requested URL
  • chrome:// tab filtering — internal Chrome pages (chrome://, chrome-extension://, about:blank) are skipped when selecting which tab to record; tab discovery waits specifically for a content tab when krometrail launched Chrome

v0.2.10 ​

Fixes ​

  • Chrome launch on macOS — chrome_start no longer times out when Chrome is already running or only available as a .app bundle; binary detection now validates each candidate with --version before spawning
  • Chrome early exit detection — if the spawned Chrome process exits immediately (e.g., delegated to an existing instance), a clear ChromeEarlyExitError is thrown instantly rather than waiting for the 10s CDP timeout
  • Default isolated profile — Chrome is now always launched with a --user-data-dir (defaulting to default profile) to prevent macOS from routing the launch to an existing Chrome window

v0.2.9 ​

Features ​

  • doctor --fix — new flag prints a copy-paste shell script to install all missing debuggers
  • EXIT_PREREQUISITES (exit code 6) — adapter prerequisite failures now return a distinct exit code, separate from resource-not-found (3); agents can distinguish "debugger missing" from "session not found"
  • fixCommand in error envelope — JSON error output for prerequisite failures now includes a fixCommand field with the exact install command

Fixes ​

  • AdapterNotFoundError message no longer references the non-existent debug_status command — now says krometrail doctor
  • doctor --json now reports correct version for Go/Delve when dlv is in ~/go/bin but not on $PATH
  • LaunchError now carries a cause_type field (spawn_failed, connection_timeout, early_exit) enabling targeted error messages
  • Error messages in text mode now include actionable guidance: install hints, PATH advice, timeout context

Internal ​

  • All 10 adapters now return fixCommand from checkPrerequisites() — single source of truth instead of hardcoded map in doctor
  • New e2e tests: doctor-completeness, prerequisite-errors (containerized), install-flow, error-exit-codes

v0.2.8 ​

Fixes ​

  • MCP install docs now default to binary (one-liner install) with npx/bunx as tabbed alternatives
  • Fixed --tools browser → --tools=browser syntax in all docs and one-liners (prevents citty misparse)
  • Fixed --help test to check for chrome subcommand after CLI rename

Internal ​

  • Added regression tests for --tools=X syntax and one-liner flag validation

v0.2.7 ​

Features ​

  • chrome run-steps / chrome_run_steps — new batch browser action executor; run click, type, navigate, wait, screenshot, and scroll actions in a single call
  • CLI chrome rename — the browser CLI command group is now chrome, matching the MCP tool names
  • Shell completions — krometrail completions [shell] generates tab-completion scripts for bash, zsh, and fish

Fixes ​

  • C# breakpoints with netcoredbg 3.1.3 — fixed via PDB PathMap configuration
  • Kotlin and C# adapter bugs resolved
  • Fixed missing spawn imports in Swift and C++ adapters
  • Screenshot directory now eagerly created when step executor starts a session

Internal ​

  • Typed error hierarchy, injection deduplication, and session-manager cleanup
  • MCP tool handlers standardized with shared helpers and centralized path utilities
  • Consolidated duplicated logic across debug adapter layer
  • E2E and integration tests added for browser step executor

v0.2.6 ​

Features ​

  • MCP auto-update — the MCP server now checks for newer versions on every startup and self-updates automatically. Binary installs download from GitHub and atomically replace in place; npx/bunx configs updated to use @latest tag; global npm/bun installs run the package manager's update command. Disable with KROMETRAIL_NO_UPDATE=1.

v0.2.5 ​

Fixes ​

  • Fixed all MCP config examples — krometrail mcp (nonexistent subcommand) corrected to krometrail --mcp across all docs
  • Fixed claude mcp add and codex mcp add one-liner commands
  • Fixed README Quick Start referencing settings.json instead of .mcp.json

Features ​

  • Getting Started now leads with the curl one-liner installer
  • Added focused tool-set one-liners (--tools debug, --tools browser) to all agent integration guides

Internal ​

  • Added installation claims test suite (14 tests covering CLI, MCP startup, install script, and doc config regression)

v0.2.4 ​

Internal ​

  • Switched npm publish to OIDC trusted publishing (no more stored tokens)
  • Added package metadata for npm listing
  • Read version from package.json at runtime instead of hardcoding

v0.2.3 ​

Features ​

  • SEO improvements: robots.txt, XML sitemap, structured data (JSON-LD), privacy policy, FAQ page, accessibility enhancements
  • Added OG image and scaled up favicon K mark

v0.2.2 ​

Release infrastructure fix — no user-facing changes.

v0.2.1 ​

Features ​

  • Browser annotation API — lightweight code-placed markers with time-window coalescing
  • CLI agent-friendly overhaul — namespaced subcommands (debug launch, browser start), JSON envelope output, structured exit codes, full MCP parity
  • MCP tool filtering — --tools debug|browser|session flag to expose only specific tool groups
  • Curl-based installer — curl -fsSL https://krometrail.dev/install.sh | sh with checksum verification and PATH management
  • "latest" session ID alias — use latest instead of looking up session IDs
  • In-browser marker overlay — visual markers rendered in the browser during recording
  • Screenshot control panel — JPEG capture with configurable intervals
  • Browser control MCP tools — chrome_start, chrome_stop, chrome_mark, chrome_status
  • GitHub Pages docs site — auto-generated tool reference from Zod schemas, Chrome Inspector color palette
  • Agent skills — split into krometrail-debug and krometrail-chrome for skilltap

Fixes ​

  • Fixed break --clear CLI bug
  • Fixed browser inspect timestamp resolution
  • Fixed daemon spawn detection, status-code filtering, and marker IDs
  • Fixed react-observer E2E tests
  • Fixed CLI command prefixes in docs: added missing debug namespace, corrected session → browser
  • Fixed landing page nav bar and 404s
  • Removed misleading HH:MM:SS relative timestamp support

Internal ​

  • Renamed project: agent-lens → bugscope → krometrail
  • Type boundary consolidation with central enums module
  • CLI E2E journey tests for doctor, commands, debug, and browser workflows
  • Browser journey test suite for React and Vue SPAs (69 tests)
  • Consolidated adapter prereqs, MCP handlers, and observer base class
  • Pattern documentation: registry, zod, errors, adapter-helpers, mcp-handler, test patterns

v0.1.0 — Initial Development ​

The initial development period before tagged releases, building the full feature set from scratch.

Core Debug Loop ​

  • DAP client for debugger communication over TCP and stdio
  • Session manager orchestrating launch, attach, breakpoints, stepping, and evaluation
  • Viewport renderer producing ~400-token summaries per debug stop
  • MCP server exposing all debug operations as tools

Multi-Language Support ​

  • Python (debugpy), Node.js (js-debug), Go (Delve), Rust (CodeLLDB), Java (java-debug-adapter), C/C++ (GDB 14+ / lldb-dap)
  • Ruby, C#, Swift, and Kotlin adapters
  • Shared adapter helpers: checkCommand, spawnAndWait, allocatePort, gracefulDispose, connectTCP

Advanced Debugging ​

  • Conditional breakpoints (when discount < 0), hit counts, logpoints
  • Exception breakpoint filtering
  • Attach mode for running processes
  • Multi-threaded debugging with thread/goroutine selection
  • Watch expressions (persistent, auto-evaluated on every stop)
  • Framework auto-detection for pytest, jest, go test, Django, Flask, mocha

Browser Observation ​

  • Chrome CDP recorder capturing network, console, DOM mutations, user input, screenshots, storage changes
  • React DevTools integration: component lifecycle, state/prop diffs, render counts, bug pattern detection (stale closures, infinite re-renders, missing cleanup)
  • Vue Devtools integration: component tracking, Pinia/Vuex store mutations
  • Session persistence to SQLite with JSONL event storage
  • Investigation tools: session_search, session_inspect, session_diff, session_replay_context
  • WebSocket lifecycle event capture
  • CLS (Cumulative Layout Shift) observer
  • Playwright/Cypress test scaffold generation from recorded sessions

Agent Test Harness ​

  • 35 scenarios across Python, Node.js, and TypeScript at 5 difficulty levels
  • MCP, CLI, and baseline comparison modes
  • Token usage tracking and reporting