signafaide 0.2.1 → 0.3.0

package/README.md

@@ -74,6 +74,35 @@ const list = wrapTools([lookupOrder, refund]);        // array
 
 None of them is a dependency: `wrapTools` recognises the objects by their shape.
 
+## Recording everything an agent can call
+
+Wrapping records the tools you wrap. Two things cover the rest: the gateway records every MCP tool call with no wrapper at all, and a tool declaration says in the chain which tools the agent has and which of them are recorded.
+
+MCP tools: the gateway. In the agent's MCP configuration, start the gateway in place of the server:
+
+```json
+{"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "support-bot", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]}
+```
+
+It runs the server, relays every message unchanged, declares the server's tools as recorded, and writes a `decision` before each `tools/call` is forwarded and an `outcome` when the answer arrives. A call that cannot be recorded is not forwarded. `--strict` (or `--strict-tools a,b`) forwards a call only once the witness has co-signed its decision; `--name-prefix github.` keeps the tool names of several servers apart; `--store-content` sends inputs and outputs too. A remote (HTTP) server goes behind a stdio bridge such as [`mcp-remote`](https://github.com/geelen/mcp-remote):
+
+```bash
+npx -y signafaide gateway --agent support-bot -- npx -y mcp-remote https://mcp.example.com/mcp
+```
+
+Framework tools: tool declarations. `wrapTools` declares the tools it wraps as recorded, with the first recorded call. Give the full list of the tools your code hands the agent, and the ones you did not wrap are declared as not recorded:
+
+```ts
+import { declareTools, wrapTools } from "signafaide";
+
+const tools = wrapTools({ refund, lookupOrder }, { agent: "support-bot" });
+declareTools(["refund", "lookupOrder", "web_search"], { agent: "support-bot" }); // web_search is not wrapped
+```
+
+`signafaide verify` then has a coverage line for each agent: `all 3 declared tools are recorded`, or `1 declared tool is not recorded: web_search`, or that no tool list was declared. It is a note, never a failure. A declaration is one signed note for the list and one for each tool in the agent's chain, so n tools are n + 1 records, counted like every other record, each time a process starts or the list changes. `{ declareTools: false }` or `SIGNAFAIDE_DECLARE_TOOLS=0` turns off the one `wrapTools` writes.
+
+What this shows, and what it does not. The gateway records every call that goes through it; a call the application makes around it is still not recorded, so the deployment has to make the gateway the only route to those tools. A declaration is the program's own signed statement of its tools: evidence of what it said it had, not proof that the list is complete. A tool list is as fresh as its last declaration: a source that stops (a gateway that is removed, a program that ends) leaves the list at its clean exit, or within 24 hours after a crash.
+
 ## Strict mode: no receipt, no action
 
 ```ts
@@ -181,6 +210,7 @@ The chain is verified first; then each recorded decision with a co-signed outcom
 | `signafaide compare --module file.mjs:fn [--agent X] [--name N] [--from T] [--to T] [--limit N] [--upload [--values]]` | re-runs recorded decisions with a candidate and compares; `--values` sends the values too (stored-content decisions only) |
 | `signafaide claim` | prints the claim link again |
 | `signafaide flush` | ships the outbox now (with no key it sends nothing and says so) |
+| `signafaide gateway [--agent X] [--name-prefix P] [--strict \| --strict-tools a,b] [--store-content] -- <command> [args...]` | runs an MCP server behind a recording proxy: every tool call that passes through is recorded, and one that cannot be recorded is not forwarded (see "Recording everything an agent can call") |
 | `signafaide agent setup [--agent <name>]... [--url <witness>] [--dry-run] [--dir <project>]` | installs the MCP server and the skill in your coding agents; `--url` sets `SIGNAFAIDE_URL` in each MCP entry |
 | `signafaide mcp` | runs the MCP server over stdio, when the separate `signafaide-mcp` package is installed (`agent setup` configures `npx -y signafaide-mcp@<version>` instead) |
 
@@ -208,7 +238,7 @@ The MCP tools: `signafaide_setup` (a preview that changes, creates and sends not
 Every request carries one header:
 
 ```
-X-Signafaide-Client: signafaide-js/0.2.1 (node 22.22.0; adapter=vercel-ai; agent=cursor; via=sdk)
+X-Signafaide-Client: signafaide-js/0.3.0 (node 22.22.0; adapter=vercel-ai; agent=cursor; via=sdk)
 ```
 
 It holds the SDK and its version, the JavaScript runtime and its version, and the framework adapter in use (`langchain`, `openai-agents`, `vercel-ai` or `none`). It also holds the coding agent that set the project up (`claude-code`, `codex`, `cursor`, `gemini-cli`, `copilot`, `windsurf` or `unknown`) and how the call was made (`sdk`, `cli` or `mcp`). The agent is found from that tool's environment variables when the project is set up (`signafaide init`, `signafaide agent setup`) and kept in `.signafaide/config.json`; it is never guessed per process, so a program started from a terminal inside a coding agent is not labelled as that agent. `signafaide verify` and `signafaide export` also send `POST /v1/events {"name": "verify"}` (or `"export"`) when there is an API key. If that fails, the command is not affected. With no API key nothing at all is sent.
@@ -228,6 +258,7 @@ The header and the events hold no content, file paths, hostnames or user names.
 | `SIGNAFAIDE_EXIT_FLUSH_MS` | `3000`: the longest a finished program is kept open to send; `0` never |
 | `SIGNAFAIDE_TEST` | test mode is on by itself under Vitest, Jest and `node --test` (records in a temporary folder, nothing sent); `1` forces it, `0` turns it off |
 | `SIGNAFAIDE_DISABLED` | `1`: wrapped functions run and nothing is recorded |
+| `SIGNAFAIDE_DECLARE_TOOLS` | `0`: `wrapTools` does not declare the tools it wraps (`declareTools()` still does) |
 | `SIGNAFAIDE_SEGMENT_BYTES` | `67108864`: a shipped chain file larger than this rolls into a sealed segment |
 | `SIGNAFAIDE_TELEMETRY` | `0` turns off the adapter, agent and strict fields and the events |
 

package/dist/{chunk-MBXHRQ2J.js → chunk-6UDL5LZL.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-S2RSID5F.js";
+} from "./chunk-DRRRZNIH.js";
 
 // src/jcs.ts
 var LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
@@ -546,6 +546,72 @@ function manifestErrors(doc) {
   return [];
 }
 
+// src/plural.ts
+var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+// src/coverage.ts
+var TOOLS = "signafaide.tools";
+var TOOL_PREFIX = "signafaide.tool/";
+var TOOL_UNRECORDED_PREFIX = "signafaide.tool_unrecorded/";
+var RESERVED_PREFIX = "signafaide.";
+var MAX_DECLARED_NAME = 101;
+var KEPT = MAX_DECLARED_NAME - 9;
+function declaredName(tool) {
+  const chars = [...tool];
+  if (chars.length <= MAX_DECLARED_NAME) return tool;
+  return `${chars.slice(0, KEPT).join("")}~${sha256Hex(new TextEncoder().encode(tool)).slice(0, 8)}`;
+}
+function toolNoteName(tool, recorded) {
+  return (recorded ? TOOL_PREFIX : TOOL_UNRECORDED_PREFIX) + declaredName(tool);
+}
+function toolNote(kind, name) {
+  if (kind !== "note" || typeof name !== "string") return null;
+  if (name === TOOLS) return "header";
+  const recorded = name.startsWith(TOOL_PREFIX);
+  if (!recorded && !name.startsWith(TOOL_UNRECORDED_PREFIX)) return null;
+  const rest = name.slice((recorded ? TOOL_PREFIX : TOOL_UNRECORDED_PREFIX).length);
+  return rest ? { name: rest, recorded } : null;
+}
+function byCodePoint(a, b) {
+  const [x, y] = [[...a], [...b]];
+  for (let i = 0; i < x.length && i < y.length; i++) {
+    const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+    if (d) return d;
+  }
+  return x.length - y.length;
+}
+function coverage(records) {
+  let at = null;
+  let tools = /* @__PURE__ */ new Map();
+  const called = /* @__PURE__ */ new Set();
+  for (const { seq, kind, name } of records) {
+    const t = toolNote(kind, name);
+    if (t === "header") {
+      at = seq;
+      tools = /* @__PURE__ */ new Map();
+    } else if (t) {
+      if (at !== null) tools.set(t.name, t.recorded);
+    } else if (kind === "decision" && typeof name === "string" && !name.startsWith(RESERVED_PREFIX)) called.add(declaredName(name));
+  }
+  if (at === null) return { declared: [], undeclared_recorded: [], declared_at_seq: null };
+  return {
+    declared: [...tools.keys()].sort(byCodePoint).map((name) => ({ name, recorded: tools.get(name) })),
+    undeclared_recorded: [...called].filter((n) => !tools.has(n)).sort(byCodePoint),
+    declared_at_seq: at
+  };
+}
+var countIs = (n, one) => `${plural(n, one)} ${n === 1 ? "is" : "are"}`;
+function coverageLines(agent, c) {
+  if (c.declared_at_seq === null) return [`${agent}: no tool list was declared, so the pack cannot show which of the agent's tools are recorded`];
+  const unrecorded = c.declared.filter((t) => !t.recorded).map((t) => t.name);
+  const out = [];
+  if (!c.declared.length) out.push(`${agent}: the declared tool list is empty`);
+  else if (!unrecorded.length) out.push(`${agent}: ${c.declared.length === 1 ? "the" : "all"} ${countIs(c.declared.length, "declared tool")} recorded`);
+  else out.push(`${agent}: ${countIs(unrecorded.length, "declared tool")} not recorded: ${unrecorded.join(", ")}`);
+  if (c.undeclared_recorded.length) out.push(`${agent}: ${countIs(c.undeclared_recorded.length, "recorded tool")} not in the declared tool list: ${c.undeclared_recorded.join(", ")}`);
+  return out;
+}
+
 // src/ots.ts
 import { ripemd160, sha1 } from "@noble/hashes/legacy";
 import { sha256 as sha2562 } from "@noble/hashes/sha2";
@@ -768,11 +834,6 @@ function rootsFromVector(m) {
 
 // src/verifier.ts
 import { hexToBytes as hexToBytes3 } from "@noble/hashes/utils";
-
-// src/plural.ts
-var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
-
-// src/verifier.ts
 var CHECKS = [
   ["schema", "Envelope schema"],
   ["record_hash", "Record hashes"],
@@ -901,6 +962,9 @@ var Report = class {
   notSent = 0;
   /** The project's name from the signed export statement, when the pack has one. */
   projectName = null;
+  /** Tool coverage per agent (§7; per chain for local state): the agent's current tool
+   * declaration and the recorded tools it does not list. A note, never a failure. */
+  coverage = {};
   /** e.g. `PASS: export of every agent, all records, generated <t>`, or
    * `PASS (agent keys taken from the pack, not independent): export of ...` (§7). */
   get resultLine() {
@@ -924,6 +988,11 @@ var Report = class {
   firstFailed() {
     return this.checks.find((c) => c.status === "fail")?.id ?? null;
   }
+  /** Tool coverage in words (§7), agent by agent: what each agent declared, then the recorded
+   * tools its declaration does not list. */
+  coverageLines() {
+    return Object.entries(this.coverage).flatMap(([agent, c]) => coverageLines(agent, c));
+  }
   lines() {
     const out = [...this.notes];
     if (this.project && this.env) {
@@ -939,6 +1008,7 @@ var Report = class {
       if (c.failures.length > 20) out.push(`      ... and ${c.failures.length - 20} more`);
     }
     if (this.checks.some((c) => c.status === "pending")) out.push(PENDING_MEANS);
+    out.push(...this.coverageLines().map((l) => `coverage: ${l}`));
     out.push(...this.after);
     out.push(...this.blocked.map((b) => `BLOCKED ${b}`));
     out.push(this.resultLine);
@@ -961,6 +1031,7 @@ var Report = class {
       independent: this.independent,
       notes: this.notes,
       checks: this.checks,
+      coverage: this.coverage,
       ...this.after.length ? { not_yet: this.after } : {},
       ...this.blocked.length ? { blocked: this.blocked } : {}
     };
@@ -1089,6 +1160,7 @@ function verifyPack(pack, serviceKeys, opts = {}) {
     byService
   });
   report.projectName = typeof pack.project_name === "string" ? pack.project_name : null;
+  report.coverage = v.coverage;
   return report;
 }
 function earliest(a, b) {
@@ -1102,6 +1174,7 @@ function verifyLocalState(local, serviceKeys, drand = null, serviceKeysPlainHttp
   const checks = v.run(local.records, [], local.chainIds);
   const report = new Report(checks, null, null, local.records.length, [], [], { service_keys: !serviceKeysPlainHttp, agent_keys: true });
   report.nothingCosigned = v.nothingCosigned;
+  report.coverage = v.coverage;
   return report;
 }
 var isU64 = (x) => typeof x === "number" && Number.isInteger(x) && x >= 0;
@@ -1232,6 +1305,8 @@ var Verifier = class {
   firstKey = /* @__PURE__ */ new Map();
   drafts = 0;
   nothingCosigned = false;
+  /** Tool coverage per chain (§7), filled by `run`. */
+  coverage = {};
   /** Local state: chain id -> the witness's signed head a chain continues after (§8). */
   localBases = {};
   /** A chain may start after seq 1 only when the export's from is after the agent's first key. */
@@ -1418,6 +1493,11 @@ var Verifier = class {
     if (starts.length) acc.notes.push(`${INSTANCE_NOTE}: ${starts.join(", ")}`);
     if (clean.length) acc.notes.push(`${CLEAN_RESTART_NOTE}: ${clean.join(", ")}`);
     if (based.length) acc.notes.push(`continues after a co-signed record this machine does not hold: ${based.join(", ")} (the witness's signed head, see signed heads)`);
+    for (const agent of [...chains.keys()].sort()) {
+      const chain = chains.get(agent);
+      const seqs = [...chain.keys()].sort((x, y) => x - y);
+      this.coverage[agent] = coverage(seqs.map((seq) => ({ seq, kind: chain.get(seq).r.envelope.kind, name: chain.get(seq).r.envelope.name })));
+    }
     return chains;
   }
   // 5
@@ -1882,6 +1962,16 @@ export {
   registration,
   manifestEntry,
   manifestErrors,
+  TOOLS,
+  TOOL_PREFIX,
+  TOOL_UNRECORDED_PREFIX,
+  MAX_DECLARED_NAME,
+  declaredName,
+  toolNoteName,
+  toolNote,
+  byCodePoint,
+  coverage,
+  coverageLines,
   DEFAULT_TIMESTAMP_URL,
   target,
   checkHeader,

package/dist/{chunk-S2RSID5F.js → chunk-DRRRZNIH.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 
 // src/telemetry.ts
 var HEADER = "X-Signafaide-Client";