@agentx-core/security-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 AgentX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Contact: founders@agentx-core.com | https://agentx-core.com

package/README.md

@@ -0,0 +1,139 @@
+# `@agentx-core/security-sdk`
+
+**See what your TypeScript AI agent actually did.**
+
+Wrap a tool in one line. Every call it makes is written down locally, and one command prints
+the report. It watches and records; it blocks nothing, so it cannot break an agent that works
+today.
+
+```bash
+npm install @agentx-core/security-sdk
+```
+
+```ts
+import { agentxWatchAll } from "@agentx-core/security-sdk";
+
+const result = await generateText({
+  model,
+  tools: agentxWatchAll({ runSql, sendEmail, writeFile }),   // was: tools: { runSql, ... }
+  prompt,
+});
+```
+
+Then, from the folder your agent ran in:
+
+```bash
+npx @agentx-core/security-sdk audit
+```
+
+```
+🔎 WHAT YOUR AGENT DID                    (local to this ledger)
+===========================================================================
+  412 calls across 3 tools since 2026-09-01 09:14
+
+  TOOL                   CALLS  SURFACE       ARGUMENTS
+  -----------------------------------------------------------------------
+  runSql                   388  DB            limit, query
+  writeFile                 19  FS            content, path
+  sendEmail                  5  -             body, subject, to
+
+  A dash under SURFACE means we could not tell what that tool touches.
+  We go by tool and argument names, and only match words we are sure of.
+
+  AgentX watches and writes down what your agent did, and blocks nothing,
+  so it cannot break a working agent.
+     ▶ To stop the dangerous ones before they run, a gateway:
+       https://agentx-core.com/gateway?utm_source=ts-sdk
+===========================================================================
+```
+
+`audit --calls` lists every call, newest first. `audit --json` is the same data for a program,
+always complete.
+
+## What it writes down, and what it never does
+
+Each call becomes one line in `.agentx-calls.jsonl` in the current folder:
+
+- the tool's name,
+- the **names** of the arguments it was called with,
+- a size band for an argument the tool itself named as an `amount` (only when a `currency`
+  sits beside it) or a `count`: a power of ten, so 1,042.55 is recorded as 1,000,
+- a coarse surface such as DB, FS, HTTP, SHELL or CLOUD, read from the names only,
+- when, and which agent.
+
+**Never an argument value, a query, a payload, or a result.** There is no code path from a
+value to that file: the wrapper reduces a call to its shape before anything is written, and
+`test/wrap.test.ts` asserts the file holds no value from a call carrying a SQL statement, an
+email address and a dollar figure. This is exactly what the Python SDK's `agentx audit` keeps.
+
+The file is yours. Add it to `.gitignore`; the wrapper reminds you once when it creates it. It
+keeps the last 30 days or 10,000 rows, and when it has trimmed, the report says the counts
+describe what was **kept**.
+
+## Nothing is blocked
+
+There are no rules in this package and it makes no decision about a call. Every wrapped call
+runs exactly as it would have, with the same arguments and the same result, and a throw
+propagates unchanged. The record answers "what did my agent do" from the calls themselves.
+
+To stop the dangerous ones before they run, add the gateway:
+https://agentx-core.com/gateway?utm_source=ts-sdk
+
+## This package phones home. `@agentx-core/scan` never does.
+
+Our two TypeScript packages make different promises:
+
+- **`@agentx-core/scan`** reads your code and makes **no network calls, ever**. Its own test
+  suite enforces that.
+- **This package** sends one anonymous usage pulse a day: an install id (a random token, not
+  derived from you or your machine), the package version, your OS, and **counts** of calls and
+  tools. Never tool names, arguments, paths, hostnames or keys. `test/pulse.test.ts` pins the
+  field list exactly, and a test on the Python side pins it to the Python SDK's list, so the
+  two SDKs cannot drift into sending different things.
+
+It tells you this on first run. Turn it off with one line:
+
+```bash
+AGENTX_TELEMETRY=off
+```
+
+Test runners and CI are excluded automatically (`VITEST`, `JEST_WORKER_ID`, `CI`,
+`GITHUB_ACTIONS` and the usual others), so your own test suite never counts as usage.
+`test/network-boundary.test.ts` fails if any file other than the pulse reaches the network.
+
+## Shapes it wraps
+
+Anything with an `execute` function: a Vercel AI SDK `tool()`, or your own object.
+`agentxWatch(tool, { name })` wraps one; `agentxWatchAll({ ... })` wraps a map and takes the
+names from its keys. A Vercel `tool()` carries no name of its own (the name is the key in your
+`tools` object), so prefer `agentxWatchAll` there. A tool with no `execute` (a client-side
+tool) is returned unchanged. LangChain.js tools run through `invoke` and are not covered in
+this version.
+
+Options: `name`, `agentId` (shown when more than one agent is on the report), and `action`,
+the closed vocabulary the rest of AgentX uses (`execute_database_query`, `fetch_url`,
+`execute_shell`, `send_message`, `write_file`, `other`). `action` fills the SURFACE column only
+when the tool and argument names leave it blank; it never overrides them.
+
+Node 18 or newer. The wrapper does nothing on a runtime without a filesystem.
+
+## Usage
+
+```bash
+npx @agentx-core/security-sdk audit              # grouped by tool
+npx @agentx-core/security-sdk audit --calls      # one line per call, newest first
+npx @agentx-core/security-sdk audit --json       # machine-readable, always complete
+npx @agentx-core/security-sdk audit --all        # every row on the human screen
+npx @agentx-core/security-sdk audit --limit 10
+```
+
+Errors go to stderr, so `audit --json > out.json` is always a JSON file. An unreadable ledger
+exits 2 and says so; it is never reported as "no calls".
+
+## The Python SDK
+
+Same product, other language: `pip install agentx-security-sdk`, `@agentx_protect` over a tool,
+`agentx audit`. The Python one also carries a keyless local shield and can block; this one, in
+this version, watches.
+
+MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+interface Io {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function main(argv: string[], io?: Io): number;
+export {};

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+/**
+ * `npx @agentx-core/security-sdk audit [--calls] [--json] [--limit N | --all]`
+ *
+ * The reader for the local record `agentxWatch` writes. Flags, errors and stream discipline
+ * follow `agentx audit` in agentx_sdk/cli.py: errors go to STDERR (so `--json > out.json` is
+ * always a JSON file), `--json` returns before any human line reaches stdout, and an
+ * unreadable ledger exits 2 rather than printing "no calls".
+ */
+const ledger_1 = require("./ledger");
+const report_1 = require("./report");
+const pulse_1 = require("./pulse");
+const USAGE = `
+🔎 agentx audit — what your agent actually did, from the local record.
+
+  ${report_1.AUDIT_COMMAND}               grouped by tool
+  ${report_1.AUDIT_COMMAND} --calls       one line per call, newest first
+  --json                          machine-readable output (always complete)
+  --limit N | --all               how many rows the human screen shows
+  --help                          this message
+
+The record is written by agentxWatch() into .agentx-calls.jsonl in the folder your agent ran
+in; run this from that folder. It holds tool and argument NAMES, never values.
+`;
+const defaultIo = {
+    out: (s) => console.log(s),
+    err: (s) => console.error(s),
+};
+function main(argv, io = defaultIo) {
+    const args = [...argv];
+    const wantsJson = args.includes("--json");
+    const usageTo = wantsJson ? io.err : io.out;
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        usageTo(USAGE.trim());
+        return 0;
+    }
+    const sub = args.shift();
+    if (sub !== "audit") {
+        io.err(`\n❌ Unknown command '${sub}'.`);
+        io.err(USAGE.trim());
+        return 1;
+    }
+    const opts = { calls: false, json: false };
+    const die = (message) => {
+        io.err(`\n❌ ${message}`);
+        io.err(`   Usage:  ${report_1.AUDIT_COMMAND} [--calls] [--json] [--limit N | --all]`);
+        return 1;
+    };
+    for (let i = 0; i < args.length; i++) {
+        const tok = args[i];
+        if (tok === "--calls")
+            opts.calls = true;
+        else if (tok === "--json")
+            opts.json = true;
+        else if (tok === "--all")
+            opts.all = true;
+        else if (tok === "--limit") {
+            const raw = args[i + 1];
+            if (raw === undefined)
+                return die("--limit needs a number.");
+            const value = Number(raw);
+            if (!Number.isInteger(value))
+                return die(`--limit needs a number, not '${raw}'.`);
+            if (value < 1)
+                return die("--limit must be at least 1.");
+            opts.limit = value;
+            i += 1;
+        }
+        else
+            return die(`Unknown option '${tok}' for \`${report_1.AUDIT_COMMAND}\`.`);
+    }
+    if (opts.all && opts.limit !== undefined)
+        return die("--all and --limit ask for different things; pass one.");
+    const env = io.env ?? process.env;
+    const file = (0, ledger_1.ledgerPath)(env);
+    (0, ledger_1.trimLedger)(file);
+    const read = (0, ledger_1.readLedger)(file);
+    if (opts.json) {
+        io.out(JSON.stringify((0, report_1.jsonPayload)(read, opts.calls ? "calls" : "tools", opts), null, 2));
+        return read.readable ? 0 : 2;
+    }
+    // A human looked. The rung this package exists to make visible, and the one thing `--json`
+    // must never climb: a cron job polling it is not a person.
+    (0, pulse_1.markAuditReportRun)(undefined, env);
+    if (!read.readable) {
+        io.err("\n❌ The ledger is on disk but could not be read, so this is not a statement that");
+        io.err(`   your agent did nothing.  ${file}`);
+        return 2;
+    }
+    io.out(opts.calls ? (0, report_1.renderCalls)(read, opts) : (0, report_1.renderTools)(read, opts));
+    return 0;
+}
+// Only auto-run as the real entry point (the published `bin`), never when a test imports `main`.
+if (require.main === module && !process.env.VITEST) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { agentxWatch, agentxWatchAll } from "./wrap";
+export type { WatchableTool, WatchOptions } from "./wrap";
+export type { Action, TargetClass } from "./shape";

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentxWatchAll = exports.agentxWatch = void 0;
+var wrap_1 = require("./wrap");
+Object.defineProperty(exports, "agentxWatch", { enumerable: true, get: function () { return wrap_1.agentxWatch; } });
+Object.defineProperty(exports, "agentxWatchAll", { enumerable: true, get: function () { return wrap_1.agentxWatchAll; } });

package/dist/ledger.d.ts

@@ -0,0 +1,46 @@
+import type { TargetClass } from "./shape";
+export declare const LEDGER_FILE = ".agentx-calls.jsonl";
+export declare const RETENTION_DAYS = 30;
+export declare const RETENTION_MAX_ROWS = 10000;
+export interface CallRow {
+    k: "call";
+    /** Epoch milliseconds. */
+    ts: number;
+    tool: string;
+    args: string[];
+    surface: TargetClass;
+    amount: number;
+    quantity: number;
+    agent: string;
+}
+/** Where the ledger lives. `AGENTX_TS_LEDGER_PATH` moves it (tests, and a shared folder). */
+export declare function ledgerPath(env?: NodeJS.ProcessEnv): string;
+/** Append one call. Returns whether this write CREATED the file (the first-run notice keys on it). */
+export declare function appendCall(row: CallRow, file?: string): {
+    created: boolean;
+};
+export interface LedgerRead {
+    path: string;
+    exists: boolean;
+    /** False when the file is there and could not be read. Never confused with empty. */
+    readable: boolean;
+    /** Oldest first. */
+    rows: CallRow[];
+    /** Cumulative rows dropped by retention. 0 means the rows are everything ever recorded. */
+    dropped: number;
+    coversAll: boolean;
+    /** Epoch ms of the oldest kept row, or null. */
+    windowStart: number | null;
+    /** Bytes the read covered, and whether they ended on a line break. trimLedger's carry-over keys on both. */
+    bytes: number;
+    cleanEnd: boolean;
+}
+export declare function readLedger(file?: string): LedgerRead;
+/**
+ * Apply retention: drop rows older than RETENTION_DAYS, then the oldest past RETENTION_MAX_ROWS.
+ * Rewrites atomically (temp file + rename) only when something was dropped, and records the
+ * cumulative drop count so `readLedger` can say the ledger was trimmed. Never throws.
+ */
+export declare function trimLedger(file?: string, now?: number, maxAgeDays?: number, maxRows?: number): {
+    dropped: number;
+};

package/dist/ledger.js

@@ -0,0 +1,183 @@
+"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.RETENTION_MAX_ROWS = exports.RETENTION_DAYS = exports.LEDGER_FILE = void 0;
+exports.ledgerPath = ledgerPath;
+exports.appendCall = appendCall;
+exports.readLedger = readLedger;
+exports.trimLedger = trimLedger;
+/**
+ * The local record: one JSON line per wrapped call, in the current directory.
+ *
+ * Kept per FOLDER, like the Python SDK's `.agentx.db`, so an agent run in ~/proj and an
+ * `audit` run from ~ read two different files. The screens name the path for exactly that
+ * reason. Retention is the Python SDK's: the last 30 days or 10,000 rows, and a trim is
+ * written down (a `trim` line carrying the cumulative count) so a reader can say "what was
+ * KEPT" instead of "everything your agent has ever done".
+ *
+ * Rows hold what `shape.ts` produced and nothing else. There is no code path from a raw
+ * argument value to this file; `wrap.ts` reduces before it records.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.LEDGER_FILE = ".agentx-calls.jsonl";
+exports.RETENTION_DAYS = 30;
+exports.RETENTION_MAX_ROWS = 10000;
+/** Where the ledger lives. `AGENTX_TS_LEDGER_PATH` moves it (tests, and a shared folder). */
+function ledgerPath(env = process.env) {
+    return path.resolve(env.AGENTX_TS_LEDGER_PATH || exports.LEDGER_FILE);
+}
+/** Append one call. Returns whether this write CREATED the file (the first-run notice keys on it). */
+function appendCall(row, file = ledgerPath()) {
+    const created = !fs.existsSync(file);
+    fs.appendFileSync(file, JSON.stringify(row) + "\n", "utf8");
+    return { created };
+}
+function parseLines(text) {
+    const rows = [];
+    let dropped = 0;
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue; // a torn line from a crash mid-write is skipped, not fatal
+        }
+        const r = parsed;
+        if (r && r.k === "trim" && typeof r.dropped === "number") {
+            dropped = Math.max(dropped, r.dropped);
+        }
+        else if (r && r.k === "call" && typeof r.tool === "string" && typeof r.ts === "number") {
+            rows.push({
+                k: "call",
+                ts: r.ts,
+                tool: r.tool,
+                args: Array.isArray(r.args) ? r.args.map(String) : [],
+                surface: r.surface || "other",
+                amount: typeof r.amount === "number" ? r.amount : 0,
+                quantity: typeof r.quantity === "number" ? r.quantity : 0,
+                agent: typeof r.agent === "string" ? r.agent : "",
+            });
+        }
+    }
+    return { rows, dropped };
+}
+function readLedger(file = ledgerPath()) {
+    const base = {
+        path: file, exists: false, readable: true, rows: [], dropped: 0, coversAll: true, windowStart: null,
+        bytes: 0, cleanEnd: true,
+    };
+    if (!fs.existsSync(file))
+        return base;
+    base.exists = true;
+    let buf;
+    try {
+        buf = fs.readFileSync(file);
+    }
+    catch {
+        // UNREADABLE IS NOT EMPTY. A reader that renders this as "no calls" makes a false
+        // statement about the developer's own data.
+        return { ...base, readable: false };
+    }
+    const { rows, dropped } = parseLines(buf.toString("utf8"));
+    rows.sort((a, b) => a.ts - b.ts);
+    return {
+        ...base,
+        rows,
+        dropped,
+        coversAll: dropped === 0,
+        windowStart: rows.length ? rows[0].ts : null,
+        bytes: buf.length,
+        cleanEnd: buf.length === 0 || buf[buf.length - 1] === 0x0a,
+    };
+}
+/**
+ * Apply retention: drop rows older than RETENTION_DAYS, then the oldest past RETENTION_MAX_ROWS.
+ * Rewrites atomically (temp file + rename) only when something was dropped, and records the
+ * cumulative drop count so `readLedger` can say the ledger was trimmed. Never throws.
+ */
+function trimLedger(file = ledgerPath(), now = Date.now(), maxAgeDays = exports.RETENTION_DAYS, maxRows = exports.RETENTION_MAX_ROWS) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        const read = readLedger(file);
+        if (!read.exists || !read.readable)
+            return { dropped: 0 };
+        const cutoff = now - maxAgeDays * 86400 * 1000;
+        let kept = read.rows.filter((r) => r.ts >= cutoff);
+        if (kept.length > maxRows)
+            kept = kept.slice(kept.length - maxRows);
+        const droppedNow = read.rows.length - kept.length;
+        if (droppedNow === 0)
+            return { dropped: 0 };
+        const trim = { k: "trim", ts: now, dropped: read.dropped + droppedNow };
+        const lines = [JSON.stringify(trim), ...kept.map((r) => JSON.stringify(r))].join("\n") + "\n";
+        fs.writeFileSync(tmp, lines, "utf8");
+        // Other processes write this file too: an agent appending in another terminal, or a second
+        // exiting agent running its own trim. Rows appended after the read (the file grew, and what
+        // was read ended on a line break) are copied onto the end of the rewrite. If the file
+        // shrank, someone else rewrote it and this pass no longer describes it; the rewrite is
+        // abandoned rather than renamed over a file this process did not read.
+        const nowBytes = fs.statSync(file).size;
+        if (nowBytes < read.bytes)
+            throw new Error("ledger rewritten during trim");
+        if (nowBytes > read.bytes) {
+            if (!read.cleanEnd)
+                throw new Error("ledger tail is mid-line; skip this trim");
+            const fd = fs.openSync(file, "r");
+            try {
+                const tail = Buffer.alloc(nowBytes - read.bytes);
+                const got = fs.readSync(fd, tail, 0, tail.length, read.bytes);
+                fs.appendFileSync(tmp, tail.subarray(0, got));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        fs.renameSync(tmp, file);
+        return { dropped: droppedNow };
+    }
+    catch {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* nothing to remove */
+        }
+        return { dropped: 0 };
+    }
+}

package/dist/pulse.d.ts

@@ -0,0 +1,102 @@
+export declare const INTEGRATION = "ts";
+export declare const DEFAULT_ENDPOINT = "https://www.agentx-core.com/api/pulse";
+export declare const DEBOUNCE_MS: number;
+export declare const 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. */
+export declare const ALLOWED_KEYS: readonly ["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. */
+export declare const ALLOWED_SESSION_KEYS: readonly ["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"];
+export interface SessionStats {
+    /** Every wrapped call this session. */
+    totalCalls: number;
+    /** Distinct wrapped tools this session. A count; the names stay on disk. */
+    distinctTools: number;
+}
+export interface PulseState {
+    install_id?: string;
+    first_seen?: string;
+    last_pulse?: number;
+    notice_shown?: boolean;
+    ran_audit_report?: boolean;
+    /** Counts from a run that ended through process.exit() before the pulse could be sent. */
+    pending?: SessionStats;
+}
+type Env = NodeJS.ProcessEnv;
+export declare function stateFile(): string;
+/** The machine-level "this machine is ours" marker the Python SDK writes. READ here, never written. */
+export declare function internalMarker(): string;
+export declare function loadState(file?: string): PulseState;
+export declare function saveState(state: PulseState, file?: string): void;
+/** True unless the developer explicitly opted out. `AGENTX_TELEMETRY` always wins when present. */
+export declare function telemetryEnabled(env?: Env): boolean;
+/** True when telemetry is on purely by default, i.e. nobody set AGENTX_TELEMETRY. Only these installs get the notice. */
+export declare function isDefaultOn(env?: Env): boolean;
+/**
+ * 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.
+ */
+export declare function isAutomationContext(env?: Env, markerExists?: () => boolean): boolean;
+/** The coarse data-plane mode, resolved the way the Python SDK resolves it. */
+export declare function mode(env?: Env): "local" | "linked" | "cloud";
+/** Where the pulse goes: the configured control plane's /api/pulse, else the public default. */
+export declare function endpoint(env?: Env): string;
+/** This build's version, from package.json. "unknown" rather than a guess. */
+export declare function sdkVersion(): string;
+/** The Python SDK sends `platform.system().lower()`; map Node's names onto the same words. */
+export declare function osName(platform?: string): string;
+/**
+ * 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.
+ */
+export declare function buildPayload(stats: SessionStats, state: PulseState, opts?: {
+    now?: Date;
+    version?: string;
+    platform?: string;
+    env?: Env;
+}): Record<string, unknown>;
+/** Pure debounce decision. */
+export declare function shouldSend(state: PulseState, nowMs: number): boolean;
+/** Fire the pulse. Swallows every error and is bounded by TIMEOUT_MS. */
+export declare function post(url: string, payload: Record<string, unknown>, timeoutMs?: number): Promise<void>;
+/**
+ * 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.
+ */
+export declare function maybeSend(stats: SessionStats, state: PulseState, file?: string, opts?: {
+    now?: number;
+    env?: Env;
+    url?: string;
+}): Promise<Record<string, unknown> | null>;
+/** The one-time transparency notice, printed BEFORE the first pulse leaves. To stderr: this runs inside someone else's program. */
+export declare function showNotice(state: PulseState, file?: string, write?: (s: string) => void): void;
+/**
+ * The session-end entry point. Fires on every run that wrapped a call. Merges in counts a
+ * previous run queued (see queuePending) so a script that always ends with process.exit()
+ * still reports, one run late rather than never.
+ */
+export interface SessionEndDeps {
+    env?: Env;
+    url?: string;
+    now?: number;
+    /** Injectable so a test can drive this path on a machine the Python SDK has marked as ours. */
+    markerExists?: () => boolean;
+    notice?: (s: string) => void;
+}
+export declare function onSessionEnd(stats: SessionStats, file?: string, deps?: SessionEndDeps): Promise<void>;
+/**
+ * The synchronous fallback for `process.on("exit")`, where nothing async can run: write the
+ * counts down so the NEXT run sends them. Never throws.
+ */
+export declare function queuePending(stats: SessionStats, file?: string, deps?: SessionEndDeps): void;
+/**
+ * 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.
+ */
+export declare function markAuditReportRun(file?: string, env?: Env): void;
+export {};