@thotischner/observability-mcp 3.7.0 → 3.8.0

package/dist/inspect/profile.test.js

@@ -0,0 +1,96 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { deriveProfile, evaluateCall, ruleId } from "./profile.js";
+let seq = 0;
+function obs(over = {}) {
+    return {
+        ts: new Date(1_700_000_000_000 + seq * 1000).toISOString(),
+        seq: ++seq,
+        principal: "key:bot",
+        auth: "apikey",
+        tenant: "default",
+        tool: "query_logs",
+        argShape: {},
+        outcome: "ok",
+        decision: "allow",
+        redactions: 0,
+        ...over,
+    };
+}
+describe("deriveProfile", () => {
+    it("creates one suggested rule per (subject,tool) with unioned constraints", () => {
+        const rules = deriveProfile([
+            obs({ principal: "alice", tool: "query_logs", service: "pay", argShape: { window: "<=1h" } }),
+            obs({ principal: "alice", tool: "query_logs", service: "order", argShape: { window: "<=5m" } }),
+            obs({ principal: "bob", tool: "query_metrics", source: "prom" }),
+        ]);
+        assert.equal(rules.length, 2);
+        const a = rules.find((r) => r.id === ruleId("alice", "query_logs"));
+        assert.equal(a.status, "suggested");
+        assert.deepEqual(a.constraints.service, ["order", "pay"]); // sorted union
+        assert.deepEqual(a.constraints.argShape.window, ["<=1h", "<=5m"]);
+        assert.equal(a.provenance.learnedFrom, 2);
+        const b = rules.find((r) => r.id === ruleId("bob", "query_metrics"));
+        assert.deepEqual(b.constraints.source, ["prom"]);
+    });
+    it("is idempotent and never overwrites a human decision", () => {
+        let rules = deriveProfile([obs({ principal: "a", tool: "t", service: "s1" })]);
+        rules = rules.map((r) => ({ ...r, status: "accepted" }));
+        // New traffic with a NEW service value arrives + re-derive.
+        const after = deriveProfile([obs({ principal: "a", tool: "t", service: "s2" })], rules);
+        const r = after.find((x) => x.id === ruleId("a", "t"));
+        assert.equal(r.status, "accepted"); // untouched
+        assert.deepEqual(r.constraints.service, ["s1"]); // NOT widened to include s2
+    });
+    it("does not resurrect a rejected rule", () => {
+        const rejected = [{
+                id: ruleId("a", "t"), subject: "a", tool: "t", constraints: {}, status: "rejected",
+                provenance: { learnedFrom: 1, firstSeen: "x", lastSeen: "x" },
+            }];
+        const after = deriveProfile([obs({ principal: "a", tool: "t" })], rejected);
+        assert.equal(after.find((r) => r.id === ruleId("a", "t")).status, "rejected");
+    });
+    it("refreshes a still-suggested rule from new traffic", () => {
+        let rules = deriveProfile([obs({ principal: "a", tool: "t", service: "s1" })]);
+        rules = deriveProfile([obs({ principal: "a", tool: "t", service: "s2" })], rules);
+        assert.deepEqual(rules.find((r) => r.id === ruleId("a", "t")).constraints.service, ["s2"]);
+    });
+});
+describe("evaluateCall", () => {
+    const rules = [{
+            id: ruleId("alice", "query_logs"), subject: "alice", tool: "query_logs",
+            constraints: { service: ["pay", "order"], argShape: { window: ["<=1h", "<=5m"] } },
+            status: "accepted", provenance: { learnedFrom: 5, firstSeen: "x", lastSeen: "y" },
+        }];
+    const call = (over = {}) => ({ principal: "alice", tool: "query_logs", argShape: {}, ...over });
+    it("allows a call within an accepted rule", () => {
+        const r = evaluateCall(call({ service: "pay", argShape: { window: "<=1h" } }), rules);
+        assert.equal(r.verdict, "allow");
+    });
+    it("flags a new resource value outside the rule", () => {
+        const r = evaluateCall(call({ service: "secret-svc" }), rules);
+        assert.equal(r.verdict, "deviation");
+        assert.equal(r.kind, "new-resource");
+        assert.match(r.detail, /service=secret-svc/);
+    });
+    it("flags an arg bucket outside the learned range", () => {
+        const r = evaluateCall(call({ service: "pay", argShape: { window: ">1d" } }), rules);
+        assert.equal(r.kind, "arg-out-of-range");
+    });
+    it("flags a known principal reaching for a new tool", () => {
+        const r = evaluateCall(call({ tool: "enrich_ips" }), rules);
+        assert.equal(r.kind, "new-tool");
+    });
+    it("flags a wholly-new principal", () => {
+        const r = evaluateCall(call({ principal: "mallory" }), rules);
+        assert.equal(r.kind, "new-principal");
+    });
+    it("ignores suggested/rejected rules (only accepted gate)", () => {
+        const sugg = [{ ...rules[0], status: "suggested" }];
+        assert.equal(evaluateCall(call({ service: "pay", argShape: { window: "<=1h" } }), sugg).kind, "new-principal");
+    });
+    it("honours a wildcard subject rule", () => {
+        const wild = [{ ...rules[0], subject: "*" }];
+        assert.equal(evaluateCall(call({ principal: "anyone", service: "pay", argShape: { window: "<=5m" } }), wild).verdict, "allow");
+    });
+});

package/dist/inspect/recorder.d.ts

@@ -0,0 +1,42 @@
+import type { HookRegistration } from "../sdk/hooks.js";
+import type { Decision, InspectStore, Outcome } from "./store.js";
+import type { ModeController } from "./mode.js";
+/** An MCP tool result signals failure via `isError: true`. */
+export declare function isErrorResult(result: unknown): boolean;
+/** Coarse auth-kind inference from the principal (HookContext has no auth). */
+export declare function authKind(principal: string): string;
+/** A profile evaluation seam — given a derived call signature, returns the
+ *  verdict against the accepted profile. Absent in pure observe mode. */
+export interface ProfileEvaluator {
+    evaluate(call: {
+        principal: string;
+        tool: string;
+        source?: string;
+        service?: string;
+        namespace?: string;
+        argShape: Record<string, string>;
+    }): {
+        verdict: "allow" | "deviation";
+        kind?: string;
+    };
+}
+export interface RecorderOptions {
+    /** Metrics seam — called once per recorded observation. */
+    onEvent?: (e: {
+        tool: string;
+        outcome: Outcome;
+        decision: Decision;
+    }) => void;
+    /** Accepted-profile evaluator. Consulted only when mode.evaluating
+     *  (dry-run / enforce). When a call deviates it is recorded `would-block`
+     *  — this post-invoke recorder never blocks (enforce blocking is a separate
+     *  pre-invoke hook). */
+    evaluator?: ProfileEvaluator;
+}
+/**
+ * Build the recorder hook (tool_post_invoke, permissive). Records every call
+ * while the mode is recording. In dry-run / enforce it also evaluates the call
+ * against the accepted profile and records a `would-block` decision + deviation
+ * kind for calls outside the profile — but never blocks (it runs post-invoke).
+ */
+export declare function createInspectRecorder(store: InspectStore, mode: ModeController, opts?: RecorderOptions): HookRegistration;

package/dist/inspect/recorder.js

@@ -0,0 +1,72 @@
+// Inspect — the observe recorder.
+//
+// Registers as a `tool_post_invoke` hook in PERMISSIVE mode so it can never
+// block a tool call (and even if it threw, the hook registry swallows it for a
+// permissive hook). It redacts the args, derives a signature, and appends one
+// observation. Pure side-effect; returns allow:true always.
+import { redactValue } from "../policy/redact.js";
+import { deriveSignature } from "./signature.js";
+/** An MCP tool result signals failure via `isError: true`. */
+export function isErrorResult(result) {
+    return !!(result && typeof result === "object" && result.isError === true);
+}
+/** Coarse auth-kind inference from the principal (HookContext has no auth). */
+export function authKind(principal) {
+    return principal === "anonymous" ? "anonymous" : "apikey";
+}
+/**
+ * Build the recorder hook (tool_post_invoke, permissive). Records every call
+ * while the mode is recording. In dry-run / enforce it also evaluates the call
+ * against the accepted profile and records a `would-block` decision + deviation
+ * kind for calls outside the profile — but never blocks (it runs post-invoke).
+ */
+export function createInspectRecorder(store, mode, opts = {}) {
+    const handler = (ctx, payload) => {
+        try {
+            if (!mode.recording)
+                return { allow: true };
+            const red = redactValue(payload.args);
+            const sig = deriveSignature(ctx.target, red.value);
+            const outcome = isErrorResult(payload.result) ? "error" : "ok";
+            let decision = "allow";
+            let deviation;
+            if (mode.evaluating && opts.evaluator) {
+                const ev = opts.evaluator.evaluate({
+                    principal: ctx.principal, tool: ctx.target,
+                    source: sig.source, service: sig.service, namespace: sig.namespace,
+                    argShape: sig.argShape,
+                });
+                if (ev.verdict === "deviation") {
+                    decision = "would-block";
+                    deviation = ev.kind;
+                }
+            }
+            store.record({
+                principal: ctx.principal,
+                auth: authKind(ctx.principal),
+                tenant: ctx.tenant,
+                tool: ctx.target,
+                source: sig.source,
+                service: sig.service,
+                namespace: sig.namespace,
+                argShape: sig.argShape,
+                outcome,
+                decision,
+                deviation,
+                redactions: red.totalMatches,
+            });
+            opts.onEvent?.({ tool: ctx.target, outcome, decision });
+        }
+        catch {
+            // Observation must never affect the call path.
+        }
+        return { allow: true };
+    };
+    return {
+        pluginName: "inspect-recorder",
+        kind: "tool_post_invoke",
+        priority: 5,
+        mode: "permissive",
+        handler,
+    };
+}

package/dist/inspect/recorder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/inspect/recorder.test.js

@@ -0,0 +1,112 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createInspectRecorder, isErrorResult, authKind } from "./recorder.js";
+import { InspectStore } from "./store.js";
+import { ModeController } from "./mode.js";
+const ctx = (over = {}) => ({
+    principal: "key:bot",
+    tenant: "default",
+    kind: "tool_post_invoke",
+    target: "query_logs",
+    ...over,
+});
+describe("recorder helpers", () => {
+    it("isErrorResult detects MCP error envelopes", () => {
+        assert.equal(isErrorResult({ isError: true }), true);
+        assert.equal(isErrorResult({ isError: false }), false);
+        assert.equal(isErrorResult({ content: [] }), false);
+        assert.equal(isErrorResult(null), false);
+    });
+    it("authKind infers from principal", () => {
+        assert.equal(authKind("anonymous"), "anonymous");
+        assert.equal(authKind("key:bot"), "apikey");
+    });
+});
+describe("createInspectRecorder", () => {
+    it("registers as a permissive tool_post_invoke hook", () => {
+        const reg = createInspectRecorder(new InspectStore(), new ModeController("observe"));
+        assert.equal(reg.kind, "tool_post_invoke");
+        assert.equal(reg.mode, "permissive");
+        assert.equal(reg.pluginName, "inspect-recorder");
+    });
+    it("records an observation with a derived signature and always allows", async () => {
+        const store = new InspectStore();
+        const reg = createInspectRecorder(store, new ModeController("observe"));
+        const r = await reg.handler(ctx({ target: "query_logs" }), { args: { source: "prom-eu", service: "pay", query: "rate(x[5m])", window: "1h" }, result: { content: [] } });
+        assert.deepEqual(r, { allow: true });
+        assert.equal(store.size, 1);
+        const o = store.all()[0];
+        assert.equal(o.tool, "query_logs");
+        assert.equal(o.source, "prom-eu");
+        assert.equal(o.service, "pay");
+        assert.equal(o.argShape.window, "<=1h");
+        assert.match(o.argShape.query, /m:x/); // fingerprint, literal never stored
+        assert.equal(o.decision, "allow");
+        assert.equal(o.outcome, "ok");
+    });
+    it("redacts secrets out of args before shaping (no PII leaks into the store)", async () => {
+        const store = new InspectStore();
+        const reg = createInspectRecorder(store, new ModeController("observe"));
+        await reg.handler(ctx(), { args: { note: "contact ops@example.com token AKIAIOSFODNN7EXAMPLE" }, result: {} });
+        const o = store.all()[0];
+        assert.ok(o.redactions >= 1, "redactor ran");
+        // the value collapses to "present"; literal never persisted regardless
+        assert.equal(o.argShape.note, "present");
+        assert.ok(!JSON.stringify(o).includes("AKIA"));
+    });
+    it("marks error outcomes from isError results", async () => {
+        const store = new InspectStore();
+        const reg = createInspectRecorder(store, new ModeController("observe"));
+        await reg.handler(ctx(), { args: {}, result: { isError: true } });
+        assert.equal(store.all()[0].outcome, "error");
+    });
+    it("records nothing when mode is off", async () => {
+        const store = new InspectStore();
+        const reg = createInspectRecorder(store, new ModeController("off"));
+        await reg.handler(ctx(), { args: {}, result: {} });
+        assert.equal(store.size, 0);
+    });
+    it("never throws and still allows even if shaping blows up", async () => {
+        const store = new InspectStore();
+        const reg = createInspectRecorder(store, new ModeController("observe"));
+        // circular args would throw in JSON paths; redactValue handles objects but
+        // we assert the contract: handler resolves allow:true regardless.
+        const circular = {};
+        circular.self = circular;
+        const r = await reg.handler(ctx(), { args: circular, result: {} });
+        assert.deepEqual(r, { allow: true });
+    });
+    it("dry-run: records would-block + deviation kind for a profile deviation", async () => {
+        const store = new InspectStore();
+        const evaluator = { evaluate: () => ({ verdict: "deviation", kind: "new-resource" }) };
+        const reg = createInspectRecorder(store, new ModeController("dryrun"), { evaluator });
+        await reg.handler(ctx({ target: "query_logs" }), { args: { service: "novel" }, result: {} });
+        const o = store.all()[0];
+        assert.equal(o.decision, "would-block");
+        assert.equal(o.deviation, "new-resource");
+    });
+    it("dry-run: records allow when the call is within profile", async () => {
+        const store = new InspectStore();
+        const evaluator = { evaluate: () => ({ verdict: "allow" }) };
+        const reg = createInspectRecorder(store, new ModeController("dryrun"), { evaluator });
+        await reg.handler(ctx(), { args: {}, result: {} });
+        assert.equal(store.all()[0].decision, "allow");
+    });
+    it("observe mode never consults the evaluator (always allow)", async () => {
+        const store = new InspectStore();
+        let consulted = false;
+        const evaluator = { evaluate: () => { consulted = true; return { verdict: "deviation", kind: "new-tool" }; } };
+        const reg = createInspectRecorder(store, new ModeController("observe"), { evaluator });
+        await reg.handler(ctx(), { args: {}, result: {} });
+        assert.equal(store.all()[0].decision, "allow");
+        assert.equal(consulted, false);
+    });
+    it("fires the onEvent metrics seam", async () => {
+        const seen = [];
+        const reg = createInspectRecorder(new InspectStore(), new ModeController("observe"), {
+            onEvent: (e) => seen.push(e),
+        });
+        await reg.handler(ctx({ target: "enrich_ips" }), { args: { ips: ["1.2.3.4"] }, result: {} });
+        assert.deepEqual(seen, [{ tool: "enrich_ips", outcome: "ok", decision: "allow" }]);
+    });
+});

package/dist/inspect/signature.d.ts

@@ -0,0 +1,32 @@
+/** The resource dimensions we treat as first-class (real values kept). */
+export declare const RESOURCE_KEYS: readonly ["source", "service", "namespace"];
+export type ResourceKey = (typeof RESOURCE_KEYS)[number];
+export interface Signature {
+    source?: string;
+    service?: string;
+    namespace?: string;
+    /** key → coarse bucket label (e.g. window → "<=1h", ips → "n=11-100"). */
+    argShape: Record<string, string>;
+}
+/** Bucket a count/length into coarse, order-of-magnitude bands. */
+export declare function countBucket(n: number): string;
+/** Parse a Prometheus/Loki-style duration (e.g. "5m", "1h30m", "90s", "2d")
+ *  to seconds. Returns null when it isn't a duration string. */
+export declare function durationToSeconds(s: string): number | null;
+/** Bucket a duration (seconds) into coarse time bands. */
+export declare function durationBucket(s: string): string;
+/** Bucket a bare number into small / medium / large bands. */
+export declare function numBucket(n: number): string;
+/**
+ * Structural fingerprint of a PromQL/LogQL query — a deterministic, bounded
+ * signal of *which* metric(s), function(s) and label key(s) it touches, WITHOUT
+ * keeping the literal query. Lets a profile rule distinguish "query_metrics on
+ * metric X" from "...on metric Y". Heuristic (not a full parser) but stable.
+ * Returns "present" when nothing structural is extractable, "empty" for blank.
+ */
+export declare function queryFingerprint(q: string): string;
+/**
+ * Derive a Signature from a tool name + its (redacted) arguments.
+ * Deterministic and pure — same input always yields the same signature.
+ */
+export declare function deriveSignature(_tool: string, args: unknown): Signature;

package/dist/inspect/signature.js

@@ -0,0 +1,200 @@
+// Inspect — argument-shape derivation.
+//
+// Turns a tool call's (already-redacted) arguments into a coarse, learnable
+// *signature*: the resource dimensions it targeted (source / service /
+// namespace — the equivalent of AppArmor's file paths) plus a bucketed shape
+// of the remaining scalar args. We deliberately never keep literal argument
+// values (especially free-text PromQL/LogQL queries) — only their shape — so
+// the store stays small, privacy-preserving, and the profile generalises
+// instead of memorising one exact call.
+/** The resource dimensions we treat as first-class (real values kept). */
+export const RESOURCE_KEYS = ["source", "service", "namespace"];
+/** Bucket a count/length into coarse, order-of-magnitude bands. */
+export function countBucket(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "?";
+    if (n <= 1)
+        return "1";
+    if (n <= 10)
+        return "2-10";
+    if (n <= 100)
+        return "11-100";
+    if (n <= 1000)
+        return "101-1000";
+    return ">1000";
+}
+/** Parse a Prometheus/Loki-style duration (e.g. "5m", "1h30m", "90s", "2d")
+ *  to seconds. Returns null when it isn't a duration string. */
+export function durationToSeconds(s) {
+    const str = s.trim();
+    if (!/^\d+(?:\.\d+)?(?:ms|s|m|h|d|w|y)(?:\d+(?:\.\d+)?(?:ms|s|m|h|d|w|y))*$/.test(str)) {
+        return null;
+    }
+    const unit = { ms: 0.001, s: 1, m: 60, h: 3600, d: 86400, w: 604800, y: 31536000 };
+    let total = 0;
+    const re = /(\d+(?:\.\d+)?)(ms|s|m|h|d|w|y)/g;
+    let match;
+    while ((match = re.exec(str)) !== null) {
+        total += parseFloat(match[1]) * unit[match[2]];
+    }
+    return total;
+}
+/** Bucket a duration (seconds) into coarse time bands. */
+export function durationBucket(s) {
+    const secs = durationToSeconds(s);
+    if (secs === null)
+        return "other";
+    if (secs <= 300)
+        return "<=5m";
+    if (secs <= 3600)
+        return "<=1h";
+    if (secs <= 86400)
+        return "<=1d";
+    return ">1d";
+}
+/** Bucket a bare number into small / medium / large bands. */
+export function numBucket(n) {
+    if (!Number.isFinite(n))
+        return "?";
+    if (n <= 10)
+        return "<=10";
+    if (n <= 100)
+        return "<=100";
+    if (n <= 1000)
+        return "<=1000";
+    return ">1000";
+}
+/** Keys whose string value should be treated as a duration when parseable. */
+const DURATION_KEY = /window|range|lookback|step|interval|since|duration|period|timeout/i;
+/** Arg keys carrying a PromQL/LogQL expression — fingerprinted, not kept literal. */
+const QUERY_KEY = /^(query|expr|promql|logql)$/i;
+const PROMQL_KEYWORDS = new Set([
+    "by", "without", "on", "ignoring", "group_left", "group_right", "offset",
+    "bool", "and", "or", "unless", "keep_metric_names", "start", "end", "inf", "nan",
+]);
+// Aggregation operators can appear as `sum by (x) (expr)` — i.e. NOT immediately
+// before "(" — so they need recognising by name, not just by a trailing paren.
+const PROMQL_AGG = new Set([
+    "sum", "min", "max", "avg", "group", "stddev", "stdvar",
+    "count", "count_values", "bottomk", "topk", "quantile",
+]);
+/**
+ * Structural fingerprint of a PromQL/LogQL query — a deterministic, bounded
+ * signal of *which* metric(s), function(s) and label key(s) it touches, WITHOUT
+ * keeping the literal query. Lets a profile rule distinguish "query_metrics on
+ * metric X" from "...on metric Y". Heuristic (not a full parser) but stable.
+ * Returns "present" when nothing structural is extractable, "empty" for blank.
+ */
+export function queryFingerprint(q) {
+    if (!q || !q.trim())
+        return "empty";
+    // Bound the input first — query args are attacker-controlled and run on the
+    // recorder/enforcer hot path; a huge string must not cost real CPU. 4 KB is
+    // ample for a structural signal; truncation stays deterministic.
+    const capped = q.length > 4096 ? q.slice(0, 4096) : q;
+    // Drop string literals so label values / quoted text never look like metrics.
+    const s = capped.replace(/"[^"]*"|'[^']*'|`[^`]*`/g, '""');
+    const funcs = new Set();
+    const labels = new Set();
+    const metrics = new Set();
+    const exclude = new Set();
+    // Functions: an identifier immediately followed by "(" (excluding keywords
+    // like `by(`), plus any aggregation operator by name (e.g. `sum by (x)`).
+    for (const m of s.matchAll(/([A-Za-z_]\w{0,127})\s*\(/g)) {
+        if (!PROMQL_KEYWORDS.has(m[1].toLowerCase()))
+            funcs.add(m[1]);
+    }
+    for (const m of s.matchAll(/[A-Za-z_]\w*/g)) {
+        if (PROMQL_AGG.has(m[0].toLowerCase()))
+            funcs.add(m[0]);
+    }
+    // Grouping labels: by/without/on/ignoring/group_* ( … ) — not metrics.
+    for (const m of s.matchAll(/\b(?:by|without|on|ignoring|group_left|group_right)\s*\(([^)]*)\)/gi)) {
+        for (const id of m[1].match(/[A-Za-z_]\w*/g) ?? []) {
+            labels.add(id);
+            exclude.add(id);
+        }
+    }
+    // Selector label keys: inside { … } before = / != / =~ / !~.
+    for (const br of s.matchAll(/\{([^}]*)\}/g)) {
+        for (const m of br[1].matchAll(/([A-Za-z_]\w*)\s*(?:=~|!~|=|!=)/g)) {
+            labels.add(m[1]);
+            exclude.add(m[1]);
+        }
+    }
+    // Metrics: identifiers (PromQL allows ':') that aren't funcs/keywords/labels,
+    // not a range-duration fragment ([5m] → "m", preceded by a digit).
+    for (const m of s.matchAll(/([A-Za-z_:][\w:]*)/g)) {
+        const idx = m.index ?? 0;
+        const id = m[1];
+        const prev = idx > 0 ? s[idx - 1] : "";
+        if (/\d/.test(prev))
+            continue;
+        const nxt = (s.slice(idx + id.length).match(/^\s*(.)/) ?? [])[1] ?? "";
+        if (nxt === "(")
+            continue;
+        if (funcs.has(id) || exclude.has(id) || PROMQL_KEYWORDS.has(id.toLowerCase()))
+            continue;
+        metrics.add(id);
+    }
+    const cap = (set) => [...set].sort().slice(0, 8).join(",");
+    const parts = [];
+    if (funcs.size)
+        parts.push("f:" + cap(funcs));
+    if (metrics.size)
+        parts.push("m:" + cap(metrics));
+    if (labels.size)
+        parts.push("l:" + cap(labels));
+    return parts.length ? parts.join(" ") : "present";
+}
+/**
+ * Derive a Signature from a tool name + its (redacted) arguments.
+ * Deterministic and pure — same input always yields the same signature.
+ */
+export function deriveSignature(_tool, args) {
+    const sig = { argShape: {} };
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        return sig;
+    const a = args;
+    for (const k of RESOURCE_KEYS) {
+        const v = a[k];
+        if (typeof v === "string" && v.trim())
+            sig[k] = v.trim();
+    }
+    for (const [k, v] of Object.entries(a)) {
+        if (RESOURCE_KEYS.includes(k))
+            continue;
+        // Never let a prototype-polluting arg name into the shape map (keys come
+        // from arbitrary tool-call arguments — js/remote-property-injection).
+        if (k === "__proto__" || k === "constructor" || k === "prototype")
+            continue;
+        if (Array.isArray(v)) {
+            sig.argShape[k] = "n=" + countBucket(v.length);
+        }
+        else if (typeof v === "number") {
+            sig.argShape[k] = numBucket(v);
+        }
+        else if (typeof v === "boolean") {
+            sig.argShape[k] = v ? "true" : "false";
+        }
+        else if (typeof v === "string") {
+            if (DURATION_KEY.test(k) && durationToSeconds(v) !== null) {
+                sig.argShape[k] = durationBucket(v);
+            }
+            else if (QUERY_KEY.test(k)) {
+                // Query args get a structural fingerprint (which metric/func/labels),
+                // not the literal — lets rules distinguish queries by shape.
+                sig.argShape[k] = queryFingerprint(v);
+            }
+            else {
+                // Other free-text values (ids, names) collapse to "present" — never
+                // the literal.
+                sig.argShape[k] = v.trim() ? "present" : "empty";
+            }
+        }
+        else if (v && typeof v === "object") {
+            sig.argShape[k] = "object";
+        }
+    }
+    return sig;
+}

package/dist/inspect/signature.test.d.ts

@@ -0,0 +1 @@
+export {};