signafaide 0.2.1 → 0.3.0

package/dist/cli.js

@@ -6,19 +6,24 @@ import {
   configure,
   envOf,
   findRoot,
+  recordingDisabled,
   replay,
   termsNotice,
+  toJsonable,
   verify
-} from "./chunk-4C2JEYAU.js";
+} from "./chunk-P3GJDXSQ.js";
 import {
   KeysRequired,
-  plural
-} from "./chunk-MBXHRQ2J.js";
+  declaredName,
+  plural,
+  recordHash,
+  sha256Hex
+} from "./chunk-6UDL5LZL.js";
 import {
   SignafaideError,
   VERSION,
   detectAgent
-} from "./chunk-S2RSID5F.js";
+} from "./chunk-DRRRZNIH.js";
 
 // src/cli.ts
 import * as fs2 from "fs";
@@ -65,7 +70,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
 
@@ -354,6 +360,367 @@ function setup(opts) {
   return chosen.map(({ agent, reason }) => ({ agent: agent.id, reason, changes: agent.install(ctx), ...agent.note ? { note: agent.note } : {} }));
 }
 
+// src/gateway.ts
+import { spawn } from "child_process";
+import * as os2 from "os";
+var GATEWAY_ERROR = -32e3;
+var FORWARD = { forward: true };
+var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function idKey(id) {
+  return typeof id === "string" ? `s:${id}` : typeof id === "number" ? `n:${id}` : void 0;
+}
+function parse(line) {
+  const text = line.toString("utf8").trim();
+  if (!text || text[0] !== "{" && text[0] !== "[") return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function resultText(result) {
+  const parts = Array.isArray(result.content) ? result.content.filter((c) => isObject(c) && c.type === "text" && typeof c.text === "string").map((c) => c.text) : [];
+  return parts.join("\n").slice(0, 2e3) || "the tool reported an error";
+}
+function outcomeContent(answer) {
+  if (isObject(answer.error)) {
+    return { error: toJsonable({ type: "JsonRpcError", message: String(answer.error.message ?? "the server answered with an error"), code: answer.error.code ?? null }) };
+  }
+  const result = answer.result;
+  if (isObject(result) && result.isError === true) return { error: { type: "ToolError", message: resultText(result) }, output: toJsonable(result) };
+  return { output: toJsonable(result) ?? null };
+}
+function runGateway(opts) {
+  return new Gateway(opts).run();
+}
+var Gateway = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.input = opts.stdin ?? process.stdin;
+    this.out = opts.stdout ?? process.stdout;
+    this.err = opts.stderr ?? process.stderr;
+    this.prefix = opts.namePrefix ?? "";
+    this.strictTools = new Set(opts.strictTools ?? []);
+    this.source = `gateway:${this.prefix || sha256Hex(new TextEncoder().encode([opts.command, ...opts.args ?? []].join("\0"))).slice(0, 8)}`;
+    this.rec = opts.recorder ?? configure({ via: "gateway", storeContent: opts.storeContent });
+  }
+  opts;
+  rec;
+  input;
+  out;
+  err;
+  prefix;
+  source;
+  strictTools;
+  off = recordingDisabled();
+  child;
+  /** Client-to-server `tools/call` requests waiting for their answer, by id. Server-to-client
+   * requests have ids of their own and are never looked up here. */
+  calls = /* @__PURE__ */ new Map();
+  /** Client-to-server `tools/list` requests waiting for their answer, by id. */
+  lists = /* @__PURE__ */ new Map();
+  /** The listing the client is paging through, and the tools of the last one it finished. */
+  listing = null;
+  shown = null;
+  /** Answers held for a client batch whose other entries went on to the server, by their ids. */
+  held = /* @__PURE__ */ new Map();
+  /** Strict calls waiting for the witness. */
+  waiting = /* @__PURE__ */ new Set();
+  /** The shown tools changed since they were last declared. */
+  undeclared = false;
+  toldDeclare = false;
+  done = false;
+  diag(msg) {
+    this.err.write(`signafaide gateway: ${msg}
+`);
+  }
+  // --- relay --------------------------------------------------------------------------
+  toServer(data) {
+    const stdin = this.child.stdin;
+    if (!stdin || stdin.destroyed || stdin.writableEnded) return;
+    if (!stdin.write(data)) {
+      this.input.pause();
+      stdin.once("drain", () => this.input.resume());
+    }
+  }
+  toClient(data) {
+    if (!this.out.write(data)) {
+      this.child.stdout?.pause();
+      this.out.once("drain", () => this.child.stdout?.resume());
+    }
+  }
+  send(v, original) {
+    if ("forward" in v) this.toServer(Buffer.concat([original, NL]));
+    else if ("reply" in v) this.toClient(JSON.stringify(v.reply) + "\n");
+  }
+  error(id, message, code) {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code: GATEWAY_ERROR, message, data: { signafaide: code } } };
+  }
+  // --- client to server -----------------------------------------------------------------
+  fromClient(line) {
+    const msg = this.off ? void 0 : parse(line);
+    if (msg === void 0) return this.toServer(Buffer.concat([line, NL]));
+    if (Array.isArray(msg)) return this.clientBatch(msg, line);
+    const v = this.clientMessage(msg);
+    if (v instanceof Promise) this.later(v.then((got) => this.send(got, line)));
+    else this.send(v, line);
+  }
+  /** Keep a strict call's wait, so the server's stdin is not closed under it. */
+  later(p) {
+    const tracked = p.catch((e) => this.diag(`${e.message}`)).finally(() => this.waiting.delete(tracked));
+    this.waiting.add(tracked);
+  }
+  /** A batch: each entry is judged like a single message. Entries that may not run are taken
+   * out and answered here; their answers travel with the server's answer to the rest. */
+  clientBatch(msgs, line) {
+    const verdicts = msgs.map((m) => this.clientMessage(m));
+    const finish = (vs) => {
+      const forward = msgs.filter((_, i) => "forward" in vs[i]);
+      const replies = vs.flatMap((v) => "reply" in v ? [v.reply] : []);
+      if (forward.length === msgs.length) return this.toServer(Buffer.concat([line, NL]));
+      if (forward.length) this.toServer(JSON.stringify(forward) + "\n");
+      if (!replies.length) return;
+      const answered = forward.flatMap((m) => isObject(m) && typeof m.method === "string" && idKey(m.id) !== void 0 ? [idKey(m.id)] : []);
+      if (!answered.length) return this.toClient(JSON.stringify(replies) + "\n");
+      const group = { replies };
+      for (const k of answered) this.held.set(k, group);
+    };
+    if (verdicts.some((v) => v instanceof Promise)) this.later(Promise.all(verdicts).then(finish));
+    else finish(verdicts);
+  }
+  clientMessage(msg) {
+    if (!isObject(msg) || typeof msg.method !== "string") return FORWARD;
+    const key = idKey(msg.id);
+    if (msg.method === "tools/list" && key !== void 0) {
+      const cursor = isObject(msg.params) ? msg.params.cursor : void 0;
+      if (typeof cursor !== "string" || !cursor || !this.listing) this.listing = { names: /* @__PURE__ */ new Set(), complete: false };
+      this.lists.set(key, this.listing);
+    } else if (msg.method === "notifications/cancelled") {
+      this.cancelled(isObject(msg.params) ? msg.params : {});
+    } else if (msg.method === "tools/call") {
+      return this.call(msg, key);
+    }
+    return FORWARD;
+  }
+  call(msg, key) {
+    const params = isObject(msg.params) ? msg.params : {};
+    const tool = params.name;
+    if (typeof tool !== "string" || !tool) return FORWARD;
+    const full = this.prefix + tool;
+    const name = declaredName(full);
+    this.declareShown();
+    const meta = { sdk: `signafaide-js/${VERSION}`, gateway: true };
+    if (name !== tool) meta.tool = tool;
+    let decision;
+    try {
+      const content = { input: toJsonable(params.arguments) ?? null, meta };
+      decision = this.rec.write("decision", name, content, { agent: this.opts.agent, storeContent: this.opts.storeContent });
+    } catch (e) {
+      const why2 = e.message;
+      this.diag(`${tool} was not run because the call could not be recorded: ${why2}`);
+      return key === void 0 ? { drop: true } : { reply: this.error(msg.id, `signafaide gateway: ${tool} was not run because the call could not be recorded: ${why2}`, "not_written") };
+    }
+    if (key === void 0) return FORWARD;
+    const old = this.calls.get(key);
+    if (old && old.state !== "cancelled") this.outcome(old, { error: { type: "NoAnswer", message: "the client used this request id again before the server answered" } });
+    const call = { key, name, decision, state: "forwarded" };
+    this.calls.set(key, call);
+    if (!(this.opts.strict || this.strictTools.has(tool)) || this.rec.test) return FORWARD;
+    call.state = "waiting";
+    const gone = () => {
+      if (this.calls.get(key) === call) this.calls.delete(key);
+      return { drop: true };
+    };
+    return this.rec.ensureReceipt(decision).then(
+      () => {
+        if (call.state === "cancelled") return gone();
+        call.state = "forwarded";
+        return FORWARD;
+      },
+      (e) => {
+        const err2 = e instanceof SignafaideError ? e : new SignafaideError(e.message);
+        this.rec.warnStrictRefused(name, err2);
+        if (call.state === "cancelled") return gone();
+        this.calls.delete(key);
+        return { reply: this.error(msg.id, `${err2.message} (strict mode: ${name} did not run)`, err2.code) };
+      }
+    );
+  }
+  cancelled(params) {
+    const key = idKey(params.requestId);
+    const call = key === void 0 ? void 0 : this.calls.get(key);
+    if (!call || call.state === "cancelled") return;
+    const reason = typeof params.reason === "string" && params.reason ? `: ${params.reason.slice(0, 500)}` : "";
+    const when = call.state === "waiting" ? "before the call was forwarded to the server" : "before the server answered";
+    this.outcome(call, { error: { type: "Cancelled", message: `the client cancelled the call ${when}${reason}` } });
+    if (call.state === "waiting") call.state = "cancelled";
+    else this.calls.delete(call.key);
+  }
+  // --- server to client -----------------------------------------------------------------
+  fromServer(line) {
+    const msg = this.off ? void 0 : parse(line);
+    if (msg === void 0) return this.toClient(Buffer.concat([line, NL]));
+    const answers = (Array.isArray(msg) ? msg : [msg]).filter((m) => isObject(m) && typeof m.method !== "string" && idKey(m.id) !== void 0);
+    for (const m of answers) this.answer(m);
+    const groups = new Set(answers.flatMap((m) => this.held.has(idKey(m.id)) ? [this.held.get(idKey(m.id))] : []));
+    for (const m of answers) this.held.delete(idKey(m.id));
+    const extra = [...groups].flatMap((g) => g.replies.splice(0));
+    if (!extra.length) return this.toClient(Buffer.concat([line, NL]));
+    if (Array.isArray(msg)) return this.toClient(JSON.stringify([...msg, ...extra]) + "\n");
+    this.toClient(Buffer.concat([line, NL]));
+    this.toClient(JSON.stringify(extra) + "\n");
+  }
+  /** An answer from the server to a request of the client's. */
+  answer(m) {
+    const key = idKey(m.id);
+    const listing = this.lists.get(key);
+    if (listing) {
+      this.lists.delete(key);
+      this.listed(listing, m);
+    }
+    const call = this.calls.get(key);
+    if (call && call.state === "forwarded") {
+      this.calls.delete(key);
+      this.outcome(call, outcomeContent(m));
+    }
+  }
+  listed(listing, m) {
+    const result = m.result;
+    if (!isObject(result) || !Array.isArray(result.tools)) return;
+    for (const t of result.tools) if (isObject(t) && typeof t.name === "string" && t.name) listing.names.add(t.name);
+    this.undeclared = true;
+    if (typeof result.nextCursor === "string" && result.nextCursor) return;
+    listing.complete = true;
+    this.shown = listing.names;
+    this.declareShown();
+  }
+  /** Declare the tools the client has been shown: the last finished listing, with the pages of
+   * the one it is still paging through. Written once per distinct list (the recorder sees to
+   * that). A failure is reported once and never stops the relay. */
+  declareShown() {
+    const paging = this.listing && !this.listing.complete ? this.listing.names : null;
+    if (!this.undeclared || !this.shown && !paging?.size) return;
+    const tools = {};
+    for (const n of [...this.shown ?? [], ...paging ?? []]) tools[this.prefix + n] = true;
+    try {
+      this.rec.declareTools(tools, { agent: this.opts.agent, source: this.source, origin: "gateway", storeContent: this.opts.storeContent });
+      this.undeclared = false;
+    } catch (e) {
+      if (!this.toldDeclare) this.diag(`could not write the tool declaration: ${e.message}`);
+      this.toldDeclare = true;
+    }
+  }
+  outcome(call, content) {
+    try {
+      this.rec.write("outcome", call.name, content, { agent: call.decision.envelope.agent, ref: recordHash(call.decision), storeContent: this.opts.storeContent });
+    } catch (e) {
+      this.diag(`could not write the outcome of ${call.name}: ${e.message}`);
+    }
+  }
+  // --- life cycle -----------------------------------------------------------------------
+  run() {
+    return new Promise((resolve3) => {
+      const { command, args = [] } = this.opts;
+      if (this.off) this.diag("SIGNAFAIDE_DISABLED is set: relaying only, nothing is recorded");
+      const child = this.child = spawn(command, args, { stdio: ["pipe", "pipe", this.opts.stderr ? "pipe" : "inherit"], windowsHide: true, env: this.opts.env ?? process.env });
+      const signals = this.opts.forwardSignals === false ? [] : ["SIGINT", "SIGTERM", "SIGHUP"];
+      let killer;
+      const onSignal = (sig) => {
+        child.kill(sig);
+        killer ??= setTimeout(() => child.kill("SIGKILL"), this.opts.killAfterMs ?? 5e3);
+        killer.unref?.();
+      };
+      for (const s of signals) process.on(s, onSignal);
+      const finish = async (result, upstream) => {
+        if (this.done) return;
+        this.done = true;
+        clearTimeout(killer);
+        for (const s of signals) process.off(s, onSignal);
+        this.input.off("data", onInput);
+        this.input.off("end", onEnd);
+        this.input.pause();
+        await Promise.allSettled([...this.waiting]);
+        for (const call of [...this.calls.values()]) {
+          if (call.state !== "cancelled") this.outcome(call, { error: { type: "UpstreamExited", message: `${upstream} before it answered` } });
+        }
+        this.calls.clear();
+        if (!this.off) this.declareShown();
+        try {
+          this.rec.releaseToolSources(this.source);
+          if (!this.opts.recorder) await this.rec.shutdown();
+        } catch (e) {
+          this.diag(e.message);
+        }
+        if (this.out.writableLength && !this.out.destroyed) await new Promise((r) => this.out.write("", () => r()));
+        resolve3(result);
+      };
+      child.once("error", (e) => {
+        this.diag(`could not start ${command}: ${e.message}`);
+        void finish({ code: e.code === "ENOENT" ? 127 : e.code === "EACCES" ? 126 : 1, signal: null }, "the MCP server could not be started");
+      });
+      const guard = (what, fn) => {
+        try {
+          fn();
+        } catch (e) {
+          this.diag(`${what} dropped: ${e.message}`);
+        }
+      };
+      const clientLines = new Lines((l) => guard("a client message was", () => this.fromClient(l)));
+      const serverLines = new Lines((l) => guard("a server message was", () => this.fromServer(l)));
+      const onInput = (chunk) => clientLines.push(chunk);
+      const onEnd = () => {
+        guard("a client message was", () => clientLines.end((rest) => this.off ? this.toServer(rest) : this.fromClientTail(rest)));
+        void Promise.allSettled([...this.waiting]).then(() => child.stdin?.end());
+      };
+      this.input.on("data", onInput);
+      this.input.once("end", onEnd);
+      child.stderr?.on("data", (chunk) => this.err.write(chunk));
+      child.stdin?.on("error", () => void 0);
+      this.out.on("error", () => child.kill("SIGTERM"));
+      child.stdout?.on("data", (chunk) => serverLines.push(chunk));
+      child.once("close", (code, signal) => {
+        guard("a server message was", () => serverLines.end((rest) => this.toClient(rest)));
+        const how = signal ? `the MCP server was ended by ${signal}` : `the MCP server exited (code ${code ?? 0})`;
+        void finish({ code: code ?? 128 + (os2.constants.signals[signal] ?? 0), signal }, how);
+      });
+    });
+  }
+  /** A last client line with no newline: judged like any other, and sent without one. */
+  fromClientTail(rest) {
+    const msg = parse(rest);
+    const v = msg === void 0 || Array.isArray(msg) ? FORWARD : this.clientMessage(msg);
+    const put = (got) => {
+      if ("forward" in got) this.toServer(rest);
+      else if ("reply" in got) this.toClient(JSON.stringify(got.reply) + "\n");
+    };
+    if (v instanceof Promise) this.later(v.then(put));
+    else put(v);
+  }
+};
+var NL = Buffer.from("\n");
+var Lines = class {
+  constructor(onLine) {
+    this.onLine = onLine;
+  }
+  onLine;
+  buf = Buffer.alloc(0);
+  push(chunk) {
+    this.buf = this.buf.length ? Buffer.concat([this.buf, Buffer.from(chunk)]) : Buffer.from(chunk);
+    let start = 0;
+    for (let i = this.buf.indexOf(10, start); i !== -1; i = this.buf.indexOf(10, start)) {
+      const line = this.buf.subarray(start, i);
+      start = i + 1;
+      this.onLine(line);
+    }
+    this.buf = this.buf.subarray(start);
+  }
+  /** What is left when the stream ends: a last line without a newline. */
+  end(onRest) {
+    if (this.buf.length) onRest(this.buf);
+    this.buf = Buffer.alloc(0);
+  }
+};
+
 // src/cli.ts
 var out = (s) => console.log(s);
 var err = (s) => console.error(s);
@@ -716,6 +1083,33 @@ var COMMANDS = {
       return 0;
     }
   },
+  gateway: {
+    help: "run an MCP server behind a recording proxy: every tool call that passes through it is recorded (a decision before the call is forwarded, an outcome when the answer arrives), and the server's tools are declared as the agent's recorded tools",
+    usage: 'gateway [--agent X] [--name-prefix P] [--strict | --strict-tools a,b] [--store-content] -- <command> [args...]\n  In the agent\'s MCP configuration, start the gateway in place of the server: {"command": "npx", "args": ["-y", "signafaide", "gateway", "--agent", "support-bot", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]}\n  --agent: the agent\'s chain name (default: the project folder\'s name)\n  --name-prefix: put before each recorded tool name, for an agent with several servers (--name-prefix github.)\n  --strict: forward a call only once the witness has co-signed its decision; --strict-tools a,b: only for those tools\n  --store-content: send inputs and outputs to the witness too (default: hash-only)\n  A remote (HTTP) server: put a stdio bridge after the --, for example `signafaide gateway -- npx -y mcp-remote https://mcp.example.com/mcp`\n  A call that cannot be recorded is not forwarded. 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.\n  Nothing is sent until the project has run `signafaide init` or has an API key. Only protocol messages go to stdout; diagnostics go to stderr.',
+    options: { agent: { type: "string" }, "name-prefix": { type: "string" }, strict: { type: "boolean" }, "strict-tools": { type: "string" }, "store-content": { type: "boolean" } },
+    async run(v, pos) {
+      if (!pos.length) {
+        err(`usage: signafaide ${(COMMANDS.gateway.usage ?? "").split("\n")[0]}`);
+        return 2;
+      }
+      const r = await runGateway({
+        command: pos[0],
+        args: pos.slice(1),
+        agent: v.agent,
+        namePrefix: v["name-prefix"],
+        strict: !!v.strict,
+        strictTools: typeof v["strict-tools"] === "string" ? v["strict-tools"].split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+        storeContent: v["store-content"] ? true : void 0
+      });
+      if (r.signal) {
+        try {
+          process.kill(process.pid, r.signal);
+        } catch {
+        }
+      }
+      return r.code;
+    }
+  },
   flush: {
     help: "ship the outbox now",
     async run() {
@@ -753,6 +1147,7 @@ function help() {
   const width = Math.max(...Object.keys(COMMANDS).map((c) => c.length));
   return ["usage: signafaide <command> [options]", "", ...Object.entries(COMMANDS).map(([c, d]) => `  ${c.padEnd(width)}  ${d.help}`)].join("\n");
 }
+var EXIT_WHEN_DONE = /* @__PURE__ */ new Set(["gateway"]);
 async function main(argv = process.argv.slice(2)) {
   const [name, ...rest] = argv;
   if (name === "--version" || name === "-v") {
@@ -764,7 +1159,8 @@ async function main(argv = process.argv.slice(2)) {
     (name && name !== "--help" && name !== "-h" ? err : out)(help());
     return name && name !== "--help" && name !== "-h" ? 1 : 0;
   }
-  if (rest.includes("--help") || rest.includes("-h")) {
+  const own = rest.includes("--") ? rest.slice(0, rest.indexOf("--")) : rest;
+  if (own.includes("--help") || own.includes("-h")) {
     out(`${cmd.help}
 usage: signafaide ${cmd.usage ?? name}`);
     return 0;
@@ -790,4 +1186,5 @@ usage: signafaide ${cmd.usage ?? name}`);
 // src/bin.ts
 main().then((code) => {
   process.exitCode = code;
+  if (EXIT_WHEN_DONE.has(process.argv[2])) process.exit(code);
 });

package/dist/{core-BMfko_ex.d.ts → core-BTJGPYVW.d.cts}

@@ -300,6 +300,62 @@ declare class Client {
 /** GET a JSON document (used for `--keys <url>`). */
 declare function fetchJson(url: string, timeoutMs?: number): Promise<any>;
 
+/**
+ * Tool declarations (SPEC §2.6) and the coverage they give (§7): which of an agent's tools are
+ * recorded, read from envelopes alone (kind, name, seq), so it holds for hash-only records.
+ * Pure: no I/O. The same names, rules and wording as the Rust core and the Python SDK.
+ *
+ * Coverage is a note, never a failure, and never a claim of completeness: a declaration is the
+ * client's own signed statement of the tools the agent has.
+ */
+/** The name of the note that starts a new tool declaration for the agent's chain. */
+declare const TOOLS = "signafaide.tools";
+/** `signafaide.tool/<tool name>`: the agent has this tool and calls to it are recorded. */
+declare const TOOL_PREFIX = "signafaide.tool/";
+/** `signafaide.tool_unrecorded/<tool name>`: the agent has this tool and calls to it are not recorded. */
+declare const TOOL_UNRECORDED_PREFIX = "signafaide.tool_unrecorded/";
+/** The longest tool name a declaration holds as it is, in characters (Unicode code points): an
+ * envelope name is at most 128 and the longer prefix takes 27. */
+declare const MAX_DECLARED_NAME = 101;
+/** A tool's name as a declaration holds it: the name itself when it has at most 101 characters,
+ * else its first 92 characters, `~`, and the first 8 hex characters of sha256(UTF-8 tool name).
+ * A name that is already short maps to itself. */
+declare function declaredName(tool: string): string;
+/** The envelope name of the note that declares `tool`. */
+declare function toolNoteName(tool: string, recorded: boolean): string;
+/** What a record says about the agent's tool list, from its kind and name alone: `"header"`,
+ * a tool, or null when it is not a tool-declaration note. */
+declare function toolNote(kind: unknown, name: unknown): "header" | {
+    name: string;
+    recorded: boolean;
+} | null;
+interface DeclaredTool {
+    name: string;
+    recorded: boolean;
+}
+/** What one agent's records show about its tools (§7 tool coverage). */
+interface Coverage {
+    /** The tools of the agent's current declaration, in name order; empty when there is none. */
+    declared: DeclaredTool[];
+    /** The names of decision records that are not in the current declaration, in name order. */
+    undeclared_recorded: string[];
+    /** The seq of the `signafaide.tools` note that starts the current declaration, or null. */
+    declared_at_seq: number | null;
+}
+/** The coverage of one agent's records, given in seq order. The current declaration is the one
+ * started by the last `signafaide.tools` note; tool notes before the first such note belong to a
+ * declaration the records do not hold and are ignored. Inside a declaration a later note for the
+ * same tool replaces an earlier one. A `decision` counts as a recorded tool unless its name
+ * starts with `signafaide.`; it is compared by its declared name. */
+declare function coverage(records: Iterable<{
+    seq: number;
+    kind: unknown;
+    name: unknown;
+}>): Coverage;
+/** The coverage of `agent` in words (§7), one line each: what was declared, then the recorded
+ * tools the declaration does not list. */
+declare function coverageLines(agent: string, c: Coverage): string[];
+
 declare const MAX_PROOF_BYTES = 65536;
 declare const MAX_NODES = 1024;
 type Attestation = ({
@@ -460,6 +516,9 @@ declare class Report {
     notSent: number;
     /** The project's name from the signed export statement, when the pack has one. */
     projectName: string | 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: Record<string, Coverage>;
     constructor(checks: Check[], project?: string | null, env?: string | null, records?: number, warnings?: string[], notes?: string[], independent?: {
         service_keys: boolean;
         agent_keys: boolean;
@@ -471,6 +530,9 @@ declare class Report {
     get result(): "PASS" | "FAIL" | "BLOCKED";
     check(id: CheckId): Check;
     firstFailed(): CheckId | null;
+    /** Tool coverage in words (§7), agent by agent: what each agent declared, then the recorded
+     * tools its declaration does not list. */
+    coverageLines(): string[];
     lines(): string[];
     toString(): string;
     toJSON(): object;
@@ -585,6 +647,6 @@ declare function clientHeader(opts?: {
     env?: Env;
 }): string;
 
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.3.0";
 
-export { countsText as $, type AgentKeyEntry as A, type BlockHeader as B, Client as C, DEFAULT_TIMESTAMP_URL as D, type Envelope as E, b64urlDecode as F, blockAttestations as G, HEADER as H, blockHeader as I, JsonNumber as J, type Kind as K, type LocalContent as L, MAX_NODES as M, NOT_INDEPENDENT as N, canonicalBytes as O, type PackFilter as P, canonicalize as Q, type Receipt as R, SigningKey as S, checkContent as T, checkHeader as U, VERSION as V, checkRoundTime as W, clampTime as X, clientHeader as Y, contentFromText as Z, contentHash as _, type SignedRecord as a, detectAgent as a0, draftErrors as a1, envelopeErrors as a2, exportStatement as a3, fetchJson as a4, hashJson as a5, isLoopbackUrl as a6, keyEntryErrors as a7, keyId as a8, leafHash as a9, signedMessage as aA, target as aB, telemetryEnabled as aC, timestampHeights as aD, validProjectId as aE, validTime as aF, verifyInclusion as aG, verifyLocalState as aH, verifyPack as aI, verifySig as aJ, wireRecord as aK, withWallTime as aL, loadDrandVerifier as aa, lookupTimestamps as ab, makeDraft as ac, makeRecord as ad, manifestEntry as ae, manifestErrors as af, merkleRoot as ag, newSalt as ah, now as ai, otsStatus as aj, parseAgentKeys as ak, parseHeadFile as al, parseJson as am, parseOts as an, parseServiceKeys as ao, receiptErrors as ap, recordErrors as aq, recordHash as ar, recordsHash as as, registration as at, resultLine as au, rootsFromVector as av, scopeText as aw, serviceKeysHash as ax, sha256Hex as ay, signDraft as az, SignafaideError as b, Report as c, type KeyDoc as d, AGENT_RE as e, ANCHOR_WINDOW_MS as f, type BlockRoots as g, CHECKS as h, type Check as i, type CheckId as j, DEFAULT_URL as k, type Domain as l, type DrandBeacon as m, type DrandVerifier as n, type KeySource as o, KeysRequired as p, MAX_PROOF_BYTES as q, MAX_ROUND as r, type PackOptions as s, type RecordFields as t, type SignedHeadDoc as u, type Status as v, agentName as w, assertPortableNumbers as x, auditPath as y, b64url as z };
+export { checkHeader as $, type AgentKeyEntry as A, type BlockHeader as B, Client as C, DEFAULT_TIMESTAMP_URL as D, type Envelope as E, TOOL_UNRECORDED_PREFIX as F, agentName as G, HEADER as H, assertPortableNumbers as I, JsonNumber as J, type Kind as K, type LocalContent as L, MAX_DECLARED_NAME as M, NOT_INDEPENDENT as N, auditPath as O, type PackFilter as P, b64url as Q, type Receipt as R, SigningKey as S, TOOLS as T, b64urlDecode as U, VERSION as V, blockAttestations as W, blockHeader as X, canonicalBytes as Y, canonicalize as Z, checkContent as _, type SignedRecord as a, checkRoundTime as a0, clampTime as a1, clientHeader as a2, contentFromText as a3, contentHash as a4, countsText as a5, coverage as a6, coverageLines as a7, declaredName as a8, detectAgent as a9, recordHash as aA, recordsHash as aB, registration as aC, resultLine as aD, rootsFromVector as aE, scopeText as aF, serviceKeysHash as aG, sha256Hex as aH, signDraft as aI, signedMessage as aJ, target as aK, telemetryEnabled as aL, timestampHeights as aM, toolNote as aN, toolNoteName as aO, validProjectId as aP, validTime as aQ, verifyInclusion as aR, verifyLocalState as aS, verifyPack as aT, verifySig as aU, wireRecord as aV, withWallTime as aW, draftErrors as aa, envelopeErrors as ab, exportStatement as ac, fetchJson as ad, hashJson as ae, isLoopbackUrl as af, keyEntryErrors as ag, keyId as ah, leafHash as ai, loadDrandVerifier as aj, lookupTimestamps as ak, makeDraft as al, makeRecord as am, manifestEntry as an, manifestErrors as ao, merkleRoot as ap, newSalt as aq, now as ar, otsStatus as as, parseAgentKeys as at, parseHeadFile as au, parseJson as av, parseOts as aw, parseServiceKeys as ax, receiptErrors as ay, recordErrors as az, SignafaideError as b, Report as c, type KeyDoc as d, AGENT_RE as e, ANCHOR_WINDOW_MS as f, type BlockRoots as g, CHECKS as h, type Check as i, type CheckId as j, type Coverage as k, DEFAULT_URL as l, type DeclaredTool as m, type Domain as n, type DrandBeacon as o, type DrandVerifier as p, type KeySource as q, KeysRequired as r, MAX_NODES as s, MAX_PROOF_BYTES as t, MAX_ROUND as u, type PackOptions as v, type RecordFields as w, type SignedHeadDoc as x, type Status as y, TOOL_PREFIX as z };