tenzro-sdk 0.1.0 → 0.3.0

package/LICENSE

@@ -48,7 +48,7 @@
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
       to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
+      submitted to the Licensor for inclusion in the Work by the copyright owner
       or by an individual or Legal Entity authorized to submit on behalf of
       the copyright owner. For the purposes of this definition, "submitted"
       means any form of electronic, verbal, or written communication sent
@@ -60,7 +60,7 @@
       designated in writing by the copyright owner as "Not a Contribution."
 
       "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
+      on behalf of whom a Contribution has been received by the Licensor and
       subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
@@ -106,7 +106,7 @@
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
+          within such NOTICE file, excluding any notices that do not
           pertain to any part of the Derivative Works, in at least one
           of the following places: within a NOTICE text file distributed
           as part of the Derivative Works; within the Source form or
@@ -175,18 +175,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Tenzro Network Contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -36,6 +36,126 @@ const result = await client.inference.request('gemma3-270m', 'Hello!', 100);
 console.log(result.output);
 ```
 
+## Browser-extension provider
+
+Browser dApps can route SDK calls through `window.tenzro` (any
+EIP-6963-announcing Tenzro extension) instead of opening a direct
+fetch to the node. The extension owns auth (DPoP-bound JWT), session
+management (CAIP-25), and user confirmation:
+
+```typescript
+import { TenzroClient, TenzroNotInstalledError } from 'tenzro-sdk';
+
+try {
+  const client = await TenzroClient.fromInjected();
+  const block = await client.getLatestBlock();
+} catch (err) {
+  if (err instanceof TenzroNotInstalledError) {
+    showInstallCta();
+  } else {
+    throw err;
+  }
+}
+```
+
+`fromInjected()` discovers the Tenzro provider via EIP-6963
+(default `rdns: network.tenzro.wallet`, override with the `rdns`
+option), wraps it in an `Eip1193Transport`, and returns a
+`TenzroClient` whose `rpc.call(...)` becomes `provider.request(...)`.
+No extra dependency to install — the EIP-6963 listener is bundled in
+the SDK. Node consumers can ignore this entrypoint entirely.
+
+## Catch-up sync
+
+A node lagging behind the network can pull batches of historical blocks via
+`getBlockRange`. The call returns up to 256 blocks per request along with a
+`nextHeight` + `moreAvailable` cursor so a sync loop steps over pruning gaps:
+
+```typescript
+let cur = 0;
+while (true) {
+  const r = await client.getBlockRange(cur, cur + 255, 256);
+  for (const b of r.blocks) { /* import block */ }
+  if (!r.moreAvailable) break;
+  cur = r.nextHeight;
+}
+```
+
+`isSyncing()` reports the live gap by comparing the local tip against
+peer-reported network tips (gossiped on `tenzro/status`); pair it with
+`getBlockRange` to drive a catch-up loop only when needed.
+
+## Transaction signing
+
+Every Tenzro transaction is hybrid post-quantum signed: a classical Ed25519
+signature **and** an ML-DSA-65 (FIPS 204) signature, both verified
+synchronously by the node against the canonical `Transaction::hash()`
+preimage (which commits to the PQ public key). An invalid or missing
+signature on either leg returns JSON-RPC error `-32003`.
+
+Two supported flows:
+
+1. **Atomic server-side sign + send (recommended).** The SDK dispatches
+   the request via `tenzro_signAndSendTransaction`. The node identifies
+   the signing wallet from the ambient DPoP-bound bearer JWT, looks up
+   the live nonce and gas price, constructs the hash preimage, signs
+   both legs, verifies them, and submits to the mempool — all in one
+   call. Private keys never travel over the wire. `nonce`, `chainId`,
+   and `gasPrice` are optional; `value` accepts the alias `amount` for
+   parity with the desktop and CLI clients. Self-sends (`from === to`)
+   return a `cannot transfer to self` validation error.
+
+   ```typescript
+   const txHash = await client.wallet.signAndSend({
+     from: '0x...',
+     to: '0x...',
+     value: 1_000_000_000_000_000_000n,
+     // nonce, chainId, gasPrice all optional — looked up live
+   });
+   ```
+
+   `client.sendTransaction(...)` and `client.wallet.signAndSend(...)`
+   are both thin wrappers over this RPC.
+
+2. **Offline sign, then submit.** Call `tenzro_signTransaction` to obtain
+   `{signature, public_key, pq_signature, pq_public_key, timestamp,
+   tx_hash}`, then resubmit later via `eth_sendRawTransaction` with all
+   six fields intact. Use this for batched or air-gapped submission.
+
+## Wallet model
+
+`client.wallet.create()` provisions a chain-agnostic 2-of-3 Ed25519 MPC
+wallet. Tenzro wallets are not per-chain — a single wallet projects into
+EVM, SVM, and Canton via the pointer-token model, so there is no `chain`
+parameter. VM-specific operations are exposed through `client.token`
+(`crossVmTransfer`, `wrapTnzo`); transfers to external chains use
+`client.bridge` (LayerZero V2, Chainlink CCIP), `client.debridge`,
+`client.wormhole`, or `client.lifi`.
+
+`client.getTransaction(hash)` resolves from finalized storage first, then
+falls back to the consensus mempool — `status` is `"pending"` while the
+transaction is in-mempool and `"finalized"` once block-included, so callers
+polling immediately after broadcast can distinguish "not yet finalized" from
+"unknown hash" (the call returns `null` only when the hash is unknown to
+both storage and mempool).
+
+## Durable state
+
+The node persists AI infrastructure to RocksDB and restores it on restart —
+SDK consumers see consistent state across node upgrades and reboots:
+
+- **Model catalog** — `ModelRegistry` writes `ModelInfo` records under
+  `info:<model_id>` in `CF_MODELS`; models survive restart without
+  re-registration.
+- **Agent runtime** — `AgentRuntime` persists `RegisteredAgent`,
+  `AgentLifecycleInfo`, and parent→children spawn trees under
+  `agent:`/`lifecycle:`/`children:` prefixes in `CF_AGENTS`. Terminated
+  agents are retained for audit of `state_history`, `registration_fee`,
+  and `tenzro_did`.
+- **Swarms** — `SwarmManager` persists `SwarmState` under `swarm:<swarm_id>`
+  in `CF_AGENTS` with write-through on create, status transitions, and
+  termination.
+
 ## AppClient (Developer Pattern)
 
 ```typescript
@@ -55,15 +175,33 @@ const result = await app.sponsorInference(user.address, 'gemma3-270m', 'Hello');
 
 | Module | Key Methods |
 |--------|------------|
+| `auth` | `onboardHuman()`, `onboardDelegatedAgent()`, `onboardAutonomousAgent()`, `revokeJwt()`, `revokeDid()`, `listPendingApprovals()`, `decideApproval()` |
 | `wallet` | `createWallet()`, `getBalance()`, `sendTransaction()` |
 | `identity` | `registerHuman()`, `resolveDid()`, `setUsername()` |
-| `agent` | `register()`, `spawnAgent()`, `createSwarm()`, `delegateTask()` |
-| `inference` | `listModels()`, `request()`, `estimateCost()` |
+| `agent` | `register(name, creator, capabilities)` (server-provisioned hybrid wallet), `registerWithKeys(name, creator, capabilities, publicKey, pqPublicKey)` (BYOK), `sendMessage(from, to, message)`, `sendMessageSigned({from, to, message, signature, pqSignature, messageType?, replyTo?})`, `spawnAgent()`, `createSwarm()`, `delegateTask()` |
+| `inference` | `listModels()`, `request()`, `estimateCost()`, plus multi-modal helpers for forecast, vision embed/similarity, text embedding, segmentation, detection, audio ASR, video embed (modality-aware routing via `tenzro_forecast`, `tenzro_visionEmbed`, `tenzro_textEmbed`, `tenzro_segment`, `tenzro_detect`, `tenzro_transcribe`, `tenzro_videoEmbed`) |
 | `token` | `createToken()`, `listTokens()`, `crossVmTransfer()` |
 | `nft` | `createCollection()`, `mintNft()`, `transferNft()` |
 | `bridge` | `bridgeTokens()`, `getRoutes()`, `getBridgeStatus()` |
-| `settlement` | `createEscrow()`, `releaseEscrow()`, `openPaymentChannel()` |
-| `payment` | `createChallenge()`, `payMpp()`, `payX402()` |
+| `wormhole` | `wormholeBridge()`, `getVaa()`, `redeemVaa()` |
+| `cct` | `cctListPools()`, `cctGetPool()` (Chainlink CCT v1.6+ pool registry) |
+| `erc8004` | `register8004Agent()`, `submit8004Feedback()`, `request8004Validation()`, `submit8004Validation()` (Trustless Agents Registry) |
+| `ap2` | `createAp2Mandate()`, `validateMandatePair()` (Agent Payments Protocol intent/cart/payment VDCs) |
+| `agentPayments` | Per-agent runtime spending policies (max-per-tx, daily-cap, enforce_operation pre-check) |
+| `bond` | AgentBond stake operations (Spec 9): `getAgentBond()`, `listAgentBonds()`, `postAgentBond()`, `increaseAgentBond()`, `withdrawAgentBond()` |
+| `insurance` | AgentBond insurance claims (Spec 9): `fileInsuranceClaim()`, `listInsuranceClaims()`, `getInsurancePool()` |
+| `lifecycle` | Agent lifecycle + kill-switch audit trail: `getAgentLifecycle()`, `listKillSwitchReceiptsByTarget()` |
+| `principalChain` | Receipt principal-chain queries (Spec 5): walk every receipt back to its human/organisational controller |
+| `cortex` | Reasoning-tier inference with TEE / TEE+ZK attestation; `DEFAULT_CORTEX_PRICING`, `computeCortexCost()` |
+| `adaptiveBurn` | Adaptive-burn governance dial — `getBurnRateConfig()`, `getSupplyMetrics()`, `getBurnRateRecommendation()` |
+| `seedAgent` | SeedAgent treasury earmark + protocol-owned bootstrap agent registry (Spec 10) |
+| `quota` | Dual-rail burn quota (Spec 3), prioritised mempool lanes, hot-state contention, DA backend registry |
+| `nanopayment` | Per-token streaming micropayment channels |
+| `circuitBreaker` | Provider health management for inference routing |
+| `erc7802` | Cross-chain token mint/burn primitive |
+| `provider` | Hardware detection, model serving, scheduling |
+| `settlement` | `createEscrow()`, `releaseEscrow()`, `refundEscrow()`, `getEscrow()`, `openPaymentChannel()` |
+| `payment` | `createChallenge()`, `payMpp()`, `payX402()`, `listX402Schemes()` (pluggable scheme adapters: `exact`, `permit2`) |
 | `compliance` | `registerCompliance()`, `checkCompliance()`, `freezeAddress()` |
 | `crypto` | `signMessage()`, `encrypt()`, `decrypt()`, `hashSha256()` |
 | `tee` | `detectTee()`, `getAttestation()`, `sealData()` |
@@ -81,12 +219,67 @@ const result = await app.sponsorInference(user.address, 'gemma3-270m', 'Hello');
 | `canton` | `listDomains()`, `submitCommand()` |
 | `skill` | `listSkills()`, `registerSkill()` |
 | `tool` | `listTools()`, `registerTool()` |
+| `svm-cross-vm` | Tenzro Cross-VM SVM-native program: `TENZRO_CROSS_VM_PROGRAM_ID_BASE58`, `encodeBridgeToEvm()`, `encodeBridgeFromEvm()`, `encodeRegisterTokenPointer()`, `encodeTransferCrossVm()`, `decodeCrossVmInstruction()` |
+
+## Auth (OAuth 2.1 + DPoP Onboarding)
+
+Onboarding uses OAuth 2.1 (RFC 6749 successor) + DPoP-bound JWTs (RFC 9449) +
+Rich Authorization Requests (RFC 9396). Participants — humans, delegated agents
+under a human controller, and fully autonomous agents — onboard via three RPCs
+that each provision a TDIP identity + MPC wallet and return a JWT bound to a
+holder-supplied DPoP `jkt` (RFC 7638 thumbprint).
+
+```typescript
+import { TenzroClient, TESTNET_CONFIG } from 'tenzro-sdk';
+
+const client = new TenzroClient(TESTNET_CONFIG);
+
+// Onboard a new human — returns identity, MPC wallet, and access token
+const session = await client.auth.onboardHuman('Alice', /* dpopJkt */ undefined);
+console.log('DID:    ', (session.identity as any).did);
+console.log('Wallet: ', (session.wallet as any).address);
+console.log('Token:  ', session.access_token.slice(0, 32), '…');
+
+// Subsequent privileged calls (sign + send tx, escrow, etc.) authenticate
+// ambiently via these env vars — the SDK forwards them as
+// `Authorization: DPoP <jwt>` and `DPoP: <proof>` on every JSON-RPC call:
+process.env.TENZRO_BEARER_JWT = session.access_token;
+process.env.TENZRO_DPOP_PROOF = '<freshly minted DPoP proof>';
+
+// Onboard a delegated agent under Alice's act-chain
+const agent = await client.auth.onboardDelegatedAgent(
+  (session.identity as any).did,
+  ['inference', 'settlement'],
+  { max_transaction_value: '1000000000000000000', allowed_chains: ['tenzro'] },
+);
+
+// Revoke (cascades through act-chain by DID)
+await client.auth.revokeDid((session.identity as any).did, 'lost device');
+```
+
+Holder-side DPoP proof generation is left to the caller — sign a per-request
+JWT with your Ed25519 holder key and the JWS-compact form lands in
+`TENZRO_DPOP_PROOF`. See RFC 9449 §4.
+
+## Examples
+
+```bash
+npx ts-node examples/quickstart.ts
+npx ts-node examples/advanced.ts
+npx ts-node examples/marketplace.ts        # 14 sections covering tasks, agents, skills, tools, NFTs, governance, payments, bridges
+npx ts-node examples/app_developer.ts
+npx ts-node examples/auth-session.ts
+npx ts-node examples/cortex.ts
+```
+
+See the [examples/](examples/) directory and [Tenzro Cookbook](https://github.com/tenzro/tenzro-cookbook).
 
 ## Live Testnet
 
 | Endpoint | URL |
 |----------|-----|
 | JSON-RPC | `https://rpc.tenzro.network` |
+| Web API | `https://api.tenzro.network` |
 | MCP Server | `https://mcp.tenzro.network/mcp` |
 | A2A Server | `https://a2a.tenzro.network` |
 

package/dist/adaptive-burn.d.ts

@@ -0,0 +1,40 @@
+import { RpcClient } from "./rpc";
+/**
+ * Client for the adaptive-burn governance dial (TNZO supply control).
+ *
+ * Surfaces the current `BurnRateConfig`, rolling `SupplyMetricsSnapshot`,
+ * the recommended action computed from the targets and metrics, and the
+ * list of in-flight adaptive-burn governance proposals.
+ *
+ * All endpoints are read-only — the auto-proposal generator and the
+ * EIP-1559 fee-market consumer ship alongside the governance executor
+ * wiring in a later wave.
+ */
+export declare class AdaptiveBurnClient {
+    private rpc;
+    constructor(rpc: RpcClient);
+    /**
+     * Returns the current `BurnRateConfig` (base/local/paymaster burn bps).
+     * @returns Active burn-rate configuration
+     */
+    getBurnRateConfig(): Promise<any>;
+    /**
+     * Returns the latest rolling supply metrics snapshot — circulating
+     * supply, epoch delta, burn breakdown, emission breakdown.
+     * @returns Latest `SupplyMetricsSnapshot`
+     */
+    getSupplyMetrics(): Promise<any>;
+    /**
+     * Computes the recommended adaptive-burn action from the current
+     * metrics and configured supply targets. May return `NoChange`,
+     * `IncreaseBurnPct`, `DecreaseBurnPct`, or alarm variants.
+     * @returns `BurnRateRecommendation`
+     */
+    getBurnRateRecommendation(): Promise<any>;
+    /**
+     * List in-flight adaptive-burn governance proposals.
+     * @returns Array of proposal records
+     */
+    listAdaptiveBurnProposals(): Promise<any[]>;
+}
+//# sourceMappingURL=adaptive-burn.d.ts.map

package/dist/adaptive-burn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-burn.d.ts","sourceRoot":"","sources":["../src/adaptive-burn.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAElC;;;;;;;;;;GAUG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,SAAS;IAElC;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC;IAIvC;;;;OAIG;IACG,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC;IAItC;;;;;OAKG;IACG,yBAAyB,IAAI,OAAO,CAAC,GAAG,CAAC;IAI/C;;;OAGG;IACG,yBAAyB,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CAGlD"}

package/dist/adaptive-burn.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveBurnClient = void 0;
+/**
+ * Client for the adaptive-burn governance dial (TNZO supply control).
+ *
+ * Surfaces the current `BurnRateConfig`, rolling `SupplyMetricsSnapshot`,
+ * the recommended action computed from the targets and metrics, and the
+ * list of in-flight adaptive-burn governance proposals.
+ *
+ * All endpoints are read-only — the auto-proposal generator and the
+ * EIP-1559 fee-market consumer ship alongside the governance executor
+ * wiring in a later wave.
+ */
+class AdaptiveBurnClient {
+    rpc;
+    constructor(rpc) {
+        this.rpc = rpc;
+    }
+    /**
+     * Returns the current `BurnRateConfig` (base/local/paymaster burn bps).
+     * @returns Active burn-rate configuration
+     */
+    async getBurnRateConfig() {
+        return this.rpc.call("tenzro_getBurnRateConfig", [{}]);
+    }
+    /**
+     * Returns the latest rolling supply metrics snapshot — circulating
+     * supply, epoch delta, burn breakdown, emission breakdown.
+     * @returns Latest `SupplyMetricsSnapshot`
+     */
+    async getSupplyMetrics() {
+        return this.rpc.call("tenzro_getSupplyMetrics", [{}]);
+    }
+    /**
+     * Computes the recommended adaptive-burn action from the current
+     * metrics and configured supply targets. May return `NoChange`,
+     * `IncreaseBurnPct`, `DecreaseBurnPct`, or alarm variants.
+     * @returns `BurnRateRecommendation`
+     */
+    async getBurnRateRecommendation() {
+        return this.rpc.call("tenzro_getBurnRateRecommendation", [{}]);
+    }
+    /**
+     * List in-flight adaptive-burn governance proposals.
+     * @returns Array of proposal records
+     */
+    async listAdaptiveBurnProposals() {
+        return this.rpc.call("tenzro_listAdaptiveBurnProposals", [{}]);
+    }
+}
+exports.AdaptiveBurnClient = AdaptiveBurnClient;
+//# sourceMappingURL=adaptive-burn.js.map

package/dist/adaptive-burn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-burn.js","sourceRoot":"","sources":["../src/adaptive-burn.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;GAUG;AACH,MAAa,kBAAkB;IACT;IAApB,YAAoB,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAEtC;;;OAGG;IACH,KAAK,CAAC,iBAAiB;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yBAAyB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,yBAAyB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,kCAAkC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,yBAAyB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAQ,kCAAkC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;CACF;AArCD,gDAqCC"}

package/dist/agent.d.ts

@@ -8,20 +8,68 @@ export declare class AgentClient {
     private rpc;
     constructor(rpc: RpcClient);
     /**
-     * Register a new AI agent on the network.
-     * @param agentId - Unique identifier for the agent
-     * @param name - Human-readable name
-     * @param capabilities - List of agent capabilities
-     * @returns Registration response with agent ID and status
+     * Register a new AI agent on the network. The node provisions a server-
+     * side hybrid (FROST Ed25519 + ML-DSA-65) wallet and binds it to a
+     * fresh `did:tenzro:machine:` identity. Returns the agent's `agent_id`,
+     * `wallet_address`, `tenzro_did`, the agent's `classical_public_key`
+     * (32-byte Ed25519 hex) and the `pq_verifying_key_len`.
+     *
+     * For self-custodial registration (no server-held keys), see
+     * {@link registerWithKeys}.
+     *
+     * @param name - Human-readable agent name
+     * @param creator - Hex-encoded address that will own this agent
+     * @param capabilities - Capability short names: `nlp`, `vision`, `code`,
+     *   `data`, `blockchain`, `smart_contract`, `api_integration`,
+     *   `coordination`. Anything else becomes a `Custom` capability.
      */
-    register(agentId: string, name: string, capabilities: string[]): Promise<RegisterAgentResponse>;
+    register(name: string, creator: string, capabilities: string[]): Promise<RegisterAgentResponse>;
     /**
-     * Send a message to another agent.
-     * @param agentId - Target agent identifier
-     * @param message - Message content
-     * @returns Message response with payload and message ID
+     * BYOK registration: register an agent self-custodially with a
+     * caller-supplied hybrid keypair. Both `publicKey` (32 bytes, Ed25519)
+     * and `pqPublicKey` (1952 bytes, ML-DSA-65) must be supplied as hex
+     * (with or without `0x` prefix). The node performs no wallet
+     * provisioning; the caller retains full control of the signing keys
+     * and is responsible for producing all `sendAgentMessage` signatures
+     * off-node. The returned envelope sets `byok: true` and omits the
+     * `classical_public_key` / `pq_verifying_key_len` fields (the caller
+     * already has them).
+     */
+    registerWithKeys(name: string, creator: string, capabilities: string[], publicKey: string, pqPublicKey: string): Promise<RegisterAgentResponse>;
+    /**
+     * Send an unsigned `AgentMessage` from one registered agent to another.
+     * Only valid when the local node's `MessageRouter` has
+     * `enable_signing == false` (test/dev configs). On the production
+     * router this call is rejected with a signature-required error — use
+     * {@link sendMessageSigned} instead.
+     */
+    sendMessage(from: string, to: string, message: string): Promise<AgentMessageResponse>;
+    /**
+     * Send a hybrid-signed `AgentMessage`. Both signature legs are required
+     * when the router enforces signing (production default); half-signed
+     * messages are rejected to prevent downgrade attacks.
+     *
+     * The signing preimage is `SHA-256(AgentMessage::signing_data())`,
+     * which depends on `from`, `to`, the resolved sender/recipient wallet
+     * addresses, the message body, the message type, and the optional
+     * `replyTo`. Callers must construct the same preimage off-node and
+     * produce both an Ed25519 (64-byte) and an ML-DSA-65 (3309-byte)
+     * signature. Both signatures are passed as hex (with or without `0x`
+     * prefix).
+     *
+     * `replyTo` (if used) MUST be set on the message before signing,
+     * because it is part of `signing_data` — the SDK forwards it verbatim
+     * so the server reconstructs the same preimage the caller signed.
      */
-    sendMessage(agentId: string, message: string): Promise<AgentMessageResponse>;
+    sendMessageSigned(params: {
+        from: string;
+        to: string;
+        message: string;
+        signature: string;
+        pqSignature: string;
+        messageType?: "task_request" | "task_response" | "query" | "query_response" | "notification" | "coordination" | "error";
+        replyTo?: string;
+    }): Promise<AgentMessageResponse>;
     /**
      * Delegate a task to an agent using the A2A protocol.
      * @param agentId - Target agent identifier
@@ -81,12 +129,19 @@ export declare class AgentClient {
     terminateSwarm(swarmId: string): Promise<TerminateSwarmResponse>;
     /**
      * Spawn a new agent from a registered template.
+     *
+     * When `parentMachineDid` is supplied, the spawned agent's effective
+     * delegation scope is the strict intersection of the parent's scope and
+     * the template's spec — the child can never be broader than its parent
+     * on any axis (numeric ceilings, allow-lists, time bound).
+     *
      * @param templateId - The template to instantiate
      * @param displayName - Optional human-readable name for the spawned agent
      * @param context - Optional key-value context passed to the agent at boot
+     * @param parentMachineDid - Optional parent machine DID to attenuate against
      * @returns Spawned agent info with agent_id, template_id, name, and status
      */
-    spawnAgentTemplate(templateId: string, displayName?: string, context?: Record<string, string>): Promise<SpawnAgentTemplateResponse>;
+    spawnAgentTemplate(templateId: string, displayName?: string, context?: Record<string, string>, parentMachineDid?: string): Promise<SpawnAgentTemplateResponse>;
     /**
      * Run an already-spawned template agent through its task loop.
      * @param agentId - The agent to run
@@ -173,5 +228,65 @@ export declare class AgentClient {
      * @returns Current gas policy
      */
     getGasPolicy(agentId: string): Promise<GasPolicy>;
+    /**
+     * Operational suspend (Active → Suspended). The reversible counterpart of
+     * `resumeAgent`. Distinct from the kill-switch `pauseAgent` /
+     * `quarantineAgent` axes (those require signed transactions).
+     * @param agentId - The agent identifier
+     * @param reason - Free-form audit reason
+     */
+    suspendAgent(agentId: string, reason: string): Promise<unknown>;
+    /**
+     * Recover a Suspended agent back to Active. Used to recover from auto-
+     * suspend (heartbeat monitor) or a manual `suspendAgent`.
+     * @param agentId - The agent identifier
+     */
+    resumeAgent(agentId: string): Promise<unknown>;
+    /**
+     * Send a liveness heartbeat for an agent. The heartbeat monitor uses
+     * `last_heartbeat` to decide whether to auto-suspend on the next sweep.
+     * @param agentId - The agent identifier
+     */
+    agentHeartbeat(agentId: string): Promise<unknown>;
+    /**
+     * Fetch every capability attestation registered on this node for
+     * `capability`. `capability` accepts the same short-form tags as
+     * `register` (`nlp`, `vision`, `code`, `data`, `blockchain`,
+     * `smart_contract`, `api_integration`, `coordination`) — anything else
+     * is treated as a `Custom` capability with that name.
+     *
+     * When `verifiedOnly` is `true` the node re-runs query-time signature
+     * + expiry checks before returning (defence in depth on top of
+     * submit-time verification per #52). Default is `false`.
+     *
+     * Returns `{capability, verified_only, attestations: [...], total}`.
+     *
+     * @param capability - Capability short-form or custom name
+     * @param verifiedOnly - Force query-time re-verification before returning
+     */
+    getCapabilityAttestations(capability: string, verifiedOnly?: boolean): Promise<unknown>;
+    /**
+     * Fetch every capability attestation issued for a specific agent. The
+     * reply includes the agent's registered capability list, the full
+     * attestation envelopes, and the agent's registered wallet address
+     * (used by the self-attestation guard).
+     *
+     * Returns `{agent_id, capabilities, attestations: [...],
+     * total_attestations, registered_address}`.
+     *
+     * @param agentId - The agent ID to look up
+     */
+    getAgentCapabilityAttestations(agentId: string): Promise<unknown>;
+    /**
+     * Pick the "best" agent on this node for `capability`. Selection prefers
+     * the most recent TEE-backed attestation, falling back to any agent that
+     * has registered the capability. `capability` is parsed with the same
+     * short-form/`Custom` rules as `getCapabilityAttestations`.
+     *
+     * Returns `{capability, best_agent: string | null, total_candidates}`.
+     *
+     * @param capability - Capability short-form or custom name
+     */
+    findBestAgentForCapability(capability: string): Promise<unknown>;
 }
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}