signafaide 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { S as SigningKey, a as SignedRecord, A as AgentKeyEntry, R as Receipt, b as SignafaideError, C as Client, K as Kind, E as Envelope, c as Report, d as KeyDoc, L as LocalContent } from './core-BMfko_ex.cjs';
-export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots, h as CHECKS, i as Check, j as CheckId, D as DEFAULT_TIMESTAMP_URL, k as DEFAULT_URL, l as Domain, m as DrandBeacon, n as DrandVerifier, H as HEADER, J as JsonNumber, o as KeySource, p as KeysRequired, M as MAX_NODES, q as MAX_PROOF_BYTES, r as MAX_ROUND, N as NOT_INDEPENDENT, P as PackFilter, s as PackOptions, t as RecordFields, u as SignedHeadDoc, v as Status, V as VERSION, w as agentName, x as assertPortableNumbers, y as auditPath, z as b64url, F as b64urlDecode, G as blockAttestations, I as blockHeader, O as canonicalBytes, Q as canonicalize, T as checkContent, U as checkHeader, W as checkRoundTime, X as clampTime, Y as clientHeader, Z as contentFromText, _ as contentHash, $ as countsText, a0 as detectAgent, a1 as draftErrors, a2 as envelopeErrors, a3 as exportStatement, a4 as fetchJson, a5 as hashJson, a6 as isLoopbackUrl, a7 as keyEntryErrors, a8 as keyId, a9 as leafHash, aa as loadDrandVerifier, ab as lookupTimestamps, ac as makeDraft, ad as makeRecord, ae as manifestEntry, af as manifestErrors, ag as merkleRoot, ah as newSalt, ai as now, aj as otsStatus, ak as parseAgentKeys, al as parseHeadFile, am as parseJson, an as parseOts, ao as parseServiceKeys, ap as receiptErrors, aq as recordErrors, ar as recordHash, as as recordsHash, at as registration, au as resultLine, av as rootsFromVector, aw as scopeText, ax as serviceKeysHash, ay as sha256Hex, az as signDraft, aA as signedMessage, aB as target, aC as telemetryEnabled, aD as timestampHeights, aE as validProjectId, aF as validTime, aG as verifyInclusion, aH as verifyLocalState, aI as verifyPack, aJ as verifySig, aK as wireRecord, aL as withWallTime } from './core-BMfko_ex.cjs';
+import { S as SigningKey, a as SignedRecord, A as AgentKeyEntry, R as Receipt, b as SignafaideError, C as Client, K as Kind, E as Envelope, c as Report, d as KeyDoc, L as LocalContent } from './core-BTJGPYVW.cjs';
+export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots, h as CHECKS, i as Check, j as CheckId, k as Coverage, D as DEFAULT_TIMESTAMP_URL, l as DEFAULT_URL, m as DeclaredTool, n as Domain, o as DrandBeacon, p as DrandVerifier, H as HEADER, J as JsonNumber, q as KeySource, r as KeysRequired, M as MAX_DECLARED_NAME, s as MAX_NODES, t as MAX_PROOF_BYTES, u as MAX_ROUND, N as NOT_INDEPENDENT, P as PackFilter, v as PackOptions, w as RecordFields, x as SignedHeadDoc, y as Status, T as TOOLS, z as TOOL_PREFIX, F as TOOL_UNRECORDED_PREFIX, V as VERSION, G as agentName, I as assertPortableNumbers, O as auditPath, Q as b64url, U as b64urlDecode, W as blockAttestations, X as blockHeader, Y as canonicalBytes, Z as canonicalize, _ as checkContent, $ as checkHeader, a0 as checkRoundTime, a1 as clampTime, a2 as clientHeader, a3 as contentFromText, a4 as contentHash, a5 as countsText, a6 as coverage, a7 as coverageLines, a8 as declaredName, a9 as detectAgent, aa as draftErrors, ab as envelopeErrors, ac as exportStatement, ad as fetchJson, ae as hashJson, af as isLoopbackUrl, ag as keyEntryErrors, ah as keyId, ai as leafHash, aj as loadDrandVerifier, ak as lookupTimestamps, al as makeDraft, am as makeRecord, an as manifestEntry, ao as manifestErrors, ap as merkleRoot, aq as newSalt, ar as now, as as otsStatus, at as parseAgentKeys, au as parseHeadFile, av as parseJson, aw as parseOts, ax as parseServiceKeys, ay as receiptErrors, az as recordErrors, aA as recordHash, aB as recordsHash, aC as registration, aD as resultLine, aE as rootsFromVector, aF as scopeText, aG as serviceKeysHash, aH as sha256Hex, aI as signDraft, aJ as signedMessage, aK as target, aL as telemetryEnabled, aM as timestampHeights, aN as toolNote, aO as toolNoteName, aP as validProjectId, aQ as validTime, aR as verifyInclusion, aS as verifyLocalState, aT as verifyPack, aU as verifySig, aV as wireRecord, aW as withWallTime } from './core-BTJGPYVW.cjs';
 
 /**
  * Local state in `.signafaide/` (SPEC §8). Node only. Same layout and formats as the Python SDK.
@@ -17,6 +17,7 @@ export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots
  * - `blocked.json`               chains the witness refused, with why (status, verify, replay)
  * - `outbox/<chain>/<seq>.json`  signed records not yet accepted by the service
  * - `head.json`                  newest signed head, `{project: {env: {agent: {head, head_sig}}}}`
+ * - `tools/<agent>.json`         the tools each source last declared for the agent (§2.6)
  * - `config.json`                coding agent; API key fingerprint -> {project, env}
  * - `sandbox.json`               the sandbox project and claim link
  *
@@ -34,6 +35,10 @@ interface ProvidedKey {
 }
 /** Returns an agent's key from a secret store, or undefined to use the key file. */
 type KeyProvider = (agent: string, scope: KeyScope) => ProvidedKey | string | undefined;
+/** A source refreshes its entry in `tools/<agent>.json` at least this often while it runs (§8). */
+declare const TOOL_SOURCE_REFRESH_MS = 3600000;
+/** An entry another source has not refreshed for this long is dropped: that source has stopped (§8). */
+declare const TOOL_SOURCE_MAX_AGE_MS = 86400000;
 /** Local state is unusable; the message says how to fix it. */
 declare class StateError extends Error {
     name: string;
@@ -195,6 +200,30 @@ declare 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: string, build: (seq: number, prev: string | null, prevTime: string | null) => SignedRecord, wire: (r: SignedRecord) => SignedRecord, stillValid?: () => boolean): SignedRecord | 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: string, builds: ((seq: number, prev: string | null, prevTime: string | null) => SignedRecord)[], wire: (r: SignedRecord) => SignedRecord, stillValid?: () => boolean): SignedRecord[] | null;
+    /** `tools/<agent>.json` (§8): the tools each source (the SDK in an application, each gateway)
+     * last declared for the agent. */
+    toolsPath(agent: string): string;
+    /** The tools every source last declared for `agent`: source -> {tool name: recorded}. */
+    toolSources(agent: string): Record<string, Record<string, boolean>>;
+    /** The entries of `tools/<agent>.json`: source -> when it last declared or refreshed, and its tools. */
+    toolEntries(agent: string): Record<string, {
+        at: string;
+        tools: Record<string, boolean>;
+    }>;
+    /** 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: string, source: string): void;
+    /** 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<T>(agent: string, source: string, tools: Record<string, boolean>, write: (all: Record<string, boolean>, expired: boolean) => T, nowMs?: number): T;
     private writeOutbox;
     private lines;
     /** Every line of a chain, drafts included (§8). */
@@ -331,6 +360,9 @@ declare class Recorder {
     /** Agents this process wrote records for since its last stop note. */
     private wrote;
     private toldStrict;
+    /** `<agent>\n<source>` -> the tool set this recorder last declared for it (§2.6), and the header's hash. */
+    private declared;
+    private toolTimer?;
     /** @internal */ _url?: string;
     /** @internal */ _apiKey?: string;
     /** `<agent>\n<scope>` -> [key, the key file's identity when loaded] */
@@ -413,6 +445,38 @@ declare class Recorder {
         ref?: string | null;
         storeContent?: boolean;
     }): SignedRecord;
+    /** `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: {
+        kind: Kind;
+        name: string;
+        content: Record<string, unknown>;
+        ref?: string | null;
+    }[], opts?: {
+        agent?: string;
+        storeContent?: boolean;
+    }): SignedRecord[];
+    /** 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: Record<string, boolean>, opts: {
+        agent?: string;
+        source: string;
+        origin: "gateway" | "wrap_tools" | "declared";
+        storeContent?: boolean;
+    }): string;
+    /** 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(): void;
+    /** 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?: string): void;
     /** 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
      * witness, so the record is a draft until the shipper has asked for the witness's head and
@@ -471,6 +535,12 @@ declare class Recorder {
     /** 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. */
     private onBeforeExit;
+    /** 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. */
+    shutdown(): Promise<void>;
+    private exitAttempt;
     private onExit;
     /** Stop the background timer and exit hooks (records stay in the outbox). */
     close(): void;
@@ -535,7 +605,8 @@ declare function getRecorder(): Recorder;
 /** Replace the default recorder (used by `init` and tests). */
 declare function configure(opts?: RecorderOptions): Recorder;
 
-/** `record`, `note` and `wrapTools`: the decision -> run -> outcome cycle. Node only. */
+/** `record`, `note`, `wrapTools` and `declareTools`: the decision -> run -> outcome cycle, and
+ * the agent's tool list (SPEC §2.6). Node only. */
 
 interface RecordOptions {
     /** Action or tool name. Defaults to the function's name. */
@@ -555,6 +626,24 @@ declare class NotRecorded extends SignafaideError {
     name: string;
 }
 type AnyFn = (...args: any[]) => any;
+/** `SIGNAFAIDE_DECLARE_TOOLS=0` turns off the declarations `wrapTools` writes by itself. */
+declare function autoDeclareTools(env?: NodeJS.ProcessEnv): boolean;
+interface DeclareOptions {
+    /** Agent chain name (default: the project folder name). */
+    agent?: string;
+    /** Tools of the agent that are known not to be wrapped: declared as not recorded. */
+    unrecorded?: Iterable<string>;
+}
+/**
+ * Declare the agent's full tool list (SPEC §2.6), so a verifier can say which of the agent's
+ * tools are recorded. A name is declared recorded when the SDK wrapped a tool of that name in
+ * this process (`record`, `wrapTools`, `wrapTool`), otherwise not recorded; `unrecorded` names
+ * tools that are not wrapped. The declaration is a signed note per tool in the agent's chain:
+ * it is evidence of what the program said its tools were, not proof that the list is complete.
+ * Written now, and again by itself when a tool of the list is wrapped later. Returns the hash of
+ * the `signafaide.tools` note ("" when recording is turned off).
+ */
+declare function declareTools(names: Iterable<string>, opts?: DeclareOptions): string;
 /**
  * Record every call of `fn`: a `decision` before it runs, an `outcome` after.
  * The decision's input is the single argument, or the argument list when there are
@@ -574,11 +663,15 @@ interface WrapOptions {
     agent?: string;
     strict?: boolean;
     storeContent?: boolean;
+    /** Declare the wrapped tools as the agent's recorded tools (SPEC §2.6), with the first
+     * recorded call. Default true; `SIGNAFAIDE_DECLARE_TOOLS=0` turns it off everywhere. */
+    declareTools?: boolean;
 }
 /**
  * Record every tool in an object (key = tool name) or an array. Accepts plain
  * functions, Vercel AI SDK tools (objects with `execute`), OpenAI Agents JS
- * function tools and LangChain.js tools. Returns the same shape.
+ * function tools and LangChain.js tools. Returns the same shape. The wrapped tools are
+ * declared as the agent's recorded tools (see `declareTools`) unless `declareTools: false`.
  */
 declare function wrapTools<T>(tools: T, opts?: WrapOptions): T;
 /** Record one tool. See `wrapTools`. */
@@ -895,4 +988,4 @@ declare function loadContent(src: string): Map<string, LocalContent>;
  */
 declare function verify(pack?: string | object | null, opts?: VerifyOptions): Promise<Report>;
 
-export { AgentKeyEntry, type Blocked, Client, type CompareOptions, Entry, Envelope, ExperimentReport, type ExperimentRow, type FlushResult, KeyDoc, Kind, NotRecorded, Receipt, type RecordOptions, Recorder, type RecorderOptions, Replay, type ReplayOptions, Report, SignafaideError, SignedRecord, SigningKey, State, StateError, type StopResult, VerificationFailed, type VerifyOptions, type WrapOptions, checkHeld, compare, configure, flush, getRecorder, init, loadContent, loadServiceKeys, notYet, note, record, recordedValue, recordingDisabled, replay, status, stop, testMode, toJsonable, verify, wrapTool, wrapTools };
+export { AgentKeyEntry, type Blocked, Client, type CompareOptions, type DeclareOptions, Entry, Envelope, ExperimentReport, type ExperimentRow, type FlushResult, KeyDoc, Kind, NotRecorded, Receipt, type RecordOptions, Recorder, type RecorderOptions, Replay, type ReplayOptions, Report, SignafaideError, SignedRecord, SigningKey, State, StateError, type StopResult, TOOL_SOURCE_MAX_AGE_MS, TOOL_SOURCE_REFRESH_MS, VerificationFailed, type VerifyOptions, type WrapOptions, autoDeclareTools, checkHeld, compare, configure, declareTools, flush, getRecorder, init, loadContent, loadServiceKeys, notYet, note, record, recordedValue, recordingDisabled, replay, status, stop, testMode, toJsonable, verify, wrapTool, wrapTools };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SigningKey, a as SignedRecord, A as AgentKeyEntry, R as Receipt, b as SignafaideError, C as Client, K as Kind, E as Envelope, c as Report, d as KeyDoc, L as LocalContent } from './core-BMfko_ex.js';
-export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots, h as CHECKS, i as Check, j as CheckId, D as DEFAULT_TIMESTAMP_URL, k as DEFAULT_URL, l as Domain, m as DrandBeacon, n as DrandVerifier, H as HEADER, J as JsonNumber, o as KeySource, p as KeysRequired, M as MAX_NODES, q as MAX_PROOF_BYTES, r as MAX_ROUND, N as NOT_INDEPENDENT, P as PackFilter, s as PackOptions, t as RecordFields, u as SignedHeadDoc, v as Status, V as VERSION, w as agentName, x as assertPortableNumbers, y as auditPath, z as b64url, F as b64urlDecode, G as blockAttestations, I as blockHeader, O as canonicalBytes, Q as canonicalize, T as checkContent, U as checkHeader, W as checkRoundTime, X as clampTime, Y as clientHeader, Z as contentFromText, _ as contentHash, $ as countsText, a0 as detectAgent, a1 as draftErrors, a2 as envelopeErrors, a3 as exportStatement, a4 as fetchJson, a5 as hashJson, a6 as isLoopbackUrl, a7 as keyEntryErrors, a8 as keyId, a9 as leafHash, aa as loadDrandVerifier, ab as lookupTimestamps, ac as makeDraft, ad as makeRecord, ae as manifestEntry, af as manifestErrors, ag as merkleRoot, ah as newSalt, ai as now, aj as otsStatus, ak as parseAgentKeys, al as parseHeadFile, am as parseJson, an as parseOts, ao as parseServiceKeys, ap as receiptErrors, aq as recordErrors, ar as recordHash, as as recordsHash, at as registration, au as resultLine, av as rootsFromVector, aw as scopeText, ax as serviceKeysHash, ay as sha256Hex, az as signDraft, aA as signedMessage, aB as target, aC as telemetryEnabled, aD as timestampHeights, aE as validProjectId, aF as validTime, aG as verifyInclusion, aH as verifyLocalState, aI as verifyPack, aJ as verifySig, aK as wireRecord, aL as withWallTime } from './core-BMfko_ex.js';
+import { S as SigningKey, a as SignedRecord, A as AgentKeyEntry, R as Receipt, b as SignafaideError, C as Client, K as Kind, E as Envelope, c as Report, d as KeyDoc, L as LocalContent } from './core-BTJGPYVW.js';
+export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots, h as CHECKS, i as Check, j as CheckId, k as Coverage, D as DEFAULT_TIMESTAMP_URL, l as DEFAULT_URL, m as DeclaredTool, n as Domain, o as DrandBeacon, p as DrandVerifier, H as HEADER, J as JsonNumber, q as KeySource, r as KeysRequired, M as MAX_DECLARED_NAME, s as MAX_NODES, t as MAX_PROOF_BYTES, u as MAX_ROUND, N as NOT_INDEPENDENT, P as PackFilter, v as PackOptions, w as RecordFields, x as SignedHeadDoc, y as Status, T as TOOLS, z as TOOL_PREFIX, F as TOOL_UNRECORDED_PREFIX, V as VERSION, G as agentName, I as assertPortableNumbers, O as auditPath, Q as b64url, U as b64urlDecode, W as blockAttestations, X as blockHeader, Y as canonicalBytes, Z as canonicalize, _ as checkContent, $ as checkHeader, a0 as checkRoundTime, a1 as clampTime, a2 as clientHeader, a3 as contentFromText, a4 as contentHash, a5 as countsText, a6 as coverage, a7 as coverageLines, a8 as declaredName, a9 as detectAgent, aa as draftErrors, ab as envelopeErrors, ac as exportStatement, ad as fetchJson, ae as hashJson, af as isLoopbackUrl, ag as keyEntryErrors, ah as keyId, ai as leafHash, aj as loadDrandVerifier, ak as lookupTimestamps, al as makeDraft, am as makeRecord, an as manifestEntry, ao as manifestErrors, ap as merkleRoot, aq as newSalt, ar as now, as as otsStatus, at as parseAgentKeys, au as parseHeadFile, av as parseJson, aw as parseOts, ax as parseServiceKeys, ay as receiptErrors, az as recordErrors, aA as recordHash, aB as recordsHash, aC as registration, aD as resultLine, aE as rootsFromVector, aF as scopeText, aG as serviceKeysHash, aH as sha256Hex, aI as signDraft, aJ as signedMessage, aK as target, aL as telemetryEnabled, aM as timestampHeights, aN as toolNote, aO as toolNoteName, aP as validProjectId, aQ as validTime, aR as verifyInclusion, aS as verifyLocalState, aT as verifyPack, aU as verifySig, aV as wireRecord, aW as withWallTime } from './core-BTJGPYVW.js';
 
 /**
  * Local state in `.signafaide/` (SPEC §8). Node only. Same layout and formats as the Python SDK.
@@ -17,6 +17,7 @@ export { e as AGENT_RE, f as ANCHOR_WINDOW_MS, B as BlockHeader, g as BlockRoots
  * - `blocked.json`               chains the witness refused, with why (status, verify, replay)
  * - `outbox/<chain>/<seq>.json`  signed records not yet accepted by the service
  * - `head.json`                  newest signed head, `{project: {env: {agent: {head, head_sig}}}}`
+ * - `tools/<agent>.json`         the tools each source last declared for the agent (§2.6)
  * - `config.json`                coding agent; API key fingerprint -> {project, env}
  * - `sandbox.json`               the sandbox project and claim link
  *
@@ -34,6 +35,10 @@ interface ProvidedKey {
 }
 /** Returns an agent's key from a secret store, or undefined to use the key file. */
 type KeyProvider = (agent: string, scope: KeyScope) => ProvidedKey | string | undefined;
+/** A source refreshes its entry in `tools/<agent>.json` at least this often while it runs (§8). */
+declare const TOOL_SOURCE_REFRESH_MS = 3600000;
+/** An entry another source has not refreshed for this long is dropped: that source has stopped (§8). */
+declare const TOOL_SOURCE_MAX_AGE_MS = 86400000;
 /** Local state is unusable; the message says how to fix it. */
 declare class StateError extends Error {
     name: string;
@@ -195,6 +200,30 @@ declare 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: string, build: (seq: number, prev: string | null, prevTime: string | null) => SignedRecord, wire: (r: SignedRecord) => SignedRecord, stillValid?: () => boolean): SignedRecord | 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: string, builds: ((seq: number, prev: string | null, prevTime: string | null) => SignedRecord)[], wire: (r: SignedRecord) => SignedRecord, stillValid?: () => boolean): SignedRecord[] | null;
+    /** `tools/<agent>.json` (§8): the tools each source (the SDK in an application, each gateway)
+     * last declared for the agent. */
+    toolsPath(agent: string): string;
+    /** The tools every source last declared for `agent`: source -> {tool name: recorded}. */
+    toolSources(agent: string): Record<string, Record<string, boolean>>;
+    /** The entries of `tools/<agent>.json`: source -> when it last declared or refreshed, and its tools. */
+    toolEntries(agent: string): Record<string, {
+        at: string;
+        tools: Record<string, boolean>;
+    }>;
+    /** 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: string, source: string): void;
+    /** 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<T>(agent: string, source: string, tools: Record<string, boolean>, write: (all: Record<string, boolean>, expired: boolean) => T, nowMs?: number): T;
     private writeOutbox;
     private lines;
     /** Every line of a chain, drafts included (§8). */
@@ -331,6 +360,9 @@ declare class Recorder {
     /** Agents this process wrote records for since its last stop note. */
     private wrote;
     private toldStrict;
+    /** `<agent>\n<source>` -> the tool set this recorder last declared for it (§2.6), and the header's hash. */
+    private declared;
+    private toolTimer?;
     /** @internal */ _url?: string;
     /** @internal */ _apiKey?: string;
     /** `<agent>\n<scope>` -> [key, the key file's identity when loaded] */
@@ -413,6 +445,38 @@ declare class Recorder {
         ref?: string | null;
         storeContent?: boolean;
     }): SignedRecord;
+    /** `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: {
+        kind: Kind;
+        name: string;
+        content: Record<string, unknown>;
+        ref?: string | null;
+    }[], opts?: {
+        agent?: string;
+        storeContent?: boolean;
+    }): SignedRecord[];
+    /** 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: Record<string, boolean>, opts: {
+        agent?: string;
+        source: string;
+        origin: "gateway" | "wrap_tools" | "declared";
+        storeContent?: boolean;
+    }): string;
+    /** 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(): void;
+    /** 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?: string): void;
     /** 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
      * witness, so the record is a draft until the shipper has asked for the witness's head and
@@ -471,6 +535,12 @@ declare class Recorder {
     /** 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. */
     private onBeforeExit;
+    /** 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. */
+    shutdown(): Promise<void>;
+    private exitAttempt;
     private onExit;
     /** Stop the background timer and exit hooks (records stay in the outbox). */
     close(): void;
@@ -535,7 +605,8 @@ declare function getRecorder(): Recorder;
 /** Replace the default recorder (used by `init` and tests). */
 declare function configure(opts?: RecorderOptions): Recorder;
 
-/** `record`, `note` and `wrapTools`: the decision -> run -> outcome cycle. Node only. */
+/** `record`, `note`, `wrapTools` and `declareTools`: the decision -> run -> outcome cycle, and
+ * the agent's tool list (SPEC §2.6). Node only. */
 
 interface RecordOptions {
     /** Action or tool name. Defaults to the function's name. */
@@ -555,6 +626,24 @@ declare class NotRecorded extends SignafaideError {
     name: string;
 }
 type AnyFn = (...args: any[]) => any;
+/** `SIGNAFAIDE_DECLARE_TOOLS=0` turns off the declarations `wrapTools` writes by itself. */
+declare function autoDeclareTools(env?: NodeJS.ProcessEnv): boolean;
+interface DeclareOptions {
+    /** Agent chain name (default: the project folder name). */
+    agent?: string;
+    /** Tools of the agent that are known not to be wrapped: declared as not recorded. */
+    unrecorded?: Iterable<string>;
+}
+/**
+ * Declare the agent's full tool list (SPEC §2.6), so a verifier can say which of the agent's
+ * tools are recorded. A name is declared recorded when the SDK wrapped a tool of that name in
+ * this process (`record`, `wrapTools`, `wrapTool`), otherwise not recorded; `unrecorded` names
+ * tools that are not wrapped. The declaration is a signed note per tool in the agent's chain:
+ * it is evidence of what the program said its tools were, not proof that the list is complete.
+ * Written now, and again by itself when a tool of the list is wrapped later. Returns the hash of
+ * the `signafaide.tools` note ("" when recording is turned off).
+ */
+declare function declareTools(names: Iterable<string>, opts?: DeclareOptions): string;
 /**
  * Record every call of `fn`: a `decision` before it runs, an `outcome` after.
  * The decision's input is the single argument, or the argument list when there are
@@ -574,11 +663,15 @@ interface WrapOptions {
     agent?: string;
     strict?: boolean;
     storeContent?: boolean;
+    /** Declare the wrapped tools as the agent's recorded tools (SPEC §2.6), with the first
+     * recorded call. Default true; `SIGNAFAIDE_DECLARE_TOOLS=0` turns it off everywhere. */
+    declareTools?: boolean;
 }
 /**
  * Record every tool in an object (key = tool name) or an array. Accepts plain
  * functions, Vercel AI SDK tools (objects with `execute`), OpenAI Agents JS
- * function tools and LangChain.js tools. Returns the same shape.
+ * function tools and LangChain.js tools. Returns the same shape. The wrapped tools are
+ * declared as the agent's recorded tools (see `declareTools`) unless `declareTools: false`.
  */
 declare function wrapTools<T>(tools: T, opts?: WrapOptions): T;
 /** Record one tool. See `wrapTools`. */
@@ -895,4 +988,4 @@ declare function loadContent(src: string): Map<string, LocalContent>;
  */
 declare function verify(pack?: string | object | null, opts?: VerifyOptions): Promise<Report>;
 
-export { AgentKeyEntry, type Blocked, Client, type CompareOptions, Entry, Envelope, ExperimentReport, type ExperimentRow, type FlushResult, KeyDoc, Kind, NotRecorded, Receipt, type RecordOptions, Recorder, type RecorderOptions, Replay, type ReplayOptions, Report, SignafaideError, SignedRecord, SigningKey, State, StateError, type StopResult, VerificationFailed, type VerifyOptions, type WrapOptions, checkHeld, compare, configure, flush, getRecorder, init, loadContent, loadServiceKeys, notYet, note, record, recordedValue, recordingDisabled, replay, status, stop, testMode, toJsonable, verify, wrapTool, wrapTools };
+export { AgentKeyEntry, type Blocked, Client, type CompareOptions, type DeclareOptions, Entry, Envelope, ExperimentReport, type ExperimentRow, type FlushResult, KeyDoc, Kind, NotRecorded, Receipt, type RecordOptions, Recorder, type RecorderOptions, Replay, type ReplayOptions, Report, SignafaideError, SignedRecord, SigningKey, State, StateError, type StopResult, TOOL_SOURCE_MAX_AGE_MS, TOOL_SOURCE_REFRESH_MS, VerificationFailed, type VerifyOptions, type WrapOptions, autoDeclareTools, checkHeld, compare, configure, declareTools, flush, getRecorder, init, loadContent, loadServiceKeys, notYet, note, record, recordedValue, recordingDisabled, replay, status, stop, testMode, toJsonable, verify, wrapTool, wrapTools };

package/dist/index.js

@@ -6,10 +6,14 @@ import {
   Replay,
   State,
   StateError,
+  TOOL_SOURCE_MAX_AGE_MS,
+  TOOL_SOURCE_REFRESH_MS,
   VerificationFailed,
+  autoDeclareTools,
   checkHeld,
   compare,
   configure,
+  declareTools,
   flush,
   getRecorder,
   init,
@@ -28,7 +32,7 @@ import {
   verify,
   wrapTool,
   wrapTools
-} from "./chunk-4C2JEYAU.js";
+} from "./chunk-P3GJDXSQ.js";
 import {
   AGENT_RE,
   ANCHOR_WINDOW_MS,
@@ -36,12 +40,16 @@ import {
   DEFAULT_TIMESTAMP_URL,
   JsonNumber,
   KeysRequired,
+  MAX_DECLARED_NAME,
   MAX_NODES,
   MAX_PROOF_BYTES,
   MAX_ROUND,
   NOT_INDEPENDENT,
   Report,
   SigningKey,
+  TOOLS,
+  TOOL_PREFIX,
+  TOOL_UNRECORDED_PREFIX,
   agentName,
   assertPortableNumbers,
   auditPath,
@@ -58,6 +66,9 @@ import {
   contentFromText,
   contentHash,
   countsText,
+  coverage,
+  coverageLines,
+  declaredName,
   draftErrors,
   envelopeErrors,
   exportStatement,
@@ -95,6 +106,8 @@ import {
   signedMessage,
   target,
   timestampHeights,
+  toolNote,
+  toolNoteName,
   validProjectId,
   validTime,
   verifyInclusion,
@@ -103,7 +116,7 @@ import {
   verifySig,
   wireRecord,
   withWallTime
-} from "./chunk-MBXHRQ2J.js";
+} from "./chunk-6UDL5LZL.js";
 import {
   Client,
   DEFAULT_URL,
@@ -114,7 +127,7 @@ import {
   detectAgent,
   fetchJson,
   telemetryEnabled
-} from "./chunk-S2RSID5F.js";
+} from "./chunk-DRRRZNIH.js";
 export {
   AGENT_RE,
   ANCHOR_WINDOW_MS,
@@ -127,6 +140,7 @@ export {
   HEADER,
   JsonNumber,
   KeysRequired,
+  MAX_DECLARED_NAME,
   MAX_NODES,
   MAX_PROOF_BYTES,
   MAX_ROUND,
@@ -139,11 +153,17 @@ export {
   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,
@@ -161,6 +181,10 @@ export {
   contentFromText,
   contentHash,
   countsText,
+  coverage,
+  coverageLines,
+  declareTools,
+  declaredName,
   detectAgent,
   draftErrors,
   envelopeErrors,
@@ -216,6 +240,8 @@ export {
   testMode,
   timestampHeights,
   toJsonable,
+  toolNote,
+  toolNoteName,
   validProjectId,
   validTime,
   verify,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signafaide",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Signed, chained records of what your AI agents decided. Hash-only by default.",
   "license": "Apache-2.0",
   "type": "module",