@k71n/agent-probe 0.1.0

package/dist/cleanup/cleanup-verify.js

@@ -0,0 +1,233 @@
+/**
+ * Workspace marker scan — server-side truth.
+ *
+ * Finds Probe Markers (`<MARKER_TOKEN>-begin <probe-id>` … `-end <probe-id>`
+ * own-line comment pairs) by reading the workspace filesystem ONLY — never
+ * agent-reported state. Detection is intentionally dumb: substring/regex per
+ * line, no AST, no language detection. Grep-equivalence is the contract.
+ *
+ * This module knows nothing of SessionManager/MCP/SQL. Probe removal
+ * and verify_cleanup (+ the MARKERS_REMAIN gate) build on these exact
+ * locations.
+ */
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { MARKER_TOKEN } from "../constants.js";
+import { log } from "../logger.js";
+const escaped = MARKER_TOKEN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Matches the token pattern anywhere on a line, regardless of comment
+ * leader (`//`, `#`, `--`, `<!--`, `;`, `*` …) — the convention must hold
+ * for any language with line comments. Own-line placement is for
+ * formatter resilience, not detection.
+ */
+const MARKER_RE = new RegExp(`${escaped}-(begin|end)[ \\t]+(\\S+)`);
+/** Trailing comment closers glued to the id (`p7-->` → `p7`) are not part of it. */
+function cleanProbeId(raw) {
+    return raw.replace(/(?:-->|\*\/)+$/, "");
+}
+/** Scan one file's text for marker lines. CRLF-tolerant; lines are 1-based. */
+export function scanText(text, file) {
+    const hits = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const m = MARKER_RE.exec(lines[i]);
+        if (!m)
+            continue;
+        const probe_id = cleanProbeId(m[2]);
+        if (probe_id === "")
+            continue; // closer-only "id" is not a marker
+        hits.push({ file, line: i + 1, kind: m[1], probe_id });
+    }
+    return hits;
+}
+/**
+ * Sequential per-file, per-probe-id pairing (nesting is not part of the
+ * convention). A begin without a later end for the same probe_id in the
+ * same file — or vice versa — is an ORPHAN, reported distinctly, never
+ * absorbed ("none orphaned").
+ */
+export function pairHits(hits) {
+    const paired = [];
+    const orphans = [];
+    const byFile = new Map();
+    for (const hit of hits) {
+        const list = byFile.get(hit.file) ?? [];
+        list.push(hit);
+        byFile.set(hit.file, list);
+    }
+    for (const fileHits of byFile.values()) {
+        fileHits.sort((a, b) => a.line - b.line);
+        /** FIFO of begins awaiting their end, per probe_id. */
+        const pending = new Map();
+        for (const hit of fileHits) {
+            if (hit.kind === "begin") {
+                const queue = pending.get(hit.probe_id) ?? [];
+                queue.push(hit);
+                pending.set(hit.probe_id, queue);
+            }
+            else {
+                const queue = pending.get(hit.probe_id);
+                const open = queue?.shift();
+                if (open)
+                    paired.push(open, hit);
+                else
+                    orphans.push(hit);
+            }
+        }
+        for (const queue of pending.values())
+            orphans.push(...queue);
+    }
+    const byLocation = (a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1;
+    paired.sort(byLocation);
+    orphans.sort(byLocation);
+    return { paired, orphans };
+}
+/**
+ * Derive deletion ranges from a scan — read-only; the server NEVER writes
+ * to workspace files. Removal is the AGENT's job (trust separation:
+ * remover = agent, verifier = server); this helper only turns paired
+ * markers into the ranges the agent deletes.
+ *
+ * The mechanical removal procedure (raw material for the playbook):
+ *   1. Scan the workspace (`scanWorkspace`).
+ *   2. Per file, sort ranges by `start_line` DESCENDING and delete
+ *      bottom-up, so earlier line numbers stay valid — deleting [10–12]
+ *      shifts every later line up by 3, so a range recorded at [20–22]
+ *      would otherwise now live at [17–19]. This ordering rule is THE
+ *      gotcha of line-based removal. (Cross-file order is irrelevant —
+ *      ranges never span files.)
+ *   3. Delete whole lines, never blank them.
+ *   4. Re-scan to confirm zero markers — locations from a scan taken
+ *      BEFORE any deletion are stale; re-scan-then-remove is the loop
+ *      invariant, and removal is repeatable until clean.
+ *
+ * Orphans are NOT ranges — they surface as orphans for the agent to
+ * resolve, never as guessed deletions.
+ */
+export function removalRanges(scan) {
+    const ranges = [];
+    /** markers holds only paired hits; re-walk them begin→end per file/probe_id. */
+    const pending = new Map();
+    const keyOf = (h) => `${h.file}\0${h.probe_id}`;
+    for (const hit of scan.markers) {
+        if (hit.kind === "begin") {
+            const queue = pending.get(keyOf(hit)) ?? [];
+            queue.push(hit);
+            pending.set(keyOf(hit), queue);
+        }
+        else {
+            const open = pending.get(keyOf(hit))?.shift();
+            if (open)
+                ranges.push({ file: hit.file, start_line: open.line, end_line: hit.line });
+        }
+    }
+    return ranges.sort((a, b) => a.file === b.file ? a.start_line - b.start_line : a.file < b.file ? -1 : 1);
+}
+/** Hard skip-list (binding): node_modules/ and .git/ at any depth. */
+function skipListed(rel) {
+    return rel.split(/[\\/]/).some((seg) => seg === "node_modules" || seg === ".git");
+}
+/** git's own heuristic: a NUL byte in the first 8 KiB means binary. */
+function isBinary(buf) {
+    return buf.subarray(0, 8192).includes(0);
+}
+/**
+ * Primary enumeration: tracked + untracked-but-not-gitignored, exactly as
+ * the spec words it, in one git command. Returns null on any failure (no
+ * repo, no git binary, non-zero exit) so the caller falls back. Local-only
+ * subprocess — no egress concern.
+ */
+function listFilesGit(root) {
+    let res;
+    try {
+        res = spawnSync("git", ["-C", root, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (res.error || res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    return res.stdout
+        .split("\0")
+        .filter(Boolean)
+        .map((p) => p.split("/").join(sep));
+}
+/**
+ * Fallback enumeration: recursive walk. Cannot honor .gitignore (no parser,
+ * by design), so build output may be over-scanned; that is accepted
+ * v1 behavior, reported honestly rather than smoothed over. Symlinks are
+ * never followed (cycle/escape guard via withFileTypes lstat semantics).
+ */
+function listFilesWalk(root) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            log.warn("cleanup-verify", `unreadable directory skipped: ${relative(root, dir)}`);
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === ".git")
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                out.push(relative(root, full));
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+/**
+ * Scan a workspace for Probe Markers. Every call is a fresh full scan —
+ * no caching, no watching (sessions are short-lived; correctness over
+ * speed). Unreadable files are skipped with a warning, never thrown:
+ * over-reporting beats silence, but a scan must not die mid-workspace.
+ */
+export function scanWorkspace(root) {
+    const files = listFilesGit(root) ?? listFilesWalk(root);
+    const markers = [];
+    const orphans = [];
+    let filesScanned = 0;
+    for (const rel of files) {
+        if (skipListed(rel))
+            continue;
+        const full = join(root, rel);
+        try {
+            // lstat: a deleted-but-tracked index entry or a symlink is skipped here.
+            if (!lstatSync(full).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let buf;
+        try {
+            buf = readFileSync(full); // one read serves sniff + scan
+        }
+        catch {
+            log.warn("cleanup-verify", `unreadable file skipped: ${rel}`);
+            continue;
+        }
+        if (isBinary(buf))
+            continue;
+        filesScanned++;
+        const { paired, orphans: fileOrphans } = pairHits(scanText(buf.toString("utf8"), rel));
+        markers.push(...paired);
+        orphans.push(...fileOrphans);
+    }
+    return { markers, orphans, files_scanned: filesScanned };
+}

package/dist/constants.js

@@ -0,0 +1,55 @@
+/**
+ * Single source of truth for every cross-module constant.
+ * Grep here before defining a constant anywhere else.
+ */
+/** The published package name (finalized 2026-06-06). */
+export const TOOL_NAME = "agent-probe";
+/**
+ * Probe Marker token (value finalized with the package name, 2026-06-06).
+ * Markers are own-line comment pairs:
+ *   // <MARKER_TOKEN>-begin <probe-id>
+ *   // <MARKER_TOKEN>-end <probe-id>
+ */
+export const MARKER_TOKEN = "agent-probe";
+/**
+ * The playbook resource URI. Advertised in the start_session
+ * response and registered in server.ts — single-sourced here.
+ */
+export const PLAYBOOK_URI = "playbook://probes";
+/** Stamped into each session DB via PRAGMA user_version for safe orphan inspection. */
+export const SCHEMA_VERSION = 1;
+/**
+ * Closed error-code enum. Every tool error is { code, message, hint } with
+ * `code` drawn from here — never inline strings.
+ */
+export const ERROR_CODES = {
+    NO_ACTIVE_SESSION: "NO_ACTIVE_SESSION",
+    STALE_SESSION_EXISTS: "STALE_SESSION_EXISTS",
+    MARKERS_REMAIN: "MARKERS_REMAIN",
+    RUN_NOT_FOUND: "RUN_NOT_FOUND",
+    INSTANCE_CONFLICT: "INSTANCE_CONFLICT",
+    /** One active session at a time (v1). */
+    SESSION_ALREADY_ACTIVE: "SESSION_ALREADY_ACTIVE",
+    /** Illegal session state-machine transition. */
+    INVALID_STATE: "INVALID_STATE",
+    /** No run is currently open. */
+    NO_ACTIVE_RUN: "NO_ACTIVE_RUN",
+};
+/** Resource caps. Featherweight is enforced, not asserted. */
+export const LIMITS = {
+    /** Oversized payloads are truncated (event kept, warning emitted). */
+    MAX_PAYLOAD_BYTES: 65536,
+    /** Further events past the cap are dropped with warning. */
+    MAX_EVENTS_PER_SESSION: 100_000,
+    /**
+     * Hard cap on events per query result (a context window holds
+     * hypotheses, not haystacks). Tool `limit` inputs clamp to this.
+     */
+    MAX_QUERY_EVENTS: 500,
+};
+/**
+ * Elicitation wait for run confirmation. Generous by design:
+ * the user is busy clicking through a reproduction. The SDK default (60s)
+ * is far too short. On timeout the run stays open and end_run closes it.
+ */
+export const ELICIT_TIMEOUT_MS = 600_000;

package/dist/evidence/evidence-store.js

@@ -0,0 +1,238 @@
+/**
+ * Evidence Store — the ONLY module that touches SQL. One SQLite file per
+ * Debug Session via node:sqlite DatabaseSync; destruction is close +
+ * unlink() of the db and any WAL sidecars (residual sidecars are
+ * shadow data).
+ *
+ * Strict layering: tools -> SessionManager -> EvidenceStore. This module
+ * knows nothing about MCP.
+ */
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { SCHEMA_VERSION } from "../constants.js";
+export class EvidenceStore {
+    db;
+    path;
+    constructor(db, path) {
+        this.db = db;
+        this.path = path;
+    }
+    /** Create a fresh per-session database with the full v1 schema. */
+    static create(dir, sessionId, goal) {
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, `${sessionId}.db`);
+        const db = new DatabaseSync(path);
+        db.exec("PRAGMA journal_mode = WAL");
+        db.exec("PRAGMA synchronous = NORMAL");
+        db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+        db.exec(`
+      CREATE TABLE session (
+        id      TEXT PRIMARY KEY,
+        goal    TEXT NOT NULL,
+        state   TEXT NOT NULL,
+        created INTEGER NOT NULL
+      );
+      CREATE TABLE runs (
+        id      TEXT PRIMARY KEY,
+        tag     TEXT,
+        started INTEGER,
+        ended   INTEGER
+      );
+      CREATE TABLE events (
+        seq       INTEGER PRIMARY KEY,
+        run_id    TEXT,
+        probe_id  TEXT NOT NULL,
+        service   TEXT NOT NULL,
+        file      TEXT NOT NULL,
+        line      INTEGER NOT NULL,
+        ts_probe  INTEGER NOT NULL,
+        ts_server INTEGER NOT NULL,
+        trace_id  TEXT,
+        parent_id TEXT,
+        payload   TEXT NOT NULL
+      );
+    `);
+        db.prepare("INSERT INTO session (id, goal, state, created) VALUES (?, ?, ?, ?)").run(sessionId, goal, "idle", Date.now());
+        return new EvidenceStore(db, path);
+    }
+    readSession() {
+        return this.db.prepare("SELECT id, goal, state, created FROM session").get();
+    }
+    /**
+     * Safe read-only inspection of a (possibly orphaned/corrupt/foreign) session
+     * file — `user_version` exists for exactly this. Never throws:
+     * corrupt files return null and are treated as disposable orphans.
+     */
+    static inspectSession(path) {
+        let db = null;
+        try {
+            db = new DatabaseSync(path, { readOnly: true });
+            const userVersion = db.prepare("PRAGMA user_version").get()
+                .user_version;
+            const row = db.prepare("SELECT goal, created FROM session").get();
+            const info = { userVersion };
+            if (row?.goal !== undefined)
+                info.goal = row.goal;
+            if (row?.created !== undefined)
+                info.created = row.created;
+            return info;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            catch {
+                /* already closed or never opened */
+            }
+        }
+    }
+    updateSessionState(state) {
+        this.db.prepare("UPDATE session SET state = ?").run(state);
+    }
+    listTables() {
+        const rows = this.db
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
+            .all();
+        return rows.map((r) => r.name);
+    }
+    userVersion() {
+        return this.db.prepare("PRAGMA user_version").get().user_version;
+    }
+    journalMode() {
+        return this.db.prepare("PRAGMA journal_mode").get().journal_mode;
+    }
+    /**
+     * Batched insert — one transaction per call (DatabaseSync
+     * is synchronous and shares the event loop; the ingest pipeline flushes
+     * once per tick). seq is the INTEGER PRIMARY KEY rowid: monotonic, server-assigned.
+     */
+    insertEvents(events) {
+        if (events.length === 0)
+            return;
+        const stmt = this.db.prepare(`INSERT INTO events (run_id, probe_id, service, file, line, ts_probe, ts_server, trace_id, parent_id, payload)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        this.db.exec("BEGIN");
+        try {
+            for (const e of events) {
+                stmt.run(e.runId, e.probeId, e.service, e.file, e.line, e.tsProbe, e.tsServer, e.traceId ?? null, e.parentId ?? null, e.payloadText);
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    insertRun(id, started, tag) {
+        this.db
+            .prepare("INSERT INTO runs (id, started, tag) VALUES (?, ?, ?)")
+            .run(id, started, tag ?? null);
+    }
+    /** A tag supplied at close OVERWRITES one from start (later decision wins). */
+    closeRun(id, ended, tag) {
+        this.db
+            .prepare("UPDATE runs SET ended = ?, tag = COALESCE(?, tag) WHERE id = ?")
+            .run(ended, tag ?? null, id);
+    }
+    /** Every run + per-run event count; zero-event and open runs included. */
+    listRunsWithCounts() {
+        return this.db
+            .prepare(`SELECT runs.id, runs.tag, runs.started, runs.ended,
+                COUNT(events.seq) AS event_count
+         FROM runs LEFT JOIN events ON events.run_id = runs.id
+         GROUP BY runs.id
+         ORDER BY runs.started`)
+            .all();
+    }
+    /**
+     * Abort: the run row is removed and its events become
+     * unattributed — never silently discarded.
+     */
+    abortRun(id) {
+        this.db.exec("BEGIN");
+        try {
+            this.db.prepare("UPDATE events SET run_id = NULL WHERE run_id = ?").run(id);
+            this.db.prepare("DELETE FROM runs WHERE id = ?").run(id);
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    readRuns() {
+        return this.db.prepare("SELECT id, tag, started, ended FROM runs ORDER BY started").all();
+    }
+    runExists(id) {
+        return (this.db.prepare("SELECT 1 AS one FROM runs WHERE id = ?").get(id) !== undefined);
+    }
+    /**
+     * Bounded, filtered event query. Run semantics are three-way:
+     * key absent = no run filter; null = unattributed (`IS NULL` — SQL NULL
+     * never matches `= ?`); string = that run. All filters combinable; the
+     * dynamic WHERE stays parameterized (clause list + params built together,
+     * values never interpolated). Ordering matches the exported comparator
+     * (`ts_probe, seq`). Returns the true total alongside the limited rows.
+     */
+    queryEvents(opts) {
+        const where = [];
+        const params = [];
+        if ("run" in opts && opts.run !== undefined) {
+            if (opts.run === null)
+                where.push("run_id IS NULL");
+            else {
+                where.push("run_id = ?");
+                params.push(opts.run);
+            }
+        }
+        if (opts.probeId !== undefined) {
+            where.push("probe_id = ?");
+            params.push(opts.probeId);
+        }
+        if (opts.service !== undefined) {
+            where.push("service = ?");
+            params.push(opts.service);
+        }
+        if (opts.tsFrom !== undefined) {
+            where.push("ts_probe >= ?");
+            params.push(opts.tsFrom);
+        }
+        if (opts.tsTo !== undefined) {
+            where.push("ts_probe <= ?");
+            params.push(opts.tsTo);
+        }
+        const clause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        const total = this.db.prepare(`SELECT COUNT(*) AS n FROM events ${clause}`).get(...params).n;
+        const rows = this.db
+            .prepare(`SELECT * FROM events ${clause} ORDER BY ts_probe, seq LIMIT ?`)
+            .all(...params, opts.limit);
+        return { rows, total };
+    }
+    countEvents() {
+        return this.db.prepare("SELECT COUNT(*) AS n FROM events").get().n;
+    }
+    readEvents() {
+        return this.db
+            .prepare("SELECT * FROM events ORDER BY seq")
+            .all();
+    }
+    /**
+     * Destructive end: close the handle, then unlink the db and any
+     * -wal/-shm sidecars. The strongest deletion the OS offers.
+     */
+    destroy() {
+        this.db.close();
+        removeSessionFiles(this.path);
+    }
+}
+/** Shared destructive-deletion semantics (orphan disposal reuses this). */
+export function removeSessionFiles(dbPath) {
+    for (const p of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+}

package/dist/evidence/query.js

@@ -0,0 +1,97 @@
+/**
+ * Query engine: get_timeline and get_span, plus THE
+ * ordering comparator — the one definition of "before" in the whole
+ * system. diff.ts imports it; nothing else may re-implement ordering.
+ *
+ * Ordering authority: ts_probe primary (execution truth), seq tiebreaker
+ * (one-clock fallback). SQL ORDER BY (ts_probe, seq) is equivalent and
+ * tested as such.
+ */
+import { ERROR_CODES, LIMITS } from "../constants.js";
+import { TypedToolError } from "../session/session-manager.js";
+/** THE comparator. ts_probe primary, seq tiebreaker. */
+export function compareEvents(a, b) {
+    if (a.ts_probe !== b.ts_probe)
+        return a.ts_probe - b.ts_probe;
+    return a.seq - b.seq;
+}
+/**
+ * Payload presentation: parsed JSON for the agent, or the raw string when
+ * unparseable (ingest truncation artifacts). Shared by timeline/span shaping
+ * and diff payload deltas.
+ */
+export function parsePayload(text) {
+    try {
+        return { value: JSON.parse(text), truncated: false };
+    }
+    catch {
+        return { value: text, truncated: true };
+    }
+}
+/**
+ * Shape ordered rows for agent consumption: seq_tied flagging (successor-
+ * flagged) + payload presentation. The stored payload
+ * text is untouched — parsing here is presentation, not re-shaping.
+ */
+export function shapeEvents(rows) {
+    return rows.map((row, i) => {
+        const shaped = {
+            seq: row.seq,
+            run_id: row.run_id,
+            probe_id: row.probe_id,
+            service: row.service,
+            file: row.file,
+            line: row.line,
+            ts_probe: row.ts_probe,
+            ts_server: row.ts_server,
+            payload: row.payload,
+        };
+        if (row.trace_id !== null)
+            shaped.trace_id = row.trace_id;
+        if (row.parent_id !== null)
+            shaped.parent_id = row.parent_id;
+        const parsed = parsePayload(row.payload);
+        shaped.payload = parsed.value;
+        if (parsed.truncated)
+            shaped.payload_truncated = true;
+        if (i > 0 && rows[i - 1].ts_probe === row.ts_probe)
+            shaped.seq_tied = true;
+        return shaped;
+    });
+}
+/** Resolve a tool-level `run` param: "unattributed" -> NULL; ids must exist. */
+function resolveRun(store, run) {
+    if (run === "unattributed")
+        return null;
+    if (!store.runExists(run)) {
+        throw new TypedToolError(ERROR_CODES.RUN_NOT_FOUND, `Run ${run} does not exist.`, 'Call list_runs to see available runs, or use "unattributed" for events outside any run.');
+    }
+    return run;
+}
+/** Timeline for a run (or "unattributed"): comparator-ordered, bounded, honest. */
+export function getTimeline(store, run, limit) {
+    const clamped = Math.min(limit ?? LIMITS.MAX_QUERY_EVENTS, LIMITS.MAX_QUERY_EVENTS);
+    const { rows, total } = store.queryEvents({ run: resolveRun(store, run), limit: clamped });
+    return { events: shapeEvents(rows), truncated: rows.length < total, total };
+}
+/**
+ * Bounded span by any combination of run/probe/service/time range.
+ * The no-filter call is the maximal query — it still clamps. Empty match
+ * is a RESULT; only a missing run id is an error.
+ */
+export function getSpan(store, filters) {
+    const clamped = Math.min(filters.limit ?? LIMITS.MAX_QUERY_EVENTS, LIMITS.MAX_QUERY_EVENTS);
+    const opts = { limit: clamped };
+    if (filters.run !== undefined)
+        opts.run = resolveRun(store, filters.run);
+    if (filters.probe !== undefined)
+        opts.probeId = filters.probe;
+    if (filters.service !== undefined)
+        opts.service = filters.service;
+    if (filters.from !== undefined)
+        opts.tsFrom = filters.from;
+    if (filters.to !== undefined)
+        opts.tsTo = filters.to;
+    const { rows, total } = store.queryEvents(opts);
+    return { events: shapeEvents(rows), truncated: rows.length < total, total };
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Entry point. The Node version gate runs BEFORE anything that could pull in
+ * `node:sqlite` loads — hence the dynamic import of the
+ * server below. Do not add static imports here beyond dependency-free modules.
+ */
+import { TOOL_NAME } from "./constants.js";
+import { meetsMinimumNode, MIN_NODE_VERSION } from "./node-version.js";
+if (!meetsMinimumNode(process.versions.node)) {
+    process.stderr.write(`${TOOL_NAME} requires Node >= ${MIN_NODE_VERSION} (found ${process.versions.node}).\n` +
+        `It relies on the built-in node:sqlite module, which is only available from ${MIN_NODE_VERSION}.\n` +
+        `Please upgrade Node and try again.\n`);
+    process.exit(1);
+}
+const { startStdioServer } = await import("./server.js");
+await startStdioServer();