bantamkit-mcp 0.26.0

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+export interface Options {
+    k: number;
+    indexBudget: number;
+    store: string | null;
+    start: string | null;
+    assetsRoot: boolean;
+    mcpReport: boolean;
+    statusline: boolean;
+}
+/** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
+export declare function parseArgs(argv: readonly string[]): Options;

package/dist/cli.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * The `bantamkit-mcp` entry point: the stdio MCP server, and six flags.
+ *
+ * THE COMMAND LINE IS DATA, NOT PRINTED TEXT. `PARSER` below is the whole description of
+ * this CLI, and `pyargparse.ts` renders it — the help table, the usage line at whatever
+ * width the terminal is, and every `bantamkit-mcp: error: …` block — with CPython
+ * `argparse`'s own algorithm. There WAS a hand-written `USAGE` constant here; it printed to
+ * the wrong stream, it had already gone stale (it never grew `[--assets-root]`), and a
+ * second hardcoded copy of a generated string is exactly the defect the `cli` conformance
+ * suite was built to catch. Add a flag to `PARSER` and the help cannot fall behind it.
+ *
+ * N1 shipped this file as a refusal — exit 69 rather than a stub that pretended to be a
+ * server — because stdout is the JSON-RPC channel and anything printed there reaches a host
+ * as a malformed frame instead of as "not wired yet". THE REFUSAL IS RETIRED HERE, and it has
+ * to be: the production invocation passes NO arguments at all (`.mcp.json` and the user-scope
+ * config both call the launcher bare), so the bare form is the one that must serve. What the
+ * refusal was protecting is kept and is now checked directly — `test/server.test.mjs` asserts
+ * that every line a real session put on stdout parses as a JSON-RPC frame, that stdout never
+ * ends mid-line, and that a clean session writes nothing to stderr either.
+ *
+ * PRODUCTION RUNS LAYERED. No `--store` means `Memory.layered`, which prepends `[project] `
+ * to a recall line; a build validated only against `--store` would ship a recall string the
+ * real deployment never produces.
+ *
+ * `--mcp-report` is the second flag that prints and returns before a transport is opened. Its
+ * contract is `docs/mcpreport.md` and its implementation is `src/mcpreport.ts`; what belongs
+ * HERE is only that it is registered after `--index-budget` and before the store group, which
+ * is what keeps the wrapped usage line byte-identical to the reference's.
+ *
+ * `--assets-root` stays. It is the arm-2 (packaged) resolution running inside a real install,
+ * so `npx`/`npm i -g` can be checked end to end without speaking the protocol. It is also the
+ * only path in this file that writes to stdout without being a frame, and it exits before a
+ * transport is ever started.
+ *
+ * THERE IS NO `--which` HERE, AND THE REASON IS NOT THE ONE THIS COMMENT USED TO GIVE.
+ * It said the flag "has no consumer anywhere in the repository or its history" and that
+ * therefore "no Node `--which` is budgeted here". Both halves are false as of `3dbedd3` on
+ * this branch: `tools/bantamkit-mcp-node` ships `--which`, and
+ * `runtime-ts/test/launcher.test.mjs` exercises it in two nodes — one over a checkout that
+ * has never been built, one over a worktree, where the flag is the only place `deps_root`
+ * diverging from `checkout` is observable at all. It is budgeted, it exists, and it is
+ * tested. (The narrow fact that comment was built on does survive: no `mcpreach` program has
+ * ever been added on any ref — `git log --all --diff-filter=A -- '*mcpreach*'` is empty,
+ * measured again 2026-08-24. A missing consumer was never the same claim as a missing flag.)
+ *
+ * WHAT IS ACTUALLY TRUE OF THIS FILE. `--which` reports where a CHECKOUT resolved its halves
+ * — the source tree, the dependency root, the entry point, the SDK — and a published `npx`
+ * package does not run from a checkout. There is no second half to report and no ambiguity
+ * about which one answered, so the flag has nothing to say at package level. The question it
+ * reaches for is answered on the wire instead, by `build_identity`. `runtime-ts/README.md`
+ * and `docs/install.md` carry the same correction in their own words.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { assetsRoot } from './assets.js';
+import { BantamError } from './errors.js';
+import { buildReport, resolveEventLogPath } from './mcpreport.js';
+import { Memory } from './memory/component.js';
+import { DEFAULT_INDEX_BUDGET } from './memory/store.js';
+import { buildServer } from './mcp/server.js';
+import { RawStdioTransport } from './mcp/transport.js';
+import { ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs as parseWithSpec, pyIntStrict, } from './pyargparse.js';
+import { statusLine } from './statusline.js';
+/** `SystemExit("...")`: the message on stderr, exit 1. */
+class Refusal extends Error {
+}
+/**
+ * `_parse_args`'s parser, as DATA — the one description of this command line in the runtime.
+ *
+ * THERE IS NO SECOND COPY OF THE USAGE LINE. There used to be: a `USAGE` constant here,
+ * written by hand, printed to the wrong stream, and already stale (it never grew
+ * `[--assets-root]`). Every string a user sees — the usage line at whatever width the
+ * terminal is, the option table, and the `bantamkit-mcp: error: …` block — is generated from
+ * this object by `pyargparse.ts`, so a flag added below cannot go missing from the help.
+ *
+ * POSITION IS WIRE-VISIBLE, exactly as it is in the reference: argparse prints optionals in
+ * the order they were added, so this array — not any format string — decides where
+ * `[--assets-root]` sits in the generated usage.
+ */
+const PARSER = {
+    prog: 'bantamkit-mcp',
+    description: 'bantamkit MCP server (stdio): per-person memory + JSON validation.',
+    actions: [
+        {
+            optionStrings: ['-h', '--help'],
+            dest: 'help',
+            kind: 'help',
+            help: 'show this help message and exit',
+            defaultValue: false,
+        },
+        {
+            optionStrings: ['--assets-root'],
+            dest: 'assets_root',
+            kind: 'storeTrue',
+            help: 'print the resolved asset pack root and its file count, then exit',
+            defaultValue: false,
+        },
+        {
+            optionStrings: ['--k'],
+            dest: 'k',
+            kind: 'store',
+            help: 'default recall budget (default: 3)',
+            convert: pyIntStrict,
+            typeName: 'int',
+            defaultValue: 3,
+        },
+        {
+            optionStrings: ['--index-budget'],
+            dest: 'index_budget',
+            metavar: 'BYTES',
+            kind: 'store',
+            help: `memory index byte budget (default: ${DEFAULT_INDEX_BUDGET})`,
+            convert: pyIntStrict,
+            typeName: 'int',
+            defaultValue: DEFAULT_INDEX_BUDGET,
+        },
+        // WHY THIS IS A FLAG ON THIS PROCESS AND NOT A NEW ENTRY POINT, and why it sits HERE.
+        // The lifecycle argument against printing from this process -- stdout is the JSON-RPC
+        // channel -- is true of a RUNNING server and not of a flag that prints and returns before
+        // a transport exists; `--assets-root` above is the precedent. It is decisive rather than
+        // merely convenient on this side: `package.json` declares exactly one bin, so anything
+        // hung off a second entry point is unreachable in the pure-npx install that is the
+        // shipped product.
+        //
+        // POSITION IS WIRE-VISIBLE AND IT IS MEASURED. `--assets-root` sits first because it
+        // needs NOTHING; this one honours `--store`/`--start` to find the event log, so it is
+        // registered after the flags it consumes and before the store group. At the 80-column
+        // fallback argparse breaks the usage after `[--index-budget BYTES]`, and that first line
+        // is pinned in `test_mcpserver.py` and as a THROWING precondition in
+        // `tools/conformance/suites/cli.mjs`. Registering here leaves it byte-identical;
+        // registering earlier would move it and turn a differential suite into a re-baselining
+        // one. Do not reorder this array to taste.
+        {
+            optionStrings: ['--mcp-report'],
+            dest: 'mcp_report',
+            kind: 'storeTrue',
+            help: "print an analysis of the host MCP log joined with bantamkit's event log, then exit",
+            defaultValue: false,
+        },
+        // THE SAME THREE ARGUMENTS AS `--mcp-report`, and the same place for the same reason:
+        // it prints and returns before a transport exists; the single bin this package declares
+        // makes a flag the ONLY reachable surface in the shipped npx install, which is what a
+        // Claude Code `statusLine` registration has to name; and it honours `--store`/`--start`
+        // to find the event log, so it belongs after the flags it consumes. Registering it here
+        // leaves the FIRST line of the 80-column usage -- the pinned one -- byte-identical.
+        {
+            optionStrings: ['--statusline'],
+            dest: 'statusline',
+            kind: 'storeTrue',
+            help: 'print one status line for a host status bar, then exit',
+            defaultValue: false,
+        },
+        {
+            optionStrings: ['--store'],
+            dest: 'store',
+            kind: 'store',
+            help: 'single memory store path (disables layering)',
+            defaultValue: null,
+        },
+        {
+            optionStrings: ['--start'],
+            dest: 'start',
+            kind: 'store',
+            help: 'directory to start project-store discovery from (default: cwd)',
+            defaultValue: null,
+        },
+    ],
+    groups: [[6, 7]],
+};
+/** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
+export function parseArgs(argv) {
+    const values = parseWithSpec(PARSER, argv);
+    return {
+        k: values['k'],
+        indexBudget: values['index_budget'],
+        store: values['store'],
+        start: values['start'],
+        assetsRoot: values['assets_root'],
+        mcpReport: values['mcp_report'],
+        statusline: values['statusline'],
+    };
+}
+/** `_build_memory`, including the two refusals argparse cannot express. */
+function buildMemory(options) {
+    if (options.k < 1)
+        throw new Refusal('--k must be >= 1');
+    if (options.indexBudget < 1)
+        throw new Refusal('--index-budget must be >= 1');
+    const shared = { k: options.k, indexBudget: options.indexBudget };
+    if (options.store !== null) {
+        if (options.store === '')
+            throw new Refusal('--store requires a non-empty path');
+        return new Memory(options.store, shared);
+    }
+    return Memory.layered(options.start, shared);
+}
+/**
+ * The version this build declares — the same bytes npm packs the tarball from.
+ *
+ * `RB-P45`'s defect has no Node analogue to fall back from: there is no installed dist-info
+ * that can go stale, because `package.json` IS the install record and it ships in the package.
+ */
+function version() {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+async function main(argv) {
+    const options = parseArgs(argv);
+    if (options.assetsRoot) {
+        const root = assetsRoot();
+        let files = 0;
+        for (const entry of readdirSync(root, { withFileTypes: true, recursive: true })) {
+            if (entry.isFile())
+                files += 1;
+        }
+        process.stdout.write(`${root}\n${files} files\n`);
+        return 0;
+    }
+    if (options.mcpReport) {
+        // Same discipline as `--assets-root`, and the same place in `main`: BEFORE
+        // `buildMemory`, which touches the filesystem, and before the transport exists at all.
+        // NOTHING HERE IS WRITTEN — `mcpreport` opens the host's log read-only, creates no
+        // directory under its root, and `resolveEventLogPath` DESIGNATES a store path without
+        // bringing a store into existence. The report is an observation, not a session.
+        //
+        // `process.stdout.write` of a UTF-8 string is LF on every platform, which is what the
+        // reference goes through `sys.stdout.buffer` to get: `print` would emit CRLF on Windows
+        // where this emits LF, and the conformance suite compares these bytes.
+        process.stdout.write(buildReport(process.env, resolveEventLogPath(process.env, options.store, options.start)));
+        return 0;
+    }
+    if (options.statusline) {
+        // Same discipline and the same place as `--mcp-report`: before `buildMemory`, before a
+        // transport exists, and nothing is written anywhere. `statusLine` is TOTAL -- there is
+        // no failure arm to print here, which is the whole property this surface exists to
+        // hold. `process.stdout.write` of a UTF-8 string is LF on every platform, which is
+        // what the reference goes through `sys.stdout.buffer` to get.
+        process.stdout.write(`${statusLine(process.env, options.store, options.start)}\n`);
+        return 0;
+    }
+    const memory = buildMemory(options);
+    const wire = new RawStdioTransport();
+    const server = buildServer(memory, wire, version());
+    await server.connect(wire);
+    // `asyncio.run(server.run_stdio_async())` returns when the client closes stdin. Here the
+    // process stays alive on the stdin listener until the transport closes, which is what an
+    // EOF on stdin means: the host has gone.
+    await new Promise((resolve) => {
+        wire.onclose = () => resolve();
+        process.stdin.on('end', () => void wire.close());
+    });
+    return 0;
+}
+try {
+    process.exitCode = await main(process.argv.slice(2));
+}
+catch (error) {
+    if (error instanceof HelpRequested) {
+        // `-h` is an ACTION, not a flag read after parsing: argparse prints and exits 0 the
+        // moment it is taken, which is why `-h --nope` is help-and-0 and not an argv error. It
+        // goes to STDOUT — the one place in this file besides `--assets-root` that writes there
+        // without being a JSON-RPC frame, and it exits before a transport is ever started.
+        process.stdout.write(formatHelp(PARSER, helpWidth()));
+        process.exitCode = 0;
+    }
+    else if (error instanceof ArgvError) {
+        process.stderr.write(`${formatUsageBlock(PARSER, helpWidth())}bantamkit-mcp: error: ${error.message}\n`);
+        process.exitCode = 2;
+    }
+    else if (error instanceof Refusal) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 1;
+    }
+    else if (error instanceof BantamError) {
+        process.stderr.write(`bantamkit-mcp: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/contract.d.ts

@@ -0,0 +1,145 @@
+import { BantamError } from './errors.js';
+import { type PyValue } from './pyjson.js';
+/**
+ * `contract.REQUIRED_KEYS`, in Python's order — the order the error message lists them.
+ *
+ * `bantamkit_read_page_next` and `bantamkit_read_unknown_part` are deliberately NOT here:
+ * the reference's tuple does not carry them (R1 added the sentences to the asset and not to
+ * the tuple), and `missing key(s): ...` lists this tuple verbatim, so a Node list that was
+ * two keys longer would refuse a thin contract with a sentence Python does not print. The
+ * two renderers below fetch their key at call time and raise by name if it is absent, which
+ * is the `KeyError` the reference would raise at the same moment.
+ */
+export declare const REQUIRED_KEYS: readonly ["schema_instruction", "schema_retry", "critique_feedback", "parse_error", "validation_error", "json_answer_retry", "loop_note", "loop_warn", "evidence_line", "evidence_no_observation", "evidence_empty", "document_manifest_empty", "document_manifest_part", "document_manifest_header_row", "document_manifest_first_row", "document_manifest_last_row", "document_manifest_package_media", "document_manifest_omitted_media", "document_manifest_omitted_blank", "document_manifest_omitted_format", "document_manifest_omitted_unread_page", "document_manifest_unread_no_operator", "document_manifest_unread_unmapped", "document_manifest_unread_whitespace", "document_manifest_unread_no_character", "document_manifest_omitted_unmapped", "document_manifest_omitted_other", "document_page_header", "document_page_next", "document_page_end", "document_page_truncated", "document_unknown", "document_offset_past_end", "document_error", "document_paste_preamble", "document_paste_part", "document_paste_complete", "document_paste_truncated", "document_paste_none", "tool_failed", "tool_arguments", "tool_arguments_none", "tool_argument_types", "tool_argument_type"];
+export declare class ContractParseError extends BantamError {
+}
+/**
+ * `yaml.safe_load` reduced to the document `assets/contracts/default.yaml` actually is.
+ *
+ * HOW default.yaml IS READ, AND WHY THAT IS SAFE WITH NO YAML ENGINE IN THE PACKAGE.
+ * N4's `parseConfigDocument` reads a DIFFERENT document — a hand-written `config.yaml` whose
+ * values are paths and lists — and this one has different needs, so it gets its own reader
+ * rather than a widened one. Measured shape of the shipped file (86 lines, 9,194 bytes):
+ * 40 whole-line comments, 1 blank line, 1 `key: <plain scalar>` (`name: default`), and 44
+ * `key: "<double-quoted scalar>"` on ONE line each. No block scalars, no wraps, no nesting,
+ * no sequences, no anchors, no tags, no multi-document stream. Every value is a string; the
+ * only escapes present are `\n` (3) and `\"` (16).
+ *
+ * So this reads exactly that: comments, blanks, an optional leading `---`, and root-level
+ * entries whose value is either a double-quoted scalar closing on its own line or a plain
+ * scalar. The double-quoted escape table is YAML 1.1's in full, so a contract that gains a
+ * `\t` or a `é` tomorrow is already read; the plain scalar goes through
+ * `resolveImplicitTag`, the SAME resolver the fact-file emitter uses, so the two halves of
+ * this package cannot disagree about what `null` or `2026-08-23` means.
+ *
+ * SAFE, in the sense the word carries for YAML, is structural: no tag handling, no anchor or
+ * alias expansion, no merge key, no constructor dispatch. `yaml.safe_load` earns the name by
+ * refusing `!!python/object`; this refuses every `!`, `&` and `*` by not implementing them.
+ * One left-to-right pass, no backtracking, so a hostile file costs time linear in its length.
+ *
+ * ANYTHING OUTSIDE THAT LANGUAGE RAISES. The failure mode of guessing is a contract key
+ * whose value is subtly wrong, which reaches the model as a malformed sentence nobody
+ * notices; the failure mode of raising is `AssetNotFound`-shaped and loud. The gate for this
+ * claim is not the reader's own opinion: `tools/conformance/suites/validate.mjs` compares
+ * this parse of the SHIPPED asset against `yaml.safe_load`'s, key for key and byte for byte,
+ * and `test/contract.test.mjs` refuses the constructs above by name.
+ */
+export declare function parseContractDocument(text: string): Map<string, string>;
+/**
+ * `load_contract`. Reads the asset EVERY call, as Python does — the prep probe measured that
+ * `contracts/default.yaml` is touched only on a validation failure, so a cache would buy
+ * nothing and would make a hot-edited contract silently stale.
+ */
+export declare function loadContract(name?: string): Record<string, string>;
+export declare function schemaRetryFeedback(error: string): string;
+export declare function parseErrorMessage(detail: unknown): string;
+export declare function validationErrorMessage(where: string, detail: string): string;
+/**
+ * The primitive shape of one omission, as `docread.Omission.asDict()` hands it over. The
+ * reference reads `dict` keys with `[]` and `.get`; the optional ones are optional here too.
+ */
+export interface OmissionRecord {
+    readonly subject: string;
+    readonly count: number;
+    readonly size?: number;
+    readonly where?: readonly string[];
+    readonly what?: string;
+    readonly facts?: Readonly<Record<string, number>>;
+}
+/** One part of a manifest, as `evalrun._document_tools` and `bantamkit_read` build it. */
+export interface ManifestPart {
+    readonly document: string;
+    readonly kind: string;
+    readonly index: number;
+    readonly part: string;
+    readonly row_count: number;
+    readonly rows: readonly string[];
+    readonly omissions?: readonly OmissionRecord[];
+}
+/** A document's own omissions, which the manifest prints before that document's parts. */
+export interface ManifestDocument {
+    readonly document: string;
+    readonly omissions?: readonly OmissionRecord[];
+}
+/**
+ * `document_manifest`: the answer to "what exists", as one observation — per part, the row
+ * count, the numbering, the header, the first and the last data row, and every omission the
+ * rendering made. A document's own omissions print before its first part; one whose
+ * omissions matched no part is still said, after every part, because `pop` makes that
+ * reachable on the reference and dropping the line would put the silence back one level up.
+ */
+export declare function documentManifest(parts: readonly ManifestPart[], documents?: readonly ManifestDocument[] | null): string;
+/**
+ * `document_page`: one page, with its own coordinates and its continuation, both in band.
+ *
+ * `nextKey` names the contract sentence for the continuation, because that sentence names
+ * the TOOL to call again: `document_read` for the eval pair, `bantamkit_read` for the MCP
+ * reader. Every other line of a page is the same bytes on both.
+ */
+export declare function documentPage(document: string, part: string, offset: number, rows: readonly string[], rowCount: number, nextOffset: number | null, truncatedBytes?: number, nextKey?: string): string;
+export declare function documentOffsetPastEnd(part: string, offset: number, rowCount: number): string;
+/**
+ * `bantamkit_read_unknown_part`: a part the file does not have — a fact about the FILE
+ * ("in {path}; it has: ...") and not about "this task", which is why it is not
+ * `document_unknown`'s sentence.
+ */
+export declare function bantamkitReadUnknownPart(part: string, path: string, available: readonly string[]): string;
+/**
+ * `document_error`: a reader failure, kept in the reader's own words, with the `error:`
+ * prefix every other tool observation in the harness uses. `str(detail)` on the reference;
+ * an `Error`'s `message` is that string here (`DocumentReadError` and `PyOSError` both put
+ * the whole sentence there).
+ */
+export declare function documentError(detail: unknown): string;
+/**
+ * `tool_failed`: a handler raised, and `detail` is the handler's OWN words.
+ *
+ * The argument-shaped failures are settled before the handler is entered (`validateArguments`
+ * here, pydantic on the reference), so what reaches this is an exception from INSIDE one —
+ * `skill_audit`'s three refusals are the only ones today. `str(detail)` on the reference; an
+ * `Error`'s `message` is that string here, which is what `SkillAuditError` carries.
+ */
+export declare function toolFailed(tool: string, detail: unknown): string;
+/**
+ * `extract_json`: a fenced block if there is one, otherwise the first `{`/`[` onward.
+ *
+ * Both arms are here because both reach the model. The fence is `re.search` with `DOTALL`
+ * and a non-greedy body, so it takes the FIRST fence and prose on either side is discarded;
+ * with no fence, `find` takes the earliest brace or bracket — including one inside a string
+ * of prose, which is faithful and occasionally wrong in exactly Python's way. `raw_decode`
+ * then stops at the end of that one value, which is why `{"a": 1} — anything else?` parses.
+ */
+export declare function extractJson(text: string): PyValue;
+/**
+ * `schema_error`: a pointed validation error for `output`, or `null` if it satisfies
+ * `schema`.
+ *
+ * `where` is `"/".join(e.absolute_path)` with `"root"` standing in for the empty path, and
+ * `detail` is `ValidationError.message` VERBATIM. The error is the one `best_match` chose,
+ * not the first one found — see `pyjsonschema.bestMatch`.
+ *
+ * The schema may be a `PyValue` (exact — use `pyjson.parseJson` when the raw text is still
+ * in hand) or a plain JS value, which is lifted with `pyjson.fromJs` and its one documented
+ * loss.
+ */
+export declare function schemaError(output: string, schema: PyValue | unknown): string | null;