bantamkit-mcp 0.26.0

package/assets/tools/skill_audit.json

@@ -0,0 +1,70 @@
+{
+  "name": "skill_audit",
+  "description": "Price the skill catalogue every session pays for, and name the collisions in it. A skill's `description:` frontmatter is loaded into the agent's context in EVERY session; its body is read only when the skill is invoked, so the descriptions are the standing bill. Walks `root` for `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` and answers one JSON document: `roots` (what was scanned), `skills` (how many were counted), `catalogue_bytes` (UTF-8 bytes of their `description:` values), `findings` and `omissions`. Counted skills plus omissions account for every SKILL.md found — an omission is `{subject, count, size, what}` with subject one of `plugin-not-enabled`, `duplicate-skill`, `stale-version`, `unreadable-file`, `unparsed-frontmatter`, and `what` naming the paths. Pass `enabled` with the plugin ids the host has switched on (`<plugin>@<marketplace>`, as settings.json spells them): the plugin cache also holds disabled plugins and stale version directories, and counting those inflated a real audit to 41 skills / 19,065 B against a true 34 / 14,515. Identity comes from the path: `<marketplace>/<plugin>/<version>/skills/<name>/SKILL.md` relative to `root`; any other shape is a skill outside a plugin, identified by its directory name alone and never excluded by `enabled`. Exactly ONE version directory is resolved per (marketplace, plugin) BEFORE anything is counted, and its skills are that plugin's skills: a name absent from the resolved version is absent, never merged in from another version directory. The winner is the version directory name that sorts LAST in byte order — a byte order and deliberately not a semver comparison, so two runtimes cannot disagree about which directory was read, and so that names which are not versions at all still have a total order (a real cache spells nine of one plugin's directories as content hashes plus the literal `unknown`). What byte order gets wrong is stated rather than hidden: `10.0.0` loses to `9.0.0`, and among non-version names the winner is deterministic but arbitrary; both losers are named in an omission record. Pass `versions` with the version directory the host actually serves, per `<plugin>@<marketplace>` — the `installPath` recorded in the same `installed_plugins.json` the caller reads `enabled` out of — and that plugin is resolved to the named directory whatever byte order would have said; a plugin absent from `versions` falls back to byte order. It is host truth the caller supplies, exactly as `enabled` is, and it is not refused when it names a plugin or a directory this `root` does not hold: a plugin with no version directory here is not resolved at all, and a directory that is not here means every directory that IS here loses and is named in a `stale-version` record. Measured 2026-09-05 on a real cache, byte order picks `unknown` for a plugin whose host serves `1dd995193ba2`, so the installed copy is discarded as a duplicate. The candidates are the version DIRECTORIES on disk — every path spelled `<marketplace>/<plugin>/<version>/skills` — and not the skills that survived reading: a version directory holding no `SKILL.md`, or only files that will not decode or will not parse, still exists and the host still serves it, so an older directory must not win by default. Every SKILL.md under a version directory that did not win is omitted, under one of two subjects: `duplicate-skill` when the resolved version has a skill of the same name standing in for it, `stale-version` when it does not — a skill the resolved version DROPPED, which is on disk, in nobody's bill, and would otherwise be resurrected by the audit. Deduping by the (marketplace, plugin, name) triple instead merges versions rather than choosing between them, and measured 2026-09-05 over a real cache holding a plugin's `0.4.0` (14 skills) and `0.5.0` (5, nine having moved to another plugin) it answered 31 skills / 9,280 bytes where the host serves 22 / 3,396. Inside the resolved version `duplicate-skill` still covers two files claiming the same (marketplace, plugin, name), which is reachable only for skills outside a plugin; the last in scan order wins. Every omission carries the bytes it would have added. A skill is identified as `<plugin>:<name>`, the spelling the host uses and the key `usage` is looked up by, or as `<name>` when it has no plugin. A `description:` folded over several lines is joined with single spaces before it is counted or scanned, and a value written as a whole-value quoted YAML scalar is UNWRAPPED after that fold and before either — the host's parser strips those quotes before a session sees the description, so they are not `catalogue_bytes`, and only quotes INSIDE the value delimit a trigger phrase. The unwrap applies to every frontmatter key, not just `description:`, so `name: \"s\"` is the name `s` and `router: \"true\"` is a router. A value is a whole-value scalar only when it begins with `\"` or `'` AND that opening quote's own closing quote is the value's LAST character, judged by YAML's two escape rules and no others: inside a `\"` scalar a backslash escapes the character after it, so `\\\"` does not close it and the sequences `\\\"` and `\\\\` resolve to `\"` and `\\` while every other `\\x` is left exactly as written; inside a `'` scalar a doubled `''` is one literal apostrophe, so it does not close it and resolves to `'`. Every other value is left as written and scanned literally: `\"a\" and \"b\"` begins and ends with `\"` and is NOT one scalar, because its opening quote closes at index 2, and stripping it would weld the value into one junk phrase and destroy both real ones. A value that OPENS with a quote and never closes one — including one whose last quote is escaped — is a LITERAL: it is not unwrapped, its quote character is counted, its unpaired quote opens no phrase, and it is not a `frontmatter-malformed` finding, which names failures of the BLOCK and not of one value. Measured 2026-09-05 over a real plugin cache: 17 of 31 enabled skills write `description: \"...\"`, so a reader that takes those quotes literally over-prices the majority of a catalogue and buries any phrase quoted inside them. Five findings, each `{kind, severity, skills, detail}`, severity fixed per kind: `shared-trigger-phrase` (high) — two or more skills quote the same literal phrase, so which one fires is a coin flip; `catalogue-over-budget` (high) — `catalogue_bytes` exceeds `budget`; `never-invoked` (low) — a counted skill has zero calls in `usage`; `frontmatter-malformed` (medium) — no frontmatter block, an unterminated one, or no `description:` key, where a block that cannot be parsed at all is also omitted as `unparsed-frontmatter` and adds nothing to `skills` while a parsed block with no description is a skill costing zero bytes; `name-mismatch` (medium) — the frontmatter `name:` is not the skill's directory name. Collisions are EXACT matches on literal quoted phrases and never a similarity score: Jaccard over description tokens was measured across 820 real pairs and refuted, topping out at 0.239 and ranking the two real collisions 118th and 791st of 820. Phrases are the text of the UNWRAPPED value between `\"` pairs, or between `'` pairs where the quote is not flanked by letters — `'don't'` is a contraction, not a phrase — and a phrase with no letter or digit in it is ignored. A router, a skill whose frontmatter carries `router: true`, quotes its siblings' phrases by design and is left out of the phrase index entirely. Four argument failures are refused with their own sentences and never as a partial answer: an unknown `check`, a negative `budget`, a `root` that is missing or is a file, and an EMPTY `root` — which passes JSON-schema `string` and would otherwise resolve to the server's own working directory. Nothing about the CONTENT of the tree refuses. Deterministic: the tool reads nothing but `root`. The three facts a directory of files cannot answer arrive from the caller — call counts in `usage` (`node tools/ledger/tool-usage.mjs --group skill --json`), switched-on plugins in `enabled`, served version directories in `versions` — never by reading the host's transcripts, settings or plugin registry.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to scan for SKILL.md files, absolute or relative to the server's working directory. It must name a directory: the empty string is refused rather than resolved, because resolving it would audit whatever directory the server happens to be standing in"
+      },
+      "enabled": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Plugin ids that are switched on, `<plugin>@<marketplace>`; when given only skills under those plugins are counted, when omitted every skill under `root` counts"
+      },
+      "usage": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "description": "Skill id (`<plugin>:<name>`) to call count, the caller's own measurement; a counted skill absent from a supplied map is treated as zero"
+      },
+      "check": {
+        "type": "string",
+        "enum": [
+          "all",
+          "phrase",
+          "budget",
+          "frontmatter"
+        ],
+        "description": "Which family of findings to report; default `all`. `skills`, `catalogue_bytes` and `omissions` are reported whatever this says"
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991,
+        "description": "Catalogue byte budget; `catalogue-over-budget` is only reported when this is given"
+      },
+      "versions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        },
+        "description": "Plugin id (`<plugin>@<marketplace>`) to the version directory name the host actually serves; when a plugin is named here that directory is resolved whatever byte order would have said, and a plugin absent from it falls back to byte order"
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "skill_auditOutput"
+  }
+}

package/assets/tools/validate_json.json

@@ -0,0 +1,31 @@
+{
+  "name": "validate_json",
+  "description": "Validate candidate output text against a JSON Schema. Returns {valid, feedback}; when invalid, feed the feedback back to the model and retry.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "properties": {
+      "output": {
+        "title": "Output",
+        "type": "string"
+      },
+      "schema": {
+        "additionalProperties": true,
+        "title": "Schema",
+        "type": "object"
+      }
+    },
+    "required": [
+      "output",
+      "schema"
+    ],
+    "type": "object",
+    "title": "validate_jsonArguments"
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": true,
+    "title": "validate_jsonDictOutput"
+  }
+}

package/dist/assets.d.ts

@@ -0,0 +1,48 @@
+import { BantamError } from './errors.js';
+export declare class AssetNotFound extends BantamError {
+}
+/** The agent-facing view of a tool asset — Python's `bantamkit.client.Tool`. */
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+/**
+ * The three arms, in Python's order.
+ *
+ *   1. `$BANTAMKIT_ASSETS`, verbatim, no existence check — the override wins even when
+ *      it is wrong, so a wrong override fails naming itself rather than falling through
+ *      to a pack the operator did not ask for.
+ *   2. The packaged pack, resolved off THIS module. When installed from the tarball
+ *      this module is `<pkg>/dist/assets.js`, so `../assets/` is `<pkg>/assets/`.
+ *      **This is the arm npx uses.**
+ *   3. The repository pack, for a dev checkout, where nothing has been vendored into
+ *      `runtime-ts/assets/`. This module is `<repo>/runtime-ts/dist/assets.js`, so the
+ *      repo root is two levels up — the count is proved by `test/assets.test.mjs`,
+ *      which builds the layout in a temp dir and imports the real build output out of
+ *      it. Python reaches the same place with `Path(__file__).resolve().parents[3]`
+ *      from `<repo>/runtime-py/src/bantamkit/assets.py`, and resolves symlinks on this
+ *      arm only; that asymmetry is mirrored here.
+ */
+export declare function assetsRoot(): string;
+/**
+ * Return one tool asset VERBATIM — every key, including the ones no surface uses.
+ *
+ * `loadTool` below narrows the same file to the three fields a model is shown. This
+ * returns the whole manifest entry, because a server has to read `surfaces` (may I
+ * register this at all?) and `output_schema` (what do I advertise as the return shape?)
+ * and neither belongs on the agent-facing `Tool`.
+ */
+export declare function loadToolAsset(name: string): Record<string, unknown>;
+/**
+ * The agent-facing view of a tool asset: name, description, input schema.
+ *
+ * The three keys are named EXPLICITLY rather than splatted. `assets/tools/` is shared by
+ * two tool surfaces and carries fields that only the MCP one consumes; a loader that
+ * passed the dict through would add them to every tool definition an eval-run model is
+ * shown, changing the agent surface every time the manifest grows.
+ */
+export declare function loadTool(name: string): Tool;
+/** Return a JSON Schema asset (parsed) — e.g. the shift-work checkpoint contract. */
+export declare function loadSchema(name: string): Record<string, unknown>;
+export declare function loadSkill(name: string): string;

package/dist/assets.js

@@ -0,0 +1,109 @@
+/**
+ * Locate and load the language-agnostic asset pack.
+ *
+ * A port of `runtime-py/src/bantamkit/assets.py`, arm for arm. The Python module is the
+ * reference; where this file deviates the deviation is a comment, not an accident.
+ */
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BantamError } from './errors.js';
+import { pyReadText } from './memory/pyfs.js';
+export class AssetNotFound extends BantamError {
+}
+/**
+ * `Path.read_text(encoding="utf-8")`, which is `memory/pyfs.pyReadText` and NOT a second
+ * spelling of it.
+ *
+ * It WAS a second spelling — `readFileSync(p, 'utf8').replace(/\r\n?/g, '\n')` — and N8
+ * measured the two decoders disagreeing: `pyReadText` dropped a leading UTF-8 BOM (its
+ * `TextDecoder` defaults `ignoreBOM` to false) while this one kept it, so one package held
+ * two UTF-8 decodes with opposite answers on the same three bytes. This one happened to be
+ * the one that matched CPython; the fix is not to keep the right copy but to keep ONE, so
+ * the next divergence has nowhere to hide. What this arm gains in the trade: `pyReadText`
+ * decodes STRICTLY, so a tool asset that is not valid UTF-8 now raises CPython's
+ * `UnicodeDecodeError` here instead of reaching a model with U+FFFD substituted into the
+ * description it reads. Universal-newline translation is unchanged and lives there too.
+ */
+function readTextUniversal(path) {
+    return pyReadText(path);
+}
+/**
+ * The three arms, in Python's order.
+ *
+ *   1. `$BANTAMKIT_ASSETS`, verbatim, no existence check — the override wins even when
+ *      it is wrong, so a wrong override fails naming itself rather than falling through
+ *      to a pack the operator did not ask for.
+ *   2. The packaged pack, resolved off THIS module. When installed from the tarball
+ *      this module is `<pkg>/dist/assets.js`, so `../assets/` is `<pkg>/assets/`.
+ *      **This is the arm npx uses.**
+ *   3. The repository pack, for a dev checkout, where nothing has been vendored into
+ *      `runtime-ts/assets/`. This module is `<repo>/runtime-ts/dist/assets.js`, so the
+ *      repo root is two levels up — the count is proved by `test/assets.test.mjs`,
+ *      which builds the layout in a temp dir and imports the real build output out of
+ *      it. Python reaches the same place with `Path(__file__).resolve().parents[3]`
+ *      from `<repo>/runtime-py/src/bantamkit/assets.py`, and resolves symlinks on this
+ *      arm only; that asymmetry is mirrored here.
+ */
+export function assetsRoot() {
+    const env = process.env.BANTAMKIT_ASSETS;
+    if (env) {
+        return env;
+    }
+    const hereDir = dirname(fileURLToPath(import.meta.url));
+    const packaged = join(hereDir, '..', 'assets');
+    if (existsSync(packaged)) {
+        return packaged;
+    }
+    const repo = join(realpathSync(hereDir), '..', '..', 'assets');
+    if (existsSync(repo)) {
+        return repo;
+    }
+    throw new AssetNotFound('no assets directory found; set BANTAMKIT_ASSETS');
+}
+/**
+ * Return one tool asset VERBATIM — every key, including the ones no surface uses.
+ *
+ * `loadTool` below narrows the same file to the three fields a model is shown. This
+ * returns the whole manifest entry, because a server has to read `surfaces` (may I
+ * register this at all?) and `output_schema` (what do I advertise as the return shape?)
+ * and neither belongs on the agent-facing `Tool`.
+ */
+export function loadToolAsset(name) {
+    const path = join(assetsRoot(), 'tools', `${name}.json`);
+    if (!existsSync(path)) {
+        throw new AssetNotFound(`tool asset not found: ${path}`);
+    }
+    return JSON.parse(readTextUniversal(path));
+}
+/**
+ * The agent-facing view of a tool asset: name, description, input schema.
+ *
+ * The three keys are named EXPLICITLY rather than splatted. `assets/tools/` is shared by
+ * two tool surfaces and carries fields that only the MCP one consumes; a loader that
+ * passed the dict through would add them to every tool definition an eval-run model is
+ * shown, changing the agent surface every time the manifest grows.
+ */
+export function loadTool(name) {
+    const data = loadToolAsset(name);
+    return {
+        name: data['name'],
+        description: data['description'],
+        parameters: data['parameters'],
+    };
+}
+/** Return a JSON Schema asset (parsed) — e.g. the shift-work checkpoint contract. */
+export function loadSchema(name) {
+    const path = join(assetsRoot(), 'schemas', `${name}.json`);
+    if (!existsSync(path)) {
+        throw new AssetNotFound(`schema asset not found: ${path}`);
+    }
+    return JSON.parse(readTextUniversal(path));
+}
+export function loadSkill(name) {
+    const path = join(assetsRoot(), 'skills', `${name}.md`);
+    if (!existsSync(path)) {
+        throw new AssetNotFound(`skill asset not found: ${path}`);
+    }
+    return readTextUniversal(path);
+}

package/dist/charsets.d.ts

@@ -0,0 +1,17 @@
+/** Every module `encodings` ships, as `encodings.search_function` would import it. */
+export declare const CODEC_MODULES: ReadonlySet<string>;
+/** `encodings.aliases.aliases`: normalized name -> module. */
+export declare const CODEC_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Module -> the 128 characters bytes 0x80..0xFF decode to (`errors="replace"`), and the
+ * 128 for 0x00..0x7F only where they are not ASCII (the EBCDIC pages).
+ */
+export declare const SINGLE_BYTE_TABLES: Readonly<Record<string, {
+    high: string;
+    low?: string;
+}>>;
+/**
+ * The CJK modules, each -> what bytes 0x80..0xFF decode to ALONE (U+FFFD: not a
+ * character by itself, so a lead byte or a refusal).
+ */
+export declare const MULTI_BYTE_SINGLES: Readonly<Record<string, string>>;