@agentx-core/security-sdk 0.1.0

package/dist/wrap.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `agentxWatch(tool)`: wrap a tool so every call is written down. Watches and records; blocks
+ * nothing. The free, keyless rung for TypeScript, and the TypeScript analogue of the Python
+ * `@agentx_protect` decorator in its watching posture.
+ *
+ * NO IMPACT ON THE WRAPPED CODE. The original `execute` is called with the same `this`, the
+ * same arguments and the same context, and whatever it returns or throws passes straight
+ * through. Recording happens first, inside its own try/catch, so an unwritable folder or a
+ * full disk costs a ledger row and never a tool call. The wrapper does not make a sync tool
+ * async and does not touch the arguments object.
+ *
+ * THE PART THAT RECORDS AND REPORTS IS SEPARATE FROM THE PART THAT WRAPS, deliberately
+ * (shape.ts / ledger.ts / report.ts against this file). If blocking ever arrives it is a
+ * different wrapper over the same record, not a rewrite.
+ */
+import { type Action } from "./shape";
+import * as pulse from "./pulse";
+/**
+ * Any object with an `execute` function: a Vercel AI SDK `tool()`, or your own. A LangChain.js
+ * tool is a class instance driven through `invoke`, and this wrapper does not cover it.
+ */
+export interface WatchableTool {
+    description?: string;
+    execute: (...args: any[]) => any;
+    [k: string]: unknown;
+}
+export interface WatchOptions {
+    /**
+     * The tool's name as it appears on the report. A Vercel AI SDK `tool()` carries none (its
+     * name is the key in your `tools` object), so pass it here or use `agentxWatchAll`, which
+     * takes the keys. Unnamed tools report as "(unnamed)".
+     */
+    name?: string;
+    /** Which agent made the call. Shown on the report only when more than one agent is on it. */
+    agentId?: string;
+    /** The closed action vocabulary the rest of the product uses. Fills the SURFACE column when the names leave it blank. */
+    action?: Action;
+}
+/** TEST ONLY. */
+export declare function __resetSessionForTests(): void;
+/** TEST ONLY. The counters as the pulse will see them. */
+export declare function __sessionStatsForTests(): pulse.SessionStats;
+/**
+ * Wrap one tool. Returns a new object with the same shape; the original is not mutated.
+ */
+export declare function agentxWatch<T extends WatchableTool>(tool: T, opts?: WatchOptions): T;
+/**
+ * Wrap a whole `tools` map, naming each by its key. The Vercel AI SDK shape:
+ *
+ *     tools: agentxWatchAll({ runSql, sendEmail })
+ */
+export declare function agentxWatchAll<T extends Record<string, WatchableTool>>(tools: T, opts?: Omit<WatchOptions, "name">): T;

package/dist/wrap.js

@@ -0,0 +1,200 @@
+"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.__resetSessionForTests = __resetSessionForTests;
+exports.__sessionStatsForTests = __sessionStatsForTests;
+exports.agentxWatch = agentxWatch;
+exports.agentxWatchAll = agentxWatchAll;
+/**
+ * `agentxWatch(tool)`: wrap a tool so every call is written down. Watches and records; blocks
+ * nothing. The free, keyless rung for TypeScript, and the TypeScript analogue of the Python
+ * `@agentx_protect` decorator in its watching posture.
+ *
+ * NO IMPACT ON THE WRAPPED CODE. The original `execute` is called with the same `this`, the
+ * same arguments and the same context, and whatever it returns or throws passes straight
+ * through. Recording happens first, inside its own try/catch, so an unwritable folder or a
+ * full disk costs a ledger row and never a tool call. The wrapper does not make a sync tool
+ * async and does not touch the arguments object.
+ *
+ * THE PART THAT RECORDS AND REPORTS IS SEPARATE FROM THE PART THAT WRAPS, deliberately
+ * (shape.ts / ledger.ts / report.ts against this file). If blocking ever arrives it is a
+ * different wrapper over the same record, not a rewrite.
+ */
+const shape_1 = require("./shape");
+const ledger_1 = require("./ledger");
+const pulse = __importStar(require("./pulse"));
+const report_1 = require("./report");
+const session = {
+    totalCalls: 0,
+    toolNames: new Set(),
+    hooked: false,
+    reported: false,
+    ending: false,
+    ledgerNoticed: false,
+};
+/** TEST ONLY. */
+function __resetSessionForTests() {
+    session.totalCalls = 0;
+    session.toolNames.clear();
+    session.reported = false;
+    session.ending = false;
+    session.ledgerNoticed = false;
+}
+/** TEST ONLY. The counters as the pulse will see them. */
+function __sessionStatsForTests() {
+    return stats();
+}
+function stats() {
+    return { totalCalls: session.totalCalls, distinctTools: session.toolNames.size };
+}
+function stderr(line) {
+    try {
+        process.stderr.write(line + "\n");
+    }
+    catch {
+        /* a closed stderr is not our problem to raise */
+    }
+}
+/**
+ * The session-end line, to stderr, only when something was wrapped and called. Says what it
+ * counted ("tool calls", every one of them) and that nothing was blocked, so the count cannot
+ * be read as protection.
+ */
+function printReport() {
+    if (session.reported || session.totalCalls === 0)
+        return;
+    session.reported = true;
+    const rule = "─".repeat(60);
+    stderr(rule);
+    stderr(` AgentX watched ${(0, report_1.plural)(session.totalCalls, "tool call")} across ${(0, report_1.plural)(session.toolNames.size, "tool")} this run.`);
+    stderr(" Watching records and blocks nothing. What your agent did:");
+    stderr(`     ${report_1.AUDIT_COMMAND}`);
+    stderr(rule);
+}
+async function onBeforeExit() {
+    // `beforeExit` fires again once the awaited send below drains the loop; the flag stops the
+    // second pass from sending a second pulse.
+    if (session.ending)
+        return;
+    session.ending = true;
+    printReport();
+    (0, ledger_1.trimLedger)();
+    await pulse.onSessionEnd(stats());
+}
+function onExit() {
+    printReport();
+    if (!session.ending) {
+        // process.exit() skipped beforeExit, so nothing async can run now: queue the counts and
+        // the next run sends them. One run late is honest; never is a lost install.
+        session.ending = true;
+        pulse.queuePending(stats());
+    }
+}
+function installHooks() {
+    if (session.hooked)
+        return;
+    if (typeof process === "undefined" || typeof process.on !== "function")
+        return;
+    session.hooked = true;
+    process.once("beforeExit", () => {
+        void onBeforeExit();
+    });
+    process.on("exit", onExit);
+}
+function record(name, args, description, opts) {
+    // REDUCE FIRST. Only the shape exists past this line; there is no variable holding a value
+    // for the ledger writer to reach.
+    const shape = (0, shape_1.callShape)(name, args, description, opts.action);
+    const row = {
+        k: "call",
+        ts: Date.now(),
+        tool: name,
+        args: shape.argNames,
+        surface: shape.targetClass,
+        amount: shape.amount,
+        quantity: shape.quantity,
+        agent: opts.agentId ?? "",
+    };
+    const file = (0, ledger_1.ledgerPath)();
+    const { created } = (0, ledger_1.appendCall)(row, file);
+    if (created && !session.ledgerNoticed) {
+        session.ledgerNoticed = true;
+        stderr(`[agentx] recording wrapped tool calls to ${file} (tool and argument NAMES, never values). Add it to .gitignore if this folder is a repository.`);
+    }
+}
+/**
+ * Wrap one tool. Returns a new object with the same shape; the original is not mutated.
+ */
+function agentxWatch(tool, opts = {}) {
+    // Anything without an `execute` function comes back untouched: a null or undefined entry
+    // in a tools map, a Vercel AI SDK client-side tool, an untyped caller's object. Manufacturing
+    // an `execute` for it would make the SDK run the tool server-side and throw inside this
+    // wrapper.
+    if (!tool || typeof tool.execute !== "function")
+        return tool;
+    const original = tool.execute;
+    const name = opts.name ?? (typeof tool.name === "string" && tool.name ? tool.name : "(unnamed)");
+    const description = typeof tool.description === "string" ? tool.description : undefined;
+    const execute = function (...callArgs) {
+        try {
+            installHooks();
+            session.totalCalls += 1;
+            session.toolNames.add(name);
+            record(name, callArgs[0], description, opts);
+        }
+        catch {
+            /* a ledger problem is never a tool problem */
+        }
+        return original.apply(this, callArgs);
+    };
+    // The copy keeps the tool's prototype and every own property, so a class-based tool whose
+    // `execute` calls `this.query(...)` still finds it: the SDK invokes `wrapped.execute`, so
+    // `this` inside the original is this copy.
+    const copy = Object.create(Object.getPrototypeOf(tool), Object.getOwnPropertyDescriptors(tool));
+    Object.defineProperty(copy, "execute", { value: execute, writable: true, configurable: true, enumerable: true });
+    return copy;
+}
+/**
+ * Wrap a whole `tools` map, naming each by its key. The Vercel AI SDK shape:
+ *
+ *     tools: agentxWatchAll({ runSql, sendEmail })
+ */
+function agentxWatchAll(tools, opts = {}) {
+    const out = {};
+    for (const [key, tool] of Object.entries(tools)) {
+        out[key] = agentxWatch(tool, { ...opts, name: key });
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@agentx-core/security-sdk",
+  "version": "0.1.0",
+  "description": "See what your TypeScript AI agent actually did. Wrap a tool in one line; every call is recorded locally (tool name, argument names, never values) and `audit` prints the report. Watches and records; blocks nothing.",
+  "license": "MIT",
+  "author": "AgentX <founders@agentx-core.com> (https://agentx-core.com)",
+  "homepage": "https://agentx-core.com",
+  "keywords": [
+    "ai",
+    "agent",
+    "agents",
+    "ai-agent",
+    "tools",
+    "tool-calling",
+    "security",
+    "audit",
+    "observability",
+    "vercel-ai-sdk",
+    "llm",
+    "typescript"
+  ],
+  "bin": {
+    "agentx-security-sdk": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.30",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}