@net-mesh/core 0.30.0 → 0.32.0

package/index.d.ts

@@ -1,5 +1,16 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * Keeps the served A2A services alive (returned by `NetMesh.serveA2a`).
+ * Dropping it or calling [`stop`](Self::stop) unregisters them.
+ */
+export declare class A2aServeHandle {
+  /** Stop accepting A2A tasks (unregister the services). Idempotent. */
+  stop(): void
+  /** Whether the services are still registered. */
+  get serving(): boolean
+}
+
 /**
  * Typed admin-event surface — one method per `AdminEvent`
  * variant. Each commits via the substrate's admin chain + returns
@@ -181,6 +192,98 @@ export declare class BlobRef {
   static treeFromParts(uri: string, rootHash: Buffer, totalSize: bigint, depth: number): BlobRef
 }
 
+export declare class CapabilityGateway {
+  constructor(mesh: NetMesh, pinStorePath?: string | undefined | null, paymentPolicyPath?: string | undefined | null, paymentProfile?: string | undefined | null, paymentUnsafeMockAutoAllow?: boolean | undefined | null, paymentSignerAddress?: string | undefined | null, paymentSigner?: ((arg: string) => Promise<string>) | undefined | null, paymentSignerSvmAddress?: string | undefined | null, paymentSignerSvm?: ((arg: string) => Promise<string>) | undefined | null, paymentSignerXrplAddress?: string | undefined | null, paymentSignerXrpl?: ((arg: string) => Promise<string>) | undefined | null)
+  /**
+   * Release the internal mesh-node reference so the underlying `NetMesh` can
+   * be `shutdown()` deterministically. A `#[napi]` class is GC-finalized, not
+   * scope-dropped, so without this the gateway's retained node clone keeps
+   * `NetMesh.shutdown()` (which needs sole ownership of the node) failing
+   * until GC runs. Call it before `mesh.shutdown()`. Idempotent; after
+   * `close()`, `search` / `describe` / `invoke` resolve to a structured
+   * `closed` status (never a throw). The operator approval verbs still work —
+   * they reopen the spend-policy store, independent of the node.
+   */
+  close(): void
+  /** The machine-shared pin store path this gateway consults, if any. */
+  get pinStorePath(): string | null
+  /**
+   * Search the mesh for capabilities matching `query` (substring over id /
+   * name / description). Resolves to `{"status":"ok","capabilities":[...]}`
+   * (each row carries `requires_approval`), or `{"status":"<err>","error":...}`.
+   * An empty index is `ok` with an empty list — never an error.
+   */
+  search(query: string): Promise<string>
+  /**
+   * Describe one capability by its `provider/capability` id. Resolves to a
+   * JSON string with the full schema + `requires_approval` + `pricing_terms`,
+   * or `{"status":"<err>","error":...}`.
+   */
+  describe(capId: string): Promise<string>
+  /**
+   * Invoke a capability through the consent gate. `argumentsJson` is the
+   * tool's own arguments as a JSON object string (default `{}`).
+   *
+   * Resolves to a JSON string whose `status` is one of `ok`,
+   * `requires_approval`, `requires_payment_approval`, `validation_error`,
+   * `denied`, `not_found`, `transport_error`, `no_daemon`, or `error`. Never
+   * rejects for a gate outcome; a malformed id / arguments is itself a
+   * structured error.
+   */
+  invoke(capId: string, argumentsJson?: string | undefined | null): Promise<string>
+  /**
+   * Approve a held payment quote under operator policy, resolving a prior
+   * `requires_payment_approval` so the next `invoke` redeems it. Resolves to
+   * `{"status":"ok","quote_id":...,"changed":bool}`, or a structured
+   * `no_payment_policy` / `error`. Operator surface — `invoke` only *requests*
+   * approval; this grants it.
+   */
+  approvePayment(quoteId: string): Promise<string>
+  /**
+   * Reject / remove a payment approval record. Resolves to
+   * `{"status":"ok","quote_id":...,"changed":bool}`, or a structured error.
+   */
+  rejectPayment(quoteId: string): Promise<string>
+  /**
+   * The quote ids awaiting approval, for a consent UX to render. Resolves to
+   * `{"status":"ok","pending":[quote_id, ...]}`, or a structured error.
+   */
+  pendingPayments(): Promise<string>
+  /**
+   * Today's reserved spend total for a `(network, x402 asset)` pair, as the
+   * canonical atomic-amount string. Resolves to
+   * `{"status":"ok","network":...,"asset":...,"spent":"<atomic>"}`, or a
+   * structured error. `network` / `asset` are the x402 wire values.
+   */
+  spentToday(network: string, asset: string): Promise<string>
+}
+
+/**
+ * A capability's canonical identity: `provider/capability`. Construction
+ * and parsing canonicalize the provider (whitespace, `0x`-hex node ids),
+ * so a pin or consent record keyed through this type can never miss a
+ * differently spelled twin. Purely a parse / inspect helper — the
+ * consent and pin APIs take the `provider/capability` string directly
+ * and canonicalize internally.
+ */
+export declare class CapabilityId {
+  /** Build from parts. The provider is canonicalized. */
+  constructor(provider: string, capability: string)
+  /**
+   * Parse the `provider/capability` display form (splits on the FIRST
+   * `/`; the capability half may itself contain `/`). Throws
+   * `consent: ...` on a missing or empty half.
+   */
+  static parse(s: string): CapabilityId
+  /** The provider node qualifier (canonical spelling). */
+  get provider(): string
+  /** The capability / tool name. */
+  get capability(): string
+  /** The `provider/capability` display / wire form. */
+  display(): string
+  toString(): string
+}
+
 /**
  * Producer-facing chunking-strategy value type for the v0.3
  * Tree store path. SDK consumers construct an instance via the
@@ -286,6 +389,41 @@ export declare class ClientStreamCall {
   close(): Promise<void>
 }
 
+/**
+ * The consumer-side consent gate: a config allowlist plus a set of pinned
+ * capabilities, deciding per capability + wire credential status. The
+ * decision logic is the SDK's — this class only carries state.
+ */
+export declare class ConsentPolicy {
+  /**
+   * An empty policy: with no entries, EVERY discovered capability
+   * requires approval (a wire credential status — including `"none"` —
+   * is never trusted).
+   */
+  constructor()
+  /** Allowlist a capability (operator config) — a standing pre-approval. */
+  allow(capId: string): void
+  /** Record an approved pin. */
+  pin(capId: string): void
+  /** Remove a pin. */
+  unpin(capId: string): void
+  /** Is the capability pinned? */
+  isPinned(capId: string): boolean
+  /** The pinned capabilities' display ids, sorted. */
+  pinned(): Array<string>
+  /**
+   * Decide whether the capability, with the given wire credential
+   * status, may be invoked: `"allowed"` or `"requires_approval"`. The
+   * decision is the SDK enum's stable string form — never re-derive it.
+   */
+  decide(capId: string, credentialStatus: string): string
+  /**
+   * Convenience: does invoking the capability require approval the
+   * operator has not granted?
+   */
+  requiresApproval(capId: string, credentialStatus: string): boolean
+}
+
 /**
  * Handle returned by [`DaemonRuntime::spawn`]. Identifies a
  * specific daemon by its `origin_hash`; cloning the JS object
@@ -645,6 +783,138 @@ export declare class DeckClient {
   subscribeFailures(sinceSeq?: bigint | undefined | null): Promise<FailureStream>
 }
 
+/**
+ * A `root → … → leaf` delegation chain that attributes a capability
+ * invocation to the terminal agent identity.
+ *
+ * Built with [`Self::derive_gateway`] and extended per-task with
+ * [`Self::extend_to_subagent`]. Verify it against a
+ * [`RevocationRegistry`] with [`Self::verify`]; serialize with
+ * [`Self::to_bytes`] to carry it.
+ */
+export declare class DelegationChain {
+  /**
+   * Build a `root → machine → gateway` chain from opaque `Identity`
+   * handles. `root` and `machine` sign their own delegations; only
+   * `gateway`'s public entity-id is used (its keypair stays with the
+   * gateway). `ttlSeconds` is the grant lifetime; the whole chain
+   * expires together. `maxDepth` (default 4) leaves room for subagent
+   * hops.
+   */
+  static deriveGateway(root: Identity, machine: Identity, gateway: Identity, ttlSeconds: number, maxDepth?: number | undefined | null): DelegationChain
+  /**
+   * Parse a serialized chain. Throws `token: invalid_format` on an
+   * empty chain, too many links, or trailing garbage.
+   */
+  static fromBytes(data: Buffer): DelegationChain
+  /**
+   * Extend this chain with a `… → subagent` link, signed by the current
+   * leaf's owner (`leafSigner`, whose entity-id must equal the chain's
+   * current leaf subject — e.g. the gateway extending to a subagent).
+   * The subagent link drops the delegate right but keeps invoke
+   * authority, so its own calls verify and are individually
+   * attributable. Returns a new chain; the original is unchanged.
+   */
+  extendToSubagent(leafSigner: Identity, subagent: Buffer): DelegationChain
+  /**
+   * `true` if the chain still authorizes an invocation by `presenter`,
+   * anchored at `root`, honoring `registry`. Returns `false` (never
+   * throws) when the chain is expired, revoked, rooted elsewhere, or
+   * presented by the wrong identity — so a caller can gate a check on
+   * it directly. `skewSeconds` tolerates clock drift (default 0 =
+   * strict).
+   */
+  verify(presenter: Buffer, root: Buffer, registry: RevocationRegistry, skewSeconds?: number | undefined | null): boolean
+  /**
+   * The terminal (leaf) subject entity-id — the agent this chain
+   * attributes to (the gateway, or a subagent after
+   * [`Self::extend_to_subagent`]).
+   */
+  get leaf(): Buffer
+  /** The root issuer entity-id the chain anchors at. */
+  get root(): Buffer
+  /** The subject entity-id of each link, root-to-leaf. */
+  subjects(): Array<Buffer>
+  /**
+   * Serialize to wire bytes (a `TokenChain` blob) for carriage on an
+   * invoke or hand-off to another process.
+   */
+  toBytes(): Buffer
+  /**
+   * Number of delegation links (2 for a bare gateway chain, +1 per
+   * subagent hop).
+   */
+  get length(): number
+}
+
+/**
+ * A device's **persisted** enrollment — its own key + the
+ * `root → device` grant it received — so it survives restarts without
+ * re-pairing. The device seed stays in Rust (H8); [`Self::device`] hands
+ * back an opaque `Identity`.
+ */
+export declare class DeviceEnrollment {
+  /**
+   * Bundle a device `Identity` handle with the `root → device` chain it
+   * received from `join`, the operator's `rendezvous` locator (from the
+   * invite, for renewal), and the unix-seconds it enrolled.
+   */
+  constructor(device: Identity, chain: DelegationChain, rendezvous: string, enrolledAt: bigint)
+  /**
+   * Load a persisted enrollment from `path`. Resolves `null` if none is
+   * saved yet; rejects on a corrupt file.
+   */
+  static load(path: string): Promise<DeviceEnrollment | null>
+  /**
+   * Persist to `path` (`0600`, atomic). Overwrites — e.g. after a
+   * renewal.
+   */
+  save(path: string): Promise<void>
+  /**
+   * The device's opaque `Identity` handle (its private seed stays in
+   * Rust) — use it to extend the grant to a gateway.
+   */
+  get device(): Identity
+  /** The `root → device` delegation chain. */
+  get chain(): DelegationChain
+  /**
+   * The operator's rendezvous locator — where the device dials to
+   * renew.
+   */
+  get rendezvous(): string
+  /** The mesh root the grant anchors at (32 bytes). */
+  get root(): Buffer
+  /** Unix-seconds the device enrolled. */
+  get enrolledAt(): bigint
+  /** Unix-seconds the grant expires. */
+  get expiresAt(): bigint
+  /**
+   * Whether the grant still verifies + is unexpired. Pass a
+   * `RevocationRegistry` (an empty one is fine device-side — the
+   * provider enforces revocation on invoke). `skewSeconds` tolerates
+   * clock drift (default 0 = strict).
+   */
+  isValid(revocation: RevocationRegistry, skewSeconds?: number | undefined | null): boolean
+  /**
+   * Whether the grant is within `windowSeconds` of expiry at `now`
+   * (unix secs) — the trigger for silent renewal.
+   */
+  needsRenewal(windowSeconds: number, now: bigint): boolean
+}
+
+/** One enrolled device in the operator's inventory. */
+export declare class DeviceRecord {
+  /** The device entity-id (32 bytes). */
+  get device(): Buffer
+  get name(): string
+  get tags(): Array<string>
+  /** Unix-seconds the device enrolled. */
+  get enrolledAt(): bigint
+  /** Unix-seconds the device was revoked, or `null` while active. */
+  get revokedAt(): bigint | null
+  get isRevoked(): boolean
+}
+
 /**
  * Open duplex RPC call. Combined send + receive surface. Use
  * `intoSplit()` to get independent `DuplexSink` + `DuplexStream`
@@ -784,6 +1054,18 @@ export declare class Encoding {
   static defaultReedSolomon(): Encoding
 }
 
+/**
+ * Keeps the served enrollment services alive (returned by
+ * `NetMesh.serveEnrollmentAuto`). Dropping it or calling
+ * [`stop`](Self::stop) unregisters them.
+ */
+export declare class EnrollmentServeHandle {
+  /** Stop serving enrollment (unregister the services). Idempotent. */
+  stop(): void
+  /** Whether the services are still registered. */
+  get serving(): boolean
+}
+
 export declare class FailureStream {
   nextRecord(): Promise<FailureRecordJs | null>
   close(): Promise<void>
@@ -929,6 +1211,87 @@ export declare class InMemoryChainReader {
   latestSeq(originHash: bigint): bigint | null
 }
 
+/**
+ * A pre-authorization to *ask* to join a mesh — not a key. Carries the
+ * mesh `root`, a `rendezvous` locator, a single-use nonce, and a short
+ * TTL.
+ */
+export declare class InviteToken {
+  /**
+   * Parse an invite string (`net-invite:<base64url>`). Throws on a
+   * missing prefix, bad base64, or malformed bytes.
+   */
+  static decode(s: string): InviteToken
+  /** Parse canonical wire bytes. */
+  static fromBytes(data: Buffer): InviteToken
+  /** The copy-paste / QR invite string. */
+  encode(): string
+  /** The mesh root entity-id this invite admits into (32 bytes). */
+  get root(): Buffer
+  /** The rendezvous locator the device dials (opaque transport string). */
+  get rendezvous(): string
+  /** Unix-seconds expiry. */
+  get expiresAt(): bigint
+  /** The displayed fingerprint of the mesh root — show it to the joiner. */
+  rootFingerprint(): string
+  /** Whether the invite has expired at `now` (unix secs). */
+  isExpired(now: bigint): boolean
+  /** Canonical wire bytes. */
+  toBytes(): Buffer
+}
+
+/**
+ * The operator's response to a join request — the payload the enrollment
+ * RPC returns to the device.
+ */
+export declare class JoinOutcome {
+  /** Parse canonical wire bytes. */
+  static fromBytes(data: Buffer): JoinOutcome
+  /** Canonical wire bytes. */
+  toBytes(): Buffer
+  /** `true` if the device was admitted. */
+  get isAdmitted(): boolean
+  /** The stable reject code (`1..=7`) if rejected, else `null`. */
+  get rejectCode(): number | null
+  /** The human reject message if rejected, else `null`. */
+  get rejectMessage(): string | null
+  /**
+   * Device-side: verify the admitted grant anchors at the invited mesh
+   * root (`inviteRoot`) and binds to this `device`, returning the
+   * `DelegationChain`. Throws if the outcome was a rejection, or the
+   * grant is untrusted (wrong root / wrong device) — defending the
+   * joiner against a rogue operator.
+   *
+   * `&self` despite the `into_` name: a `#[napi]` method can't consume
+   * `self` (the object is JS-owned), and the JS-facing name
+   * deliberately mirrors the SDK's `JoinOutcome::into_chain` (pinned by
+   * the Python binding and callers).
+   */
+  intoChain(device: Buffer, inviteRoot: Buffer): DelegationChain
+}
+
+/** A device's request to join, signed by the device's own key. */
+export declare class JoinRequest {
+  /**
+   * Build + sign a request against `invite`. `device` is the opaque
+   * `Identity` handle whose key is being enrolled (H8: seed stays in
+   * Rust).
+   */
+  static create(device: Identity, name: string, tags: Array<string>, invite: InviteToken): JoinRequest
+  /** Parse canonical wire bytes (does not verify the signature). */
+  static fromBytes(data: Buffer): JoinRequest
+  /** `true` if the device's self-signature verifies (it holds its key). */
+  verifySelfSignature(): boolean
+  /** The device entity-id (32 bytes). */
+  get device(): Buffer
+  /** The device-chosen name. */
+  get name(): string
+  /** The device-chosen tags. */
+  get tags(): Array<string>
+  /** Canonical wire bytes. */
+  toBytes(): Buffer
+}
+
 /**
  * Inbound request-stream handle for client-streaming + duplex
  * server handlers. Drain via `await stream.next()` until it
@@ -1013,6 +1376,36 @@ export declare class JsResponseSink {
   send(body: Buffer): boolean
 }
 
+/**
+ * A live publication of a node's own local tools (from
+ * `NetMesh.publishTools`). Hold it to keep the tools announced + served;
+ * [`withdraw`](Self::withdraw) reverses it (re-announcing the remainder), and
+ * dropping it (or [`stop`](Self::stop)) unregisters the services.
+ */
+export declare class LocalPublicationHandle {
+  /**
+   * The served tool ids (channel-safe; a sanitized id differs from the
+   * original name). Empty once withdrawn / stopped.
+   */
+  get tools(): Array<string>
+  /** Tool names skipped because they had no usable id (an empty name). */
+  get skippedTools(): Array<string>
+  /** Whether the publication is still live. */
+  get serving(): boolean
+  /**
+   * Withdraw the publication immediately: re-announce the remaining
+   * publications' set so peers stop advertising these tools, then stop the
+   * services. Idempotent — a second call resolves to a no-op.
+   */
+  withdraw(): Promise<void>
+  /**
+   * Stop serving (unregister the services on drop; unlike
+   * [`withdraw`](Self::withdraw) this does not re-announce — the announcement
+   * reconciles at the next registry change). Idempotent.
+   */
+  stop(): void
+}
+
 export declare class LogStream {
   /**
    * Resolve to the next log record, or `null` when the stream
@@ -1881,6 +2274,84 @@ export declare class NetDb {
  * ```
  */
 export declare class NetMesh {
+  /**
+   * **Executor side.** Serve the A2A task lifecycle on this node, backed
+   * by a JS **async** task executor
+   * `(brief: TaskBriefJs) => Promise<string>` returning the result's
+   * artifact ref, with a fresh task registry. Hold the resolved handle
+   * to keep accepting tasks; call `handle.stop()` before `shutdown()`.
+   * This node must be `start()`ed. (Requires the `a2a` feature.)
+   *
+   * `options.handlerTimeoutMs` bounds how long the executor may take to
+   * settle each task's Promise (default 1 hour; `0` disables) — past the
+   * deadline the task records a `Failed` terminal state instead of
+   * staying `Running` forever behind a wedged event loop.
+   *
+   * Sync setup (the `Function` is `!Send`, so the TSFN is built on the
+   * JS thread), then `spawn_future` for the registration — the SDK's
+   * `serve_rpc` spawns a response-drainer task, which needs the tokio
+   * runtime context only the future has (the `publish.rs` shape).
+   */
+  serveA2a(executor: (arg: TaskBriefJs) => Promise<string>, options?: ServeA2aOptions | undefined | null): Promise<A2aServeHandle>
+  /**
+   * **Requester side.** Hand `prompt` (+ optional Datafort `contextRefs`
+   * + routing `tags`) to the executor at `targetNodeId`; resolves the
+   * accepted task id. Rejects if the executor refused the brief. The
+   * node must already be connected to `targetNodeId`. (Requires the
+   * `a2a` feature.)
+   */
+  submitTask(targetNodeId: bigint, prompt: string, contextRefs?: Array<string> | undefined | null, tags?: Array<string> | undefined | null): Promise<string>
+  /**
+   * **Requester side.** The executor's status record for `taskId` as a
+   * JSON string (`{brief, state, updated_at}`), or `null` if the
+   * executor doesn't know it. (Requires the `a2a` feature.)
+   */
+  taskStatus(targetNodeId: bigint, taskId: string): Promise<string | null>
+  /**
+   * **Requester side.** Cancel `taskId` on the executor; resolves
+   * whether it was in flight. The executor's select observes the token
+   * and the task state flips to `cancelled` — the JS handler's eventual
+   * result is discarded (see the module docs on one-sided
+   * cancellation). (Requires the `a2a` feature.)
+   */
+  cancelTask(targetNodeId: bigint, taskId: string): Promise<boolean>
+  /**
+   * The invite `rendezvous` locator for this node (addr + Noise pubkey
+   * + node id), to pass to `OperatorEnrollment.invite`. Devices dial it
+   * via `join`. (Requires the `delegation` feature.)
+   */
+  rendezvousString(): string
+  /**
+   * Device-side enrollment: enroll `device`'s key into the mesh named
+   * by the `invite` string, under `name` + `tags`, returning the
+   * verified `root → device` `DelegationChain`. This node must be
+   * `start()`ed and built with `permissiveChannels: true` (the
+   * enrollment nRPC uses dynamic per-caller reply channels the strict
+   * registry rejects). (Requires the `delegation` feature.)
+   */
+  join(device: Identity, invite: string, name: string, tags?: Array<string> | undefined | null): Promise<DelegationChain>
+  /**
+   * Operator-side: serve the full device lifecycle on this node (auto —
+   * the invite is the authorization): **enroll** (join) + **renew**.
+   * Hold the resolved handle for as long as enrollment should stay
+   * open; call `handle.stop()` before `shutdown()`. This node must be
+   * `start()`ed and built with `permissiveChannels: true`. (Requires
+   * the `delegation` feature.)
+   *
+   * `async` although the registration itself is synchronous: the SDK's
+   * `serve_rpc` spawns a response-drainer task, which needs the tokio
+   * runtime context napi only provides to `async fn`s — a plain sync
+   * method here panics with "no reactor running" (the same reason the
+   * Python binding wraps this in `runtime.enter()`).
+   */
+  serveEnrollmentAuto(operator: OperatorEnrollment, grantTtlSeconds: number, maxDepth?: number | undefined | null): Promise<EnrollmentServeHandle>
+  /**
+   * Device-side renewal: refresh the grant carried by `enrollment` over
+   * the mesh, returning the verified **fresh** `root → device`
+   * `DelegationChain`. This node must be `start()`ed and built with
+   * `permissiveChannels: true`. (Requires the `delegation` feature.)
+   */
+  renew(enrollment: DeviceEnrollment): Promise<DelegationChain>
   /**
    * Publish this node's island-topology record (host forced to self).
    * Self-indexed locally + broadcast to peers; returns the peer
@@ -1933,6 +2404,12 @@ export declare class NetMesh {
   static create(options: MeshOptions): Promise<NetMesh>
   /** Get this node's Noise public key (hex-encoded). */
   publicKey(): string
+  /**
+   * This node's actual bound socket address (`"ip:port"`). With
+   * `bindAddr: "127.0.0.1:0"` the OS assigns the port; read it here to
+   * hand to a peer's `connect(...)`. Mirrors the Python `local_addr`.
+   */
+  localAddr(): string
   /**
    * Get this node's ID. Returned as `BigInt` so full u64
    * precision is preserved — keypair-derived node_ids
@@ -1955,6 +2432,12 @@ export declare class NetMesh {
    * Declared `async` so napi-rs invokes it with an active
    * tokio runtime — `MeshNode::start()` spawns background
    * tasks via `tokio::spawn` and panics outside a reactor.
+   *
+   * Uses `start_arc` (like the C FFI and the Rust SDK) so
+   * the Arc-scoped lifecycle loops run too: periodic
+   * capability re-announce (with the reflex-diff
+   * re-classify trigger) and — when `autoDirectUpgrade`
+   * is set — the background direct-path upgrade.
    */
   start(): Promise<void>
   /** Send raw bytes to a direct peer. */
@@ -2139,6 +2622,28 @@ export declare class NetMesh {
   unregisterPlacementFilter(id: string): boolean
   /** Whether `id` is currently registered. Mainly for tests. */
   hasPlacementFilter(id: string): boolean
+  /**
+   * Publish this node's OWN local `tools` as mesh capabilities, backed by
+   * a JS **async** `handler`. Each tool is
+   * `{ name, description?, inputSchema }` (`inputSchema` a JSON-object
+   * string); the `handler` is
+   * `(args: { toolName, argumentsJson }) => Promise<{ text, isError? }>`,
+   * called when a consumer invokes a tool — its resolved `text` is the
+   * tool's output (`isError: true` flags a tool-level failure). A
+   * consumer discovers + invokes these through the ordinary
+   * `CapabilityGateway`; no consume-side change.
+   *
+   * `options.ownerOrigin` scopes admission: an `originHash` (BigInt)
+   * admits only that caller; omit it to admit **only this node itself**
+   * (fail-closed default — the tools are backed by an arbitrary local
+   * callback). Set `options.allowAnyCaller = true` to explicitly admit
+   * every mesh peer (overrides `ownerOrigin`; gate invocations yourself).
+   *
+   * Resolves to a [`LocalPublicationHandle`](crate::publish::LocalPublicationHandle)
+   * that must be held to keep the tools published. This node must be
+   * `start()`ed. (Requires the `publish` feature.)
+   */
+  publishTools(tools: Array<PublishToolJs>, handler: (arg: ToolInvokeArgs) => Promise<ToolCallResultJs>, options?: PublishOptions | undefined | null): Promise<LocalPublicationHandle>
   /**
    * Walk the local capability fold for every AI tool
    * published in the mesh and return one
@@ -2220,11 +2725,16 @@ export declare class NetMesh {
    */
   reclassifyNat(): Promise<void>
   /**
-   * Cumulative NAT-traversal counters for this mesh.
-   * Object shape: `{ punchesAttempted, punchesSucceeded,
-   * relayFallbacks }` — all u64 bigints, monotonic, never
-   * reset. Useful for telemetry on punch success rate and
-   * relay load.
+   * Cumulative NAT-traversal counters for this mesh — the
+   * full stage-5 snapshot: punch attempt/success/derived-
+   * failure counts, the three failure-cause counters
+   * (timeouts / rejections / no-relay), background-upgrade
+   * activity, and port-mapping state. Base counters are
+   * monotonic and never reset (`punchesFailed` is derived
+   * and can decrease while a punch is in flight;
+   * `portMappingRenewals` resets on a fresh install —
+   * difference only the base counters). Useful for
+   * telemetry on punch success rate and relay load.
    */
   traversalStats(): TraversalStats
   /**
@@ -2246,6 +2756,18 @@ export declare class NetMesh {
    * handshake error.
    */
   connectDirect(peerNodeId: bigint, peerPublicKey: Buffer, coordinator: bigint): Promise<void>
+  /**
+   * Like `connectDirect`, but auto-selects the rendezvous
+   * coordinator: the relay currently forwarding to the
+   * peer, then a `relay-capable` mutual peer, then any
+   * mutual peer.
+   *
+   * **Optimization, not correctness.** Punch-needing pairs
+   * with no coordinator candidate reject with
+   * `traversal: rendezvous-no-relay` — the caller simply
+   * stays on the routed path, which is always available.
+   */
+  connectDirectAuto(peerNodeId: bigint, peerPublicKey: Buffer): Promise<void>
   /**
    * Install a runtime reflex override. Forces `natType()`
    * to `"open"` and `reflexAddr()` to `external`
@@ -2286,6 +2808,71 @@ export declare class NetStream {
   get streamId(): bigint
 }
 
+/**
+ * The operator side: mint invites, approve join requests into
+ * `root → device` delegations, and manage the device inventory —
+ * composing the enrollment authority + device registry + revocation
+ * store for one mesh root.
+ */
+export declare class OperatorEnrollment {
+  /**
+   * Build a coordinator for the `root` `Identity` handle, with explicit
+   * device-registry and revocation-store paths.
+   */
+  constructor(root: Identity, registryPath: string, revocationPath: string)
+  /**
+   * Build using the per-user default store paths (the same
+   * machine-shared files the CLI and a `net wrap` provider converge
+   * on). Throws if neither path resolves.
+   */
+  static withDefaultPaths(root: Identity): OperatorEnrollment
+  /** The mesh root entity-id (32 bytes). */
+  get rootId(): Buffer
+  /** The displayed fingerprint of the mesh root. */
+  rootFingerprint(): string
+  /**
+   * Mint an invite for this mesh valid for `ttlSeconds`, tracking it so
+   * a later `approve` can match a request to it. `rendezvous` is the
+   * transport locator devices dial (e.g. `NetMesh.rendezvousString()`).
+   */
+  invite(rendezvous: string, ttlSeconds: number): InviteToken
+  /**
+   * Approve an arriving request (auto — invite-as-authorization),
+   * reading the system clock: run the fail-closed checks, record the
+   * device, retire the single-use invite, and return the
+   * `root → device` `DelegationChain`. Rejects on any refusal
+   * (unknown/expired/wrong invite, bad signature). Runs off the JS
+   * thread (store file IO).
+   */
+  approve(request: JoinRequest, grantTtlSeconds: number, maxDepth?: number | undefined | null): Promise<DelegationChain>
+  /**
+   * The **server-side** handler: turn serialized `JoinRequest` bytes
+   * into serialized `JoinOutcome` bytes (auto — invite-as-
+   * authorization). This is what the enrollment RPC moves; a JS host
+   * can serve enrollment by feeding it received request bytes and
+   * returning the outcome bytes. Never throws — a malformed request or
+   * a rejection is a coded `JoinOutcome`.
+   */
+  handleJoinRequest(requestBytes: Buffer, grantTtlSeconds: number, maxDepth?: number | undefined | null): Promise<Buffer>
+  /**
+   * Revoke a device: raise its revocation floor (kills all current
+   * delegations) and stamp the inventory. Reads the system clock.
+   */
+  revoke(device: Buffer): Promise<void>
+  /** The enrolled devices in the inventory. */
+  devices(): Promise<Array<DeviceRecord>>
+  /**
+   * Prune a device from the inventory entirely (orthogonal to revoking
+   * its floor). Returns whether a record existed.
+   */
+  forget(device: Buffer): Promise<boolean>
+  /**
+   * Outstanding (minted, unredeemed, unexpired at `now` unix-secs)
+   * invites.
+   */
+  pendingInvites(now: bigint): Array<InviteToken>
+}
+
 /**
  * Operator identity. Operator id is the keypair's 64-bit origin
  * hash. Construct via `generate()` (tests) or `fromSeed(buffer)`
@@ -2376,6 +2963,101 @@ export declare class OperatorRegistry {
   verifyBundle(signatures: Array<OperatorSignatureJs>, payload: Buffer, threshold: number): void
 }
 
+export declare class PaymentProvider {
+  /**
+   * Build a provider over a started `mesh`. `statePath` is the settlement
+   * store file — it holds the replay/idempotency index and **must be
+   * durable + single-owner** (a temp path loses paid quotes across
+   * restarts). `billingLogPath` optionally records the immutable
+   * `net.billing.event@1` stream.
+   */
+  constructor(mesh: NetMesh, statePath: string, billingLogPath?: string | undefined | null)
+  /**
+   * Release the mesh node + tear down the quote/pay wire so the underlying
+   * `NetMesh` can be `shutdown()` deterministically (a `#[napi]` class is
+   * GC-finalized, not scope-dropped). Call it — plus `stop()`/`withdraw()`
+   * on any handles from `publishPaidTools` — before `mesh.shutdown()`.
+   * Idempotent; after `close()`, `publishPaidTools` throws. `readBilling`
+   * + `providerEntityId` still work (they hold no node reference).
+   */
+  close(): void
+  /**
+   * The node's 32-byte mesh entity id — the provider identity these tools
+   * price + quote under. Pass it to `buildPricingTerms`.
+   */
+  get providerEntityId(): Buffer
+  /**
+   * The immutable billing events this provider recorded, oldest first —
+   * each a `net.billing.event@1` JSON string. Read-only (billing is
+   * emitted by the engine; this only reads). Requires a `billingLogPath`
+   * at construction, else rejects.
+   */
+  readBilling(): Promise<Array<string>>
+  /**
+   * Publish priced tools, gated by this provider's payment engine. `tools`
+   * + `handler` + `options` are exactly as on `NetMesh.publishTools`;
+   * `pricing` maps a tool name to its `net.pricing.terms@1` JSON (from
+   * `buildPricingTerms`). A priced tool serves only **after** its quote is
+   * paid + redeemed (at-most-once, against this same engine). Fail-closed:
+   * an empty `pricing` map throws (use `NetMesh.publishTools` for free
+   * tools); a pricing key naming no published tool is a publish error.
+   * Resolves to a `LocalPublicationHandle` — hold it to keep serving.
+   */
+  publishPaidTools(tools: Array<PublishToolJs>, handler: (arg: ToolInvokeArgs) => Promise<ToolCallResultJs>, pricing: Record<string, string>, options?: PublishOptions | undefined | null): Promise<LocalPublicationHandle>
+}
+
+/**
+ * The persistent, machine-shared pin store — a *path-scoped handle*, with
+ * Promise-returning methods.
+ *
+ * Reads load a fresh snapshot of the file; every mutation runs a full
+ * load→apply→save transaction under the SDK's cross-process advisory
+ * lock on napi's tokio runtime, so a concurrent `net mcp pin` CLI
+ * invocation, a running `net mcp serve` shim, or another handle can never
+ * be clobbered by a stale snapshot.
+ *
+ * `request` is the model-callable verb (only ever writes a *pending*
+ * record); `approve` / `reject` are operator verbs — keep them out of any
+ * model loop.
+ */
+export declare class PinStore {
+  /**
+   * A handle on the pin store file at `path`. The file need not exist
+   * yet — a missing store reads as empty and is created on the first
+   * mutation.
+   */
+  constructor(path: string)
+  /** The store's file path. */
+  get path(): string
+  /**
+   * Record a pin **request** (the model-callable verb). Writes a
+   * `"pending"` record if none exists; an existing record — pending or
+   * approved — is left untouched (a request never upgrades a pin).
+   * Resolves to the resulting state.
+   */
+  request(capId: string): Promise<string>
+  /**
+   * **Approve** a pin (operator verb; creates the record if absent).
+   * Resolves to whether this changed the stored state.
+   */
+  approve(capId: string): Promise<boolean>
+  /**
+   * **Reject / remove** a pin entirely (operator verb). Resolves to
+   * whether a record was removed.
+   */
+  reject(capId: string): Promise<boolean>
+  /** Is the capability approved (fresh snapshot)? */
+  isApproved(capId: string): Promise<boolean>
+  /** The capability's state — `"pending"`, `"approved"`, or `null`. */
+  state(capId: string): Promise<string | null>
+  /** Every approved capability's display id, sorted. */
+  approved(): Promise<Array<string>>
+  /** Every pending capability's display id, sorted. */
+  pending(): Promise<Array<string>>
+  /** All records as `{ capId, state }` objects, sorted by capId. */
+  list(): Promise<Array<PinRecordJs>>
+}
+
 /**
  * Fluent builder for the common-ops query shape. Each
  * chainable method returns a fresh builder so callers can
@@ -2754,6 +3436,49 @@ export declare class ReplicaGroup {
   get healthyCount(): number
 }
 
+/**
+ * Shared per-issuer revocation floor. Bumping an issuer's floor
+ * invalidates every outstanding delegation from that issuer — including
+ * delegated children — the moment `verify` next runs.
+ *
+ * One registry is shared by a gateway and all its subagents (Arc-backed),
+ * so a revoke is observed by every chain that verifies against it.
+ */
+export declare class RevocationRegistry {
+  /** A fresh registry — every issuer's floor is implicitly 0. */
+  constructor()
+  /**
+   * Set `issuer`'s floor to `generation`. Any token from `issuer` with
+   * `issuer_generation < generation` is rejected on the next verify.
+   * Monotonic: a value <= the current floor is a no-op.
+   */
+  revokeBelow(issuer: Buffer, generation: number): void
+  /**
+   * Convenience: revoke every generation-0 delegation from `issuer`
+   * (bumps the floor to 1). Revoking the *machine* identity kills its
+   * gateway chain and, transitively, that gateway's subagents — while a
+   * different machine's chain is untouched.
+   */
+  revoke(issuer: Buffer): void
+  /** The current revocation floor for `issuer` (0 if never revoked). */
+  floor(issuer: Buffer): number
+  /**
+   * Reload the machine-shared revocation floors at `path` into this
+   * registry (monotonic — floors only ever rise, so re-loading is
+   * idempotent and composes with any in-process `revoke`). A missing
+   * store file is a no-op (nothing revoked yet); an unreadable or
+   * corrupt store rejects.
+   *
+   * This is what lets a *caller's* self-check observe an operator's
+   * `net identity revoke` — written to the same file a
+   * `net wrap --owner-root` provider honors — so a revoked chain fails
+   * [`DelegationChain::verify`] on the caller side too, not only when
+   * the provider re-verifies. Use [`default_revocation_store_path`]
+   * (or the `NET_MESH_REVOCATION_STORE` override) for `path`.
+   */
+  loadFromStore(path: string): Promise<void>
+}
+
 /**
  * Open streaming RPC call. Yields chunks via `next()` until EOF
  * (returns `null`). Drop OR explicit `close()` emits CANCEL to
@@ -3309,6 +4034,22 @@ export declare function blobPublish(adapterId: string, uri: string, data: Buffer
  */
 export declare function blobResolve(adapterId: string, payload: Buffer): Promise<Buffer>
 
+/**
+ * Author the canonical `net.pricing.terms@1` JSON string that prices a
+ * capability — to hand to `publishPaidTools` or announce at discovery.
+ *
+ * `providerEntityId` is the node's 32-byte mesh entity id
+ * (`PaymentProvider.providerEntityId`) — the identity that issues quotes for
+ * these terms. Only the public id crosses; keys never do. `requirementsJson` is
+ * a JSON array of x402 `PaymentRequirements` objects (`scheme`, `network`,
+ * `amount`, `asset`, `payTo`, `maxTimeoutSeconds`, optional `extra` — the x402
+ * camelCase wire names); one entry per acceptable `(scheme, network, asset)`.
+ * Returns the canonical, byte-preserved terms string — opaque downstream and
+ * echoed verbatim at discovery. Throws on a bad entity id, malformed JSON, or
+ * an empty list.
+ */
+export declare function buildPricingTerms(providerEntityId: Buffer, capability: string, requirementsJson: string): string
+
 /**
  * Cache policy as a tagged plain-object shape. `kind` is one
  * of `"permanent"` (cache until LRU eviction; use only when
@@ -3564,6 +4305,19 @@ export interface ChannelConfigJs {
  */
 export declare function channelHash(channel: string): bigint
 
+/**
+ * Classify a wrapped MCP server's credential exposure. Returns the status
+ * label: `"credentialed"`, `"external_api"`, `"unknown"`, or `"none"`.
+ *
+ * Conservative by construction (the classifier is the bridge's one Rust
+ * implementation): detection can never yield the ungated `"none"` — only
+ * `credentialOverride="no-credentials"` with `force=true` can, mirroring
+ * `net wrap --no-credentials --force`. Only env KEYS drive detection;
+ * values are never inspected beyond presence and never appear in the
+ * result.
+ */
+export declare function classifyMcpServer(program: string, args: Array<string>, envs: Array<EnvPairJs>, credentialOverride?: string | undefined | null, force?: boolean | undefined | null): string
+
 /**
  * A captured CortEX adapter state snapshot, suitable for
  * `openFromSnapshot`. Callers persist both fields together.
@@ -3578,6 +4332,15 @@ export interface CortexSnapshot {
   lastSeq?: bigint
 }
 
+/**
+ * Does a wire-declared credential status require local consent before the
+ * capability may be invoked? Implements the core trust boundary: a wire
+ * `"none"` is NOT trusted (it gates like `"unknown"`), so even `"none"`
+ * (and any unrecognised value) returns `true` — a discovered capability
+ * can only ever over-gate, never bypass consent.
+ */
+export declare function credentialRequiresConsent(status: string): boolean
+
 /**
  * Supervisor → daemon control event, in the cross-binding wire
  * form. Variants:
@@ -3756,6 +4519,16 @@ export declare function decodeJoined(row: ResultRow): JoinedRow | null
  */
 export declare function decodeWindow(row: ResultRow): WindowBoundary | null
 
+/**
+ * The per-user default revocation-store path — the same file a
+ * `net wrap --owner-root` provider honors and `net identity revoke`
+ * writes — or `null` if neither a data-local nor a home directory
+ * resolves. Pass it (or the `NET_MESH_REVOCATION_STORE` override) to
+ * [`RevocationRegistry::load_from_store`] so a caller-side check
+ * observes an operator revocation.
+ */
+export declare function defaultRevocationStorePath(): string | null
+
 /**
  * Delegate a token to a new subject. The `parent_bytes` token must
  * have `delegation_depth > 0` and include the `delegate` scope; the
@@ -3763,6 +4536,28 @@ export declare function decodeWindow(row: ResultRow): WindowBoundary | null
  */
 export declare function delegateToken(signer: Identity, parentBytes: Buffer, newSubject: Buffer, restrictedScope: Array<string>): Buffer
 
+/**
+ * Derive a stable child `Identity` handle from `parent` under `label`.
+ *
+ * Deterministic (blake3 KDF over the parent seed), so a machine / gateway
+ * identity is reproducible across restarts from the root alone — no extra
+ * persistence, and every process that holds the root derives the same
+ * child. The returned handle owns its keypair; the private seed is never
+ * exposed (H8). `label` namespaces siblings, e.g. `"machine:hostA"` vs
+ * `"gateway:hostA:hermes"`.
+ */
+export declare function deriveChildIdentity(parent: Identity, label: string): Identity
+
+/**
+ * One env addition passed to the wrapped server — only the KEY drives
+ * classification; the value is never inspected beyond presence and never
+ * appears in a result.
+ */
+export interface EnvPairJs {
+  key: string
+  value: string
+}
+
 /** Configuration options for creating an EventBus. */
 export interface EventBusOptions {
   /** Number of shards (defaults to CPU core count) */
@@ -3796,6 +4591,13 @@ export interface FailureRecordJs {
   recordedAtMs: bigint
 }
 
+/**
+ * A short, human-comparable fingerprint of an entity-id (the 32-byte
+ * ed25519 public key), shown on both sides of a join so a human can
+ * confirm the mesh identity matches — `A1B2-C3D4-E5F6-0789`.
+ */
+export declare function fingerprint(entity: Buffer): string
+
 export interface ForkGroupConfigJs {
   forkCount: number
   lbStrategy: StrategyJs
@@ -3809,6 +4611,13 @@ export interface ForkRecordJs {
   fromSnapshotSeq?: bigint
 }
 
+/**
+ * The well-known channel every gateway delegation binds to (never
+ * actually published to). Exported so JS callers and tests can
+ * reference the exact string.
+ */
+export const GATEWAY_DELEGATION_CHANNEL: string
+
 /**
  * Generate a new Net keypair for encrypted UDP transport.
  *
@@ -4158,6 +4967,34 @@ export interface LogRecordJs {
   message: string
 }
 
+/**
+ * The lowered-tool DTO. `descriptor` is the `net_sdk` ToolDescriptor as a
+ * JSON-encoded string (`JSON.parse` it), and `bridgeMetadata` the
+ * `tool::<id>::<field>` announcement metadata (classification labels
+ * only, never a secret).
+ */
+export interface LoweredToolJs {
+  /** The channel-safe (possibly sanitized) service id. */
+  toolId: string
+  /** The original tool name `tools/call` must use. */
+  mcpName: string
+  /** The Net discovery descriptor, JSON-encoded (`JSON.parse` it). */
+  descriptor: string
+  /** `tool::<id>::<field>` announcement metadata — labels only. */
+  bridgeMetadata: Record<string, string>
+}
+
+/**
+ * Lower one MCP `tools/list` entry (as its JSON object string) to the Net
+ * discovery shape.
+ *
+ * `credentialStatus` takes the exact label the classifier produced
+ * (including a forced `"none"` — this is trusted local input, not a wire
+ * value); `substitutability` is `"provider_local"` (default) or
+ * `"provider_equivalent"`.
+ */
+export declare function lowerMcpTool(toolJson: string, serverVersion: string, credentialStatus: string, substitutability?: string | undefined | null): LoweredToolJs
+
 /**
  * Maintenance state projection. The `kind` discriminator carries
  * the variant; `sinceMs` / `deadlineRemainingMs` / `reason` are
@@ -4327,6 +5164,38 @@ export interface MeshOptions {
    * without `--features port-mapping`.
    */
   tryPortMapping?: boolean
+  /**
+   * Enable the background direct-path upgrade: once a
+   * session to a peer is established via a relay, the mesh
+   * opportunistically re-handshakes over a direct path and
+   * migrates the session, cutting relay hops out of the
+   * data plane. The swap is guarded by a migration
+   * contract (lower-id initiator, compare-and-swap
+   * install, busy-session deferral) so in-flight work is
+   * never dropped.
+   *
+   * **Optimization, not correctness** — traffic rides the
+   * relay until (and unless) a direct path lands. Default
+   * `false`. Silently ignored when the binding was built
+   * without `--features nat-traversal`.
+   */
+  autoDirectUpgrade?: boolean
+  /**
+   * Opt out of channel authorization: when `true`, no
+   * `ChannelConfigRegistry` is installed on the node, so
+   * membership/subscribe requests aren't gated against
+   * per-channel config (any channel is reachable). Default
+   * `false` — the registry is installed and unconfigured
+   * channels are rejected with `UnknownChannel`.
+   *
+   * Required for dynamic-channel surfaces whose channels
+   * aren't pre-registered — notably `publishTools` (the
+   * served tools + describe service ride dynamically-named
+   * channels). Mirrors the Python binding's
+   * `permissive_channels`. Leave `false` for
+   * production nodes that pre-register their channels.
+   */
+  permissiveChannels?: boolean
 }
 
 export interface MeshOsConfigJs {
@@ -4581,6 +5450,14 @@ export interface PeerSnapshotJs {
   forkedFrom?: bigint
 }
 
+/** One pin record — the JS shape `{ capId, state }`. */
+export interface PinRecordJs {
+  /** The capability's `provider/capability` display id. */
+  capId: string
+  /** `"pending"` or `"approved"`. */
+  state: string
+}
+
 /**
  * Candidate handed to the JS placement-filter predicate.
  *
@@ -4711,6 +5588,29 @@ export interface PublishFailureJs {
   message: string
 }
 
+/** Optional knobs for [`NetMesh::publish_tools`](crate::NetMesh). */
+export interface PublishOptions {
+  /** Server version string used in the lowering. Default `"0"`. */
+  version?: string
+  /**
+   * Restrict invocation to a single caller origin (an `originHash`, as
+   * BigInt). Omit to admit **only this node itself** — the fail-closed
+   * default, since the tools are backed by an arbitrary local callback.
+   */
+  ownerOrigin?: bigint
+  /**
+   * Admit **every** mesh peer (overrides `ownerOrigin`). Default `false`.
+   * You must gate invocations yourself when you set this.
+   */
+  allowAnyCaller?: boolean
+  /**
+   * Per-call handler timeout in milliseconds. Default `120000`. The total
+   * budget across the handler returning its Promise and that Promise
+   * resolving.
+   */
+  handlerTimeoutMs?: number
+}
+
 /** Per-peer report returned by `publish`. */
 export interface PublishReportJs {
   /** Total subscribers the publisher attempted to reach. */
@@ -4721,6 +5621,25 @@ export interface PublishReportJs {
   errors: Array<PublishFailureJs>
 }
 
+/**
+ * One tool to publish: `name` + optional `description` + its input JSON Schema
+ * as a JSON object string. Consumers invoke it as `provider/<sanitizedName>`.
+ */
+export interface PublishToolJs {
+  /**
+   * The tool's name (its original name; the served id is a sanitized,
+   * channel-safe form).
+   */
+  name: string
+  /** Human-readable description shown on describe. Optional. */
+  description?: string
+  /**
+   * The tool's input JSON Schema, as a JSON object string (e.g.
+   * `'{"type":"object","properties":{...}}'`).
+   */
+  inputSchema: string
+}
+
 /** A materialized RedEX event: `seq` + `payload`. */
 export interface RedexEventJs {
   seq: bigint
@@ -5096,6 +6015,20 @@ export interface ScopeFilterJs {
   regions?: Array<string>
 }
 
+/** Optional knobs for [`NetMesh::serve_a2a`]. */
+export interface ServeA2aOptions {
+  /**
+   * Per-task budget in milliseconds for the JS executor to settle its
+   * Promise (the handler returning the Promise + that Promise
+   * resolving, one deadline across both). Default `3600000` (1 hour).
+   * Past it the task records a `Failed` terminal state. Pass `0` to
+   * disable the deadline entirely (Python-binding parity, where
+   * cancellation is the only control) — a wedged event loop then leaves
+   * the task `Running` until a requester cancels it.
+   */
+  handlerTimeoutMs?: number
+}
+
 /**
  * Per-service caller- + server-side nRPC counters at a point
  * in time. Element of [`RpcMetricsSnapshotJs::services`].
@@ -5294,6 +6227,21 @@ export interface Task {
   updatedNs: bigint
 }
 
+/** The brief handed to the JS task executor. */
+export interface TaskBriefJs {
+  /** The registry-assigned task id (poll / cancel by this). */
+  taskId: string
+  /** What to do. */
+  prompt: string
+  /**
+   * Datafort refs carrying the task's context (the executor doesn't
+   * share the requester's memory).
+   */
+  contextRefs: Array<string>
+  /** Routing / bookkeeping tags. */
+  tags: Array<string>
+}
+
 /**
  * Filter for [`TasksAdapter::list_tasks`] and
  * [`TasksAdapter::watch_tasks`].
@@ -5353,6 +6301,21 @@ export interface TokenInfo {
  */
 export declare function tokenIsExpired(bytes: Buffer): boolean
 
+/**
+ * The JS tool handler's return object: the tool's text output plus an optional
+ * tool-level error flag.
+ */
+export interface ToolCallResultJs {
+  /** The tool's text output. */
+  text: string
+  /**
+   * `true` iff the tool ran but produced an error *result* — a tool-level
+   * failure, distinct from a transport failure (which is a thrown / rejected
+   * Promise). Default `false`.
+   */
+  isError?: boolean
+}
+
 /**
  * Wire-compatible mirror of the substrate's
  * [`ToolDescriptor`](net::adapter::net::cortex::tool::ToolDescriptor).
@@ -5375,9 +6338,28 @@ export interface ToolDescriptorJs {
   stateless: boolean
   streaming: boolean
   tags: Array<string>
+  /**
+   * `net.pricing.terms@1` envelope as canonical JSON when the tool is
+   * paid; `None` = free. Opaque to the binding (byte-preserved — payment
+   * semantics live in `net-payments`). Surfaced so `listTools()` reports
+   * the announced price `watchTools()` already carries; displaying a price
+   * never implies authorization to spend it.
+   */
+  pricingTerms?: string
   nodeCount: number
 }
 
+/** The argument object handed to the JS tool handler. */
+export interface ToolInvokeArgs {
+  /**
+   * The invoked tool's original name (the `name` you published, not the
+   * sanitized id).
+   */
+  toolName: string
+  /** The invocation arguments as a JSON object string (default `{}`). */
+  argumentsJson: string
+}
+
 export interface ToolJs {
   toolId: string
   name?: string
@@ -5402,9 +6384,14 @@ export declare function transferStreamId(nonce: bigint): bigint
 
 /**
  * Cumulative NAT-traversal counters surfaced via
- * `NetMesh.traversalStats()`. All counters are monotonic u64s
- * and never reset — subtract snapshots for deltas. Exposed as
- * BigInt because JavaScript numbers can't round-trip full u64.
+ * `NetMesh.traversalStats()`. Base counters are monotonic u64s
+ * and never reset — subtract snapshots for deltas — with two
+ * exemptions: `punchesFailed` is derived at snapshot time
+ * (`attempted - succeeded`) and can decrease when an in-flight
+ * punch lands, and `portMappingRenewals` resets to zero on each
+ * fresh mapping install. Difference only the base counters for
+ * rates. Exposed as BigInt because JavaScript numbers can't
+ * round-trip full u64.
  *
  * Framing reminder (plan §5): NAT traversal is an optimization,
  * not a connectivity requirement. `relay_fallbacks` isn't a
@@ -5414,8 +6401,8 @@ export declare function transferStreamId(nonce: bigint): bigint
  */
 export interface TraversalStats {
   /**
-   * Number of hole-punch attempts the pair-type matrix
-   * elected to initiate. Bumps once per attempt, whether the
+   * Number of hole-punch attempts whose coordinator mediation
+   * succeeded. Bumps once per mediated attempt, whether the
    * punch eventually succeeds or falls back.
    */
   punchesAttempted: bigint
@@ -5425,6 +6412,12 @@ export interface TraversalStats {
    * punch-failure rate.
    */
   punchesSucceeded: bigint
+  /**
+   * **Derived** at snapshot time: `punchesAttempted -
+   * punchesSucceeded` (a punch in flight counts as failed
+   * until it resolves).
+   */
+  punchesFailed: bigint
   /**
    * Number of `connect_direct` resolutions that stayed on
    * the routed-handshake path — matrix-skipped pairs plus
@@ -5433,6 +6426,51 @@ export interface TraversalStats {
    * this counter.
    */
   relayFallbacks: bigint
+  /**
+   * Punch flows that gave up on a deadline. Failure *cause*
+   * counter — includes pre-mediation introduce-wait timeouts,
+   * so not a partition of `punchesFailed`.
+   */
+  punchTimeouts: bigint
+  /**
+   * Punch flows refused by a typed coordinator reject
+   * (rate-limited / unknown target reflex / no session with
+   * target / reflex mismatch). Cause counter.
+   */
+  punchRejections: bigint
+  /**
+   * Punch-needing pairs skipped because no rendezvous
+   * coordinator candidate existed. Cause counter; the caller
+   * stayed on the routed path.
+   */
+  rendezvousNoRelay: bigint
+  /** Background direct-path upgrades started. */
+  upgradesAttempted: bigint
+  /**
+   * Upgrades that replaced a relay-routed session with a
+   * punched direct session.
+   */
+  upgradesSucceeded: bigint
+  /**
+   * Upgrades deferred because the session was busy (open
+   * streams / unacked data). Retried later; not failures.
+   */
+  upgradesDeferredBusy: bigint
+  /**
+   * `true` while a UPnP / NAT-PMP / PCP port mapping is
+   * installed on the operator's router.
+   */
+  portMappingActive: boolean
+  /**
+   * Mapped external `"ip:port"`, or `null` when no mapping is
+   * active.
+   */
+  portMappingExternal?: string
+  /**
+   * Successful renewal ticks since the current mapping was
+   * installed. Resets on a fresh install.
+   */
+  portMappingRenewals: bigint
 }
 
 /**