@agentx-core/security-sdk 0.1.0

package/dist/report.js

@@ -0,0 +1,359 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRAP_SNIPPET = exports.DOCS_URL = exports.AUDIT_COMMAND = exports.PACKAGE = exports.GATEWAY_URL = exports.AUDIT_SCHEMA = void 0;
+exports.plural = plural;
+exports.fit = fit;
+exports.fitNames = fitNames;
+exports.formatBucket = formatBucket;
+exports.sincePhrase = sincePhrase;
+exports.summariseTools = summariseTools;
+exports.renderTools = renderTools;
+exports.renderCalls = renderCalls;
+exports.jsonPayload = jsonPayload;
+/**
+ * The `audit` screens. The design is `agentx audit` in agentx_sdk/cli.py, copied rather than
+ * reinvented: the same header, the same TOOL / CALLS / SURFACE / ARGUMENTS table, the same
+ * "what was KEPT" disclosure when retention has trimmed the file, and the same rule about
+ * naming the ledger path on an empty screen (the likeliest reason a screen is empty is the
+ * reader standing in a different folder).
+ *
+ * Every line keeps to 75 columns, with one documented exception carried over from the Python
+ * screen: a single argument name longer than the ARGUMENTS budget is kept whole up to
+ * MAX_WHOLE_NAME (40) characters, because a reader greps for a name and cannot grep half of
+ * one. So a --calls row can reach 48 + 40 columns plus a " +N more" suffix (96 with one name
+ * dropped), and a grouped row 46 + 40 plus the same suffix.
+ */
+const shape_1 = require("./shape");
+const ledger_1 = require("./ledger");
+const pulse_1 = require("./pulse");
+/** The wire-format version of `--json`. Its own namespace: this package versions independently of the Python `agentx.audit/1`. */
+exports.AUDIT_SCHEMA = "agentx.ts-audit/1";
+/**
+ * The call to action, with its OWN tag. The two TypeScript calls to action we can already
+ * measure (scan's, and the /docs handoff) both read about one click each, so this one carries
+ * `utm_source=ts-sdk` rather than borrowing either, and the /gateway view beacon can finally
+ * say which of the three, if any, moves anyone.
+ */
+exports.GATEWAY_URL = "https://agentx-core.com/gateway?utm_source=ts-sdk";
+exports.PACKAGE = "@agentx-core/security-sdk";
+exports.AUDIT_COMMAND = `npx ${exports.PACKAGE} audit`;
+exports.DOCS_URL = "https://agentx-core.com/docs";
+/** The one snippet every empty screen shows. Written once so two screens cannot teach two spellings. */
+exports.WRAP_SNIPPET = [
+    `import { agentxWatch } from "${exports.PACKAGE}";`,
+    'const guardedTool = agentxWatch(tool, { name: "runSql" });   // around any tool',
+];
+const RULE = "=".repeat(75);
+const DEFAULT_TOOL_ROWS = 25;
+const DEFAULT_CALL_ROWS = 50;
+const MAX_WHOLE_NAME = 40;
+const MAGNITUDE_WORTH_SHOWING = 100;
+function plural(n, singular, pluralForm) {
+    const word = n === 1 ? singular : pluralForm ?? singular + "s";
+    return `${n.toLocaleString("en-US")} ${word}`;
+}
+function pad(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function padLeft(text, width) {
+    return text.length >= width ? text : " ".repeat(width - text.length) + text;
+}
+/** Clip with a visible ellipsis, never silently: a truncated name that still looks like a name is worse. */
+function fit(text, width) {
+    text = String(text ?? "");
+    return text.length <= width ? text : text.slice(0, Math.max(0, width - 3)) + "...";
+}
+/**
+ * Join argument names to fit `width`, dropping WHOLE names rather than cutting one, and saying
+ * "+N more" for what was dropped. A half name matches nothing when the reader greps for it.
+ * Port of cli.py `_fit_names`, including its one deliberate overrun: a single name longer than
+ * the budget is kept whole up to MAX_WHOLE_NAME.
+ */
+function fitNames(namesIn, width) {
+    const names = namesIn.map((n) => String(n ?? "")).filter(Boolean);
+    if (!names.length)
+        return "(none)";
+    const joined = names.join(", ");
+    if (joined.length <= width)
+        return joined;
+    const reserve = ` +${names.length} more`.length;
+    const kept = [];
+    for (let name of names) {
+        // The first name is kept whole up to MAX_WHOLE_NAME and clipped past it; later names
+        // must fit the remaining budget or are dropped and counted.
+        name = kept.length ? name : fit(name, MAX_WHOLE_NAME);
+        const candidate = [...kept, name].join(", ");
+        if (kept.length && candidate.length > width - reserve)
+            continue;
+        kept.push(name);
+    }
+    const dropped = names.length - kept.length;
+    return dropped ? `${kept.join(", ")} +${dropped} more` : kept.join(", ");
+}
+/** A magnitude BUCKET rendered as the ">= floor" it means, never as a figure the ledger does not hold. */
+function formatBucket(amount) {
+    if (!amount || amount < 1)
+        return "";
+    return `≥${Math.trunc(amount).toLocaleString("en-US")}`;
+}
+function localDay(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+function localClock(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** " since <local date time>" for a window, or "". */
+function sincePhrase(windowStart) {
+    if (!windowStart)
+        return "";
+    const d = new Date(windowStart);
+    const p = (n) => String(n).padStart(2, "0");
+    return ` since ${localDay(windowStart)} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+/** Group the rows by tool, busiest first. */
+function summariseTools(rows) {
+    const byTool = new Map();
+    for (const r of rows) {
+        let s = byTool.get(r.tool);
+        if (!s) {
+            s = {
+                tool: r.tool, calls: 0, classes: [], argNames: [], maxAmount: 0, maxQuantity: 0, agents: [],
+                firstTs: r.ts, lastTs: r.ts, _classes: new Set(), _args: new Set(), _agents: new Set(),
+            };
+            byTool.set(r.tool, s);
+        }
+        s.calls += 1;
+        if (r.surface && r.surface !== shape_1.CLASS_OTHER)
+            s._classes.add(r.surface);
+        for (const a of r.args)
+            s._args.add(a);
+        if (r.agent)
+            s._agents.add(r.agent);
+        s.maxAmount = Math.max(s.maxAmount, r.amount || 0);
+        s.maxQuantity = Math.max(s.maxQuantity, r.quantity || 0);
+        s.firstTs = Math.min(s.firstTs, r.ts);
+        s.lastTs = Math.max(s.lastTs, r.ts);
+    }
+    return [...byTool.values()]
+        .map(({ _classes, _args, _agents, ...s }) => ({
+        ...s, classes: [..._classes].sort(), argNames: [..._args].sort(), agents: [..._agents].sort(),
+    }))
+        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool));
+}
+function effectiveLimit(opts, fallback) {
+    if (opts.limit !== undefined)
+        return opts.limit;
+    if (opts.all)
+        return null;
+    return fallback;
+}
+function ledgerPathLine(read, indent) {
+    return `${indent}${read.path}${read.exists ? "" : "  (not created yet)"}`;
+}
+function emptyScreen(read) {
+    return [
+        "  No calls recorded yet.",
+        ledgerPathLine(read, "     "),
+        "     Calls are recorded per ledger, so running this from another folder",
+        "     reads a different one.",
+        "",
+        "  AgentX records every wrapped tool call. If you have not wrapped a tool yet:",
+        "",
+        ...exports.WRAP_SNIPPET.map((l) => "      " + l),
+        "",
+        RULE,
+    ];
+}
+function trimmedNote(read, indent = "  ") {
+    if (read.coversAll)
+        return [];
+    return [
+        `${indent}⚠️  This ledger has been trimmed, so the counts below describe what was`,
+        `${indent}    KEPT, not everything your agent has ever done. It keeps the last`,
+        `${indent}    ${ledger_1.RETENTION_DAYS} days or ${ledger_1.RETENTION_MAX_ROWS.toLocaleString("en-US")} records.`,
+        "",
+    ];
+}
+function footer() {
+    return [
+        "  AgentX watches and writes down what your agent did, and blocks nothing,",
+        "  so it cannot break a working agent.",
+        // The URL on its own line, as the Python session summary prints its gateway link: on one
+        // line with the sentence this ran to 101 columns and broke the 75-column fence every
+        // screen keeps to. Found by the fence test written for a different row.
+        "     ▶ To stop the dangerous ones before they run, a gateway:",
+        `       ${exports.GATEWAY_URL}`,
+        RULE,
+    ];
+}
+/** The grouped screen. Returns the text; the caller prints it. */
+function renderTools(read, opts = {}) {
+    const out = [
+        "",
+        "🔎 WHAT YOUR AGENT DID                    (local to this ledger)",
+        RULE,
+    ];
+    if (!read.rows.length)
+        return [...out, ...emptyScreen(read)].join("\n");
+    out.push(...trimmedNote(read));
+    const tools = summariseTools(read.rows);
+    const limit = effectiveLimit(opts, DEFAULT_TOOL_ROWS);
+    const shown = limit === null ? tools : tools.slice(0, limit);
+    out.push(`  ${plural(read.rows.length, "call")} across ${plural(tools.length, "tool")}${sincePhrase(read.windowStart)}`);
+    if (shown.length < tools.length) {
+        out.push(`  (showing the busiest ${shown.length}; ${tools.length - shown.length} more not listed -- use --all)`);
+    }
+    out.push("");
+    // The same widths as the Python screen: "  %-20s  %6s  %-13s %s", ARGUMENTS gets 75 - 46.
+    const row = (a, b, c, d) => `  ${pad(a, 20)}  ${padLeft(b, 6)}  ${pad(c, 13)} ${d}`;
+    out.push(row("TOOL", "CALLS", "SURFACE", "ARGUMENTS"));
+    out.push("  " + "-".repeat(71));
+    const agentsOnScreen = new Set(shown.flatMap((s) => s.agents));
+    const showAgents = agentsOnScreen.size > 1;
+    let unknownSurface = false;
+    for (const s of shown) {
+        const classes = s.classes.map((c) => shape_1.SURFACE_LABELS[c] ?? c).join("/") || "-";
+        if (classes === "-")
+            unknownSurface = true;
+        out.push(row(fit(s.tool, 20), s.calls.toLocaleString("en-US"), fit(classes, 13), fitNames(s.argNames, 75 - 46)));
+        const detail = [];
+        if (s.maxAmount >= MAGNITUDE_WORTH_SHOWING)
+            detail.push(`largest amount passed: ${formatBucket(s.maxAmount)}`);
+        if (s.maxQuantity >= MAGNITUDE_WORTH_SHOWING)
+            detail.push(`largest count passed: ${formatBucket(s.maxQuantity)}`);
+        if (showAgents && s.agents.length)
+            detail.push(`agent: ${fitNames(s.agents, 39)}`);
+        if (detail.length)
+            out.push(`  ${pad("", 20)}          ${detail.join("; ")}`);
+    }
+    out.push("");
+    if (unknownSurface) {
+        out.push("  A dash under SURFACE means we could not tell what that tool touches.");
+        out.push("  We go by tool and argument names, and only match words we are sure of.");
+        out.push("");
+    }
+    out.push(...footer());
+    return out.join("\n");
+}
+/** The `--calls` screen: one line per call, newest first. The ORDER is the point. */
+function renderCalls(read, opts = {}) {
+    const out = [
+        "",
+        "🔎 WHAT YOUR AGENT DID, CALL BY CALL     (local to this ledger)",
+        RULE,
+    ];
+    if (!read.rows.length)
+        return [...out, ...emptyScreen(read)].join("\n");
+    if (!read.coversAll) {
+        out.push("  This ledger has been trimmed, so the rows below are what was KEPT, not");
+        out.push("  everything your agent has ever done.");
+    }
+    const newestFirst = [...read.rows].sort((a, b) => b.ts - a.ts);
+    const tools = new Set(newestFirst.map((r) => r.tool)).size;
+    const limit = effectiveLimit(opts, DEFAULT_CALL_ROWS);
+    const shown = limit === null ? newestFirst : newestFirst.slice(0, limit);
+    out.push(`  ${plural(read.rows.length, "call")} across ${plural(tools, "tool")}${sincePhrase(read.windowStart)}`);
+    if (shown.length < newestFirst.length) {
+        out.push(`  (showing the most recent ${shown.length}; ${(newestFirst.length - shown.length).toLocaleString("en-US")} more not listed -- use --all)`);
+    }
+    out.push("");
+    // "  %-8s  %-20s %-6s %-7s %s" -> 2 + 8 + 2 + 20 + 1 + 6 + 1 + 7 + 1 = 48, ARGUMENTS gets 27.
+    // The Python screen gives STATUS 12 because its widest value is "ran, flagged"; on this
+    // door every row is "ran", so the column is its header's width and the nine characters go
+    // to ARGUMENTS, the column a reader opens this screen for. Seen on the founder's first walk:
+    // at 19 a three-name call rendered "amount +2 more". TOOL is 20, as on the grouped screen.
+    const row = (a, b, c, d, e) => `  ${pad(a, 8)}  ${pad(b, 20)} ${pad(c, 6)} ${pad(d, 7)} ${e}`;
+    out.push(row("TIME", "TOOL", "STATUS", "SURFACE", "ARGUMENTS"));
+    out.push("  " + "-".repeat(71));
+    let shownDay = null;
+    for (const r of shown) {
+        const day = localDay(r.ts);
+        if (day !== shownDay) {
+            out.push(`  ${day}`);
+            shownDay = day;
+        }
+        // Every row is "ran": this package has no opinion about a call, so there is no other status.
+        out.push(row(localClock(r.ts), fit(r.tool || "(unnamed)", 20), "ran", shape_1.SURFACE_LABELS[r.surface] ?? "-", fitNames(r.args, 75 - 48)));
+    }
+    out.push("");
+    // The Python `--calls` screen ends here too: the pointer to the grouped view, and no gateway
+    // link. One next step per screen; the grouped screen carries the CTA.
+    out.push(`  Grouped by tool:  ${exports.AUDIT_COMMAND}`);
+    out.push(RULE);
+    return out.join("\n");
+}
+/**
+ * The `--json` document. ALWAYS COMPLETE unless the caller passed `--limit`: a program reading
+ * a silently truncated list would report a smaller agent than the one that ran. Carries a
+ * `schema` and a `view` so a file read in isolation says which flag produced it, and a
+ * `produced_by` block so a reader who has never heard of us knows what made it, which build,
+ * and where to look. Field names follow the Python `agentx audit --json` wherever the two
+ * describe the same fact (`ledger.*`, `time`, `status_label`, `arg_names`, `amount_bucket`,
+ * `surface`), so one consumer can read both files.
+ */
+function jsonPayload(read, view, opts = {}) {
+    const surfaceLabel = (c) => (c && c !== shape_1.CLASS_OTHER ? shape_1.SURFACE_LABELS[c] ?? c : null);
+    const base = {
+        schema: exports.AUDIT_SCHEMA,
+        view,
+        produced_by: {
+            tool: "agentx-security-sdk audit",
+            version: (0, pulse_1.sdkVersion)(),
+            docs: exports.DOCS_URL,
+        },
+        generated_at: new Date().toISOString(),
+        ledger: {
+            readable: read.readable,
+            path: read.path,
+            exists: read.exists,
+            window_start: read.windowStart ? read.windowStart / 1000 : null,
+            window_start_iso: read.windowStart ? new Date(read.windowStart).toISOString() : null,
+            covers_all: read.readable ? read.coversAll : null,
+            dropped: read.readable ? read.dropped : null,
+            retention_days: ledger_1.RETENTION_DAYS,
+            max_rows: ledger_1.RETENTION_MAX_ROWS,
+        },
+        cta: { gateway: exports.GATEWAY_URL, command: exports.AUDIT_COMMAND },
+    };
+    if (!read.readable)
+        return base;
+    const limit = opts.limit ?? null;
+    const tools = summariseTools(read.rows);
+    if (view === "tools") {
+        const shown = limit === null ? tools : tools.slice(0, limit);
+        base.totals = { calls: read.rows.length, tools: tools.length, shown: shown.length, listed_total: tools.length };
+        base.tools = shown.map((s) => ({
+            tool: s.tool,
+            calls: s.calls,
+            surfaces: s.classes.map((c) => shape_1.SURFACE_LABELS[c] ?? c),
+            arg_names: s.argNames,
+            max_amount_bucket: s.maxAmount,
+            max_count_bucket: s.maxQuantity,
+            agents: s.agents,
+            first_time: new Date(s.firstTs).toISOString(),
+            last_time: new Date(s.lastTs).toISOString(),
+        }));
+    }
+    else {
+        const newestFirst = [...read.rows].sort((a, b) => b.ts - a.ts);
+        const shown = limit === null ? newestFirst : newestFirst.slice(0, limit);
+        base.totals = { calls: read.rows.length, tools: tools.length, shown: shown.length, rows: read.rows.length };
+        base.calls = shown.map((r) => ({
+            ts: r.ts / 1000,
+            time: new Date(r.ts).toISOString(),
+            tool: r.tool,
+            status: "ALLOWED",
+            status_label: "ran",
+            arg_names: r.args,
+            amount_bucket: r.amount,
+            count_bucket: r.quantity,
+            surface: surfaceLabel(r.surface),
+            agent: r.agent || null,
+        }));
+    }
+    return base;
+}

package/dist/shape.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The SHAPE of a call: what gets written down about it, and the rule deciding what does not.
+ *
+ * A port of `agentx_sdk/db.py::_call_shape` and the helpers around it. Only the KEYS of the
+ * arguments are read, plus the power-of-ten magnitude of a value the developer themselves
+ * named as an amount (with a currency beside it) or a count. No argument VALUE is ever
+ * returned from this module, so nothing downstream can write one.
+ *
+ * The numbers and the hint table below are pinned to the Python ones by
+ * `sdk_tests/test_ts_sdk_matches_python.py`. "Same limits as the Python SDK" is a test, not a
+ * sentence in a README.
+ */
+export type TargetClass = "filesystem" | "http" | "db" | "shell" | "cloud" | "other";
+export declare const CLASS_OTHER: TargetClass;
+/** What the SURFACE column prints. The stored value stays long (`filesystem`); the screen is short. */
+export declare const SURFACE_LABELS: Record<TargetClass, string>;
+/**
+ * Token -> class. Matched against the TOOL NAME and the ARGUMENT NAMES only, never against
+ * argument values, so nothing a user's data says can influence the result. First match wins
+ * in THIS order.
+ *
+ * Deliberately under-inclusive, and it should stay that way: `query`, `table`, `cursor`,
+ * `request`, `bucket`, `cluster` and `command` were all removed on the Python side after each
+ * mislabelled a real tool. A confident wrong class on a screen the developer reads as a
+ * statement about their own agent is worse than `other`, which says we do not know.
+ *
+ * ONE HINT PER LINE. The Python-side tripwire reads this table line by line.
+ */
+export declare const CLASS_HINTS: ReadonlyArray<readonly [readonly string[], TargetClass]>;
+/**
+ * The closed action vocabulary the whole product uses (the gateway's `action` field, and the
+ * `action` option on the TypeScript guard in examples/ts-guard). Reused here EXACTLY, so a call
+ * is described the same way on every surface. A developer's own label fills the SURFACE
+ * column only when the tool and argument names left it blank; it never overrides them.
+ */
+export type Action = "execute_database_query" | "fetch_url" | "execute_shell" | "send_message" | "write_file" | "other";
+export declare const ACTION_SURFACE: Record<Action, TargetClass>;
+/** Bounds on the argument-name list, so one 400-parameter tool cannot bloat a row. */
+export declare const MAX_ARG_NAMES = 24;
+export declare const MAX_ARG_NAMES_CHARS = 512;
+export interface CallShape {
+    /** Sorted, comma-free, budgeted argument NAMES. */
+    argNames: string[];
+    /** Power-of-ten floor of the largest labelled amount, or 0. */
+    amount: number;
+    /** Power-of-ten floor of the largest labelled count, or 0. */
+    quantity: number;
+    targetClass: TargetClass;
+}
+export declare function normaliseKey(key: unknown): string;
+export declare function isAmountKey(name: string): boolean;
+export declare function isCurrencyKey(name: string): boolean;
+export declare function isCountKey(name: string): boolean;
+/** A currency key must CARRY a currency: `null` and booleans are not one. */
+export declare function isRealCurrencyValue(value: unknown): boolean;
+/**
+ * The bucket FLOOR for a numeric magnitude, as a power of ten. 5 -> 1, 42 -> 10, 1500 -> 1000,
+ * 0 -> 0. Anything non-numeric returns 0: a string is never coerced, because parsing one is
+ * how a value sneaks into a numeric column.
+ */
+export declare function magnitudeBucket(value: unknown): number;
+/**
+ * Whole lowercase tokens from identifier-ish text. camelCase is a boundary too (`sendHttpRequest`
+ * is three tokens), and the match below is on WHOLE tokens, never substrings: `send_feedback`
+ * must not classify as DB because "fee(db)ack" contains "db".
+ */
+export declare function nameTokens(raw: unknown): Set<string>;
+/** The bounded target class from the tool name and argument NAMES. Reads no values. */
+export declare function classifyTarget(toolName: string, names: readonly string[]): TargetClass;
+/** The same closed set, from a tool's own advertised description. Display-only, by rule. */
+export declare function classifyText(text: unknown): TargetClass;
+/**
+ * Derive the shape of one call. Pure, never throws.
+ *
+ * The caller's own words decide first (tool and argument names). The `action` label and then
+ * the description are consulted only when those leave the class blank: they can fill a `-`,
+ * never override what the developer actually called.
+ */
+export declare function callShape(toolName: string, args: unknown, description?: string, action?: Action): CallShape;

package/dist/shape.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * The SHAPE of a call: what gets written down about it, and the rule deciding what does not.
+ *
+ * A port of `agentx_sdk/db.py::_call_shape` and the helpers around it. Only the KEYS of the
+ * arguments are read, plus the power-of-ten magnitude of a value the developer themselves
+ * named as an amount (with a currency beside it) or a count. No argument VALUE is ever
+ * returned from this module, so nothing downstream can write one.
+ *
+ * The numbers and the hint table below are pinned to the Python ones by
+ * `sdk_tests/test_ts_sdk_matches_python.py`. "Same limits as the Python SDK" is a test, not a
+ * sentence in a README.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ARG_NAMES_CHARS = exports.MAX_ARG_NAMES = exports.ACTION_SURFACE = exports.CLASS_HINTS = exports.SURFACE_LABELS = exports.CLASS_OTHER = void 0;
+exports.normaliseKey = normaliseKey;
+exports.isAmountKey = isAmountKey;
+exports.isCurrencyKey = isCurrencyKey;
+exports.isCountKey = isCountKey;
+exports.isRealCurrencyValue = isRealCurrencyValue;
+exports.magnitudeBucket = magnitudeBucket;
+exports.nameTokens = nameTokens;
+exports.classifyTarget = classifyTarget;
+exports.classifyText = classifyText;
+exports.callShape = callShape;
+exports.CLASS_OTHER = "other";
+/** What the SURFACE column prints. The stored value stays long (`filesystem`); the screen is short. */
+exports.SURFACE_LABELS = {
+    db: "DB",
+    filesystem: "FS",
+    http: "HTTP",
+    shell: "SHELL",
+    cloud: "CLOUD",
+    other: "-",
+};
+/**
+ * Token -> class. Matched against the TOOL NAME and the ARGUMENT NAMES only, never against
+ * argument values, so nothing a user's data says can influence the result. First match wins
+ * in THIS order.
+ *
+ * Deliberately under-inclusive, and it should stay that way: `query`, `table`, `cursor`,
+ * `request`, `bucket`, `cluster` and `command` were all removed on the Python side after each
+ * mislabelled a real tool. A confident wrong class on a screen the developer reads as a
+ * statement about their own agent is worse than `other`, which says we do not know.
+ *
+ * ONE HINT PER LINE. The Python-side tripwire reads this table line by line.
+ */
+exports.CLASS_HINTS = [
+    [["sql", "db", "database", "postgres", "mysql", "mongo", "sqlite"], "db"],
+    [["aws", "gcp", "azure", "cloud", "terraform", "s3"], "cloud"],
+    [["http", "https", "url", "webhook"], "http"],
+    [["shell", "exec", "cmd", "bash", "subprocess"], "shell"],
+    [["file", "path", "dir", "directory", "unlink", "chmod"], "filesystem"],
+];
+exports.ACTION_SURFACE = {
+    execute_database_query: "db",
+    fetch_url: "http",
+    execute_shell: "shell",
+    send_message: "other",
+    write_file: "filesystem",
+    other: "other",
+};
+// Which argument is money: the developer tells us. Named `amount` (or `<prefix>_amount`) AND
+// the same call carries a `currency` key holding a real value. A range bound (`min_amount`) is
+// a read, not money moved. Both rules ported from the Python writer, which ported them from
+// the gateway, so all three answer "which number is money" the same way.
+const AMOUNT_KEY = "amount";
+const CURRENCY_KEY = "currency";
+const COUNT_KEY = "count";
+const RANGE_BOUND_PREFIXES = new Set(["min", "max", "lower", "upper"]);
+/** Bounds on the argument-name list, so one 400-parameter tool cannot bloat a row. */
+exports.MAX_ARG_NAMES = 24;
+exports.MAX_ARG_NAMES_CHARS = 512;
+function normaliseKey(key) {
+    return String(key).trim().toLowerCase().replace(/-/g, "_").replace(/\./g, "_");
+}
+function isAmountKey(name) {
+    return name === AMOUNT_KEY || name.endsWith("_" + AMOUNT_KEY);
+}
+function isCurrencyKey(name) {
+    return name === CURRENCY_KEY || name.endsWith("_" + CURRENCY_KEY);
+}
+function isCountKey(name) {
+    return name === COUNT_KEY || name.endsWith("_" + COUNT_KEY);
+}
+/** `total_amount` -> `total`, `amount` -> ``. For the range-bound check. */
+function amountPrefix(name) {
+    return name.slice(0, name.length - AMOUNT_KEY.length).replace(/_+$/, "");
+}
+/** A currency key must CARRY a currency: `null` and booleans are not one. */
+function isRealCurrencyValue(value) {
+    if (value === null || value === undefined || typeof value === "boolean")
+        return false;
+    return String(value).trim().length > 0;
+}
+/**
+ * The bucket FLOOR for a numeric magnitude, as a power of ten. 5 -> 1, 42 -> 10, 1500 -> 1000,
+ * 0 -> 0. Anything non-numeric returns 0: a string is never coerced, because parsing one is
+ * how a value sneaks into a numeric column.
+ */
+function magnitudeBucket(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return 0;
+    const size = Math.abs(value);
+    if (size < 1)
+        return 0;
+    let bucket = 1;
+    while (bucket * 10 <= size) {
+        bucket *= 10;
+        if (bucket >= 1e15)
+            break;
+    }
+    return bucket;
+}
+/**
+ * Whole lowercase tokens from identifier-ish text. camelCase is a boundary too (`sendHttpRequest`
+ * is three tokens), and the match below is on WHOLE tokens, never substrings: `send_feedback`
+ * must not classify as DB because "fee(db)ack" contains "db".
+ */
+function nameTokens(raw) {
+    const spaced = String(raw ?? "").replace(/(?<=[a-z0-9])(?=[A-Z])/g, " ");
+    return new Set(spaced.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+}
+function classifyTokens(tokens) {
+    for (const [needles, klass] of exports.CLASS_HINTS) {
+        if (needles.some((n) => tokens.has(n)))
+            return klass;
+    }
+    return exports.CLASS_OTHER;
+}
+/** The bounded target class from the tool name and argument NAMES. Reads no values. */
+function classifyTarget(toolName, names) {
+    return classifyTokens(nameTokens([toolName, ...names].join(" ")));
+}
+/** The same closed set, from a tool's own advertised description. Display-only, by rule. */
+function classifyText(text) {
+    return classifyTokens(nameTokens(text));
+}
+/**
+ * Derive the shape of one call. Pure, never throws.
+ *
+ * The caller's own words decide first (tool and argument names). The `action` label and then
+ * the description are consulted only when those leave the class blank: they can fill a `-`,
+ * never override what the developer actually called.
+ */
+function callShape(toolName, args, description, action) {
+    const record = args && typeof args === "object" && !Array.isArray(args) ? args : {};
+    // The comma is the record separator on the Python side and in the screens, so a key carrying
+    // one would split into two names the tool never had. Stripped, not escaped.
+    const names = Object.keys(record).map((k) => k.replace(/,/g, " ")).sort();
+    // Budget the LIST, then join. `continue`, not `break`: names arrive sorted, and one oversized
+    // name must not discard every name after it.
+    const kept = [];
+    let used = 0;
+    for (const name of names.slice(0, exports.MAX_ARG_NAMES)) {
+        const cost = name.length + (kept.length ? 1 : 0);
+        if (used + cost > exports.MAX_ARG_NAMES_CHARS)
+            continue;
+        kept.push(name);
+        used += cost;
+    }
+    let amount = 0;
+    try {
+        const entries = Object.entries(record);
+        const hasCurrency = entries.some(([k, v]) => isCurrencyKey(normaliseKey(k)) && isRealCurrencyValue(v));
+        if (hasCurrency) {
+            for (const [k, v] of entries) {
+                const norm = normaliseKey(k);
+                if (!isAmountKey(norm) || RANGE_BOUND_PREFIXES.has(amountPrefix(norm)))
+                    continue;
+                amount = Math.max(amount, magnitudeBucket(v));
+            }
+        }
+    }
+    catch {
+        amount = 0;
+    }
+    let quantity = 0;
+    try {
+        for (const [k, v] of Object.entries(record)) {
+            if (!isCountKey(normaliseKey(k)))
+                continue;
+            quantity = Math.max(quantity, magnitudeBucket(v));
+        }
+    }
+    catch {
+        quantity = 0;
+    }
+    let targetClass = classifyTarget(toolName, names);
+    if (targetClass === exports.CLASS_OTHER && action && action in exports.ACTION_SURFACE) {
+        targetClass = exports.ACTION_SURFACE[action];
+    }
+    if (targetClass === exports.CLASS_OTHER && description) {
+        targetClass = classifyText(description);
+    }
+    return { argNames: kept, amount, quantity, targetClass };
+}