@agentx-core/security-sdk 0.1.0

package/dist/pulse.js

@@ -0,0 +1,401 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_SESSION_KEYS = exports.ALLOWED_KEYS = exports.TIMEOUT_MS = exports.DEBOUNCE_MS = exports.DEFAULT_ENDPOINT = exports.INTEGRATION = void 0;
+exports.stateFile = stateFile;
+exports.internalMarker = internalMarker;
+exports.loadState = loadState;
+exports.saveState = saveState;
+exports.telemetryEnabled = telemetryEnabled;
+exports.isDefaultOn = isDefaultOn;
+exports.isAutomationContext = isAutomationContext;
+exports.mode = mode;
+exports.endpoint = endpoint;
+exports.sdkVersion = sdkVersion;
+exports.osName = osName;
+exports.buildPayload = buildPayload;
+exports.shouldSend = shouldSend;
+exports.post = post;
+exports.maybeSend = maybeSend;
+exports.showNotice = showNotice;
+exports.onSessionEnd = onSessionEnd;
+exports.queuePending = queuePending;
+exports.markAuditReportRun = markAuditReportRun;
+/**
+ * Anonymous usage pulse. ON by default, one-line opt-out (`AGENTX_TELEMETRY=off`).
+ *
+ * The same pulse the Python SDK sends, to the same receiver (`/api/pulse` on the control
+ * plane), with the same field list. `integration` is `"ts"`, which is how the funnel tells
+ * this package's installs from the Python decorator's and the MCP proxy's.
+ *
+ * Hard rules, asserted by test/pulse.test.ts and pinned against the Python allowlist by
+ * sdk_tests/test_ts_sdk_matches_python.py:
+ *   * Never sends arguments, tool names, paths, hostnames, usernames or keys. COUNTS only.
+ *   * Only the keys in ALLOWED_KEYS / ALLOWED_SESSION_KEYS ever leave, and exactly those.
+ *   * Fire-and-forget: never throws, bounded by a 1s timeout, fails open offline.
+ *   * Test and CI runs are excluded entirely, even when on: automation is not adoption.
+ *
+ * One difference from the Python pulse, stated so the two doors' columns are read right: the
+ * session counts here are the SUM of every session since the last pulse (a run that ends
+ * through process.exit() queues its counts; a run inside the day's debounce keeps them
+ * queued), so one pulse can carry a day's worth of sessions. The Python SDK sends one
+ * session's counts and drops a debounced session's.
+ *
+ * THIS IS THE ONLY FILE IN THE PACKAGE THAT REACHES THE NETWORK, and test/network-boundary.test.ts
+ * fails if a second one appears. `@agentx-core/scan` never phones home at all; this package
+ * does, once a day, with counts. Two packages, two promises, and each README says which.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+exports.INTEGRATION = "ts";
+// The receiver: the control plane's POST /api/pulse. MUST be the canonical www host: the
+// bare apex answers a 307 to www, and a POST that is not re-sent on redirect is a pulse
+// silently dropped.
+exports.DEFAULT_ENDPOINT = "https://www.agentx-core.com/api/pulse";
+exports.DEBOUNCE_MS = 24 * 60 * 60 * 1000; // at most one pulse per install per day
+exports.TIMEOUT_MS = 1000;
+/** The complete set of top-level keys that may leave the machine. KEEP IN SYNC with agentx_sdk/pulse.py _ALLOWED_KEYS. */
+exports.ALLOWED_KEYS = [
+    "install_id", "sdk_version", "python", "os", "first_seen", "ts",
+    "mode", "gateway_present", "reasoning_enabled", "contributed",
+    "block_category", "integration", "session", "ran_audit_report",
+];
+/** The session COUNT keys. KEEP IN SYNC with agentx_sdk/pulse.py _ALLOWED_SESSION_KEYS. */
+exports.ALLOWED_SESSION_KEYS = [
+    "tools_monitored", "intercepts", "critical_blocks",
+    "human_escalations", "self_corrections", "would_blocks",
+    "had_block", "first_block_ever", "shield_failopens",
+    "own_agent_block", "audit_calls", "audit_tools",
+];
+// A separate file from the Python SDK's pulse.json: two SDKs on one machine are two installs,
+// and sharing a file would couple this writer to that one's atomic-write format.
+function stateFile() {
+    return path.join(os.homedir(), ".agentx", "ts-pulse.json");
+}
+/** The machine-level "this machine is ours" marker the Python SDK writes. READ here, never written. */
+function internalMarker() {
+    return path.join(os.homedir(), ".agentx", "internal");
+}
+function loadState(file = stateFile()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function saveState(state, file = stateFile()) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(state), "utf8");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* telemetry must never break a run */
+    }
+}
+function ensureIdentity(state) {
+    if (!state.install_id)
+        state.install_id = (0, crypto_1.randomUUID)();
+    if (!state.first_seen)
+        state.first_seen = new Date().toISOString().slice(0, 10);
+    return state;
+}
+function truthy(v) {
+    return ["1", "true", "on", "yes"].includes(String(v ?? "").trim().toLowerCase());
+}
+/** True unless the developer explicitly opted out. `AGENTX_TELEMETRY` always wins when present. */
+function telemetryEnabled(env = process.env) {
+    const explicit = env.AGENTX_TELEMETRY;
+    if (explicit !== undefined && explicit !== "")
+        return truthy(explicit);
+    return true;
+}
+/** True when telemetry is on purely by default, i.e. nobody set AGENTX_TELEMETRY. Only these installs get the notice. */
+function isDefaultOn(env = process.env) {
+    return env.AGENTX_TELEMETRY === undefined || env.AGENTX_TELEMETRY === "";
+}
+const CI_ENV_VARS = [
+    "CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "JENKINS_URL",
+    "CIRCLECI", "TRAVIS", "BUILDKITE", "TF_BUILD", "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER", "APPVEYOR", "DRONE", "CODEBUILD_BUILD_ID",
+];
+// Test runners set these on every worker. A developer running THEIR suite over an agent that
+// imports us is exactly the run that must not count as adoption.
+const TEST_RUNNER_VARS = ["VITEST", "JEST_WORKER_ID", "NODE_TEST_CONTEXT"];
+/**
+ * True when this run is a test/CI invocation, an explicitly flagged dev environment
+ * (`AGENTX_ENV=development|dev|test`), or a machine the Python SDK has marked as ours. Such
+ * runs send nothing and climb no rung. Never throws.
+ *
+ * Unlike the Python side, this never WRITES the machine marker: a wrong write deletes a real
+ * user from the funnel permanently, and the Python SDK already owns that decision.
+ */
+function isAutomationContext(env = process.env, markerExists = () => fs.existsSync(internalMarker())) {
+    try {
+        if (["development", "dev", "test"].includes(String(env.AGENTX_ENV ?? "").trim().toLowerCase()))
+            return true;
+        if (CI_ENV_VARS.some((v) => env[v]))
+            return true;
+        if (TEST_RUNNER_VARS.some((v) => env[v]))
+            return true;
+        return markerExists();
+    }
+    catch {
+        return false;
+    }
+}
+/** The coarse data-plane mode, resolved the way the Python SDK resolves it. */
+function mode(env = process.env) {
+    const m = String(env.AGENTX_MODE ?? "").trim().toLowerCase();
+    if (m === "local" || m === "linked" || m === "cloud")
+        return m;
+    if (truthy(env.AGENTX_ALLOW_PAYLOAD_SYNC))
+        return "cloud";
+    return String(env.CONTROL_PLANE_URL ?? "").trim() ? "linked" : "local";
+}
+function isHttp(url) {
+    return /^https?:\/\//i.test(url);
+}
+/** Where the pulse goes: the configured control plane's /api/pulse, else the public default. */
+function endpoint(env = process.env) {
+    const plane = String(env.CONTROL_PLANE_URL ?? "").trim();
+    if (isHttp(plane)) {
+        const base = plane.replace(/\/+$/, "");
+        return base.endsWith("/api/pulse") ? base : base + "/api/pulse";
+    }
+    return exports.DEFAULT_ENDPOINT;
+}
+/** This build's version, from package.json. "unknown" rather than a guess. */
+function sdkVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** The Python SDK sends `platform.system().lower()`; map Node's names onto the same words. */
+function osName(platform = process.platform) {
+    if (platform === "win32")
+        return "windows";
+    return platform || "unknown";
+}
+/**
+ * Assemble the pulse. ALLOWLIST ONLY: it reads two counters off `stats` and never a name.
+ * Every key in ALLOWED_KEYS is present, so the receiver sees one shape from every SDK; the
+ * fields this door has no way to observe are null or false, never omitted.
+ */
+function buildPayload(stats, state, opts = {}) {
+    const env = opts.env ?? process.env;
+    const n = (v) => (typeof v === "number" && Number.isFinite(v) ? Math.max(0, Math.trunc(v)) : 0);
+    return {
+        install_id: state.install_id,
+        // The bare package version. The receiver stores every SDK's version in one column beside
+        // `integration`, and scripts/funnel.py keys its version bar on the pair, so "0.1.0" here
+        // and "0.1.0" from the Python SDK never share a bucket.
+        sdk_version: opts.version ?? sdkVersion(),
+        // A Node runtime has no Python version. Null, not a Node version in a column named
+        // python: the receiver's column carries a meaning and this door cannot supply it.
+        python: null,
+        os: osName(opts.platform),
+        first_seen: state.first_seen,
+        ts: (opts.now ?? new Date()).toISOString(),
+        mode: mode(env),
+        // No gateway leg on this door, so these are the honest constants. Not omitted: absent
+        // reads as "pre-signal" on the receiver, and this install is not pre-anything.
+        gateway_present: false,
+        reasoning_enabled: null,
+        contributed: false,
+        block_category: null,
+        integration: exports.INTEGRATION,
+        session: {
+            tools_monitored: n(stats.totalCalls),
+            intercepts: 0,
+            critical_blocks: 0,
+            human_escalations: 0,
+            self_corrections: 0,
+            would_blocks: 0,
+            had_block: false,
+            first_block_ever: false,
+            shield_failopens: 0,
+            own_agent_block: false,
+            // The audit rung, same meaning as the Python counters: calls the record saw and
+            // DISTINCT tools it saw. Counts; the names never leave.
+            audit_calls: n(stats.totalCalls),
+            audit_tools: n(stats.distinctTools),
+        },
+        ran_audit_report: Boolean(state.ran_audit_report),
+    };
+}
+/** Pure debounce decision. */
+function shouldSend(state, nowMs) {
+    const last = state.last_pulse ?? 0;
+    return nowMs - last >= exports.DEBOUNCE_MS;
+}
+/** Fire the pulse. Swallows every error and is bounded by TIMEOUT_MS. */
+async function post(url, payload, timeoutMs = exports.TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": `agentx-ts-sdk-pulse/${String(payload.sdk_version ?? "?")}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        /* offline, blocked, timed out: all fine */
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Send one pulse if telemetry is on and the day's window is open. Persists BEFORE dispatch so
+ * a crash mid-send cannot double-count tomorrow. Returns the payload sent, or null.
+ */
+async function maybeSend(stats, state, file = stateFile(), opts = {}) {
+    try {
+        const env = opts.env ?? process.env;
+        if (!telemetryEnabled(env))
+            return null;
+        ensureIdentity(state);
+        const now = opts.now ?? Date.now();
+        if (!shouldSend(state, now)) {
+            saveState(state, file); // persist identity even when we skip
+            return null;
+        }
+        state.last_pulse = now;
+        // A send is being attempted, so the queued counts are spent here whether or not the
+        // network answers: post() swallows failure and the day's debounce stands either way.
+        delete state.pending;
+        saveState(state, file);
+        const payload = buildPayload(stats, state, { now: new Date(now), env });
+        await post(opts.url ?? endpoint(env), payload);
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/** The one-time transparency notice, printed BEFORE the first pulse leaves. To stderr: this runs inside someone else's program. */
+function showNotice(state, file = stateFile(), write = (s) => process.stderr.write(s)) {
+    try {
+        const rule = "─".repeat(60);
+        write(`\n${rule}\n` +
+            " AgentX shares ANONYMOUS usage by default: SDK version, OS, and call\n" +
+            " COUNTS only. Never your code, your arguments, or your data.\n" +
+            " Opt out anytime:  AGENTX_TELEMETRY=off\n" +
+            " Questions or feedback: founders@agentx-core.com\n" +
+            `${rule}\n`);
+        state.notice_shown = true;
+        ensureIdentity(state);
+        saveState(state, file);
+    }
+    catch {
+        /* never break a run */
+    }
+}
+function sum(a, b) {
+    if (!a)
+        return { ...b };
+    return { totalCalls: a.totalCalls + b.totalCalls, distinctTools: Math.max(a.distinctTools, b.distinctTools) };
+}
+async function onSessionEnd(stats, file = stateFile(), deps = {}) {
+    try {
+        const env = deps.env ?? process.env;
+        if (!telemetryEnabled(env))
+            return;
+        if (isAutomationContext(env, deps.markerExists))
+            return;
+        const state = loadState(file);
+        // Everything not yet carried by a pulse is `pending`, this session included. maybeSend
+        // clears it on its send path only, right before its own write, so each path writes the
+        // state file once and the file never holds a version with the counts missing.
+        state.pending = sum(state.pending, stats);
+        if (isDefaultOn(env) && !state.notice_shown)
+            showNotice(state, file, deps.notice);
+        await maybeSend(state.pending, state, file, { env, url: deps.url, now: deps.now });
+    }
+    catch {
+        /* never break a run */
+    }
+}
+/**
+ * The synchronous fallback for `process.on("exit")`, where nothing async can run: write the
+ * counts down so the NEXT run sends them. Never throws.
+ */
+function queuePending(stats, file = stateFile(), deps = {}) {
+    try {
+        const env = deps.env ?? process.env;
+        if (!telemetryEnabled(env))
+            return;
+        if (isAutomationContext(env, deps.markerExists))
+            return;
+        const state = loadState(file);
+        state.pending = sum(state.pending, stats);
+        saveState(state, file);
+    }
+    catch {
+        /* never break a run */
+    }
+}
+/**
+ * A human ran `audit`. STICKY, and excluded from automation for the same reason the Python
+ * side is: this is the conversion event the funnel is built around and it cannot be
+ * un-climbed, so one CI job must not mark an install converted forever.
+ */
+function markAuditReportRun(file = stateFile(), env = process.env) {
+    try {
+        if (isAutomationContext(env))
+            return;
+        const state = ensureIdentity(loadState(file));
+        state.ran_audit_report = true;
+        saveState(state, file);
+    }
+    catch {
+        /* a reader command must never fail on bookkeeping */
+    }
+}

package/dist/report.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+import { type TargetClass } from "./shape";
+import { type CallRow, type LedgerRead } from "./ledger";
+/** The wire-format version of `--json`. Its own namespace: this package versions independently of the Python `agentx.audit/1`. */
+export declare const 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.
+ */
+export declare const GATEWAY_URL = "https://agentx-core.com/gateway?utm_source=ts-sdk";
+export declare const PACKAGE = "@agentx-core/security-sdk";
+export declare const AUDIT_COMMAND = "npx @agentx-core/security-sdk audit";
+export declare const DOCS_URL = "https://agentx-core.com/docs";
+/** The one snippet every empty screen shows. Written once so two screens cannot teach two spellings. */
+export declare const WRAP_SNIPPET: readonly string[];
+export interface ViewOptions {
+    /** Explicit --limit. */
+    limit?: number;
+    /** --all. */
+    all?: boolean;
+}
+export declare function plural(n: number, singular: string, pluralForm?: string): string;
+/** Clip with a visible ellipsis, never silently: a truncated name that still looks like a name is worse. */
+export declare function fit(text: string, width: number): string;
+/**
+ * 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.
+ */
+export declare function fitNames(namesIn: readonly unknown[], width: number): string;
+/** A magnitude BUCKET rendered as the ">= floor" it means, never as a figure the ledger does not hold. */
+export declare function formatBucket(amount: number): string;
+/** " since <local date time>" for a window, or "". */
+export declare function sincePhrase(windowStart: number | null): string;
+export interface ToolSummary {
+    tool: string;
+    calls: number;
+    classes: TargetClass[];
+    argNames: string[];
+    maxAmount: number;
+    maxQuantity: number;
+    agents: string[];
+    firstTs: number;
+    lastTs: number;
+}
+/** Group the rows by tool, busiest first. */
+export declare function summariseTools(rows: readonly CallRow[]): ToolSummary[];
+/** The grouped screen. Returns the text; the caller prints it. */
+export declare function renderTools(read: LedgerRead, opts?: ViewOptions): string;
+/** The `--calls` screen: one line per call, newest first. The ORDER is the point. */
+export declare function renderCalls(read: LedgerRead, opts?: ViewOptions): string;
+/**
+ * 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.
+ */
+export declare function jsonPayload(read: LedgerRead, view: "tools" | "calls", opts?: ViewOptions): Record<string, unknown>;