bantamkit-mcp 0.26.0

package/dist/mcp/transport.js

@@ -0,0 +1,111 @@
+import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+import { PY_LINESEP } from '../memory/pyfs.js';
+/** A JSON-RPC id is a string or a number; the map key is its JSON text, which is total. */
+const idKey = (id) => JSON.stringify(id ?? null);
+export class RawStdioTransport {
+    input;
+    output;
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    buffer = Buffer.alloc(0);
+    started = false;
+    rawLines = new Map();
+    exactResults = new Map();
+    ondata = (chunk) => this.consume(chunk);
+    onstreamerror = (error) => this.onerror?.(error);
+    constructor(input = process.stdin, output = process.stdout) {
+        this.input = input;
+        this.output = output;
+    }
+    /** The verbatim request line that carried this id, or `undefined` if it is gone. */
+    rawLineFor(id) {
+        return this.rawLines.get(idKey(id));
+    }
+    /** Register the exact JSON text to send as this request's `result`. */
+    setExactResult(id, json) {
+        this.exactResults.set(idKey(id), json);
+    }
+    async start() {
+        if (this.started)
+            throw new Error('RawStdioTransport already started');
+        this.started = true;
+        this.input.on('data', this.ondata);
+        this.input.on('error', this.onstreamerror);
+    }
+    async close() {
+        this.input.off('data', this.ondata);
+        this.input.off('error', this.onstreamerror);
+        if (this.input.listenerCount('data') === 0)
+            this.input.pause();
+        this.buffer = Buffer.alloc(0);
+        this.rawLines.clear();
+        this.exactResults.clear();
+        this.onclose?.();
+    }
+    send(message) {
+        return new Promise((resolve) => {
+            const text = this.frame(message);
+            // `os.linesep`, because the reference's stdout is a TEXT stream. The Python SDK writes
+            // its frames through `TextIOWrapper(sys.stdout.buffer)` with the default
+            // `newline=None`, so on Windows every frame CPython emits ends `\r\n`. MEASURED, run
+            // 32646521489: all nine `wire/*: raw frame bytes` cases differed by exactly one byte
+            // per frame and by nothing else. A client is free to strip it; a port that claims to
+            // be byte-compatible on the wire does not get to decide it is decoration.
+            if (this.output.write(`${text}${PY_LINESEP}`))
+                resolve();
+            else
+                this.output.once('drain', () => resolve());
+        });
+    }
+    /**
+     * One frame, in the reference's key order, with an exact `result` when one was registered.
+     *
+     * The raw line and the exact text are both dropped here rather than in the handler: the
+     * handler cannot know whether the protocol will actually send its answer (a cancelled
+     * request never reaches `send`), and a map that only ever grows is a leak in a process
+     * that is meant to run for a session.
+     */
+    frame(message) {
+        const framed = message;
+        if (framed.id === undefined)
+            return JSON.stringify(message);
+        const key = idKey(framed.id);
+        this.rawLines.delete(key);
+        const id = JSON.stringify(framed.id);
+        if ('result' in framed) {
+            const exact = this.exactResults.get(key);
+            this.exactResults.delete(key);
+            return `{"jsonrpc":"2.0","id":${id},"result":${exact ?? JSON.stringify(framed.result)}}`;
+        }
+        this.exactResults.delete(key);
+        if ('error' in framed)
+            return `{"jsonrpc":"2.0","id":${id},"error":${JSON.stringify(framed.error)}}`;
+        return JSON.stringify(message);
+    }
+    consume(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        for (;;) {
+            const at = this.buffer.indexOf(0x0a);
+            if (at === -1)
+                return;
+            const line = this.buffer.toString('utf8', 0, at).replace(/\r$/, '');
+            this.buffer = this.buffer.subarray(at + 1);
+            if (line.trim() === '')
+                continue;
+            let message;
+            try {
+                message = JSONRPCMessageSchema.parse(JSON.parse(line));
+            }
+            catch (error) {
+                this.onerror?.(error);
+                continue;
+            }
+            const id = message.id;
+            if (id !== undefined)
+                this.rawLines.set(idKey(id), line);
+            this.onmessage?.(message);
+        }
+    }
+}

package/dist/mcpreport.d.ts

@@ -0,0 +1,214 @@
+import { formatTimestamp } from './eventlog.js';
+/**
+ * Overrides the platform default for the host-log root. The default is only KNOWN on macOS
+ * (see `defaultHostLogRoot`), so this is what makes the analyst usable at all on Linux and
+ * Windows — and what lets a test run against a fixture tree.
+ */
+export declare const HOST_LOG_ROOT_ENV = "BANTAMKIT_HOST_LOG_ROOT";
+/**
+ * The ONLY directory name read under a slug directory. `mcp-logs-clickup` and sixteen
+ * others sit beside it; globbing `mcp-logs-*` would read another program's log.
+ */
+export declare const HOST_LOG_DIRNAME = "mcp-logs-bantamkit";
+/**
+ * How far outside the host's `[dispatch, completion]` interval an event's `ts` may fall and
+ * still be a CANDIDATE. Not a tolerance for clock skew — both stamps come from one machine
+ * clock — but for the lag between the component deciding and the host stamping the reply it
+ * eventually read. Widening it produces MORE ambiguity, not more matches.
+ */
+export declare const DEFAULT_WINDOW_MS = 250;
+/** Report format version. Bump when a section, a field or an order changes; both runtimes move together. */
+export declare const REPORT_VERSION = 1;
+/**
+ * Outcomes worth asking "and then what?" about. An `escalate` that ended a session and an
+ * `escalate` followed by nine more calls are different facts about the same word.
+ */
+export declare const FOLLOW_UP_OUTCOMES: readonly string[];
+/**
+ * `2026-08-23T17:38:47.243Z` -> integer epoch milliseconds, or `null`.
+ *
+ * Hand-rolled rather than `Date.parse` for the reason the reference is hand-rolled rather
+ * than `datetime.fromisoformat`: each stdlib accepts a DIFFERENT wider set (`+00:00`, no
+ * `Z`, six fractional digits, `2026-08-23` alone), and this is a compared field. A parser
+ * that accepted more would put records on the timeline the host never put there. One regex
+ * that admits exactly the host's spelling is the same function on both sides.
+ *
+ * The arithmetic is done in integers here: no `Date` object is constructed on the way IN,
+ * so no local time zone can reach the answer. `formatTimestamp` is the event log's, which
+ * is `toISOString()` and is UTC by definition — the two are inverses over the range that
+ * matters.
+ */
+export declare function parseTimestamp(text: string): number | null;
+/** The inverse, reusing the event log's formatter so one spelling exists in the repo. */
+export { formatTimestamp };
+/**
+ * One classified host line. THERE IS NO FIELD HERE THAT CAN HOLD HOST TEXT.
+ *
+ * `kind` is a token from this module's vocabulary, `tool` passed `[a-z0-9_]{1,64}`,
+ * `session` passed `[A-Za-z0-9-]{1,64}`, and the rest are integers. That is the whole leak
+ * guard: not a filter applied on the way out, but an absence of anywhere to put it.
+ */
+export interface HostRecord {
+    readonly tsMs: number;
+    readonly session: string;
+    readonly kind: 'call-start' | 'call-ok' | 'call-fail' | 'error' | 'other';
+    readonly tool: string | null;
+    readonly durationMs: number | null;
+}
+/**
+ * One JSONL line -> a `HostRecord`, or `null` for anything unparseable.
+ *
+ * `null` covers a blank line, a truncated tail (the host is appending while this reads), a
+ * record with no usable timestamp, and a record with no `debug` and no `error` string. All
+ * of them are counted as `unclassified` by the caller and nothing else.
+ */
+export declare function parseHostLine(line: string): HostRecord | null;
+/** A dispatch paired with its completion. Either end may be missing; say which. */
+export interface HostCall {
+    readonly tool: string;
+    readonly session: string;
+    readonly startMs: number | null;
+    readonly endMs: number | null;
+    readonly ok: boolean | null;
+    readonly durationMs: number | null;
+}
+/** The one timestamp the join hangs on when only one end was logged. */
+export declare function anchorMs(call: HostCall): number;
+export interface PairedCalls {
+    readonly calls: HostCall[];
+    readonly incomplete: number;
+    readonly orphanCompletions: number;
+}
+/**
+ * Dispatches to completions, FIFO within one `(session, tool)`.
+ *
+ * FIFO and not nearest-time, because within one session and one tool the host's own file
+ * order IS the dispatch order — it is one writer appending. Across sessions or across tools
+ * no order is assumed, which is why the queue key carries both.
+ *
+ * Returns the calls plus two honesty counters: dispatches that never completed (the process
+ * was killed, or the file was rotated mid-call) and completions with no dispatch in view
+ * (the dispatch is in an earlier file that was rotated away).
+ */
+export declare function pairCalls(records: readonly HostRecord[]): PairedCalls;
+/** What source A yielded, including the reason it yielded nothing. */
+export interface HostScan {
+    readonly root: string | null;
+    readonly missing: null | 'not-found' | 'unknown-platform';
+    readonly platform: string;
+    readonly dirs: number;
+    readonly files: number;
+    readonly records: number;
+    readonly lifecycle: number;
+    readonly unclassified: number;
+    readonly errors: number;
+    readonly errorsWithTool: number;
+    readonly calls: HostCall[];
+    readonly incomplete: number;
+    readonly orphanCompletions: number;
+}
+/**
+ * `~/Library/Caches/claude-cli-nodejs` — ON macOS, AND NOWHERE ELSE.
+ *
+ * Where Claude Code writes this on Linux and on Windows has NOT been measured, and a guess
+ * dressed as a default would produce an empty report that reads like "nothing happened". So
+ * off darwin this returns `null`, the report says which platform it is on and names
+ * `BANTAMKIT_HOST_LOG_ROOT`, and source B is reported alone. `CLAUDE.md`'s parity rule is
+ * satisfied by the analyst RUNNING on Windows and saying what it cannot see, not by
+ * pretending it looked. Lifting the limitation is a MEASUREMENT, not a code change.
+ */
+export declare function defaultHostLogRoot(platform: string, home: string): string | null;
+export declare function resolveHostLogRoot(env: Readonly<Record<string, string | undefined>>, platform?: string, home?: string): string | null;
+/**
+ * Every `<root>/*​/mcp-logs-bantamkit/*.jsonl`, sorted, and NOTHING else.
+ *
+ * The slug directories are listed and each is asked for `mcp-logs-bantamkit` BY NAME. No
+ * `mcp-logs-*` pattern is ever built, so a sibling server's directory cannot be reached by
+ * this function even by accident — `mcp-logs-clickup` is right there.
+ */
+export declare function hostLogFiles(root: string): string[];
+/**
+ * `platform` is carried into the scan, not read at render time, so an injected platform
+ * reaches the "unknown on this platform" line and a test can see it.
+ */
+export declare function scanHostLog(root: string | null, platform?: string): HostScan;
+export interface Event {
+    readonly tsMs: number;
+    readonly tool: string;
+    readonly outcome: string;
+}
+export interface EventScan {
+    readonly path: string | null;
+    readonly missing: null | 'not-found' | 'off';
+    readonly records: number;
+    readonly unreadable: number;
+    readonly events: Event[];
+}
+/** One `docs/eventlog.md` record. Wrong shape or wrong `ts` -> `null`. */
+export declare function parseEventLine(line: string): Event | null;
+/**
+ * Reads the live file AND the one rotated generation, because the rotation rule keeps
+ * `<path>.1` and a report that ignored it would lose the older half of a session.
+ */
+export declare function scanEventLog(path: string | null): EventScan;
+/**
+ * The whole result of the join, uncertainty first.
+ *
+ * `matched` holds only MUTUALLY UNIQUE pairs. `ambiguousGroups` holds the size of every
+ * component that was not one-to-one, as `[events, calls]`. Nothing is dropped: every event
+ * lands in exactly one of matched / ambiguous / unmatched, and so does every call.
+ */
+export interface Join {
+    readonly windowMs: number;
+    readonly matched: [Event, HostCall][];
+    readonly ambiguousGroups: [number, number][];
+    readonly ambiguousEvents: number;
+    readonly ambiguousCalls: number;
+    readonly unmatchedEvents: Event[];
+    readonly unmatchedCalls: HostCall[];
+}
+/**
+ * Mutual uniqueness or nothing.
+ *
+ * A greedy nearest-time pass would produce a bigger `matched` number and a report that lies
+ * about which session an outcome belongs to. The component rule cannot: an event whose
+ * candidate call is also some other event's candidate is not paired with it, and both land
+ * in one ambiguous group whose sizes are printed. The traversal is ITERATIVE — a busy day
+ * is thousands of calls and a recursive flood fill would blow the stack on the one input
+ * that matters.
+ */
+export declare function join(events: readonly Event[], calls: readonly HostCall[], windowMs: number): Join;
+/**
+ * The LOWER median: an element of the input, never a mean.
+ *
+ * A mean of two integers is a float, a float has to be formatted, and two runtimes format
+ * floats differently at the edges. `Array.prototype.sort` is LEXICOGRAPHIC by default, so
+ * the numeric comparator is not decoration: `[9, 51]` sorts to `[51, 9]` without it.
+ */
+export declare function p50(values: readonly number[]): number;
+/** The report, as the bytes `docs/mcpreport.md` specifies. No clock is read here. */
+export declare function render(host: HostScan, events: EventScan, joined: Join): string;
+export interface ReportOptions {
+    readonly windowMs?: number;
+    readonly platform?: string;
+    readonly home?: string;
+}
+export declare function buildReport(env: Readonly<Record<string, string | undefined>>, eventLogPath: string | null, options?: ReportOptions): string;
+/**
+ * Where source B would be for THIS invocation, resolved exactly as the server resolves it.
+ *
+ * ONE VOCABULARY FOR `BANTAMKIT_EVENT_LOG`, NOT TWO: `eventlog.resolvePath` decides
+ * off / default / literal, and this only supplies the store root it needs. The root comes
+ * from `--store` when given and otherwise from `discoverProjectStore`, which walks up and
+ * DESIGNATES without creating anything — so asking for a report never brings a store into
+ * existence.
+ *
+ * A pinned `BANTAMKIT_MEMORY_DIR` that does not exist makes the walk throw. That is a real
+ * answer, not a crash to hide: the report then names the path the walk would have
+ * designated, and the `not found at` line says the rest.
+ *
+ * `pyJoin` on the way out because the reference returns a `Path` and prints `str(Path)`,
+ * which collapses `//` and `./` in a literal the operator typed. The file identity does not
+ * move; the printed line does, and the line is compared byte for byte.
+ */
+export declare function resolveEventLogPath(env: Readonly<Record<string, string | undefined>>, store?: string | null, start?: string | null): string | null;