@k71n/agent-probe 0.1.0

package/dist/session/session-manager.js

@@ -0,0 +1,354 @@
+/**
+ * Session state machine — owns the store lifecycle.
+ *
+ * Explicit union type + transition table: idle -> instrumented -> run(n) ->
+ * analyzing -> cleanup-verify -> destroyed. Illegal transitions throw typed
+ * errors. No boolean flags standing in for states.
+ *
+ * Crash-only design: no state outside the SQLite file; sudden death leaves
+ * only the orphan .db (stale-session scan/disposal owns recovery).
+ */
+import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { scanWorkspace } from "../cleanup/cleanup-verify.js";
+import { ERROR_CODES, LIMITS } from "../constants.js";
+import { EvidenceStore, removeSessionFiles } from "../evidence/evidence-store.js";
+import { log } from "../logger.js";
+import { locksDir, resolveStateRoot, sessionsDir } from "./state-dir.js";
+/** Thrown by manager operations; tools serialize it as { code, message, hint }. */
+export class TypedToolError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = "TypedToolError";
+    }
+}
+/**
+ * The full transition table, defined once. `destroyed` is reachable from
+ * every active state — the MARKERS_REMAIN gate sits in front of it
+ * (seam: endSession), not in this table.
+ */
+export const TRANSITIONS = {
+    idle: ["instrumented", "destroyed"],
+    instrumented: ["run", "destroyed"],
+    run: ["run", "analyzing", "destroyed"],
+    analyzing: ["run", "cleanup-verify", "destroyed"],
+    "cleanup-verify": ["destroyed"],
+    destroyed: [],
+};
+export class SessionManager {
+    stateRoot;
+    active = null;
+    constructor(opts = {}) {
+        this.stateRoot = opts.stateRoot ?? resolveStateRoot();
+    }
+    get activeSessionId() {
+        return this.active?.id ?? null;
+    }
+    /** Store of the active session (ingest writes only through the store). */
+    get activeStore() {
+        return this.active?.store ?? null;
+    }
+    get state() {
+        return this.active?.state ?? null;
+    }
+    /** Deterministic lock filename per workspace_root (exposed for tests and orphan disposal). */
+    lockName(workspaceRoot) {
+        return `${createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16)}.lock`;
+    }
+    startSession(goal, workspaceRoot, stale) {
+        if (this.active) {
+            throw new TypedToolError(ERROR_CODES.SESSION_ALREADY_ACTIVE, `Session ${this.active.id} is already active.`, "End the active session with end_session before starting a new one (one active session at a time in v1).");
+        }
+        // Stale gate: starting anew while stale sessions exist requires an explicit decision
+        const orphans = this.scanOrphans();
+        if (orphans.length > 0) {
+            if (stale === undefined) {
+                const listing = orphans
+                    .map((o) => `${o.sessionId}${o.goal ? ` ("${o.goal}")` : ""}`)
+                    .join(", ");
+                throw new TypedToolError(ERROR_CODES.STALE_SESSION_EXISTS, `Stale debug session(s) found: ${listing}.`, `Stale: ${listing}. Ask the user what to do, then re-call start_session with ` +
+                    `stale: "dispose" to delete the stale evidence, or stale: "keep" to proceed and ` +
+                    `leave it (it will surface again). Stale sessions can never be resumed - probes ` +
+                    `bake in a dead session ID and port.`);
+            }
+            if (stale === "dispose")
+                this.disposeOrphans(orphans);
+            // "keep": proceed once; orphans surface again next time
+        }
+        // a fresh session ALWAYS mints a new ID and file - no resume path exists
+        const sessionId = `s-${Date.now()}-${randomUUID().slice(0, 8)}`;
+        const lockPath = this.acquireLock(workspaceRoot, sessionId);
+        const store = EvidenceStore.create(sessionsDir(this.stateRoot), sessionId, goal);
+        this.active = {
+            id: sessionId,
+            goal,
+            workspaceRoot,
+            store,
+            state: { kind: "idle" },
+            lockPath,
+            currentRun: null,
+            runCount: 0,
+        };
+        log.info("session", `started ${sessionId} (workspace ${workspaceRoot})`);
+        return { sessionId, workspaceRoot };
+    }
+    /** Enforce the transition table; illegal edges throw INVALID_STATE. */
+    transition(to) {
+        const session = this.requireActive();
+        const from = session.state.kind;
+        if (!TRANSITIONS[from].includes(to)) {
+            throw new TypedToolError(ERROR_CODES.INVALID_STATE, `Illegal transition ${from} -> ${to}.`, `Legal next states from ${from}: ${TRANSITIONS[from].join(", ") || "(none)"}.`);
+        }
+        session.state =
+            to === "run"
+                ? { kind: "run", n: ++session.runCount }
+                : { kind: to };
+        session.store.updateSessionState(to);
+    }
+    /**
+     * Server-side cleanup verification: scan the workspace
+     * RECORDED at start_session and return the scan unmodified — exact
+     * locations are the deliverable. Takes NO path argument: accepting one
+     * would reintroduce the agent-trust hole this verification exists to close.
+     *
+     * State bookkeeping: analyzing -> cleanup-verify via the table; already
+     * cleanup-verify stays (re-verification after another removal pass is the
+     * normal loop); any other active state scans WITHOUT transitioning — the
+     * scan is read-only and the endSession gate enforces ordering.
+     */
+    verifyCleanup() {
+        const session = this.requireActive();
+        const scan = this.scanRecordedRoot(session);
+        if (session.state.kind === "analyzing")
+            this.transition("cleanup-verify");
+        return scan;
+    }
+    /** Fail closed: an unscannable root is markers-UNKNOWN, never markers-zero. */
+    scanRecordedRoot(session) {
+        try {
+            readdirSync(session.workspaceRoot); // accessibility probe: deleted/unreadable throws
+        }
+        catch {
+            throw new TypedToolError(ERROR_CODES.MARKERS_REMAIN, `workspace_root ${session.workspaceRoot} could not be scanned — residual probe markers cannot be ruled out.`, "Restore access to the workspace and re-verify with verify_cleanup; or — only after asking the user — re-call end_session with override: true.");
+        }
+        return scanWorkspace(session.workspaceRoot);
+    }
+    /**
+     * Destructive end: close + unlink the store, release the lock —
+     * guarded by the MARKERS_REMAIN gate. The gate counts ANY token
+     * occurrence (paired markers AND orphans: the standard is grep-for-token
+     * count zero, not zero pairs). `override` is the USER's decision, never
+     * the agent's shortcut — it waives VERIFICATION, never DELETION, and is
+     * reported back in the result, never silent.
+     */
+    endSession(override = false) {
+        const session = this.requireActive();
+        let hits = null; // null = unknown (unscannable root)
+        try {
+            const scan = this.scanRecordedRoot(session);
+            hits = [...scan.markers, ...scan.orphans];
+        }
+        catch (err) {
+            if (!override)
+                throw err; // fail closed; override is the user's escape hatch
+        }
+        if (hits !== null && hits.length > 0 && !override) {
+            const examples = hits
+                .slice(0, 3)
+                .map((h) => `${h.file}:${h.line}`)
+                .join(", ");
+            throw new TypedToolError(ERROR_CODES.MARKERS_REMAIN, `${hits.length} probe marker(s) remain in ${session.workspaceRoot} (e.g. ${examples}).`, "Run verify_cleanup for exact locations, remove the probes (delete marked ranges inclusive, bottom-up), and re-verify; or — only after asking the user — re-call end_session with override: true.");
+        }
+        // destruction EXACTLY as before the gate (destruction is never weakened by the override)
+        session.state = { kind: "destroyed" };
+        session.store.destroy();
+        if (existsSync(session.lockPath))
+            unlinkSync(session.lockPath);
+        log.info("session", `destroyed ${session.id} (db unlinked)`);
+        this.active = null;
+        if (hits === null || hits.length > 0) {
+            log.warn("session", `closed with override: ${hits === null ? "workspace unscannable" : `${hits.length} residual marker(s)`}`);
+            return {
+                override: {
+                    residual_count: hits === null ? null : hits.length,
+                    locations: (hits ?? []).slice(0, LIMITS.MAX_QUERY_EVENTS),
+                },
+            };
+        }
+        return {};
+    }
+    /** ID of the open run, or null (drives ingest attribution). */
+    get activeRunId() {
+        return this.active?.currentRun?.id ?? null;
+    }
+    /**
+     * Open a run with a server-owned start boundary. First run from `idle`
+     * implies instrumentation happened agent-side: idle -> instrumented -> run
+     * in one step (nothing observable marks "instrumented" alone).
+     */
+    startRun(tag) {
+        const session = this.requireActive();
+        if (session.currentRun) {
+            throw new TypedToolError(ERROR_CODES.INVALID_STATE, `Run ${session.currentRun.id} is already open.`, "Close it with end_run (or confirm the pending elicitation) before starting another run.");
+        }
+        if (session.state.kind === "idle")
+            this.transition("instrumented");
+        this.transition("run");
+        const n = session.state.n;
+        const runId = `r${n}`;
+        const started = Date.now();
+        session.store.insertRun(runId, started, tag);
+        session.currentRun = { id: runId, started };
+        log.info("session", `run ${runId} opened${tag ? ` (tag: ${tag})` : ""}`);
+        return { runId, n };
+    }
+    /** Close the open run with a server-owned end boundary; close-tag overwrites start-tag. */
+    closeRun(tag) {
+        const session = this.requireActive();
+        const run = this.requireRun(session);
+        const ended = Date.now();
+        session.store.closeRun(run.id, ended, tag);
+        session.currentRun = null;
+        this.transition("analyzing");
+        log.info("session", `run ${run.id} closed`);
+        return { runId: run.id, started: run.started, ended };
+    }
+    /** Every run with tag, boundaries, and event count. */
+    listRuns() {
+        return this.requireActive().store.listRunsWithCounts();
+    }
+    /** Abort the open run (elicitation declined): row deleted, events unattributed. */
+    abortRun() {
+        const session = this.requireActive();
+        const run = this.requireRun(session);
+        session.store.abortRun(run.id);
+        session.currentRun = null;
+        this.transition("analyzing");
+        log.warn("session", `run ${run.id} aborted; its events are now unattributed`);
+        return { runId: run.id };
+    }
+    requireRun(session) {
+        if (!session.currentRun) {
+            throw new TypedToolError(ERROR_CODES.NO_ACTIVE_RUN, "No run is currently open.", "Open one with start_run.");
+        }
+        return session.currentRun;
+    }
+    /**
+     * Orphan = a session .db NOT claimed by any lockfile with a live PID.
+     * The sessions dir is machine-global: a file claimed by another LIVING
+     * instance (different workspace) is NOT stale and must never be touched.
+     * A claim by our own PID for a non-active session is stale by definition.
+     */
+    scanOrphans() {
+        const dir = sessionsDir(this.stateRoot);
+        if (!existsSync(dir))
+            return [];
+        const claims = this.readClaims();
+        const orphans = [];
+        for (const file of readdirSync(dir)) {
+            if (!file.endsWith(".db"))
+                continue; // -wal/-shm sidecars follow their .db
+            const sessionId = file.slice(0, -3);
+            if (sessionId === this.active?.id)
+                continue; // our own live session
+            const claimPid = claims.get(sessionId);
+            const claimedByLiveOther = claimPid !== undefined && claimPid !== process.pid && isPidAlive(claimPid);
+            if (claimedByLiveOther)
+                continue;
+            const path = join(dir, file);
+            const info = EvidenceStore.inspectSession(path); // null for corrupt = still disposable
+            const orphan = { sessionId, path };
+            if (info?.goal !== undefined)
+                orphan.goal = info.goal;
+            if (info?.created !== undefined)
+                orphan.created = info.created;
+            orphans.push(orphan);
+        }
+        return orphans;
+    }
+    /** Destructive deletion semantics for orphans: db + sidecars + any lock claiming them. */
+    disposeOrphans(orphans) {
+        const orphanIds = new Set(orphans.map((o) => o.sessionId));
+        for (const orphan of orphans) {
+            removeSessionFiles(orphan.path);
+            log.warn("session", `disposed stale session ${orphan.sessionId}`);
+        }
+        const lDir = locksDir(this.stateRoot);
+        if (!existsSync(lDir))
+            return;
+        for (const file of readdirSync(lDir)) {
+            const lock = this.readLock(join(lDir, file));
+            if (lock?.session_id !== undefined && orphanIds.has(lock.session_id)) {
+                unlinkSync(join(lDir, file));
+            }
+        }
+    }
+    /** session_id -> holder PID, from all parseable lockfiles. */
+    readClaims() {
+        const claims = new Map();
+        const dir = locksDir(this.stateRoot);
+        if (!existsSync(dir))
+            return claims;
+        for (const file of readdirSync(dir)) {
+            const lock = this.readLock(join(dir, file));
+            if (lock?.session_id !== undefined)
+                claims.set(lock.session_id, lock.pid);
+        }
+        return claims;
+    }
+    /** The active session's store, or a typed NO_ACTIVE_SESSION error (query-tool entry point). */
+    requireStore() {
+        return this.requireActive().store;
+    }
+    requireActive() {
+        if (!this.active) {
+            throw new TypedToolError(ERROR_CODES.NO_ACTIVE_SESSION, "No active debug session.", "Start one with start_session(goal, workspace_root).");
+        }
+        return this.active;
+    }
+    /** PID lockfile per workspace_root; stale locks reaped. */
+    acquireLock(workspaceRoot, sessionId) {
+        const dir = locksDir(this.stateRoot);
+        mkdirSync(dir, { recursive: true });
+        const lockPath = join(dir, this.lockName(workspaceRoot));
+        if (existsSync(lockPath)) {
+            const holder = this.readLock(lockPath);
+            if (holder && isPidAlive(holder.pid) && holder.pid !== process.pid) {
+                throw new TypedToolError(ERROR_CODES.INSTANCE_CONFLICT, `Another instance is already debugging ${holder.workspace_root}.`, `Held by PID ${holder.pid}. End that session (or stop that process) first; one session per workspace.`);
+            }
+            // dead PID (or our own) -> stale lock, reap it
+            log.warn("session", `reaped stale lock for ${workspaceRoot}`);
+            unlinkSync(lockPath);
+        }
+        const content = {
+            pid: process.pid,
+            workspace_root: workspaceRoot,
+            session_id: sessionId,
+        };
+        writeFileSync(lockPath, JSON.stringify(content));
+        return lockPath;
+    }
+    readLock(lockPath) {
+        try {
+            return JSON.parse(readFileSync(lockPath, "utf8"));
+        }
+        catch {
+            return null; // corrupt lock = stale
+        }
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/session/state-dir.js

@@ -0,0 +1,26 @@
+/**
+ * OS state-dir resolution: $XDG_STATE_HOME if set; else
+ * Linux ~/.local/state, macOS ~/Library/Application Support, Windows
+ * %LOCALAPPDATA% — with `<tool>/sessions/` under each.
+ */
+import { join } from "node:path";
+import { TOOL_NAME } from "../constants.js";
+export function resolveStateRoot(platform = process.platform, env = process.env) {
+    if (env.XDG_STATE_HOME)
+        return join(env.XDG_STATE_HOME, TOOL_NAME);
+    const home = env.HOME ?? "";
+    switch (platform) {
+        case "darwin":
+            return join(home, "Library", "Application Support", TOOL_NAME);
+        case "win32":
+            return join(env.LOCALAPPDATA ?? join(home, "AppData", "Local"), TOOL_NAME);
+        default:
+            return join(home, ".local", "state", TOOL_NAME);
+    }
+}
+export function sessionsDir(stateRoot) {
+    return join(stateRoot, "sessions");
+}
+export function locksDir(stateRoot) {
+    return join(stateRoot, "locks");
+}

package/dist/tools.js

@@ -0,0 +1,242 @@
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { LIMITS, PLAYBOOK_URI } from "./constants.js";
+import { diffRuns } from "./evidence/diff.js";
+import { getSpan, getTimeline } from "./evidence/query.js";
+import { armRun } from "./session/run-boundaries.js";
+import { TypedToolError } from "./session/session-manager.js";
+function errorResult(error) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(error) }],
+    };
+}
+/** Serialize TypedToolError as the standard error shape; rethrow the rest. */
+function asToolError(err) {
+    if (err instanceof TypedToolError) {
+        return errorResult({ code: err.code, message: err.message, hint: err.hint });
+    }
+    throw err;
+}
+export function registerTools(server, deps) {
+    function okResult(data, total = 1, truncated = false) {
+        const envelope = { data, truncated, total };
+        const warnings = deps.drainWarnings?.() ?? [];
+        if (warnings.length > 0)
+            envelope.warnings = warnings;
+        return { content: [{ type: "text", text: JSON.stringify(envelope) }] };
+    }
+    server.registerTool("start_session", {
+        description: "Start a Debug Session scoped to a stated goal.",
+        inputSchema: {
+            goal: z.string().describe("What this debug session is trying to find out"),
+            workspace_root: z
+                .string()
+                .refine(isAbsolute, "workspace_root must be an absolute path")
+                .describe("Absolute path to the workspace being debugged"),
+            stale: z
+                .enum(["dispose", "keep"])
+                .optional()
+                .describe("Decision about stale sessions (required if STALE_SESSION_EXISTS was returned; ask the user first): dispose deletes them, keep proceeds once"),
+        },
+    }, async ({ goal, workspace_root, stale }) => {
+        try {
+            const { sessionId, workspaceRoot } = deps.manager.startSession(goal, workspace_root, stale);
+            return okResult({
+                session_id: sessionId,
+                port: deps.ingestPort(),
+                workspace_root: workspaceRoot,
+                // Discoverability: hosts don't reliably surface resource lists,
+                // so the pull-once playbook URI rides the start_session response.
+                playbook: PLAYBOOK_URI,
+            });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("start_run", {
+        description: "Arm a Run: the user reproduces the flow while probe events are attributed to it. " +
+            "With elicitation support this call waits for the user's confirm and returns the closed run; " +
+            "otherwise the run stays open and end_run closes it.",
+        inputSchema: {
+            tag: z.string().min(1).optional().describe('Run tag, e.g. "buggy" or "clean"'),
+        },
+    }, async ({ tag }) => {
+        try {
+            const outcome = await armRun({
+                server,
+                manager: deps.manager,
+                ...(tag !== undefined ? { tag } : {}),
+                ...(deps.elicitTimeoutMs !== undefined ? { elicitTimeoutMs: deps.elicitTimeoutMs } : {}),
+            });
+            const port = deps.ingestPort();
+            switch (outcome.kind) {
+                case "closed":
+                    return okResult({
+                        run_id: outcome.runId,
+                        status: "closed",
+                        started: outcome.started,
+                        ended: outcome.ended,
+                        port,
+                    });
+                case "aborted":
+                    return okResult({
+                        run_id: outcome.runId,
+                        status: "aborted",
+                        note: "User declined; the run's events are now unattributed.",
+                        port,
+                    });
+                case "open":
+                    return okResult({
+                        run_id: outcome.runId,
+                        status: "open",
+                        ...(outcome.reason !== "no_elicitation" ? { reason: outcome.reason } : {}),
+                        note: "Run is open; call end_run when the user says the reproduction is done.",
+                        port,
+                    });
+            }
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("end_run", {
+        description: "Close the open Run with a server-owned end boundary.",
+        inputSchema: {
+            tag: z.string().min(1).optional().describe('Run tag, e.g. "buggy" or "clean" (overwrites a tag set at start)'),
+        },
+    }, async ({ tag }) => {
+        try {
+            const closed = deps.manager.closeRun(tag);
+            return okResult({
+                run_id: closed.runId,
+                status: "closed",
+                started: closed.started,
+                ended: closed.ended,
+            });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("list_runs", {
+        description: "List every Run in the session with tag, boundaries, and event count.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const runs = deps.manager.listRuns().map((r) => ({
+                run_id: r.id,
+                tag: r.tag,
+                started: r.started,
+                ended: r.ended,
+                event_count: r.event_count,
+            }));
+            return okResult({ runs }, runs.length);
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("get_timeline", {
+        description: "Time-ordered Timeline of all probe events across all services for a Run.",
+        inputSchema: {
+            run: z.string().describe('Run ID (see list_runs) or "unattributed"'),
+            limit: z.number().int().positive().optional().describe("Max events to return (clamped server-side)"),
+        },
+    }, async ({ run, limit }) => {
+        try {
+            const { events, truncated, total } = getTimeline(deps.manager.requireStore(), run, limit);
+            return okResult({ events }, total, truncated);
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("get_span", {
+        description: "Bounded span of probe events by any combination of run, probe, service, and time range.",
+        inputSchema: {
+            run: z.string().optional().describe('Run ID (see list_runs) or "unattributed"'),
+            probe: z.string().optional().describe("Probe ID to match"),
+            service: z.string().optional().describe("Service name to match"),
+            from: z.number().int().optional().describe("Inclusive lower bound on ts_probe (epoch ms)"),
+            to: z.number().int().optional().describe("Inclusive upper bound on ts_probe (epoch ms)"),
+            limit: z.number().int().positive().optional().describe("Max events to return (clamped server-side)"),
+        },
+    }, async ({ run, probe, service, from, to, limit }) => {
+        try {
+            const filters = {};
+            if (run !== undefined)
+                filters.run = run;
+            if (probe !== undefined)
+                filters.probe = probe;
+            if (service !== undefined)
+                filters.service = service;
+            if (from !== undefined)
+                filters.from = from;
+            if (to !== undefined)
+                filters.to = to;
+            if (limit !== undefined)
+                filters.limit = limit;
+            const { events, truncated, total } = getSpan(deps.manager.requireStore(), filters);
+            return okResult({ events }, total, truncated);
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("diff_runs", {
+        description: "Structured account of differences between two Runs: presence/absence, ordering changes, payload deltas.",
+        inputSchema: {
+            a: z.string().describe("First run ID (e.g. the clean run)"),
+            b: z.string().describe("Second run ID (e.g. the buggy run)"),
+        },
+    }, async ({ a, b }) => {
+        try {
+            const { data, total, truncated } = diffRuns(deps.manager.requireStore(), a, b);
+            return okResult(data, total, truncated);
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("verify_cleanup", {
+        description: "Server-side scan of the session workspace for residual probe markers; returns exact locations.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const scan = deps.manager.verifyCleanup();
+            const total = scan.markers.length + scan.orphans.length;
+            const markers = scan.markers.slice(0, LIMITS.MAX_QUERY_EVENTS);
+            const orphans = scan.orphans.slice(0, LIMITS.MAX_QUERY_EVENTS);
+            const truncated = markers.length < scan.markers.length || orphans.length < scan.orphans.length;
+            return okResult({ clean: total === 0, markers, orphans, files_scanned: scan.files_scanned }, total, truncated);
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool("end_session", {
+        description: "End the active Debug Session destructively: all stored probe events are deleted. " +
+            "Refused with MARKERS_REMAIN while probe markers remain in the workspace.",
+        inputSchema: {
+            override: z
+                .boolean()
+                .optional()
+                .describe("Close despite residual probe markers. Requires the user's explicit choice — ask first; the override is reported in the result."),
+        },
+    }, async ({ override }) => {
+        try {
+            const sessionId = deps.manager.activeSessionId;
+            const result = deps.manager.endSession(override ?? false);
+            return okResult({
+                session_id: sessionId,
+                destroyed: true,
+                ...(result.override !== undefined ? { override: result.override } : {}),
+            });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@k71n/agent-probe",
+  "version": "0.1.0",
+  "description": "LLM-in-the-loop multi-service debugger - MCP server with leave-no-trace probe instrumentation",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "bin": {
+    "agent-probe": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node build-playbook.mjs",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src *.js *.mjs *.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "eslint": "^10.4.1",
+    "prettier": "^3.8.3",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.1",
+    "vitest": "^4.1.8"
+  }
+}