@agentx-core/security-sdk 0.1.0 → 0.2.0

package/dist/report.js

@@ -178,6 +178,35 @@ function trimmedNote(read, indent = "  ") {
         "",
     ];
 }
+/**
+ * The denominator: how many tools were WRAPPED, against how many actually ran.
+ *
+ * Silent on a ledger with no roster row, which is every ledger written before this shipped and
+ * every one written by an older version of the package. An absent roster means we do not know
+ * the total, and printing "0 never ran" from that would be a claim, not a gap.
+ *
+ * 🔴 IT COUNTS AGAINST THE ROSTER, AND CANNOT SEE THE SCREEN. `--limit` shortens the table
+ * above; a remainder computed from the visible rows would report a smaller roster every time
+ * someone narrowed the view. This function is not passed the limit, or the shown rows, or any
+ * count derived from them, so that mistake has nowhere to enter. An earlier version took a
+ * `calledCount` fallback parameter: fault injection showed nothing could redden it, because
+ * `renderTools` returns the empty screen before reaching here, so the fallback was unreachable
+ * and the test guarding it was guarding a risk the code did not have.
+ */
+function rosterLine(read, indent = "  ") {
+    if (!read.roster.length)
+        return [];
+    // 🔴 COUNT THE INTERSECTION, NOT THE LEDGER. `roster` is the newest run's; `rows` is every run
+    // this folder has kept. Counting all distinct tools in the ledger against a roster from one
+    // run produced a self-contradicting line: yesterday's script wrapped and ran A, B and C, today's
+    // wraps D and E and runs only D, and the screen said "2 tools wrapped. 4 called. 0 never ran."
+    // It also disagreed with `--json`, whose `never_ran` was already a set difference. Same basis
+    // for both now.
+    const ran = new Set(read.rows.map((r) => r.tool || "(unnamed)"));
+    const called = read.roster.filter((t) => ran.has(t)).length;
+    const never = read.roster.length - called;
+    return [`  ${plural(read.roster.length, "tool")} wrapped. ${called} called. ${never} never ran.`.replace(/^ {2}/, indent)];
+}
 function footer() {
     return [
         "  AgentX watches and writes down what your agent did, and blocks nothing,",
@@ -190,8 +219,14 @@ function footer() {
         RULE,
     ];
 }
-/** The grouped screen. Returns the text; the caller prints it. */
-function renderTools(read, opts = {}) {
+/**
+ * The grouped screen. Returns the text; the caller prints it.
+ *
+ * `novelty` is the already-rendered "what changed" block, passed IN rather than computed here.
+ * This module stays a pure formatter: reading the stored mark and moving it are side effects,
+ * and they belong with the caller that also decides whether a human is looking.
+ */
+function renderTools(read, opts = {}, novelty = []) {
     const out = [
         "",
         "🔎 WHAT YOUR AGENT DID                    (local to this ledger)",
@@ -204,6 +239,7 @@ function renderTools(read, opts = {}) {
     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)}`);
+    out.push(...rosterLine(read));
     if (shown.length < tools.length) {
         out.push(`  (showing the busiest ${shown.length}; ${tools.length - shown.length} more not listed -- use --all)`);
     }
@@ -236,6 +272,11 @@ function renderTools(read, opts = {}) {
         out.push("  We go by tool and argument names, and only match words we are sure of.");
         out.push("");
     }
+    // After the table, before the footer: the table is what the agent did, this is what is
+    // different about it, and the footer is what to do next. An empty block prints nothing at
+    // all, so a quiet run does not grow a bare header over a blank space.
+    if (novelty.length)
+        out.push(...novelty, "");
     out.push(...footer());
     return out.join("\n");
 }
@@ -326,6 +367,13 @@ function jsonPayload(read, view, opts = {}) {
     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 };
+        // The roster, as a first-class field and NULL rather than [] when the ledger has none. A
+        // consumer must be able to tell "this run wrapped nothing" from "this ledger predates the
+        // roster and cannot answer", which an empty array collapses into one.
+        base.roster = read.roster.length ? read.roster : null;
+        base.never_ran = read.roster.length
+            ? read.roster.filter((t) => !tools.some((s) => s.tool === t))
+            : null;
         base.tools = shown.map((s) => ({
             tool: s.tool,
             calls: s.calls,

package/dist/wrap.js

@@ -54,13 +54,19 @@ exports.agentxWatchAll = agentxWatchAll;
  */
 const shape_1 = require("./shape");
 const ledger_1 = require("./ledger");
+const novelty_1 = require("./novelty");
 const pulse = __importStar(require("./pulse"));
 const report_1 = require("./report");
 const session = {
     totalCalls: 0,
     toolNames: new Set(),
+    /** Every tool WRAPPED this process, called or not. The roster's whole source. */
+    wrapped: new Set(),
+    /** Groups this run's roster rows together. See RosterRow in ledger.ts. */
+    id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
     hooked: false,
     reported: false,
+    rosterWritten: false,
     ending: false,
     ledgerNoticed: false,
 };
@@ -68,10 +74,28 @@ const session = {
 function __resetSessionForTests() {
     session.totalCalls = 0;
     session.toolNames.clear();
+    session.wrapped.clear();
+    session.id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
     session.reported = false;
+    session.rosterWritten = false;
     session.ending = false;
     session.ledgerNoticed = false;
 }
+/**
+ * Write down what this run WRAPPED, so the screen has a denominator: 23 wrapped, 4 called, 19
+ * that never ran. The set is already in hand at wrap time and was previously thrown away.
+ *
+ * ⚠️ ONLY WHEN A CALL WAS RECORDED, which is a deliberate limit and not an oversight.
+ * `appendRoster` refuses to create the ledger, so a process that wraps tools and calls none
+ * leaves no file behind, exactly as before this shipped. The denominator is only meaningful
+ * beside a numerator, and `audit` already has an honest empty screen for the other case.
+ */
+function writeRoster() {
+    if (session.rosterWritten || !session.wrapped.size || session.totalCalls === 0)
+        return;
+    session.rosterWritten = true;
+    (0, ledger_1.appendRoster)({ k: "roster", ts: Date.now(), session: session.id, tools: [...session.wrapped] });
+}
 /** TEST ONLY. The counters as the pulse will see them. */
 function __sessionStatsForTests() {
     return stats();
@@ -101,19 +125,59 @@ function printReport() {
     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}`);
+    printSessionNovelty();
     stderr(rule);
 }
+/**
+ * ONE LINE saying how much is new, and NOT the block itself.
+ *
+ * 🔴 IT USED TO PRINT THE WHOLE BLOCK, AND A FOUNDER WALK IS WHAT KILLED THAT. The common path
+ * is run the agent, then read the report. On that path the exit line printed four novelty lines
+ * and `audit` printed the same four again, immediately below. Correct by design and tiresome to
+ * read.
+ *
+ * A COUNT AND A POINTER KEEPS BOTH PROPERTIES THE TWO MARKS EXIST FOR. Nothing is eaten: this
+ * screen advances only its OWN mark, so `audit` still has the whole thing to say. And nothing is
+ * repeated, because the detail only ever lives in one place. Collapsing to a single shared mark
+ * would have removed the repetition too, by reintroducing the bug the two marks prevent.
+ *
+ * Wrapped whole in a try/catch and bounded to the same cheap read `audit` does. This runs while
+ * someone else's program is exiting: a novelty line is a nicety, and it must never be the reason
+ * a run ends badly.
+ */
+function printSessionNovelty() {
+    try {
+        const read = (0, ledger_1.readLedger)();
+        if (!read.readable || !read.rows.length)
+            return;
+        const marks = (0, novelty_1.noveltyPath)();
+        const novelty = (0, novelty_1.readNovelty)("session", read.rows, marks);
+        // The wording lives in novelty.ts as a pure function, because this call site is inside an
+        // exit hook where no test can read what it printed.
+        const line = (0, novelty_1.sessionNoveltyLine)(novelty);
+        if (!line)
+            return;
+        stderr(line);
+        // Only after the line is actually out. See the note in novelty.ts on not consuming a read.
+        (0, novelty_1.advanceMark)("session", novelty.current, marks);
+    }
+    catch {
+        /* a novelty line is never worth a broken exit */
+    }
+}
 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;
+    writeRoster();
     printReport();
     (0, ledger_1.trimLedger)();
     await pulse.onSessionEnd(stats());
 }
 function onExit() {
+    writeRoster();
     printReport();
     if (!session.ending) {
         // process.exit() skipped beforeExit, so nothing async can run now: queue the counts and
@@ -149,9 +213,55 @@ function record(name, args, description, opts) {
     };
     const file = (0, ledger_1.ledgerPath)();
     const { created } = (0, ledger_1.appendCall)(row, file);
+    // 🔴 KEYED ON LEDGER CREATION, AND AN ATTEMPT TO WIDEN THAT WAS REVERTED. Someone upgrading
+    // from a version that wrote no mark file already has a ledger, so `created` is false for them
+    // forever and they are never told about `.agentx-novelty.json`. The fix tried was to also fire
+    // when the MARK file is absent. That is worse: the mark is written only by `advanceMark` at
+    // session exit, only when a novelty line was non-empty, and `saveMarkFile` swallows write
+    // errors. A process killed with SIGKILL, a read-only directory, or several processes sharing a
+    // directory then print this notice on EVERY run, turning a first-run line into a nag. Inferring
+    // "already told" from a file a different code path may never write is the defect, not the
+    // wording. Creation of the ledger is the one event that happens exactly once, so it stays.
+    //
+    // The upgrading reader is covered in prose instead: both READMEs name this file and say to
+    // ignore it, and `published-surface.test.ts` reddens if either stops. Founder call 2026-09-09.
     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.`);
+        // NAMES BOTH FILES. The novelty mark sits beside the ledger, so a developer who followed this
+        // notice exactly still found an untracked `.agentx-novelty.json` in `git status`, or committed
+        // one. A notice that lists some of what we write is worse than none, because it reads as all.
+        //
+        // 🔴 A GITIGNORE LINE IS A PATTERN, NOT A PATH, AND THIS WENT WRONG IN BOTH DIRECTIONS BEFORE
+        // SETTLING HERE. First it printed the two default constants, which ignored a moved ledger and
+        // named a file that was not there. The fix for that printed the RESOLVED ABSOLUTE paths, which
+        // is worse: git anchors any pattern containing a slash to the .gitignore's own directory, so
+        // an absolute path matches nothing and both files stay tracked, and on Windows the separator
+        // is a backslash, which git reads as an escape. The common case was broken to serve a rare one.
+        //
+        // The basename of each real path is right in both cases: `.agentx-calls.jsonl` by default, and
+        // the moved ledger's own name when someone moved it. It is DERIVED rather than retyped from
+        // LEDGER_FILE / NOVELTY_FILE on purpose -- a constant repeated here would be a second copy of
+        // the same fact, free to drift, which is the defect class this whole file keeps paying for.
+        // 🔴 BOTH FILES ON THE UNCONDITIONAL LINE. Naming the novelty file only on the gitignore
+        // line meant that once that line became conditional, a developer whose ledger sits outside
+        // the folder was told about one of the two files we write. "A notice that lists some of what
+        // we write is worse than none" was already the rule three fixes ago; making another line
+        // conditional quietly broke it, and the guard that should have caught it had been weakened.
+        stderr(`[agentx] recording wrapped tool calls to ${file} (tool and argument NAMES, never values).`);
+        stderr(`[agentx] it also keeps ${(0, novelty_1.noveltyPath)()}, which remembers what you have already seen.`);
+        // 🔴 NO .gitignore ADVICE HERE, AND THE ABSENCE IS THE DECISION. Four attempts at that one
+        // line were each wrong in a different way: the default constants ignored a moved ledger;
+        // absolute paths are not valid gitignore patterns at all, so both files stayed tracked; a
+        // bare basename ignores nothing when the file sits outside the folder AND matches at every
+        // depth, so it can untrack an unrelated `calls.jsonl` someone wants committed; and making
+        // the line conditional left the novelty file named nowhere in the suppressed case.
+        //
+        // Four wrong answers to "what pattern should we print" is not a run of bad luck, it is the
+        // question being wrong. We do not know the reader's repository root, whether this folder is
+        // even in a repository, or which of several `.gitignore` files would apply. The two lines
+        // above say exactly what we do know: which files we write and where. What to do about them
+        // is the developer's call, and the READMEs cover the ordinary case in prose, where a wrong
+        // guess costs a sentence rather than a silently untracked file. Founder call 2026-09-08.
     }
 }
 /**
@@ -166,6 +276,10 @@ function agentxWatch(tool, opts = {}) {
         return tool;
     const original = tool.execute;
     const name = opts.name ?? (typeof tool.name === "string" && tool.name ? tool.name : "(unnamed)");
+    try {
+        session.wrapped.add(name);
+    }
+    catch { /* the roster is never worth a failed wrap */ }
     const description = typeof tool.description === "string" ? tool.description : undefined;
     const execute = function (...callArgs) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentx-core/security-sdk",
-  "version": "0.1.0",
+  "version": "0.2.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)",