signafaide 0.2.1 → 0.3.0

package/dist/index.cjs

@@ -35,7 +35,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.2.1";
+    VERSION = "0.3.0";
   }
 });
 
@@ -248,6 +248,7 @@ __export(src_exports, {
   HEADER: () => HEADER,
   JsonNumber: () => JsonNumber,
   KeysRequired: () => KeysRequired,
+  MAX_DECLARED_NAME: () => MAX_DECLARED_NAME,
   MAX_NODES: () => MAX_NODES,
   MAX_PROOF_BYTES: () => MAX_PROOF_BYTES,
   MAX_ROUND: () => MAX_ROUND,
@@ -260,11 +261,17 @@ __export(src_exports, {
   SigningKey: () => SigningKey,
   State: () => State,
   StateError: () => StateError,
+  TOOLS: () => TOOLS,
+  TOOL_PREFIX: () => TOOL_PREFIX,
+  TOOL_SOURCE_MAX_AGE_MS: () => TOOL_SOURCE_MAX_AGE_MS,
+  TOOL_SOURCE_REFRESH_MS: () => TOOL_SOURCE_REFRESH_MS,
+  TOOL_UNRECORDED_PREFIX: () => TOOL_UNRECORDED_PREFIX,
   VERSION: () => VERSION,
   VerificationFailed: () => VerificationFailed,
   agentName: () => agentName,
   assertPortableNumbers: () => assertPortableNumbers,
   auditPath: () => auditPath,
+  autoDeclareTools: () => autoDeclareTools,
   b64url: () => b64url,
   b64urlDecode: () => b64urlDecode,
   blockAttestations: () => blockAttestations,
@@ -282,6 +289,10 @@ __export(src_exports, {
   contentFromText: () => contentFromText,
   contentHash: () => contentHash,
   countsText: () => countsText,
+  coverage: () => coverage,
+  coverageLines: () => coverageLines,
+  declareTools: () => declareTools,
+  declaredName: () => declaredName,
   detectAgent: () => detectAgent,
   draftErrors: () => draftErrors,
   envelopeErrors: () => envelopeErrors,
@@ -337,6 +348,8 @@ __export(src_exports, {
   testMode: () => testMode,
   timestampHeights: () => timestampHeights,
   toJsonable: () => toJsonable,
+  toolNote: () => toolNote,
+  toolNoteName: () => toolNoteName,
   validProjectId: () => validProjectId,
   validTime: () => validTime,
   verify: () => verify3,
@@ -1468,6 +1481,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";
@@ -2068,18 +2083,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), canonicalize(rec) + "\n");
+        fs.appendFileSync(this.chainPath(chain), recs.map((r) => canonicalize(r) + "\n").join(""));
       } catch (e) {
         throw fsError(e, this.home);
       }
-      if (!rec.draft) this.writeOutbox(chain, wire(rec));
-      return rec;
+      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 {
+        writeJson(file, { sources: live });
+      } catch (e) {
+        throw fsError(e, this.home);
+      }
+      return out;
     });
   }
   writeOutbox(chain, rec) {
@@ -2384,6 +2478,71 @@ function wireOf(rec, store) {
 
 // src/runtime.ts
 init_telemetry();
+
+// 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;
 var LOCAL_CODES = /* @__PURE__ */ new Set(["too_old", "chain_exists"]);
@@ -2418,6 +2577,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 */
@@ -2639,32 +2801,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(
@@ -2673,7 +2842,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 list = [...byName.keys()].sort(byCodePoint).map((d) => byName.get(d));
+      const recorded = list.filter((t) => t.recorded).length;
+      const items = [
+        { kind: "note", name: TOOLS, content: { source: opts.origin, tools: list.length, recorded, unrecorded: list.length - recorded } },
+        ...list.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
@@ -3093,10 +3331,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 stop2 = this.instanceStop && this.wrote.size > 0 && !this.test;
-    if (this.exitFlushed || !this.exitFlushMs || !this.apiKey || !this.waiting() && !stop2) return;
+    if (this.exitFlushed || !this.exitFlushMs || !this.apiKey || !this.waiting() && !stop2) 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();
@@ -3106,15 +3356,16 @@ ${k.keyId}`;
       clearTimeout(timer);
       this.exitFlushed = true;
     };
-    if (!stop2) void this.flushLogged(this.exitFlushMs, "exit").finally(done);
-    else void this.stop(this.exitFlushMs, "exit").then((r) => {
+    if (!stop2) 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\``);
@@ -3123,6 +3374,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();
@@ -3651,6 +3904,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() {
@@ -3674,6 +3930,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) {
@@ -3689,6 +3950,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);
@@ -3711,6 +3973,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 } : {}
     };
@@ -3839,6 +4102,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) {
@@ -3852,6 +4116,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;
@@ -3982,6 +4247,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. */
@@ -4168,6 +4435,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
@@ -4592,16 +4864,89 @@ init_version();
 var NotRecorded = class extends SignafaideError {
   name = "NotRecorded";
 };
+var WRAPPED = /* @__PURE__ */ new Map();
+var LISTED = /* @__PURE__ */ new Map();
+var EXPLICIT = /* @__PURE__ */ new Map();
+var toolsVersion = 0;
+var checked = /* @__PURE__ */ new WeakMap();
+var toldDeclare = false;
+function autoDeclareTools(env = process.env) {
+  return !/^(0|false|no|off)$/i.test((env.SIGNAFAIDE_DECLARE_TOOLS ?? "").trim());
+}
+function remember(map, agent, name) {
+  const set = map.get(agent ?? "") ?? /* @__PURE__ */ new Set();
+  map.set(agent ?? "", set);
+  if (!set.has(name)) {
+    set.add(name);
+    toolsVersion++;
+  }
+}
+function namesFor(map, agent, isDefault) {
+  return /* @__PURE__ */ new Set([...map.get(agent) ?? [], ...isDefault ? map.get("") ?? [] : []]);
+}
+function ownTools(rec, agent) {
+  const isDefault = agent === rec.defaultAgent;
+  const explicit = EXPLICIT.get(agent) ?? (isDefault ? EXPLICIT.get("") : void 0);
+  if (explicit) {
+    const wrapped = namesFor(WRAPPED, agent, isDefault);
+    const tools = {};
+    for (const n of explicit.names) tools[n] = wrapped.has(n) && !explicit.unrecorded.has(n);
+    for (const n of explicit.unrecorded) tools[n] = false;
+    return [tools, "declared"];
+  }
+  const listed = namesFor(LISTED, agent, isDefault);
+  if (!listed.size || !autoDeclareTools()) return null;
+  return [Object.fromEntries([...listed].map((n) => [n, true])), "wrap_tools"];
+}
+function declareOwn(rec, agentOpt, storeContent) {
+  const agent = agentOpt || rec.defaultAgent;
+  const own = ownTools(rec, agent);
+  if (!own) return "";
+  return rec.declareTools(own[0], { agent, source: "sdk", origin: own[1], storeContent });
+}
+function declareBeforeCall(rec, agentOpt) {
+  const agent = agentOpt || rec.defaultAgent;
+  const seen = checked.get(rec) ?? /* @__PURE__ */ new Map();
+  checked.set(rec, seen);
+  if (seen.get(agent) === toolsVersion || noWrites.getStore()) return;
+  try {
+    declareOwn(rec, agentOpt);
+    seen.set(agent, toolsVersion);
+  } catch (e) {
+    seen.set(agent, toolsVersion);
+    if (!toldDeclare) {
+      toldDeclare = true;
+      console.error(`signafaide: could not write the tool declaration for ${agent}: ${e.message}`);
+    }
+  }
+}
+function declareTools(names, opts = {}) {
+  const list = [...names];
+  const unrecorded = [...opts.unrecorded ?? []];
+  for (const n of [...list, ...unrecorded]) if (typeof n !== "string" || !n) throw new TypeError("declareTools needs tool names: non-empty strings");
+  EXPLICIT.set(opts.agent ?? "", { names: list, unrecorded: new Set(unrecorded) });
+  toolsVersion++;
+  if (recordingDisabled()) return "";
+  const rec = getRecorder();
+  const hash = declareOwn(rec, opts.agent);
+  const seen = checked.get(rec) ?? /* @__PURE__ */ new Map();
+  checked.set(rec, seen);
+  seen.set(opts.agent || rec.defaultAgent, toolsVersion);
+  return hash;
+}
 var Spec = class {
-  constructor(name, opts) {
+  constructor(name, opts, listed = false) {
     this.name = name;
     this.opts = opts;
     if (!name) throw new TypeError('record(fn) needs a name: record(fn, { name: "approve_payout" })');
+    remember(WRAPPED, opts.agent, name);
+    if (listed) remember(LISTED, opts.agent, name);
   }
   name;
   opts;
   decide(input) {
     const rec = getRecorder();
+    declareBeforeCall(rec, this.opts.agent);
     const meta = { sdk: `signafaide-js/${VERSION}`, ...this.opts.meta ?? {} };
     const content = { input: toJsonable(input) ?? null, meta: toJsonable(meta) };
     return [rec, rec.write("decision", this.name, content, { agent: this.opts.agent, storeContent: this.opts.storeContent })];
@@ -4655,7 +5000,9 @@ var Spec = class {
   }
 };
 function record(fn, opts = {}) {
-  const spec = new Spec(opts.name ?? fn.name, opts);
+  return recordWith(new Spec(opts.name ?? fn.name, opts), fn);
+}
+function recordWith(spec, fn) {
   const wrapped = function(...args) {
     return spec.call(args.length === 1 ? args[0] : args, () => fn.apply(this, args));
   };
@@ -4678,7 +5025,8 @@ var isOpenAIAgentsTool = (t) => t?.type === "function" && typeof t.invoke === "f
 var isLangChainTool = (t) => Array.isArray(t?.lc_namespace) && typeof t._call === "function" && typeof t.invoke === "function";
 function wrapTool(tool, opts = {}) {
   const t = tool;
-  const spec = (name) => new Spec(opts.name ?? name, opts);
+  const { declareTools: declare = true, ...ropts } = opts;
+  const spec = (name) => new Spec(ropts.name ?? name, ropts, declare);
   if (isOpenAIAgentsTool(t)) {
     const s = spec(t.name);
     ADAPTERS.add("openai-agents");
@@ -4696,7 +5044,7 @@ function wrapTool(tool, opts = {}) {
     };
     return proxy;
   }
-  if (typeof t === "function") return record(t, { ...opts, name: opts.name ?? t.name });
+  if (typeof t === "function") return recordWith(spec(t.name), t);
   if (typeof t?.execute === "function") {
     const s = spec(t.name ?? "");
     ADAPTERS.add("vercel-ai");
@@ -5342,6 +5690,7 @@ async function verify3(pack, opts = {}) {
   HEADER,
   JsonNumber,
   KeysRequired,
+  MAX_DECLARED_NAME,
   MAX_NODES,
   MAX_PROOF_BYTES,
   MAX_ROUND,
@@ -5354,11 +5703,17 @@ async function verify3(pack, opts = {}) {
   SigningKey,
   State,
   StateError,
+  TOOLS,
+  TOOL_PREFIX,
+  TOOL_SOURCE_MAX_AGE_MS,
+  TOOL_SOURCE_REFRESH_MS,
+  TOOL_UNRECORDED_PREFIX,
   VERSION,
   VerificationFailed,
   agentName,
   assertPortableNumbers,
   auditPath,
+  autoDeclareTools,
   b64url,
   b64urlDecode,
   blockAttestations,
@@ -5376,6 +5731,10 @@ async function verify3(pack, opts = {}) {
   contentFromText,
   contentHash,
   countsText,
+  coverage,
+  coverageLines,
+  declareTools,
+  declaredName,
   detectAgent,
   draftErrors,
   envelopeErrors,
@@ -5431,6 +5790,8 @@ async function verify3(pack, opts = {}) {
   testMode,
   timestampHeights,
   toJsonable,
+  toolNote,
+  toolNoteName,
   validProjectId,
   validTime,
   verify,