@k71n/agent-probe 0.1.0

package/dist/ingest/contract.js

@@ -0,0 +1,94 @@
+/**
+ * Probe Event contract v1 — FROZEN wire vocabulary.
+ * The wire<->code boundary mapping lives HERE and only here:
+ * snake_case in, typed camelCase out. No ad-hoc field renaming elsewhere.
+ *
+ * ## Wire shape (HTTP POST of JSON to http://127.0.0.1:<port>/events)
+ *
+ * | field      | type    | required | meaning                                    |
+ * |------------|---------|----------|--------------------------------------------|
+ * | session_id | string  | yes      | active session (from start_session)        |
+ * | probe_id   | string  | yes      | this probe's identity (matches its marker) |
+ * | service    | string  | yes      | which service emitted it ("web", "api"...) |
+ * | file       | string  | yes      | source file the probe lives in             |
+ * | line       | int     | yes      | source line                                |
+ * | ts_probe   | int     | yes      | epoch MILLISECONDS at emission             |
+ * | payload    | JSON    | yes      | any JSON value; stored exactly as received |
+ * | trace_id   | string  | no       | W3C-Trace-Context headroom                 |
+ * | parent_id  | string  | no       | W3C-Trace-Context headroom                 |
+ *
+ * The server assigns `ts_server` + monotonic `seq` on ingestion.
+ * Optional fields are OMITTED when absent, never null.
+ *
+ * ## The contract is language-agnostic
+ *
+ * Anything that can POST JSON to localhost conforms. `Content-Type` is
+ * recommended but NOT required — the server parses the raw body as JSON
+ * regardless (a shell one-liner sets no headers). No per-language library
+ * exists or is needed: the LLM is the SDK.
+ *
+ * ## Timestamps: epoch milliseconds, a one-liner in every language
+ *
+ *   JS/TS:   Date.now()
+ *   Python:  int(time.time() * 1000)
+ *   Shell:   $(date +%s%3N)
+ *   Go:      time.Now().UnixMilli()
+ *
+ * ## JS/TS probe idiom (fire-and-forget)
+ *
+ * Non-awaited, error-swallowed, NO retries, NO shared logging helpers
+ * (probes must stay self-contained one-liners or they aren't removable):
+ *
+ *   fetch(`http://127.0.0.1:${PORT}/events`, { method: "POST", body: JSON.stringify({ session_id: SID, probe_id: "p7", service: "web", file: "form.ts", line: 42, ts_probe: Date.now(), payload: { categoryId } }) }).catch(() => {});
+ *
+ * Browser, near page unload, add keepalive so the request survives navigation:
+ *
+ *   fetch(`http://127.0.0.1:${PORT}/events`, { method: "POST", keepalive: true, body: JSON.stringify({ ... }) }).catch(() => {});
+ *
+ * `PORT` and `SID` come from the start_session response — bake them in.
+ *
+ * ## run_id and "unattributed"
+ *
+ * `run_id` exists only in the store, never on the wire. SQL NULL there is a
+ * semantic value: *unattributed* (the event arrived outside any Run).
+ * Query tools (`get_timeline`, `get_span`) accept
+ * `run: "unattributed"` to retrieve exactly those events.
+ *
+ * ## Conformance enforcement
+ *
+ * Unknown extra keys are ignored, not rejected — probes are hand-written
+ * by agents in any language; strictness here would break language-agnosticism. Malformed
+ * events are dropped server-side (ring buffer + warnings), never propagated
+ * as application errors.
+ */
+import { z } from "zod";
+const jsonValue = z.lazy(() => z.union([z.string(), z.number(), z.boolean(), z.null(), z.array(jsonValue), z.record(z.string(), jsonValue)]));
+export const probeEventWireSchema = z.object({
+    session_id: z.string(),
+    probe_id: z.string(),
+    service: z.string(),
+    file: z.string(),
+    line: z.number().int(),
+    ts_probe: z.number().int(),
+    payload: jsonValue,
+    trace_id: z.string().optional(),
+    parent_id: z.string().optional(),
+});
+/** Parse + map wire->code. Throws ZodError on non-conformant input. */
+export function parseProbeEvent(input) {
+    const wire = probeEventWireSchema.parse(input);
+    const event = {
+        sessionId: wire.session_id,
+        probeId: wire.probe_id,
+        service: wire.service,
+        file: wire.file,
+        line: wire.line,
+        tsProbe: wire.ts_probe,
+        payload: wire.payload,
+    };
+    if (wire.trace_id !== undefined)
+        event.traceId = wire.trace_id;
+    if (wire.parent_id !== undefined)
+        event.parentId = wire.parent_id;
+    return event;
+}

package/dist/ingest/ingest.js

@@ -0,0 +1,211 @@
+/**
+ * Ingestion — POST /events on 127.0.0.1:ephemeral, started at process
+ * startup (listener lifecycle is per-process; Validation Issue #2).
+ *
+ * Non-perturbation is the soul of this module: the server responds 202 BEFORE any
+ * validation work, never applies backpressure, and a malformed/oversized/
+ * over-cap event NEVER becomes an application-visible error.
+ *
+ * Pipeline: body -> [202] -> JSON.parse -> contract validate -> caps ->
+ * buffer -> flush once per event-loop tick in ONE transaction.
+ * Rejections/drops go to an in-memory ring buffer (last 50; NOT a DB
+ * table -- rejections fire precisely when no session DB exists) and
+ * surface via `warnings` on tool responses + one stderr line each.
+ *
+ * Bind-level localhost: host hardcoded; remote connections are
+ * refused by the kernel, not middleware. No auth, no TLS -- by design.
+ */
+import { createServer } from "node:http";
+import { parseProbeEvent } from "./contract.js";
+import { LIMITS } from "../constants.js";
+import { log } from "../logger.js";
+const RING_CAPACITY = 50;
+/** In-memory rejection/drop ring buffer (last 50), drained via warnings. */
+class RingBuffer {
+    entries = [];
+    push(message) {
+        this.entries.push(message);
+        if (this.entries.length > RING_CAPACITY)
+            this.entries.shift();
+    }
+    /** Drain-on-read: each warning is delivered to the agent exactly once. */
+    drain() {
+        const out = this.entries;
+        this.entries = [];
+        return out;
+    }
+    get size() {
+        return this.entries.length;
+    }
+}
+export class IngestPipeline {
+    deps;
+    ring = new RingBuffer();
+    limits;
+    buffer = [];
+    flushScheduled = false;
+    /** In-memory event counter for the cap; sessions never resume, so 0 at start is sound. */
+    counted = { sessionId: null, n: 0 };
+    constructor(deps) {
+        this.deps = deps;
+        this.limits = deps.limits ?? {
+            maxPayloadBytes: LIMITS.MAX_PAYLOAD_BYTES,
+            maxEventsPerSession: LIMITS.MAX_EVENTS_PER_SESSION,
+        };
+    }
+    /** Validation + buffering. Runs AFTER the 202 was dispatched. */
+    process(rawBody) {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            return this.reject("dropped malformed event (invalid JSON)");
+        }
+        let event;
+        try {
+            event = parseProbeEvent(parsed);
+        }
+        catch {
+            const probeId = typeof parsed === "object" && parsed !== null && "probe_id" in parsed
+                ? String(parsed.probe_id)
+                : "unknown";
+            return this.reject(`dropped nonconformant event (probe_id=${probeId})`);
+        }
+        const activeId = this.deps.getActiveSessionId();
+        if (activeId === null) {
+            return this.reject(`rejected event (probe_id=${event.probeId}): no active session`);
+        }
+        if (event.sessionId !== activeId) {
+            // probes bake in dead session IDs after a restart -- observable, never silent
+            return this.reject(`rejected event (probe_id=${event.probeId}): session_id ${event.sessionId} is not the active session`);
+        }
+        if (this.counted.sessionId !== activeId)
+            this.counted = { sessionId: activeId, n: 0 };
+        if (this.counted.n >= this.limits.maxEventsPerSession) {
+            return this.reject(`dropped event (probe_id=${event.probeId}): session at MAX_EVENTS_PER_SESSION cap`);
+        }
+        let payloadText = JSON.stringify(event.payload);
+        if (Buffer.byteLength(payloadText) > this.limits.maxPayloadBytes) {
+            payloadText = Buffer.from(payloadText)
+                .subarray(0, this.limits.maxPayloadBytes)
+                .toString();
+            // event KEPT; truncated text may no longer parse as JSON -- documented
+            this.warnOnly(`truncated oversized payload (probe_id=${event.probeId}); event kept`);
+        }
+        const insert = {
+            // attribution at acceptance time: in-run events carry the run_id,
+            // outside events stay NULL = unattributed
+            runId: this.deps.getActiveRunId?.() ?? null,
+            probeId: event.probeId,
+            service: event.service,
+            file: event.file,
+            line: event.line,
+            tsProbe: event.tsProbe,
+            tsServer: Date.now(), // assigned at acceptance
+            payloadText,
+        };
+        if (event.traceId !== undefined)
+            insert.traceId = event.traceId;
+        if (event.parentId !== undefined)
+            insert.parentId = event.parentId;
+        this.buffer.push(insert);
+        this.counted.n += 1;
+        this.scheduleFlush();
+    }
+    /** Once per event-loop tick, one transaction. */
+    scheduleFlush() {
+        if (this.flushScheduled)
+            return;
+        this.flushScheduled = true;
+        setImmediate(() => {
+            this.flushScheduled = false;
+            this.flush();
+        });
+    }
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer;
+        this.buffer = [];
+        const store = this.deps.getStore();
+        if (store === null || this.deps.getActiveSessionId() !== this.counted.sessionId) {
+            this.ring.push(`dropped ${batch.length} buffered event(s): session ended before flush`);
+            log.warn("ingest", `dropped ${batch.length} buffered event(s): session ended before flush`);
+            return;
+        }
+        store.insertEvents(batch);
+    }
+    reject(message) {
+        this.ring.push(message);
+        log.warn("ingest", message);
+    }
+    /** Body exceeded the listener read cap; cannot be kept without unbounded buffering. */
+    rejectOversizedBody(bytes) {
+        this.reject(`dropped event: request body ${bytes} bytes exceeds the read cap`);
+    }
+    warnOnly(message) {
+        this.ring.push(message);
+        log.warn("ingest", message);
+    }
+    /** Surfaced via `warnings` on every tool response. */
+    drainWarnings() {
+        return this.ring.drain();
+    }
+    /**
+     * Stage a warning from outside the ingest path (e.g. the startup stale-
+     * session scan) onto the same observability channel.
+     */
+    pushWarning(message) {
+        this.ring.push(message);
+    }
+}
+export async function startIngestListener(pipeline) {
+    // generous read cap: payloads up to ~2x the payload cap still parse and get
+    // truncate-kept; beyond it we cannot keep a valid event without unbounded
+    // buffering, so the body is dropped (with warning). 202 is sent regardless.
+    const readCap = pipeline.limits.maxPayloadBytes * 2 + 4096;
+    const server = createServer((req, res) => {
+        if (req.method !== "POST" || req.url !== "/events") {
+            res.statusCode = 404;
+            res.end();
+            return;
+        }
+        const chunks = [];
+        let received = 0;
+        let overCap = false;
+        req.on("data", (chunk) => {
+            received += chunk.length;
+            if (received > readCap) {
+                overCap = true;
+                chunks.length = 0; // stop buffering; memory guard
+            }
+            else if (!overCap) {
+                chunks.push(chunk);
+            }
+        });
+        req.on("end", () => {
+            // 202 FIRST -- a probe never waits on validation
+            res.statusCode = 202;
+            res.end();
+            setImmediate(() => {
+                if (overCap) {
+                    pipeline.rejectOversizedBody(received);
+                    return;
+                }
+                pipeline.process(Buffer.concat(chunks).toString());
+            });
+        });
+        req.on("error", () => {
+            /* client vanished mid-request (fire-and-forget near unload) -- never an error */
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    log.info("ingest", `listening on 127.0.0.1:${address.port}`);
+    return {
+        port: address.port,
+        server,
+        close: () => new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+    };
+}

package/dist/logger.js

@@ -0,0 +1,18 @@
+/**
+ * stderr-only logger. stdout belongs to MCP stdio framing — writing to it
+ * anywhere outside the transport is a build-breaking offense.
+ *
+ * Format: `[level] component: message`. `[debug]` is gated by the DEBUG env var.
+ * Timestamps, when needed, are ISO 8601 (epoch-ms is a wire/store rule only).
+ */
+function write(level, component, message) {
+    if (level === "debug" && !process.env.DEBUG)
+        return;
+    process.stderr.write(`[${level}] ${component}: ${message}\n`);
+}
+export const log = {
+    debug: (component, message) => write("debug", component, message),
+    info: (component, message) => write("info", component, message),
+    warn: (component, message) => write("warn", component, message),
+    error: (component, message) => write("error", component, message),
+};

package/dist/node-version.js

@@ -0,0 +1,18 @@
+/**
+ * Runtime Node version gate: `engines` is advisory; this
+ * check is the real gate. It must run before any module that imports
+ * `node:sqlite` loads — keep this module dependency-free.
+ */
+/** Floor where `node:sqlite` runs flag-free. */
+export const MIN_NODE_VERSION = "22.13.0";
+export function meetsMinimumNode(version) {
+    const [major = 0, minor = 0, patch = 0] = version
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+    const [minMajor = 0, minMinor = 0, minPatch = 0] = MIN_NODE_VERSION.split(".").map(Number);
+    if (major !== minMajor)
+        return major > minMajor;
+    if (minor !== minMinor)
+        return minor > minMinor;
+    return patch >= minPatch;
+}

package/dist/server.js

@@ -0,0 +1,90 @@
+/**
+ * MCP server setup. stdout is sacred — it carries stdio MCP framing and
+ * nothing else; all diagnostics go through the stderr logger.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MARKER_TOKEN, PLAYBOOK_URI, TOOL_NAME } from "./constants.js";
+import { IngestPipeline, startIngestListener } from "./ingest/ingest.js";
+import { log } from "./logger.js";
+import { clientSupportsElicitation } from "./session/run-boundaries.js";
+import { SessionManager } from "./session/session-manager.js";
+import { registerTools } from "./tools.js";
+const SERVER_VERSION = "0.1.0";
+let playbookCache = null;
+/**
+ * Load the playbook prose. Built layout first (dist/server.js
+ * finds its sibling dist/assets/playbook.md, the build-injected artifact),
+ * then the repo template (../assets/playbook.md — dev under tsx/vitest).
+ * The {{MARKER_TOKEN}} replacement is ALWAYS applied: idempotent on the
+ * injected file, and what makes dev mode serve real tokens (belt and
+ * braces with build-playbook.mjs). Loaded lazily at first resource read —
+ * never on the ingestion hot path; a missing file is a loud error on read,
+ * never a crash at connect. `candidates` is a test seam.
+ */
+export function loadPlaybook(candidates) {
+    if (candidates === undefined && playbookCache !== null)
+        return playbookCache;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const paths = candidates ?? [
+        join(here, "assets", "playbook.md"),
+        join(here, "..", "assets", "playbook.md"),
+    ];
+    for (const path of paths) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const text = raw.replaceAll("{{MARKER_TOKEN}}", MARKER_TOKEN);
+        if (candidates === undefined)
+            playbookCache = text;
+        return text;
+    }
+    log.error("server", `playbook not found (looked in: ${paths.join(", ")})`);
+    throw new Error("playbook resource unavailable: assets/playbook.md is missing from this installation");
+}
+export function createServer(deps) {
+    const server = new McpServer({ name: TOOL_NAME, version: SERVER_VERSION });
+    registerTools(server, deps);
+    server.registerResource("playbook", PLAYBOOK_URI, {
+        title: "Probe Playbook",
+        description: "Probe conventions, event contract, and strategy — pull once at session start.",
+        mimeType: "text/markdown",
+    }, (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "text/markdown", text: loadPlaybook() }],
+    }));
+    return server;
+}
+// Capability detection lives with the ladder; re-exported for callers.
+export { clientSupportsElicitation };
+export async function startStdioServer() {
+    // Listener starts at process startup; port is per-process (Validation Issue #2).
+    const manager = new SessionManager();
+    const pipeline = new IngestPipeline({
+        getActiveSessionId: () => manager.activeSessionId,
+        getStore: () => manager.activeStore,
+        getActiveRunId: () => manager.activeRunId,
+    });
+    const ingest = await startIngestListener(pipeline);
+    const server = createServer({
+        manager,
+        ingestPort: () => ingest.port,
+        drainWarnings: () => pipeline.drainWarnings(),
+    });
+    // Startup orphan scan: surface stale sessions on stderr now and on
+    // the next tool response via the warnings channel.
+    for (const orphan of manager.scanOrphans()) {
+        const created = orphan.created ? ` created ${new Date(orphan.created).toISOString()}` : "";
+        log.warn("session", `stale session found: ${orphan.sessionId}${orphan.goal ? ` ("${orphan.goal}")` : ""}${created}`);
+        pipeline.pushWarning(`stale session ${orphan.sessionId}${orphan.goal ? ` ("${orphan.goal}")` : ""} exists; start_session will require a stale decision`);
+    }
+    await server.connect(new StdioServerTransport());
+    log.info("server", `${TOOL_NAME} connected over stdio`);
+    log.debug("server", `client elicitation support: ${clientSupportsElicitation(server)}`);
+}

package/dist/session/run-boundaries.js

@@ -0,0 +1,44 @@
+import { ELICIT_TIMEOUT_MS } from "../constants.js";
+import { log } from "../logger.js";
+/**
+ * Capability detection: client
+ * capabilities advertise elicitation support; checked at call time.
+ */
+export function clientSupportsElicitation(server) {
+    return Boolean(server.server.getClientCapabilities()?.elicitation);
+}
+/** Open a run and walk the ladder. Never throws for ladder outcomes. */
+export async function armRun(deps) {
+    const { runId, n } = deps.manager.startRun(deps.tag);
+    if (!clientSupportsElicitation(deps.server)) {
+        // fallback rung: run stays open; end_run closes it when the user says "done"
+        return { kind: "open", runId, reason: "no_elicitation" };
+    }
+    try {
+        const result = await deps.server.server.elicitInput({
+            message: `Run #${n} armed — click through the flow, confirm here when done.`,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    done: { type: "boolean", description: "Confirm the run is complete" },
+                },
+            },
+        }, { timeout: deps.elicitTimeoutMs ?? ELICIT_TIMEOUT_MS });
+        if (result.action === "accept") {
+            const closed = deps.manager.closeRun();
+            return { kind: "closed", ...closed };
+        }
+        // decline or cancel: abort — events become unattributed, never discarded
+        const { runId: aborted } = deps.manager.abortRun();
+        log.warn("run-boundaries", `run ${aborted} ${result.action}d by user; aborted`);
+        return { kind: "aborted", runId: aborted };
+    }
+    catch (err) {
+        // timeout or transport failure: the run stays open; end_run closes it
+        const reason = err instanceof Error && /timeout|timed out/i.test(err.message)
+            ? "elicitation_timeout"
+            : "elicitation_failed";
+        log.warn("run-boundaries", `elicitation for ${runId} failed (${reason}); run stays open`);
+        return { kind: "open", runId, reason };
+    }
+}