@mcp-index/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,133 @@
+Required Notice: Copyright Bhartis LLC (https://mcpindex.ai)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Bhartis LLC (https://mcpindex.ai)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,49 @@
+# @mcp-index/sdk
+
+Pre-flight MCP tool-contract drift interceptor. One line — `wrap()` an MCP client
+session and the gate **HOLDs a tool call before your agent acts** the moment the
+tool's contract silently changes from what you pinned. In-path, on your host; no
+credentials, no egress.
+
+## Install
+
+```sh
+npm i @mcp-index/sdk
+```
+
+Peer dependency: `@modelcontextprotocol/sdk` >= 1.0.0.
+
+## Use
+
+```ts
+import { wrap } from '@mcp-index/sdk';
+
+// wrap an already-connected MCP client session
+const guarded = wrap(session);   // pins each tool's contract on first use (TOFU)
+
+// use `guarded` exactly like `session`; a drifted contract is HELD before the call
+// fires. A PreflightHold surfaces (Guard/Strict) so you can route the agent to
+// Review / Re-pin / Validate.
+```
+
+## What it does
+
+- Pins each MCP tool's contract trust-on-first-use (TOFU), persisted across restarts.
+- Runs a **deterministic** contract-diff (the ChangeKind taxonomy: added-required-param,
+  constraint-narrowed, annotation-flip-to-destructive, output-schema-changed,
+  type/enum/removed, …) plus an injection/exfil marker scan over input and output schema.
+- **HOLDs** the call with the ⬡ banner when the contract drifted; **PROCEEDs** silently
+  on a benign change (no false alarm).
+- Postures: `Monitor` (notify + proceed) / `Guard` (default; hold dangerous) /
+  `Strict` (hold any drift).
+
+## What it is NOT
+
+The verdict is a **contract-diff, not a safety oracle** — it tells you the contract
+*changed* versus your pin, not that the new contract is safe. It does not "block attacks"
+or "guarantee safe." You decide what a HOLD means for your agent.
+
+## License
+
+PolyForm Noncommercial 1.0.0 — © Bhartis LLC. Free for noncommercial use; commercial use
+requires a separate license. See [`LICENSE`](./LICENSE) and https://mcpindex.ai.

package/dist/src/canonical.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The canonical serialization + per-tool hash — a BYTE-FOR-BYTE port of the
+ * Python `trust.contract.canonical_bytes` / `_canonicalize` and the connector's
+ * `_tool_hash`. A TS-pinned hash MUST equal a Python-pinned hash for the SAME
+ * contract, or the cross-language pin chain breaks.
+ *
+ * CONFORMANCE RULES (from contract.py, load-bearing):
+ *  - Objects: keys NFC-normalized, sorted by their string form, separators
+ *    `(",",":")`, `ensure_ascii=True` (every non-ASCII char escaped as \uXXXX).
+ *  - Strings/keys: Unicode NFC.
+ *  - Floats: Python `%.17e` form (`1.50000000000000000e-01`) — exponent sign
+ *    ALWAYS present, exponent ALWAYS >= 2 digits zero-padded. JS
+ *    `toExponential(17)` does NOT zero-pad the exponent, so we re-pad.
+ *  - Integers stay integers; -0.0 collapses to 0.0; non-finite floats raise.
+ *  - Depth-capped at 64.
+ *
+ * NOTE the hash preimage key is `input_schema` (snake_case) — the Python
+ * `_hash_tool` maps the public `inputSchema` field onto `input_schema` before
+ * hashing. We replicate that exactly.
+ */
+/** A JSON-ish value the canonicalizer accepts. */
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+/** THE canonical serialization — every hash site MUST use this (port of
+ * `contract.canonical_bytes`). */
+export declare function canonicalBytes(obj: unknown): Buffer;
+/** The connector's per-tool hash, byte-identical to Python `_tool_hash`. The
+ * preimage is `{name, description, input_schema}` (snake_case schema key). */
+export declare function toolHash(name: string, description: string, inputSchema: Record<string, unknown>): string;
+/** Hash a PUBLIC tool-definition dict (port of cse `_hash_tool`): coerces
+ * name/description to strings, an absent/non-object inputSchema to `{}`.
+ *
+ * LATENT divergence (audit L2): on a `null` name/description we coerce to `""`,
+ * whereas Python `_hash_tool` does `str(None)` -> `"None"`. This is UNREACHABLE
+ * via the wrapper: `wrap.toolToDict` already normalizes a null/absent description
+ * to `""` before this is ever called (and a tool with a null NAME is dropped), so
+ * both languages hash `""`. The divergence only surfaces on a RAW-dict direct call
+ * to `hashTool({description: null})` that bypasses the wrapper's normalization —
+ * we keep the `""` coercion (it is the wrapper-faithful value) and note the gap. */
+export declare function hashTool(defn: Record<string, unknown>): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/src/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,kDAAkD;AAClD,MAAM,MAAM,IAAI,GACZ,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,IAAI,EAAE,GACN;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAoK1B;kCACkC;AAClC,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;8EAC8E;AAC9E,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAOR;AAED;;;;;;;;;oFASoF;AACpF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAY9D"}

package/dist/src/canonical.js

@@ -0,0 +1,231 @@
+/**
+ * The canonical serialization + per-tool hash — a BYTE-FOR-BYTE port of the
+ * Python `trust.contract.canonical_bytes` / `_canonicalize` and the connector's
+ * `_tool_hash`. A TS-pinned hash MUST equal a Python-pinned hash for the SAME
+ * contract, or the cross-language pin chain breaks.
+ *
+ * CONFORMANCE RULES (from contract.py, load-bearing):
+ *  - Objects: keys NFC-normalized, sorted by their string form, separators
+ *    `(",",":")`, `ensure_ascii=True` (every non-ASCII char escaped as \uXXXX).
+ *  - Strings/keys: Unicode NFC.
+ *  - Floats: Python `%.17e` form (`1.50000000000000000e-01`) — exponent sign
+ *    ALWAYS present, exponent ALWAYS >= 2 digits zero-padded. JS
+ *    `toExponential(17)` does NOT zero-pad the exponent, so we re-pad.
+ *  - Integers stay integers; -0.0 collapses to 0.0; non-finite floats raise.
+ *  - Depth-capped at 64.
+ *
+ * NOTE the hash preimage key is `input_schema` (snake_case) — the Python
+ * `_hash_tool` maps the public `inputSchema` field onto `input_schema` before
+ * hashing. We replicate that exactly.
+ */
+import { createHash } from "node:crypto";
+const FLOAT_DIGITS = 17;
+const MAX_CANON_DEPTH = 64;
+function nfc(s) {
+    return s.normalize("NFC");
+}
+/**
+ * KNOWN CROSS-LANGUAGE GAP (audit H2) — integral-valued floats.
+ *
+ * Python's canonicalizer keys off the RUNTIME TYPE: a Python `int` stays an int,
+ * a Python `float` becomes the `%.17e` string. Python `json.loads` PRESERVES that
+ * distinction off the wire — `0.0` parses to `float`, `0` to `int` — so Python
+ * `_hash_tool` gives DIFFERENT hashes for `minimum:0.0` vs `minimum:0`.
+ *
+ * JS `JSON.parse` does NOT: it collapses `0.0` -> the Number `0`, and the decimal
+ * is GONE before `wrap()` (or this canonicalizer) ever sees the Tool object — the
+ * SDK parsed it. A bare JS `number` carries no int/float tag, and the wrapper does
+ * NOT control the SDK's parse step, so the distinction is UNRECOVERABLE at this layer.
+ *
+ * We therefore emit INTEGRAL-VALUED numbers (`Number.isInteger(n)` true — includes
+ * `0.0`, `1.0`, `-0.0`, `1e300`, `1.5e10`) as integers, matching a Python `int`, and
+ * route only genuinely NON-INTEGRAL values through the `%.17e` float path. Consequence:
+ *   - A schema bound/default authored as an integral-valued FLOAT (e.g. `minimum:0.0`)
+ *     hashes in TS as if it were the int `0`, DIVERGING from Python's float hash.
+ *   - This degrades to a tier-1 cross-language definition_hash MISS, which is
+ *     FAIL-CLOSED-SAFE: the tier-0-INCONCLUSIVE -> tier-1-lookup-by-hash flow MISSES,
+ *     stays INCONCLUSIVE, and HOLDS on the wire. It NEVER produces a wrong PROCEED —
+ *     it only loses the cross-language cache/flywheel benefit on that one contract.
+ *   - The TS client's OWN in-session drift detection is UNAFFECTED: pin and live are
+ *     BOTH computed with this same TS `hashTool`, so an integral-valued float pins and
+ *     re-derives identically within TS. The gap is purely cross-LANGUAGE.
+ *
+ * Genuinely non-integral floats (`0.5`, `0.1`, `3.14`, `1.5`, ...) ARE recoverable
+ * (JS keeps them as non-integral numbers) and hash BYTE-IDENTICAL to Python via
+ * `pythonFloatRepr` below — pinned in test/parity.test.ts against live-Python refs.
+ *
+ * True cross-language parity on integral-valued floats would need a VALUE-BASED (not
+ * type-based) canonicalization decision ON THE PYTHON SIDE — a corpus-migration /
+ * hash-format one-way door, out of this slice's scope. Tracked in tasks/todo-s6-ts.md.
+ */
+function isIntegral(n) {
+    return Number.isInteger(n);
+}
+function pythonFloatRepr(n) {
+    if (Number.isNaN(n) || !Number.isFinite(n)) {
+        throw new Error("non-finite float is not canonicalizable");
+    }
+    let v = n;
+    if (v === 0)
+        v = 0; // collapse -0.0 -> 0.0
+    // toExponential(17): "d.<17 digits>e±X" but the exponent is NOT zero-padded.
+    const raw = v.toExponential(FLOAT_DIGITS);
+    const m = /^(-?\d\.\d+)e([+-])(\d+)$/.exec(raw);
+    if (m === null) {
+        throw new Error(`unexpected exponential form: ${raw}`);
+    }
+    const mantissa = m[1];
+    const sign = m[2];
+    let exp = m[3];
+    if (exp.length < 2)
+        exp = exp.padStart(2, "0");
+    return `${mantissa}e${sign}${exp}`;
+}
+function canonicalize(o, depth) {
+    if (depth > MAX_CANON_DEPTH) {
+        throw new Error("canonical depth exceeded");
+    }
+    if (o === null || o === undefined) {
+        return null;
+    }
+    if (typeof o === "boolean") {
+        return o;
+    }
+    if (typeof o === "number") {
+        if (isIntegral(o)) {
+            if (!Number.isFinite(o)) {
+                throw new Error("non-finite number is not canonicalizable");
+            }
+            return o; // emitted as an integer, matching a Python int
+        }
+        return pythonFloatRepr(o);
+    }
+    if (typeof o === "bigint") {
+        return Number(o);
+    }
+    if (typeof o === "string") {
+        return nfc(o);
+    }
+    if (Array.isArray(o)) {
+        return o.map((v) => canonicalize(v, depth + 1));
+    }
+    if (typeof o === "object") {
+        const src = o;
+        // NFC-normalize keys, then sort by the normalized string (Python sorts by
+        // `str(k)`; all our keys are already strings).
+        const entries = Object.keys(src).map((k) => [
+            nfc(k),
+            src[k],
+        ]);
+        entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        const out = {};
+        for (const [k, v] of entries) {
+            out[k] = canonicalize(v, depth + 1);
+        }
+        return out;
+    }
+    throw new Error(`non-canonicalizable type ${typeof o}`);
+}
+/** ensure_ascii=True JSON encoder with `(",",":")` separators over an already-
+ * canonicalized (key-sorted) value. We escape every non-ASCII char as \uXXXX to
+ * match Python's `json.dumps(ensure_ascii=True)`. */
+function encodeAscii(v) {
+    if (v === null)
+        return "null";
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "number") {
+        // Only integers reach here as numbers (floats are pre-stringified).
+        return String(v);
+    }
+    if (typeof v === "string")
+        return encodeAsciiString(v);
+    if (Array.isArray(v)) {
+        return "[" + v.map(encodeAscii).join(",") + "]";
+    }
+    // object: keys already canonical-sorted; preserve insertion order.
+    const parts = [];
+    for (const k of Object.keys(v)) {
+        parts.push(encodeAsciiString(k) + ":" + encodeAscii(v[k]));
+    }
+    return "{" + parts.join(",") + "}";
+}
+function encodeAsciiString(s) {
+    let out = '"';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === "\\")
+            out += "\\\\";
+        else if (ch === "\b")
+            out += "\\b";
+        else if (ch === "\f")
+            out += "\\f";
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (cp < 0x20)
+            out += "\\u" + cp.toString(16).padStart(4, "0");
+        else if (cp < 0x7f)
+            out += ch;
+        else {
+            // ensure_ascii: emit \uXXXX (surrogate pair for astral planes), matching
+            // Python's json encoder.
+            if (cp > 0xffff) {
+                const c = cp - 0x10000;
+                const hi = 0xd800 + (c >> 10);
+                const lo = 0xdc00 + (c & 0x3ff);
+                out +=
+                    "\\u" +
+                        hi.toString(16).padStart(4, "0") +
+                        "\\u" +
+                        lo.toString(16).padStart(4, "0");
+            }
+            else {
+                out += "\\u" + cp.toString(16).padStart(4, "0");
+            }
+        }
+    }
+    return out + '"';
+}
+/** THE canonical serialization — every hash site MUST use this (port of
+ * `contract.canonical_bytes`). */
+export function canonicalBytes(obj) {
+    return Buffer.from(encodeAscii(canonicalize(obj, 0)), "utf-8");
+}
+/** The connector's per-tool hash, byte-identical to Python `_tool_hash`. The
+ * preimage is `{name, description, input_schema}` (snake_case schema key). */
+export function toolHash(name, description, inputSchema) {
+    const bytes = canonicalBytes({
+        name,
+        description,
+        input_schema: inputSchema,
+    });
+    return "sha256:" + createHash("sha256").update(bytes).digest("hex");
+}
+/** Hash a PUBLIC tool-definition dict (port of cse `_hash_tool`): coerces
+ * name/description to strings, an absent/non-object inputSchema to `{}`.
+ *
+ * LATENT divergence (audit L2): on a `null` name/description we coerce to `""`,
+ * whereas Python `_hash_tool` does `str(None)` -> `"None"`. This is UNREACHABLE
+ * via the wrapper: `wrap.toolToDict` already normalizes a null/absent description
+ * to `""` before this is ever called (and a tool with a null NAME is dropped), so
+ * both languages hash `""`. The divergence only surfaces on a RAW-dict direct call
+ * to `hashTool({description: null})` that bypasses the wrapper's normalization —
+ * we keep the `""` coercion (it is the wrapper-faithful value) and note the gap. */
+export function hashTool(defn) {
+    const name = defn.name === undefined || defn.name === null ? "" : String(defn.name);
+    const desc = defn.description === undefined || defn.description === null
+        ? ""
+        : String(defn.description);
+    const schema = defn.inputSchema;
+    const inSch = schema !== null && typeof schema === "object" && !Array.isArray(schema)
+        ? schema
+        : {};
+    return toolHash(name, desc, inSch);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/src/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/canonical.ts"],"names":[],"mappings":"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"}

package/dist/src/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The LOCAL breadcrumb store for OUR-OWN code failures (graceful-fail capture) —
+ * a port of Python `tooling/cse/errors.py`. A bug in our gate/wrapper must NEVER
+ * crash the agent's call: the entry points catch it, fail closed to a generic
+ * internal-error HOLD, and record a SCRUBBED breadcrumb here. A record carries
+ * ONLY the exception CLASS NAME, a closed `Operation`, our-authored location, the
+ * client version, and a dedup fingerprint — NEVER user data.
+ */
+export declare const CLIENT_VERSION = "0.1.0";
+export declare const ERROR_RECORD_KEYS: ReadonlySet<string>;
+export declare enum Operation {
+    CALL_TOOL = "call_tool",
+    SEND_REQUEST = "send_request",
+    LIST_TOOLS = "list_tools",
+    GATE_DECISION = "gate_decision",
+    PROXY_GATE = "proxy_gate",
+    PROXY_RELAY = "proxy_relay"
+}
+export interface ErrorRecord {
+    readonly at: string;
+    readonly errorClass: string;
+    readonly operation: Operation;
+    readonly ourCodeLocation: string;
+    readonly clientVersion: string;
+    readonly fingerprint: string;
+}
+/** The SCRUBBED projection — only the `ERROR_RECORD_KEYS` allowlist. */
+export declare function asRecord(r: ErrorRecord): Record<string, string>;
+/** On-device append-only breadcrumb store; ZERO egress. */
+export declare class ErrorStore {
+    private readonly now;
+    private readonly records;
+    constructor(now?: () => string);
+    capture(excClassName: string, operation: Operation, ourCodeLocation: string, clientVersion?: string): ErrorRecord;
+    snapshot(): ErrorRecord[];
+    scrubbedRecords(): Array<Record<string, string>>;
+    fingerprintCounts(): Record<string, number>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAMhD,CAAC;AAEH,oBAAY,SAAS;IACnB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,aAAa,kBAAkB;IAC/B,UAAU,eAAe;IACzB,WAAW,gBAAgB;CAC5B;AAOD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ/D;AAID,2DAA2D;AAC3D,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEhB,GAAG,GAAE,MAAM,MAAkB;IAE1D,OAAO,CACL,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,EACpB,eAAe,EAAE,MAAM,EACvB,aAAa,GAAE,MAAuB,GACrC,WAAW;IAgBd,QAAQ,IAAI,WAAW,EAAE;IAIzB,eAAe,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAIhD,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAO5C"}

package/dist/src/errors.js

@@ -0,0 +1,79 @@
+/**
+ * The LOCAL breadcrumb store for OUR-OWN code failures (graceful-fail capture) —
+ * a port of Python `tooling/cse/errors.py`. A bug in our gate/wrapper must NEVER
+ * crash the agent's call: the entry points catch it, fail closed to a generic
+ * internal-error HOLD, and record a SCRUBBED breadcrumb here. A record carries
+ * ONLY the exception CLASS NAME, a closed `Operation`, our-authored location, the
+ * client version, and a dedup fingerprint — NEVER user data.
+ */
+import { createHash } from "node:crypto";
+import { utcNowIso } from "./preflight.js";
+export const CLIENT_VERSION = "0.1.0";
+export const ERROR_RECORD_KEYS = new Set([
+    "error_class",
+    "operation",
+    "our_code_location",
+    "client_version",
+    "fingerprint",
+]);
+export var Operation;
+(function (Operation) {
+    Operation["CALL_TOOL"] = "call_tool";
+    Operation["SEND_REQUEST"] = "send_request";
+    Operation["LIST_TOOLS"] = "list_tools";
+    Operation["GATE_DECISION"] = "gate_decision";
+    Operation["PROXY_GATE"] = "proxy_gate";
+    Operation["PROXY_RELAY"] = "proxy_relay";
+})(Operation || (Operation = {}));
+function fingerprint(errorClass, ourCodeLocation) {
+    const pre = `${errorClass}|${ourCodeLocation}`;
+    return createHash("sha256").update(pre, "utf-8").digest("hex").slice(0, 16);
+}
+/** The SCRUBBED projection — only the `ERROR_RECORD_KEYS` allowlist. */
+export function asRecord(r) {
+    return {
+        error_class: r.errorClass,
+        operation: r.operation,
+        our_code_location: r.ourCodeLocation,
+        client_version: r.clientVersion,
+        fingerprint: r.fingerprint,
+    };
+}
+const MAX_RECORDS = 10_000;
+/** On-device append-only breadcrumb store; ZERO egress. */
+export class ErrorStore {
+    now;
+    records = [];
+    constructor(now = utcNowIso) {
+        this.now = now;
+    }
+    capture(excClassName, operation, ourCodeLocation, clientVersion = CLIENT_VERSION) {
+        const rec = {
+            at: this.now(),
+            errorClass: excClassName,
+            operation,
+            ourCodeLocation,
+            clientVersion,
+            fingerprint: fingerprint(excClassName, ourCodeLocation),
+        };
+        this.records.push(rec);
+        if (this.records.length > MAX_RECORDS) {
+            this.records.splice(0, this.records.length - MAX_RECORDS);
+        }
+        return rec;
+    }
+    snapshot() {
+        return [...this.records];
+    }
+    scrubbedRecords() {
+        return this.records.map(asRecord);
+    }
+    fingerprintCounts() {
+        const counts = {};
+        for (const r of this.records) {
+            counts[r.fingerprint] = (counts[r.fingerprint] ?? 0) + 1;
+        }
+        return counts;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IAC5D,aAAa;IACb,WAAW;IACX,mBAAmB;IACnB,gBAAgB;IAChB,aAAa;CACd,CAAC,CAAC;AAEH,MAAM,CAAN,IAAY,SAOX;AAPD,WAAY,SAAS;IACnB,oCAAuB,CAAA;IACvB,0CAA6B,CAAA;IAC7B,sCAAyB,CAAA;IACzB,4CAA+B,CAAA;IAC/B,sCAAyB,CAAA;IACzB,wCAA2B,CAAA;AAC7B,CAAC,EAPW,SAAS,KAAT,SAAS,QAOpB;AAED,SAAS,WAAW,CAAC,UAAkB,EAAE,eAAuB;IAC9D,MAAM,GAAG,GAAG,GAAG,UAAU,IAAI,eAAe,EAAE,CAAC;IAC/C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAWD,wEAAwE;AACxE,MAAM,UAAU,QAAQ,CAAC,CAAc;IACrC,OAAO;QACL,WAAW,EAAE,CAAC,CAAC,UAAU;QACzB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,iBAAiB,EAAE,CAAC,CAAC,eAAe;QACpC,cAAc,EAAE,CAAC,CAAC,aAAa;QAC/B,WAAW,EAAE,CAAC,CAAC,WAAW;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,WAAW,GAAG,MAAM,CAAC;AAE3B,2DAA2D;AAC3D,MAAM,OAAO,UAAU;IAGQ;IAFZ,OAAO,GAAkB,EAAE,CAAC;IAE7C,YAA6B,MAAoB,SAAS;QAA7B,QAAG,GAAH,GAAG,CAA0B;IAAG,CAAC;IAE9D,OAAO,CACL,YAAoB,EACpB,SAAoB,EACpB,eAAuB,EACvB,gBAAwB,cAAc;QAEtC,MAAM,GAAG,GAAgB;YACvB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,UAAU,EAAE,YAAY;YACxB,SAAS;YACT,eAAe;YACf,aAAa;YACb,WAAW,EAAE,WAAW,CAAC,YAAY,EAAE,eAAe,CAAC;SACxD,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,iBAAiB;QACf,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7B,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}