signafaide-mcp 0.2.1 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ The signafAIde MCP server for coding agents, over stdio. It is a separate packag
 the SDK's version:
 
 ```json
-{"command": "npx", "args": ["-y", "signafaide-mcp@0.2.1"]}
+{"command": "npx", "args": ["-y", "signafaide-mcp@0.3.0"]}
 ```
 
 Tools: `signafaide_setup` (previews the install command and code edit, changes nothing),
@@ -15,4 +15,20 @@ Tools: `signafaide_setup` (previews the install command and code edit, changes n
 (creates the external sandbox; call it only after the user has agreed, with
 `confirm_user_agreed: true` and `user_words`, what the user wrote; without both it creates nothing).
 
+## Recording everything an agent can call
+
+The setup this server previews has two parts beyond wrapping tools. The MCP servers the
+application's own agent uses are started through the gateway of the `signafaide` package,
+`npx -y signafaide gateway --agent <name> -- <the server's command>`, which records every tool
+call that passes through it and forwards none it cannot record. And the program gives the full
+list of the tools it hands the agent, with `declareTools([...])` (TypeScript) or
+`signafaide.declare_tools([...])` (Python), so `signafaide_verify` can say which of the agent's
+tools are recorded.
+
+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 statement of its tools, not proof that the list is complete. A
+tool list is as fresh as its last declaration: a source that stops leaves the list at its clean
+exit, or within 24 hours after a crash.
+
 Apache-2.0. Source: the `js/` folder of the signafAIde SDK repository.

package/dist/{chunk-T43S3SPH.js → chunk-2NXHIOEZ.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";

package/dist/{chunk-YVYCQPVG.js → chunk-AZJ6Z2QX.js}

@@ -7,7 +7,7 @@ import {
   clientHeader,
   detectAgent,
   telemetryEnabled
-} from "./chunk-T43S3SPH.js";
+} from "./chunk-2NXHIOEZ.js";
 
 // src/mcp.ts
 import * as fs6 from "fs";
@@ -641,6 +641,8 @@ function fsError(e, home) {
   }
   return e;
 }
+var TOOL_SOURCE_REFRESH_MS = 36e5;
+var TOOL_SOURCE_MAX_AGE_MS = 864e5;
 var LOCK_STALE_MS = 1e4;
 var LOCK_WAIT_MS = 15e3;
 var PENDING = "_pending";
@@ -1241,18 +1243,97 @@ var State = class _State {
    * and put `wire(record)` in the outbox. Returns null when `stillValid()` is false once
    * the lock is held (the chain was just moved under its project; resolve it again). */
   append(chain, build, wire, stillValid = () => true) {
+    return this.appendRun(chain, [build], wire, stillValid)?.[0] ?? null;
+  }
+  /** `append` for several records that must follow each other with nothing between them (a tool
+   * declaration, §2.6): all of them are built and written under one hold of the chain lock, in
+   * one write, so no other writer's record lands inside the run. */
+  appendRun(chain, builds, wire, stillValid = () => true) {
     this.ensure();
     return this.lock(chain, () => {
       if (!stillValid()) return null;
-      const [seq, prev, prevTime] = this.tail(chain);
-      const rec = build(seq + 1, prev, prevTime);
+      let [seq, prev, prevTime] = this.tail(chain);
+      const recs = [];
+      for (const build of builds) {
+        const rec = build(seq + 1, prev, prevTime);
+        recs.push(rec);
+        [seq, prev, prevTime] = [rec.envelope.seq, recordHash(rec), rec.envelope.time];
+      }
+      try {
+        fs.appendFileSync(this.chainPath(chain), recs.map((r) => canonicalize(r) + "\n").join(""));
+      } catch (e) {
+        throw fsError(e, this.home);
+      }
+      for (const rec of recs) if (!rec.draft) this.writeOutbox(chain, wire(rec));
+      return recs;
+    });
+  }
+  // --- tool declarations --------------------------------------------------------
+  /** `tools/<agent>.json` (§8): the tools each source (the SDK in an application, each gateway)
+   * last declared for the agent. */
+  toolsPath(agent) {
+    return path.join(this.home, "tools", `${agent}.json`);
+  }
+  /** The tools every source last declared for `agent`: source -> {tool name: recorded}. */
+  toolSources(agent) {
+    return Object.fromEntries(Object.entries(this.toolEntries(agent)).map(([src, e]) => [src, e.tools]));
+  }
+  /** The entries of `tools/<agent>.json`: source -> when it last declared or refreshed, and its tools. */
+  toolEntries(agent) {
+    const doc = readJson(this.toolsPath(agent));
+    const out = {};
+    const sources = doc?.sources;
+    if (!sources || typeof sources !== "object" || Array.isArray(sources)) return out;
+    for (const [src, entry] of Object.entries(sources)) {
+      const tools = entry?.tools;
+      if (!tools || typeof tools !== "object" || Array.isArray(tools)) continue;
+      out[src] = { at: typeof entry.at === "string" ? entry.at : "", tools: Object.fromEntries(Object.entries(tools).filter(([, v]) => typeof v === "boolean")) };
+    }
+    return out;
+  }
+  /** A source that ends cleanly takes its own entry out of `tools/<agent>.json`, so the next
+   * declaration by any source no longer counts its tools (§8). Nothing is written to the chain. */
+  releaseToolSource(agent, source) {
+    const file = this.toolsPath(agent);
+    if (!fs.existsSync(file)) return;
+    this.lockAt(path.join(this.home, "tools", `${agent}.lock`), () => {
+      const entries = this.toolEntries(agent);
+      if (!(source in entries)) return;
+      delete entries[source];
+      writeJson(file, { sources: entries });
+    });
+  }
+  /** Set the tools `source` declares for `agent` and call `write` with the agent's whole tool
+   * list: the union over every source, a tool recorded when any source records it (§8). Held
+   * under `tools/<agent>.lock`, so two sources never write declarations that miss each other's
+   * tools. The source's own entry gets the time `nowMs`; another source's entry not refreshed for
+   * `TOOL_SOURCE_MAX_AGE_MS` is dropped (that source has stopped), and `expired` tells `write`
+   * whether dropping changed the agent's tool list. The file is updated only when `write` returns. */
+  declareTools(agent, source, tools, write, nowMs = Date.now()) {
+    this.ensure();
+    const file = this.toolsPath(agent);
+    return this.lockAt(path.join(this.home, "tools", `${agent}.lock`), () => {
+      const union = (entries) => {
+        const all2 = {};
+        for (const src of Object.keys(entries).sort()) for (const [name, recorded] of Object.entries(entries[src].tools)) all2[name] = all2[name] === true || recorded;
+        return all2;
+      };
+      const sorted = (all2) => JSON.stringify(Object.keys(all2).sort().map((n) => [n, all2[n]]));
+      const held = { ...this.toolEntries(agent), [source]: { at: new Date(nowMs).toISOString(), tools } };
+      const live = Object.fromEntries(
+        Object.entries(held).filter(([src, e]) => {
+          const at = Date.parse(e.at);
+          return src === source || Number.isFinite(at) && nowMs - at <= TOOL_SOURCE_MAX_AGE_MS;
+        })
+      );
+      const all = union(live);
+      const out = write(all, sorted(all) !== sorted(union(held)));
       try {
-        fs.appendFileSync(this.chainPath(chain), canonicalize(rec) + "\n");
+        writeJson(file, { sources: live });
       } catch (e) {
         throw fsError(e, this.home);
       }
-      if (!rec.draft) this.writeOutbox(chain, wire(rec));
-      return rec;
+      return out;
     });
   }
   writeOutbox(chain, rec) {
@@ -1555,6 +1636,69 @@ function wireOf(rec, store) {
   return out;
 }
 
+// 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/runtime.ts
 var BATCH_MAX = 1e3;
 var KEY_MAX_AGE_MS = 7 * 864e5 - 36e5;
@@ -1587,6 +1731,9 @@ var Recorder = class {
   /** Agents this process wrote records for since its last stop note. */
   wrote = /* @__PURE__ */ new Set();
   toldStrict = false;
+  /** `<agent>\n<source>` -> the tool set this recorder last declared for it (§2.6), and the header's hash. */
+  declared = /* @__PURE__ */ new Map();
+  toolTimer;
   /** @internal */
   _url;
   /** @internal */
@@ -1808,32 +1955,39 @@ ${scope}`;
   /** Sign and chain one record locally (synchronous) and queue it for shipping.
    * The chain is this API key's `<project>/<env>/<agent>` (§8). */
   write(kind, name, content, opts = {}) {
+    return this.writeRun([{ kind, name, content, ref: opts.ref }], opts)[0];
+  }
+  /** `write` for records that must follow each other with nothing between them (a tool
+   * declaration, §2.6): they are signed and appended under one hold of the chain lock. */
+  writeRun(items, opts = {}) {
     const why = noWrites.getStore();
-    if (why) throw new SignafaideError(`${why} must not write records: candidate functions must be side-effect free (it tried to record "${name}")`, { code: "no_writes" });
+    if (why) throw new SignafaideError(`${why} must not write records: candidate functions must be side-effect free (it tried to record "${items[0]?.name}")`, { code: "no_writes" });
     const agent = opts.agent || this.defaultAgent;
     if (!AGENT_RE.test(agent)) throw new Error(`agent "${agent}" is invalid: use lowercase letters, digits, '.', '_' or '-' (max 64)`);
     const sc = opts.storeContent ?? this.storeContent;
     const apiKey = this.apiKey;
-    let rec = null;
-    while (!rec) {
+    let recs = null;
+    while (!recs) {
       const bucket = this.writeBucket(apiKey, agent);
       const scope = scopeOf(bucket);
       const key = this.key(agent, scope);
       const chain = `${bucket}/${agent}`;
       if (!fs2.existsSync(this.state.chainPath(chain))) for (const e of Object.values(this.adoptInto(bucket, apiKey))) this.report(`signafaide: ${e.message}`);
       const [project, env] = bucket.split("/");
-      const build = bucket.startsWith(PENDING + "/") ? (seq, prev, prevTime) => {
-        const [time, c] = this.timed(content, prevTime, agent, scope);
-        return makeDraft(key, { kind, agent, seq, prev, name, content: c, ref: opts.ref ?? null, time }, sc);
-      } : (seq, prev, prevTime) => {
-        const [time, c] = this.timed(content, prevTime, agent, scope);
-        return makeRecord(key, { kind, project, env, agent, seq, prev, name, content: c, ref: this.state.translateRef(chain, opts.ref), time });
-      };
-      rec = this.state.append(chain, build, (r) => wireRecord(r, sc), () => this.writeBucket(apiKey, agent) === bucket);
+      const builds = items.map(
+        ({ kind, name, content, ref }) => bucket.startsWith(PENDING + "/") ? (seq, prev, prevTime) => {
+          const [time, c] = this.timed(content, prevTime, agent, scope);
+          return makeDraft(key, { kind, agent, seq, prev, name, content: c, ref: ref ?? null, time }, sc);
+        } : (seq, prev, prevTime) => {
+          const [time, c] = this.timed(content, prevTime, agent, scope);
+          return makeRecord(key, { kind, project, env, agent, seq, prev, name, content: c, ref: this.state.translateRef(chain, ref), time });
+        }
+      );
+      recs = this.state.appendRun(chain, builds, (r) => wireRecord(r, sc), () => this.writeBucket(apiKey, agent) === bucket);
     }
-    this.pending++;
+    this.pending += recs.length;
     this.exitFlushed = false;
-    if (name !== INSTANCE_STOP) this.wrote.add(agent);
+    if (items.some((i) => i.name !== INSTANCE_STOP)) this.wrote.add(agent);
     if (!apiKey && !this.toldLocal && !this.quiet && !this.test) {
       this.toldLocal = true;
       console.error(
@@ -1842,7 +1996,76 @@ ${scope}`;
     }
     this.start();
     if (this.pending >= this.flushSize) void this.tick();
-    return rec;
+    return recs;
+  }
+  /** Declare the tools one source knows for an agent (§2.6): a `signafaide.tools` note followed
+   * by one note per tool, written as one run. `source` names who declares (the SDK in this
+   * program, or one gateway); the notes list the agent's whole tool list, the union over every
+   * source that declared on this machine (§8 `tools/<agent>.json`), a tool recorded when any
+   * source records it. Written at most once per recorder for the same set: the first time, and
+   * again when the set changes. Returns the header's record hash. */
+  declareTools(tools, opts) {
+    const agent = opts.agent || this.defaultAgent;
+    if (!AGENT_RE.test(agent)) throw new Error(`agent "${agent}" is invalid: use lowercase letters, digits, '.', '_' or '-' (max 64)`);
+    const names = Object.keys(tools).sort(byCodePoint);
+    const bad = names.find((n) => !n || /[\u0000-\u001f\u007f]/.test(n));
+    if (bad !== void 0) throw new TypeError(`a tool name must be a non-empty string without control characters (got ${JSON.stringify(bad)})`);
+    const id = `${agent}
+${opts.source}`;
+    const sig = JSON.stringify(names.map((n) => [n, tools[n]]));
+    const held = this.declared.get(id);
+    const hash = this.state.declareTools(agent, opts.source, tools, (all, expired) => {
+      if (held?.sig === sig && !expired) return held.hash;
+      const byName = /* @__PURE__ */ new Map();
+      for (const [tool, recorded2] of Object.entries(all)) {
+        const d = declaredName(tool);
+        const prev = byName.get(d);
+        if (!prev || recorded2 && !prev.recorded) byName.set(d, { tool, recorded: recorded2 });
+      }
+      const list2 = [...byName.keys()].sort(byCodePoint).map((d) => byName.get(d));
+      const recorded = list2.filter((t) => t.recorded).length;
+      const items = [
+        { kind: "note", name: TOOLS, content: { source: opts.origin, tools: list2.length, recorded, unrecorded: list2.length - recorded } },
+        ...list2.map((t) => ({ kind: "note", name: toolNoteName(t.tool, t.recorded), content: { tool: t.tool, recorded: t.recorded } }))
+      ];
+      return recordHash(this.writeRun(items, { agent, storeContent: opts.storeContent })[0]);
+    });
+    this.declared.set(id, { sig, hash, agent, source: opts.source, origin: opts.origin, tools, storeContent: opts.storeContent });
+    if (!this.toolTimer && !this.closed) {
+      this.toolTimer = setInterval(() => this.refreshToolSources(), TOOL_SOURCE_REFRESH_MS);
+      this.toolTimer.unref?.();
+    }
+    return hash;
+  }
+  /** Refresh this recorder's entries in `tools/<agent>.json` (§8): each gets the current time,
+   * so other sources keep counting its tools, and entries of sources that stopped more than 24
+   * hours ago drop out. Nothing is written to the chain unless that changed the agent's tool
+   * list. Runs by itself once an hour while the process lives. Never throws. */
+  refreshToolSources() {
+    for (const d of [...this.declared.values()]) {
+      try {
+        this.declareTools(d.tools, { agent: d.agent, source: d.source, origin: d.origin, storeContent: d.storeContent });
+      } catch (e) {
+        this.report(`signafaide: could not refresh the tool list of ${d.agent}: ${e.message}`);
+      }
+    }
+  }
+  /** A clean end of this source (§8): its entries leave `tools/<agent>.json`, so the next
+   * declaration by any source no longer counts its tools. Nothing is written to the chain. With
+   * `source`, only that source ends (a gateway run inside another program). Never throws. */
+  releaseToolSources(source) {
+    for (const [id, d] of [...this.declared]) {
+      if (source !== void 0 && d.source !== source) continue;
+      try {
+        this.state.releaseToolSource(d.agent, d.source);
+      } catch {
+      }
+      this.declared.delete(id);
+    }
+    if (!this.declared.size && this.toolTimer) {
+      clearInterval(this.toolTimer);
+      this.toolTimer = void 0;
+    }
   }
   /** Where `agent`'s next record goes. A known project whose chain for `agent` is not on this
    * disk (an empty `SIGNAFAIDE_HOME` on Lambda or Cloud Run) may already have that chain on the
@@ -2262,10 +2485,22 @@ ${k.keyId}`;
   /** The program has nothing left to do: one last attempt, held open at most `exitFlushMs`.
    * Background requests never keep the process alive, so they are cut off here. */
   onBeforeExit = () => {
+    void this.exitAttempt();
+  };
+  /** The last attempt of a program that ends on its own schedule (the gateway, once its server
+   * has exited): what happens by itself when a program runs out of work. Ships what is left and,
+   * when stop notes are on, writes the signed stop note, all within `exitFlushMs`; then stops the
+   * background timer. Never throws. */
+  async shutdown() {
+    await this.exitAttempt();
+    this.releaseToolSources();
+    this.close();
+  }
+  exitAttempt() {
     const stop = this.instanceStop && this.wrote.size > 0 && !this.test;
-    if (this.exitFlushed || !this.exitFlushMs || !this.apiKey || !this.waiting() && !stop) return;
+    if (this.exitFlushed || !this.exitFlushMs || !this.apiKey || !this.waiting() && !stop) return void 0;
     this.exitFlushed = true;
-    if (this.halted && this.halted.fp === this.configFp()) return;
+    if (this.halted && this.halted.fp === this.configFp()) return void 0;
     this.bgAbort.abort();
     this.bgAbort = new AbortController();
     const ctrl = new AbortController();
@@ -2275,15 +2510,16 @@ ${k.keyId}`;
       clearTimeout(timer);
       this.exitFlushed = true;
     };
-    if (!stop) void this.flushLogged(this.exitFlushMs, "exit").finally(done);
-    else void this.stop(this.exitFlushMs, "exit").then((r) => {
+    if (!stop) return this.flushLogged(this.exitFlushMs, "exit").then(done, done);
+    return this.stop(this.exitFlushMs, "exit").then((r) => {
       const errs = Object.entries(r.errors);
       if (errs.length && !ctrl.signal.aborted) this.report("signafaide: " + errs.map(([a, e]) => e.message.includes(a) ? e.message : `${a}: ${e.message}`).join("; "));
     }, (e) => {
       if (!ctrl.signal.aborted) this.report(`signafaide: ${e.message}`);
-    }).finally(done);
-  };
+    }).then(done, done);
+  }
   onExit = () => {
+    this.releaseToolSources();
     const left = this.waiting();
     if (left && !this.quiet && this.apiKey) {
       console.error(`signafaide: ${plural(left, "record")} kept in ${path2.join(this.state.home, "outbox")}; they ship on the next run or with \`signafaide flush\``);
@@ -2292,6 +2528,8 @@ ${k.keyId}`;
   /** Stop the background timer and exit hooks (records stay in the outbox). */
   close() {
     this.closed = true;
+    if (this.toolTimer) clearInterval(this.toolTimer);
+    this.toolTimer = void 0;
     if (this.timer) clearInterval(this.timer);
     this.timer = void 0;
     this.bgAbort.abort();
@@ -2814,6 +3052,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() {
@@ -2837,6 +3078,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) {
@@ -2852,6 +3098,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);
@@ -2874,6 +3121,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 } : {}
     };
@@ -3002,6 +3250,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) {
@@ -3015,6 +3264,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;
@@ -3145,6 +3395,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. */
@@ -3331,6 +3583,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
@@ -3787,7 +4044,7 @@ async function readInput(src, flag) {
       }
       console.error(`WARNING: ${flag} ${src} uses plain http:// on this machine; the keys do not count as independent`);
     }
-    return parseJson(JSON.stringify(await (await import("./http-2GGI355E.js")).fetchJson(src)));
+    return parseJson(JSON.stringify(await (await import("./http-ME5BOUS6.js")).fetchJson(src)));
   }
   return parseJson(fs3.readFileSync(src, "utf8"));
 }
@@ -3941,7 +4198,8 @@ Use it when the user asks for an audit trail, tamper-evident records or complian
    A reason or choice that is not a tool call: \`signafaide.note("chose_escalation", {"reason": ...})\` (Python) or \`note(...)\` (TypeScript).
 
    Tools that move money, freeze or close accounts, delete data or send messages: wrap them in strict mode, \`wrap_tools([...], agent="claims-bot", strict=True)\` or \`wrapTools({...}, { agent: "claims-bot", strict: true })\`, so the tool runs only once the witness has co-signed its decision record, and not at all when it cannot be reached. Strict mode needs an API key: until a person opts in, a strict call fails with \`no_key\` and its tool does not run, so say so in your final message.
-3. Run the agent once, then \`signafaide verify\` (\`uv run signafaide verify\`, \`.venv/bin/signafaide verify\` or \`npx signafaide verify\`). It checks signatures, chain links and content hashes on this machine, and ends with a line such as \`PASS: 4 of 12 checks passed, 8 not checked (nothing co-signed yet)\`. The other checks need the witness.
+3. Record what you did not wrap. MCP servers the agent uses: start each one through the gateway in the agent's MCP configuration, \`{"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "claims-bot", "--", <the server's command and arguments>]}\`; it records every tool call that passes through it and forwards none it cannot record. Then give the full list of the tools your code hands the agent, once at start-up: \`signafaide.declare_tools(["approve_payout", "escalate", "web_search"], agent="claims-bot")\` (Python) or \`declareTools([...], { agent: "claims-bot" })\` (TypeScript). A tool you did not wrap is declared as not recorded, and \`signafaide verify\` names it. The gateway records only the calls that go through it, so make it the only route to those tools.
+4. Run the agent once, then \`signafaide verify\` (\`uv run signafaide verify\`, \`.venv/bin/signafaide verify\` or \`npx signafaide verify\`). It checks signatures, chain links and content hashes on this machine, and ends with a line such as \`PASS: 4 of 12 checks passed, 8 not checked (nothing co-signed yet)\`. The other checks need the witness.
 
 ## Sending records to the witness
 
@@ -4107,6 +4365,12 @@ var ERRORS = [
     means: "Strict mode: the decision got no receipt from the service, so the function did not run.",
     fix: "Fix the cause in the message (often `network`), then call again. Use strict mode only where an action must never run unrecorded."
   },
+  {
+    code: "not_written",
+    status: 0,
+    means: "The gateway could not write the decision record on this machine, so it did not forward the tool call to the MCP server (it fails closed).",
+    fix: "Fix the cause in the message, usually a folder that cannot be written: set SIGNAFAIDE_HOME to a writable folder for the gateway, then call the tool again."
+  },
   {
     code: "no_receipts",
     status: 0,
@@ -4386,7 +4650,8 @@ function steps(language, framework, install, verifyCmd) {
     snippet(language, framework),
     "```",
     "",
-    `3. Run the agent once so a wrapped function is called, then: ${verifyCmd} (or the signafaide_verify tool). Its last line must start with PASS.`
+    `3. Record what you did not wrap. For each MCP server the agent uses, start it through the gateway in the agent's MCP configuration: {"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "<agent name>", "--", <the server's command and arguments>]}. Then give the full list of the tools your code hands the agent, once at start-up: ${language === "python" ? 'signafaide.declare_tools(["tool_a", "tool_b"], agent="<agent name>")' : 'declareTools(["tool_a", "tool_b"], { agent: "<agent name>" })'}; a tool you did not wrap is declared as not recorded, and verify names it. The gateway records only the calls that go through it, so make it the only route to those tools.`,
+    `4. Run the agent once so a wrapped function is called, then: ${verifyCmd} (or the signafaide_verify tool). Its last line must start with PASS.`
   ].join("\n");
 }
 function createServer(root = process.cwd()) {

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   serve
-} from "./chunk-YVYCQPVG.js";
-import "./chunk-T43S3SPH.js";
+} from "./chunk-AZJ6Z2QX.js";
+import "./chunk-2NXHIOEZ.js";
 
 // src/mcp-bin.ts
 await serve();

package/dist/{http-2GGI355E.js → http-ME5BOUS6.js}

@@ -5,7 +5,7 @@ import {
   SignafaideError,
   fetchJson,
   fetchTransport
-} from "./chunk-T43S3SPH.js";
+} from "./chunk-2NXHIOEZ.js";
 export {
   Client,
   DEFAULT_URL,

package/dist/index.js

@@ -2,8 +2,8 @@ import {
   createServer,
   inside,
   serve
-} from "./chunk-YVYCQPVG.js";
-import "./chunk-T43S3SPH.js";
+} from "./chunk-AZJ6Z2QX.js";
+import "./chunk-2NXHIOEZ.js";
 export {
   createServer,
   inside,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signafaide-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The signafAIde MCP server for coding agents (Claude Code, Codex, Cursor, Gemini CLI, Copilot, Windsurf).",
   "license": "Apache-2.0",
   "type": "module",