signafaide 0.2.1 → 0.3.0

package/dist/{chunk-4C2JEYAU.js → chunk-P3GJDXSQ.js}

@@ -9,13 +9,16 @@ import {
   KeysRequired,
   MAX_CLOCK_SKEW_MS,
   SigningKey,
+  TOOLS,
   agentName,
   b64url,
   b64urlDecode,
+  byCodePoint,
   canonicalize,
   checkContent,
   clampTime,
   contentFromText,
+  declaredName,
   hashJson,
   instanceStartContent,
   instanceStopContent,
@@ -37,6 +40,7 @@ import {
   registration,
   signDraft,
   timestampHeights,
+  toolNoteName,
   useNativeCrypto,
   validProjectId,
   validTime,
@@ -45,7 +49,7 @@ import {
   verifySig,
   wireRecord,
   withWallTime
-} from "./chunk-MBXHRQ2J.js";
+} from "./chunk-6UDL5LZL.js";
 import {
   ADAPTERS,
   Client,
@@ -57,7 +61,7 @@ import {
   detectAgent,
   fetchJson,
   telemetryEnabled
-} from "./chunk-S2RSID5F.js";
+} from "./chunk-DRRRZNIH.js";
 
 // src/nodecrypto.ts
 import { createHash, createPublicKey, verify } from "crypto";
@@ -160,6 +164,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";
@@ -760,18 +766,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) {
@@ -1109,6 +1194,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 */
@@ -1330,32 +1418,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(
@@ -1364,7 +1459,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
@@ -1784,10 +1948,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();
@@ -1797,15 +1973,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\``);
@@ -1814,6 +1991,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();
@@ -1993,16 +2172,89 @@ function termsNotice(l) {
 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 })];
@@ -2056,7 +2308,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));
   };
@@ -2079,7 +2333,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");
@@ -2097,7 +2352,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");
@@ -2610,7 +2865,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-YWG535HP.js")).fetchJson(src)));
+    return parseJson(JSON.stringify(await (await import("./http-BZI6VZM3.js")).fetchJson(src)));
   }
   return parseJson(fs4.readFileSync(src, "utf8"));
 }
@@ -2731,6 +2986,8 @@ async function verify2(pack, opts = {}) {
 }
 
 export {
+  TOOL_SOURCE_REFRESH_MS,
+  TOOL_SOURCE_MAX_AGE_MS,
   StateError,
   findRoot,
   State,
@@ -2742,6 +2999,8 @@ export {
   configure,
   termsNotice,
   NotRecorded,
+  autoDeclareTools,
+  declareTools,
   record,
   note,
   wrapTools,