agent0-sdk 1.5.3 → 1.7.0

package/README.md

@@ -14,11 +14,16 @@ Agent0 SDK enables you to:
 - **Cross-chain registration** - One-line registration with IPFS nodes, Pinata, Filecoin, or HTTP URIs
 - **Public indexing** - Subgraph indexing both on-chain and IPFS data for fast search and retrieval
 
-## Release (1.5.3)
+## Release (1.7.0)
 
-This release includes the unified agent discovery/search API.
+This release adds two major new capabilities to the TypeScript SDK: **x402 payment-required HTTP** and **A2A (Agent-to-Agent)** messaging/task support.
 
-For breaking changes and migration notes, see `release_notes/RELEASE_NOTES_1.5.3.md` (and prior notes in `release_notes/`).
+- **x402 request flows**: `sdk.request()` / `sdk.fetchWithX402()` now return `{ x402Required: true, x402Payment }` on HTTP 402 instead of throwing, so callers can inspect payment requirements and continue with `x402Payment.pay()` or `x402Payment.payFirst()`.
+- **A2A client flows**: `Agent.messageA2A()`, `Agent.listTasks()`, `Agent.loadTask()`, and `sdk.createA2AClient(...)` let you talk to A2A endpoints from either a loaded `Agent` or an `AgentSummary`.
+- **Cross-chain/RPC improvements**: built-in default RPCs plus `overrideRpcUrls` support x402 payments and agent loading across multiple chains from one SDK instance.
+- **Examples, tests, and docs**: the release ships with a full `examples/x402-a2a-demo.ts`, extensive unit/integration/Anvil coverage, and updated public docs.
+
+For detailed changes, migration notes, and testing guidance, see `release_notes/RELEASE_NOTES_1.7.0.md` (and prior notes in `release_notes/`).
 
 **Bug reports & feedback:** GitHub: [Report issues](https://github.com/agent0lab/agent0-ts/issues) | Telegram: [Agent0 channel](https://t.me/agent0kitchen) | Email: team@ag0.xyz
 
@@ -41,7 +46,7 @@ npm install agent0-sdk
 To install a specific version explicitly:
 
 ```bash
-npm install agent0-sdk@1.5.3
+npm install agent0-sdk@1.7.0
 ```
 
 **Note:** This package is an ESM (ECMAScript Module) package. Use `import` statements in your code:
@@ -71,9 +76,9 @@ import { SDK } from 'agent0-sdk';
 // Initialize SDK with IPFS and subgraph
 const sdk = new SDK({
   chainId: 11155111, // Ethereum Sepolia testnet (use 1 for Ethereum Mainnet)
-  rpcUrl: process.env.RPC_URL!,
+  rpcUrl: process.env.RPC_URL, // Optional for supported chains (built-in default RPC is used if omitted)
   privateKey: process.env.PRIVATE_KEY ?? process.env.AGENT_PRIVATE_KEY, // Optional: for write operations
-  ipfs: 'pinata', // Options: 'pinata', 'filecoinPin', 'node'
+  ipfs: 'pinata', // Options: 'pinata', 'filecoinPin', 'node' (Kubo daemon), 'helia' (embedded)
   pinataJwt: process.env.PINATA_JWT // For Pinata
   // Subgraph URL auto-defaults from DEFAULT_SUBGRAPH_URLS
 });
@@ -81,7 +86,7 @@ const sdk = new SDK({
 
 ### 1b. Initialize SDK (browser-side with ERC-6963 wallets)
 
-In the browser you typically keep **reads on your `rpcUrl`** and use a wallet (EIP-1193) for **writes**.
+In the browser you typically keep **reads on your RPC** (default or `rpcUrl`) and use a wallet (EIP-1193) for **writes**.
 
 ```typescript
 import { SDK } from 'agent0-sdk';
@@ -137,6 +142,30 @@ console.log(`Agent registered: ${registrationFile.agentId}`); // e.g., "11155111
 console.log(`Agent URI: ${registrationFile.agentURI}`); // e.g., "ipfs://Qm..."
 ```
 
+### 2b. Fully on-chain registration (EIP-8004 `data:` URI)
+
+ERC-8004 allows storing the entire registration JSON **directly on-chain** by setting `agentURI`/`tokenURI` to a base64 JSON data URI (e.g. `data:application/json;base64,...`).
+
+```typescript
+// Register (or update) with a fully on-chain registration file (data URI)
+const tx = await agent.registerOnChain();
+const { result: registrationFile } = await tx.waitConfirmed({ timeoutMs: 180_000 });
+console.log(`Agent URI (on-chain data): ${registrationFile.agentURI}`);
+```
+
+Notes:
+
+- **Gas**: data URIs can be expensive; keep registration files compact.
+- **Size limit**: `loadAgent()` enforces a default max decoded size of **256 KiB** for data URIs. Override with:
+
+```typescript
+const sdk = new SDK({
+  chainId: 11155111,
+  rpcUrl: process.env.RPC_URL!,
+  registrationDataUriMaxBytes: 512 * 1024,
+});
+```
+
 ### 3. Load and Edit Agent
 
 ```typescript
@@ -229,10 +258,10 @@ const summary = await sdk.getReputationSummary('1:123'); // Ethereum Mainnet
 ```typescript
 // Optional: prepare an OFF-CHAIN feedback file (only needed for rich fields)
 const feedbackFile = sdk.prepareFeedbackFile({
-  capability: 'tools',
-  name: 'code_generation',
-  skill: 'python',
-  context: { sessionId: 'abc' },
+  text: 'Great agent!',
+  mcpTool: 'code_generation',
+  a2aSkills: ['python'],
+  a2aContextId: 'session:abc',
 });
 
 // Give feedback (on-chain fields are passed directly)
@@ -249,7 +278,7 @@ const { receipt, result: feedback } = await tx.waitConfirmed();
 
 // Search feedback
 const feedbackResults = await sdk.searchFeedback(
-  { agentId: '11155111:123', capabilities: ['tools'] },
+  { agentId: '11155111:123', capabilities: ['code_generation'] }, // capabilities filters by feedbackFile.mcpTool
   { minValue: 80, maxValue: 100 }
 );
 
@@ -270,16 +299,24 @@ const sdk = new SDK({
   filecoinPrivateKey: 'your-filecoin-private-key'
 });
 
-// Option 2: IPFS Node
+// Option 2: Embedded Helia (no daemon required)
+const sdk = new SDK({
+  chainId: 11155111,
+  rpcUrl: '...',
+  signer: privateKey,
+  ipfs: 'helia',
+});
+
+// Option 3: IPFS Node (Kubo daemon HTTP RPC API)
 const sdk = new SDK({
   chainId: 11155111,
   rpcUrl: '...',
   signer: privateKey,
   ipfs: 'node',
-  ipfsNodeUrl: 'https://ipfs.infura.io:5001'
+  ipfsNodeUrl: 'http://localhost:5001'
 });
 
-// Option 3: Pinata (free for ERC-8004 agents)
+// Option 4: Pinata (free for ERC-8004 agents)
 const sdk = new SDK({
   chainId: 11155111,
   rpcUrl: '...',
@@ -288,7 +325,7 @@ const sdk = new SDK({
   pinataJwt: 'your-pinata-jwt-token'
 });
 
-// Option 4: HTTP registration (no IPFS)
+// Option 5: HTTP registration (no IPFS)
 const sdk = new SDK({ chainId: 11155111, rpcUrl: '...', signer: privateKey });
 const regTx = await agent.registerHTTP('https://example.com/agent-registration.json');
 await regTx.waitConfirmed();
@@ -351,14 +388,18 @@ const allChainsReputation = await sdk.searchAgents(
 // Pagination has been removed; multi-chain results are returned as a flat list.
 ```
 
+### RPC URL defaults and overrides
+
+The SDK ships with **built-in default free RPC URLs** for supported chains (Ethereum, Base, Polygon mainnets and Sepolia testnets). Override order: **defaults** → **`rpcUrl`** (for the primary chain) → **`overrideRpcUrls`** (per-chain overrides, e.g. for x402 payments on other chains). You can omit `rpcUrl` when using a supported chain; pass `rpcUrl` and/or `overrideRpcUrls` to override.
+
 ### Default Chain Behavior
 
 When you initialize the SDK, you specify a default chain. Agent IDs without a `chainId:` prefix use the default chain:
 
 ```typescript
 const sdk = new SDK({
-  chainId: 11155111,  // Default chain
-  rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY'
+  chainId: 11155111,  // Default chain; rpcUrl optional (built-in default used)
+  rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY'  // optional override
 });
 
 // Uses default chain (11155111)

package/dist/core/a2a-client.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A2A (Agent-to-Agent) HTTP client: message:send, task query/cancel, response parsing.
+ * Used by Agent.messageA2A(); protocol details live here for testability and reuse.
+ * When x402Deps is provided, 402 is returned as x402Required + x402Payment.pay() instead of throwing.
+ */
+import type { Part, MessageResponse, TaskResponse, AgentTask, MessageA2AOptions, TaskSummary, ListTasksOptions, CredentialObject, AgentCardAuth } from '../models/a2a.js';
+import { type X402RequestDeps } from './x402-request.js';
+import type { X402RequiredResponse } from './x402-types.js';
+/** Result of sendMessage or task.message() when 402 is supported (x402Deps provided). */
+export type A2AMessageResult = MessageResponse | TaskResponse | X402RequiredResponse<MessageResponse | TaskResponse>;
+/** Normalized A2A interface from agent card (v1 supportedInterfaces or 0.3 url + additionalInterfaces). */
+export type NormalizedInterface = {
+    url: string;
+    binding: 'HTTP+JSON' | 'JSONRPC' | 'GRPC' | 'AUTO';
+    version: string | undefined;
+    tenant?: string;
+};
+/**
+ * Normalize agent card (v1 or 0.3 style) to a list of interfaces. Doc §6.1.
+ */
+export declare function normalizeInterfaces(card: Record<string, unknown> | null | undefined): NormalizedInterface[];
+/**
+ * Pick the best interface from the list that the client supports. Prefers HTTP+JSON then JSON-RPC. Doc §6.1.
+ * AUTO is always allowed so interfaces with no protocolBinding are picked and sendMessage will try both bindings.
+ */
+export declare function pickInterface(interfaces: NormalizedInterface[], preferredBindings: readonly NormalizedInterface['binding'][]): NormalizedInterface | null;
+/**
+ * Resolved A2A interface from an endpoint URL (agent card fetch + pickInterface + auth from card).
+ * Used by A2AClientFromSummary and by tests.
+ */
+export interface ResolvedA2A {
+    baseUrl: string;
+    a2aVersion: string;
+    binding: NormalizedInterface['binding'];
+    tenant?: string;
+    auth?: AgentCardAuth;
+}
+/**
+ * Resolve A2A interface from an endpoint URL: fetch agent card, pick interface, extract auth from card.
+ * Discovery: if URL looks like a card path, fetch it; else try /.well-known/agent-card.json and agent.json.
+ */
+export declare function resolveA2aFromEndpointUrl(url: string): Promise<ResolvedA2A>;
+export interface A2AAuth {
+    headers: Record<string, string>;
+    queryParams: Record<string, string>;
+}
+/**
+ * Apply credential to request using AgentCard securitySchemes and security (spec §2.5, OpenAPI 3 style).
+ * Walks security[] in order and uses the first scheme for which the credential object has a string value (first-match).
+ * Credential object keys must match scheme names (e.g. apiKey, bearerAuth). String credential normalizes to { apiKey }.
+ * Supported: apiKey (in: header|query|cookie + name), http (bearer → Authorization: Bearer; basic → Authorization: Basic base64(user:password)).
+ */
+export declare function applyCredential(credential: string | CredentialObject, auth: AgentCardAuth): A2AAuth;
+type CreateTaskHandleFn = (baseUrl: string, a2aVersion: string, taskId: string, contextId: string, x402Deps?: X402RequestDeps, auth?: A2AAuth, tenant?: string) => AgentTask;
+/**
+ * Parse JSON response from POST /message:send into MessageResponse or TaskResponse.
+ */
+export declare function parseMessageSendResponse(data: Record<string, unknown>, createTaskHandle: CreateTaskHandleFn, baseUrl: string, a2aVersion: string, x402Deps?: X402RequestDeps, auth?: A2AAuth): MessageResponse | TaskResponse;
+/**
+ * POST to /message:send, handle 402/!ok, parse JSON into MessageResponse | TaskResponse.
+ * Path order from version (+ optional tenant). On 404 try next path once.
+ */
+export declare function postAndParseMessageSend(baseUrl: string, a2aVersion: string, body: Record<string, unknown>, createTaskHandle: CreateTaskHandleFn, auth?: A2AAuth, tenant?: string): Promise<MessageResponse | TaskResponse>;
+/**
+ * Build an AgentTask handle that can query, message, and cancel.
+ * When x402Deps is provided, task methods use requestWithX402 and may return 402 + pay().
+ */
+export declare function createTaskHandle(baseUrl: string, a2aVersion: string, taskId: string, contextId: string, x402Deps?: X402RequestDeps, auth?: A2AAuth, tenant?: string): AgentTask;
+export interface ListTasksParams {
+    baseUrl: string;
+    a2aVersion: string;
+    options?: ListTasksOptions;
+    auth?: AgentCardAuth;
+    /** Optional tenant from agent card for path prefix (e.g. /tenants/{tenant}/tasks). */
+    tenant?: string;
+}
+/**
+ * Fetch a single task by ID (GET /tasks/:id). Used by loadTask to get contextId and build AgentTask.
+ * When x402Deps provided, 402 returns x402Required + pay() instead of throwing.
+ * Optional payment sends with first request (spec §4.2).
+ */
+export declare function getTask(baseUrl: string, a2aVersion: string, taskId: string, auth?: A2AAuth, x402Deps?: X402RequestDeps, payment?: string, tenant?: string): Promise<TaskSummary | X402RequiredResponse<TaskSummary>>;
+/**
+ * List tasks (GET /tasks with optional filter, historyLength). Fetches all pages internally.
+ * When x402Deps provided, 402 on the first request returns x402Required + pay().
+ */
+export declare function listTasks(params: ListTasksParams, x402Deps?: X402RequestDeps): Promise<TaskSummary[] | X402RequiredResponse<TaskSummary[]>>;
+export interface SendMessageParams {
+    baseUrl: string;
+    a2aVersion: string;
+    content: string | {
+        parts: Part[];
+    };
+    options?: MessageA2AOptions;
+    /** From AgentCard: where and how to send credential (per §2.5). */
+    auth?: AgentCardAuth;
+    /** Optional tenant from agent card for path prefix. */
+    tenant?: string;
+    /** When JSONRPC, use JSON-RPC binding; when AUTO (or unspecified in card), try HTTP+JSON then JSON-RPC. */
+    binding?: 'HTTP+JSON' | 'JSONRPC' | 'GRPC' | 'AUTO';
+}
+/**
+ * Send a message to the A2A endpoint. Returns MessageResponse or TaskResponse per spec §2.1.
+ * When x402Deps is provided, 402 is returned as x402Required + x402Payment.pay() instead of throwing.
+ * When binding is AUTO (card did not declare protocolBinding), tries HTTP+JSON first, then JSON-RPC on binding mismatch.
+ */
+export declare function sendMessage(params: SendMessageParams, x402Deps?: X402RequestDeps): Promise<MessageResponse | TaskResponse | X402RequiredResponse<MessageResponse | TaskResponse>>;
+export {};
+//# sourceMappingURL=a2a-client.d.ts.map

package/dist/core/a2a-client.d.ts.map

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