@blocks-network/mcp-server 0.1.62 → 0.1.65

package/LICENSE

@@ -0,0 +1,26 @@
+Blocks Network Software Development Kit License Agreement
+Copyright © 2026 Blocks Network Inc. All rights reserved.
+
+Subject to the terms and conditions of the license, you are hereby granted
+a non-exclusive, worldwide, royalty-free license to (a) copy and modify
+the software in source code or binary form for use with the software services
+and interfaces provided by Blocks Network, and (b) redistribute unmodified copies
+of the software to third parties. The software may not be incorporated in
+or used to provide any product or service competitive with the products
+and services of Blocks Network.
+
+The above copyright notice and this license shall be included
+in or with all copies or substantial portions of the software.
+
+This license does not grant you permission to use the trade names, trademarks,
+service marks, or product names of Blocks Network, except as required for reasonable
+and customary use in describing the origin of the software and reproducing
+the content of this license.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL BLOCKS NETWORK OR THE AUTHORS OR COPYRIGHT HOLDERS OF THE SOFTWARE BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -2,29 +2,30 @@
 
 MCP (Model Context Protocol) server that exposes Blocks Network consumer operations as tools for AI assistants.
 
-## Setup
-
-```bash
-cd mcp
-npm install
-npm run build
-```
+Get API Key: https://app.blocks.ai/manage/api-keys
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `BLOCKS_API_KEY` | Yes | Your Blocks Network API key |
+| `BLOCKS_ORG_ID` | For billing tools | Your consumer org ID (required by `check_balance` and `request_topup`). Find it in the dashboard URL or `blocks whoami --json`. |
 | `BLOCKS_MCP_FILE_ROOT` | No | Allowed root directory for file uploads (default: cwd) |
 
 All other configuration (keys, endpoints) is resolved automatically from CDM.
 
 ## Installation
 
+```bash
+npm i @blocks-network/mcp-server
+```
+
+`BLOCKS_ORG_ID` in the snippets below is only required by the billing tools (`check_balance`, `request_topup`); omit it if you don't plan to use them.
+
 ### Claude Code (CLI)
 
 ```bash
-claude mcp add blocks-network -- node /path/to/blocks-sdk/mcp/dist/index.js
+claude mcp add blocks-network -- npx @blocks-network/mcp-server
 ```
 
 Or add to your `.claude/settings.json`:
@@ -33,10 +34,11 @@ Or add to your `.claude/settings.json`:
 {
   "mcpServers": {
     "blocks-network": {
-      "command": "node",
-      "args": ["/path/to/blocks-sdk/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -51,10 +53,11 @@ Add to your `claude_desktop_config.json`:
 {
   "mcpServers": {
     "blocks-network": {
-      "command": "node",
-      "args": ["/path/to/blocks-sdk/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -73,10 +76,11 @@ Create an `mcp.json` file:
 {
   "mcpServers": {
     "blocks-network": {
-      "command": "node",
-      "args": ["/path/to/blocks-sdk/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -91,10 +95,11 @@ Add to your `~/.gemini/settings.json`:
 {
   "mcpServers": {
     "blocks-network": {
-      "command": "node",
-      "args": ["/path/to/blocks-sdk/mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["@blocks-network/mcp-server"],
       "env": {
-        "BLOCKS_API_KEY": "your-api-key"
+        "BLOCKS_API_KEY": "your-api-key",
+        "BLOCKS_ORG_ID": "your-consumer-org-id"
       }
     }
   }
@@ -109,9 +114,17 @@ Add to your `~/.gemini/settings.json`:
 | `get_task` | Get the current status of a task |
 | `list_tasks` | List tasks, optionally filtered by agent or state |
 | `cancel_task` | Cancel a running task |
+| `pause_task` | Pause a running pipe task |
+| `resume_task` | Resume a paused pipe task |
+| `retry_task` | Retry a failed task |
 | `list_agents` | List available agents in the registry |
+| `search_agent` | Search the registry for agents by free-text query (name, description, tags, provider, category) |
 | `get_agent_card` | Get the full agent card for a specific agent |
+| `get_agent_status` | Check live availability for agents (online instance count and total task count). Per-instance live activity counters (`activeTasks`, `concurrentTasksPerInstance`, `startedAt`, `totalActiveTasks`) are reserved in the response shape but currently return `0` — the backend does not yet populate them. |
 | `connect_task` | Connect to an existing task and stream events |
+| `download_artifact` | Download a single task artifact by file name (inline content or save to disk) |
+| `check_balance` | Get the consumer billing balance for the configured org |
+| `request_topup` | Create a Stripe Checkout URL to add USD to the consumer balance (user completes payment in a browser). Minimum top-up is `$5` (platform `MIN_BILLING_AMOUNT`). |
 
 ## Development
 

package/dist/agent-status.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent presence/availability helper.
+ *
+ * Calls GET /api/v1/agent-status with the Blocks-Protocol-Version
+ * header. Backend route is optionalAuth so the API key is forwarded
+ * when available but not required.
+ *
+ * Response shape mirrors the service's agent-status types.
+ */
+/** MUST stay in sync with the service's agent-status types. */
+export declare const MAX_AGENT_NAMES = 50;
+export declare const AGENT_NAME_PATTERN: RegExp;
+export interface AgentInstanceStatus {
+    instanceId: string;
+    uuid: string;
+    online: true;
+    /**
+     * Reserved — backend currently returns 0 (live activity counters are not
+     * yet populated by the agent-status service). Do not use for routing or
+     * availability decisions.
+     */
+    activeTasks: number;
+    /** Reserved — backend currently returns 0. See `activeTasks`. */
+    concurrentTasksPerInstance: number;
+    /** Reserved — backend currently returns 0. See `activeTasks`. */
+    startedAt: number;
+    sdkVersion: string | null;
+    cliVersion: string | null;
+    preferredProtocolVersion: string | null;
+    protocolVersions: string[];
+}
+export interface AgentStatus {
+    agentName: string;
+    instances: AgentInstanceStatus[];
+    onlineCount: number;
+    /** Reserved — backend currently returns 0. See `AgentInstanceStatus.activeTasks`. */
+    totalActiveTasks: number;
+    taskCount: number;
+}
+export interface AgentStatusResponse {
+    agents: Record<string, AgentStatus>;
+}
+export interface FetchAgentStatusOptions {
+    baseUrl: string;
+    agentNames: string[];
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function fetchAgentStatus(opts: FetchAgentStatusOptions): Promise<AgentStatusResponse>;

package/dist/agent-status.js

@@ -0,0 +1,40 @@
+/**
+ * Agent presence/availability helper.
+ *
+ * Calls GET /api/v1/agent-status with the Blocks-Protocol-Version
+ * header. Backend route is optionalAuth so the API key is forwarded
+ * when available but not required.
+ *
+ * Response shape mirrors the service's agent-status types.
+ */
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/** MUST stay in sync with the service's agent-status types. */
+export const MAX_AGENT_NAMES = 50;
+export const AGENT_NAME_PATTERN = /^[a-zA-Z0-9_]+$/;
+export async function fetchAgentStatus(opts) {
+    const names = opts.agentNames.map((n) => n.trim()).filter(Boolean);
+    if (names.length === 0) {
+        throw new Error('agentNames must contain at least one value');
+    }
+    if (names.length > MAX_AGENT_NAMES) {
+        throw new Error(`agentNames must be at most ${MAX_AGENT_NAMES} values`);
+    }
+    for (const n of names) {
+        if (!AGENT_NAME_PATTERN.test(n)) {
+            throw new Error(`Invalid agent name: ${n}`);
+        }
+    }
+    const params = new URLSearchParams({ agentNames: names.join(',') });
+    const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/agent-status?${params}`;
+    const headers = {
+        [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+    };
+    if (opts.apiKey)
+        headers['Authorization'] = `Bearer ${opts.apiKey}`;
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, { headers });
+    if (!response.ok) {
+        throw new Error(`Agent status failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}

package/dist/billing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Billing helpers — direct HTTP to the routes that accept Bearer
+ * API-key auth (`requireAuth` middleware path on the backend).
+ *
+ *   GET  /api/v1/billing/:orgId/consumer/balance
+ *   POST /api/v1/billing/:orgId/consumer/topup
+ *
+ * Other billing routes (ledger, usage-summary, dashboard-summary,
+ * topup-from-earnings) are session-only on the backend and are not
+ * callable from an MCP server holding only an API key.
+ */
+/**
+ * Platform minimum top-up amount in USD. MUST stay in sync with
+ * the service's MIN_BILLING_AMOUNT
+ * (decimal-dollar string `'5'`). The backend rejects values below this floor
+ * via `stripeMoneyAtLeast(MIN_BILLING_AMOUNT, ...)`; we mirror it here so MCP
+ * callers get the real contract up front instead of a runtime HTTP 400.
+ */
+export declare const MIN_TOPUP_AMOUNT_USD = 5;
+export interface ConsumerBalance {
+    /** Ledger balance as a decimal-dollar string (e.g. "12.34"). */
+    balance: string;
+    /** Currently reserved (held for in-flight tasks). */
+    reservedBalance: string;
+    /** balance - reservedBalance. */
+    availableBalance: string;
+    /** ISO timestamp of when the balance snapshot was taken. */
+    updatedAt: string;
+}
+export interface TopUpSession {
+    /** Stripe Checkout URL the user opens in a browser to complete payment. */
+    checkoutUrl: string;
+    /** Stripe Checkout session id. */
+    sessionId: string;
+}
+export interface BillingClientBase {
+    baseUrl: string;
+    orgId: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function getConsumerBalance(opts: BillingClientBase): Promise<ConsumerBalance>;
+export interface CreateTopUpOptions extends BillingClientBase {
+    /**
+     * Whole-dollar (or whole-cent decimal) USD amount, e.g. 25 or 19.99.
+     * Must be at least `MIN_TOPUP_AMOUNT_USD` ($5) — backend rejects below this.
+     */
+    amountUsd: number;
+}
+export declare function createConsumerTopUp(opts: CreateTopUpOptions): Promise<TopUpSession>;

package/dist/billing.js

@@ -0,0 +1,72 @@
+/**
+ * Billing helpers — direct HTTP to the routes that accept Bearer
+ * API-key auth (`requireAuth` middleware path on the backend).
+ *
+ *   GET  /api/v1/billing/:orgId/consumer/balance
+ *   POST /api/v1/billing/:orgId/consumer/topup
+ *
+ * Other billing routes (ledger, usage-summary, dashboard-summary,
+ * topup-from-earnings) are session-only on the backend and are not
+ * callable from an MCP server holding only an API key.
+ */
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/**
+ * Platform minimum top-up amount in USD. MUST stay in sync with
+ * the service's MIN_BILLING_AMOUNT
+ * (decimal-dollar string `'5'`). The backend rejects values below this floor
+ * via `stripeMoneyAtLeast(MIN_BILLING_AMOUNT, ...)`; we mirror it here so MCP
+ * callers get the real contract up front instead of a runtime HTTP 400.
+ */
+export const MIN_TOPUP_AMOUNT_USD = 5;
+function buildHeaders(apiKey) {
+    return {
+        [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+}
+function billingUrl(baseUrl, orgId, suffix) {
+    return `${baseUrl.replace(/\/+$/, '')}/api/v1/billing/${encodeURIComponent(orgId)}${suffix}`;
+}
+export async function getConsumerBalance(opts) {
+    const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/balance');
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, {
+        method: 'GET',
+        headers: buildHeaders(opts.apiKey),
+    });
+    if (!response.ok) {
+        throw new Error(`Balance lookup failed: HTTP ${response.status}`);
+    }
+    return (await response.json());
+}
+export async function createConsumerTopUp(opts) {
+    if (!Number.isFinite(opts.amountUsd) || opts.amountUsd <= 0) {
+        throw new Error('amountUsd must be a positive finite number');
+    }
+    if (Math.round(opts.amountUsd * 100) / 100 !== opts.amountUsd) {
+        throw new Error('amountUsd must be a whole-cent value (no sub-cent fractions)');
+    }
+    if (opts.amountUsd < MIN_TOPUP_AMOUNT_USD) {
+        throw new Error(`amountUsd must be at least $${MIN_TOPUP_AMOUNT_USD}.00 (platform minimum)`);
+    }
+    const amount = opts.amountUsd.toFixed(2);
+    const url = billingUrl(opts.baseUrl, opts.orgId, '/consumer/topup');
+    const fetchFn = opts.fetchImpl ?? fetch;
+    const response = await fetchFn(url, {
+        method: 'POST',
+        headers: buildHeaders(opts.apiKey),
+        body: JSON.stringify({ amount }),
+    });
+    if (!response.ok) {
+        let detail = '';
+        try {
+            detail = await response.text();
+        }
+        catch {
+            // ignore body decode failures
+        }
+        throw new Error(`Top-up failed: HTTP ${response.status}${detail ? ` — ${detail}` : ''}`);
+    }
+    return (await response.json());
+}

package/dist/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-import { resolve, relative } from 'node:path';
-import { realpathSync } from 'node:fs';
+import { resolve, relative, dirname } from 'node:path';
+import { realpathSync, mkdirSync, writeFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { TaskClient, textPart, filePartFromPath, fetchCdmConfig, getAgent, BLOCKS_MAX_UPLOAD_BYTES, } from '@blocks-network/sdk';
-import { listAgentsAuthenticated } from './registry-list.js';
-import { sendTask, getTask, listTasks, cancelTask, listAgents, getAgentCard, connectTask, defaultFileSize, } from './tools.js';
+import { listAllAgentsAuthenticated } from './registry-list.js';
+import { fetchAgentStatus, MAX_AGENT_NAMES } from './agent-status.js';
+import { getConsumerBalance, createConsumerTopUp } from './billing.js';
+import { sendTask, getTask, listTasks, cancelTask, pauseTask, resumeTask, retryTask, listAgents, searchAgents, getAgentCard, getAgentStatus, connectTask, downloadArtifact, checkBalance, requestTopup, defaultFileSize, } from './tools.js';
 const ALLOWED_ROOT = process.env.BLOCKS_MCP_FILE_ROOT ?? process.cwd();
 if (!process.env.BLOCKS_API_KEY) {
     console.error('Warning: BLOCKS_API_KEY is not set. Private agents and paid tasks will not work.');
@@ -27,6 +29,19 @@ function validateFilePath(filePath) {
     }
     return real;
 }
+function resolveSavePath(filePath) {
+    const root = realpathSync(resolve(ALLOWED_ROOT));
+    const resolved = resolve(root, filePath);
+    const rel = relative(root, resolved);
+    if (rel.startsWith('..') || resolve(root, rel) !== resolved) {
+        throw new Error(`Save path must be within ${ALLOWED_ROOT}`);
+    }
+    mkdirSync(dirname(resolved), { recursive: true });
+    return resolved;
+}
+function writeFile(filePath, data) {
+    writeFileSync(filePath, data);
+}
 const taskClients = new Map();
 let resolvedBaseUrl;
 async function getBaseUrl() {
@@ -52,10 +67,16 @@ async function getTaskClient(billingMode = 'free') {
 const deps = {
     getBaseUrl,
     getApiKey: () => process.env.BLOCKS_API_KEY,
+    getOrgId: () => process.env.BLOCKS_ORG_ID,
     getTaskClient,
     getAgentByName: (agentName, options) => getAgent(agentName, options),
-    listAgents: listAgentsAuthenticated,
+    listAgents: listAllAgentsAuthenticated,
+    fetchAgentStatus,
+    getConsumerBalance,
+    createConsumerTopUp,
     validateFilePath,
+    resolveSavePath,
+    writeFile,
     fileSize: defaultFileSize,
     maxUploadBytes: BLOCKS_MAX_UPLOAD_BYTES,
     filePartFromPath,
@@ -87,19 +108,67 @@ server.tool('list_tasks', 'List tasks, optionally filtered by agent or state', {
     limit: z.number().optional().describe('Max results to return'),
 }, (params) => listTasks(params, deps));
 server.tool('cancel_task', 'Cancel a running task', { taskId: z.string().describe('The task ID to cancel') }, (params) => cancelTask(params, deps));
-server.tool('list_agents', 'List available agents in the Blocks Network registry. Use listing="private" with an API key to discover your private agents.', {
-    skill: z.string().optional().describe('Filter by skill name'),
+server.tool('pause_task', 'Pause a running pipe task. Resume later with resume_task.', { taskId: z.string().describe('The task ID to pause') }, (params) => pauseTask(params, deps));
+server.tool('resume_task', 'Resume a paused pipe task', { taskId: z.string().describe('The task ID to resume') }, (params) => resumeTask(params, deps));
+server.tool('retry_task', 'Retry a failed task', { taskId: z.string().describe('The task ID to retry') }, (params) => retryTask(params, deps));
+server.tool('list_agents', 'List available agents in the Blocks Network registry. By default only agents with at least one online instance are returned; set includeOffline=true to also list registered agents that are currently offline. Use listing="private" with an API key to discover your private agents.', {
+    tag: z.string().optional().describe('Filter by tag slug'),
     listing: z
         .enum(['public', 'private'])
         .optional()
         .describe('Filter by listing visibility (default: public)'),
-    limit: z.number().optional().describe('Max results to return'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Max agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+        .boolean()
+        .optional()
+        .describe('Include agents with no online instances (default: false)'),
 }, (params) => listAgents(params, deps));
+server.tool('search_agent', 'Search the Blocks Network registry for agents matching a free-text query. The query matches against agent name, display name, description, tags, provider, and category, and supports field qualifiers (e.g. "agentname:translate", tag:"data"), quoted phrases, and negation ("-deprecated"). By default only agents with at least one online instance are returned; set includeOffline=true to also include matching agents that are currently offline. Use listing="private" with an API key to search your private agents.', {
+    query: z.string().describe('Free-text search query'),
+    tag: z.string().optional().describe('Additionally filter by tag slug'),
+    listing: z
+        .enum(['public', 'private'])
+        .optional()
+        .describe('Filter by listing visibility (default: public)'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Max matching agents to fetch across all pages; omit to fetch all'),
+    includeOffline: z
+        .boolean()
+        .optional()
+        .describe('Include agents with no online instances (default: false)'),
+}, (params) => searchAgents(params, deps));
 server.tool('get_agent_card', 'Get the full agent card for a specific agent', { agentName: z.string().describe('Agent name to look up') }, (params) => getAgentCard(params, deps));
+server.tool('get_agent_status', 'Check live availability for one or more agents: how many instances are online, total task count for the agent, and SDK/CLI versions per instance. (Per-instance live activity counters such as `activeTasks`, `concurrentTasksPerInstance`, `startedAt`, and `totalActiveTasks` are reserved in the response shape but not yet populated by the backend — they currently return 0.)', {
+    agentNames: z
+        .array(z.string())
+        .min(1)
+        .max(MAX_AGENT_NAMES)
+        .describe(`Agent names to check (1-${MAX_AGENT_NAMES})`),
+}, (params) => getAgentStatus(params, deps));
+server.tool('check_balance', 'Get the consumer billing balance for the configured org (BLOCKS_ORG_ID): ledger balance, active reservations, and available balance.', {}, (_params) => checkBalance({}, deps));
+server.tool('request_topup', 'Create a Stripe Checkout session to add USD to the consumer balance. Returns a URL the user opens in a browser to complete payment; the MCP server does not handle payment itself. Minimum top-up is $5 (platform `MIN_BILLING_AMOUNT`).', {
+    amountUsd: z
+        .number()
+        .positive()
+        .describe('Amount to add in USD (e.g. 25 or 19.99). Whole-cent precision. Must be at least $5 (platform minimum).'),
+}, (params) => requestTopup(params, deps));
 server.tool('connect_task', 'Connect to an existing task, stream events and data until completion', {
     taskId: z.string().describe('The task ID to connect to'),
     timeoutMs: z.number().optional().describe('Timeout in milliseconds (default: 60000)'),
 }, (params) => connectTask(params, deps));
+server.tool('download_artifact', 'Download a single artifact from a task by file name. If savePath is provided, writes the artifact to disk under BLOCKS_MCP_FILE_ROOT; otherwise returns the content inline (text decoded, binary base64-encoded).', {
+    taskId: z.string().describe('The task ID that produced the artifact'),
+    fileName: z.string().describe('Artifact file name as listed by get_task'),
+    savePath: z
+        .string()
+        .optional()
+        .describe('Optional path (relative to BLOCKS_MCP_FILE_ROOT) to write the artifact to'),
+}, (params) => downloadArtifact(params, deps));
 function shutdown() {
     for (const client of taskClients.values()) {
         client.destroy();

package/dist/protocol-headers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared protocol-version header constants for direct-HTTP backend
+ * callers (`registry-list`, `agent-status`, `billing`).
+ *
+ * MUST stay in sync with
+ * blocks-sdk/sdks/node/src/runtime/protocol-version.ts (the canonical
+ * source). Until the SDK exports these from its public surface, both
+ * files must update atomically when the protocol version bumps.
+ */
+export declare const PROTOCOL_VERSION_HEADER = "Blocks-Protocol-Version";
+export declare const CURRENT_PROTOCOL_VERSION = "2026-05-01";

package/dist/protocol-headers.js

@@ -0,0 +1,11 @@
+/**
+ * Shared protocol-version header constants for direct-HTTP backend
+ * callers (`registry-list`, `agent-status`, `billing`).
+ *
+ * MUST stay in sync with
+ * blocks-sdk/sdks/node/src/runtime/protocol-version.ts (the canonical
+ * source). Until the SDK exports these from its public surface, both
+ * files must update atomically when the protocol version bumps.
+ */
+export const PROTOCOL_VERSION_HEADER = 'Blocks-Protocol-Version';
+export const CURRENT_PROTOCOL_VERSION = '2026-05-01';

package/dist/registry-list.d.ts

@@ -5,15 +5,13 @@
  * header (required by the backend protocol-version middleware) and an
  * optional Bearer API key for private/owned listings.
  */
-export declare const PROTOCOL_VERSION_HEADER = "Blocks-Protocol-Version";
-export declare const CURRENT_PROTOCOL_VERSION = "2026-05-01";
 export interface AgentListEntry {
     agentName: string;
     name?: string;
     description?: string;
     listing?: string;
     billingMode?: string;
-    skills?: Array<{
+    tags?: Array<{
         id: string;
         name: string;
     }>;
@@ -21,13 +19,35 @@ export interface AgentListEntry {
 export interface ListAgentsOptions {
     baseUrl: string;
     apiKey?: string;
-    skill?: string;
+    /** Free-text search query (`q`); matches agent name, description, tags, etc. */
+    q?: string;
+    tag?: string;
     listing?: 'public' | 'private';
+    /** Page size for a single request. The backend caps this at 100. */
     limit?: number;
+    /** Opaque pagination cursor returned as `next` by a previous request. */
+    cursor?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ListAgentsResult {
     agents: AgentListEntry[];
     totalCount?: number;
+    /** Opaque cursor for the next page, or null/absent when there are no more. */
+    next?: string | null;
+    /** Total agents with at least one online instance (ignores cursor). */
+    totalOnlineCount?: number;
 }
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export declare const REGISTRY_PAGE_SIZE = 100;
 export declare function listAgentsAuthenticated(opts: ListAgentsOptions): Promise<ListAgentsResult>;
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export declare function listAllAgentsAuthenticated(opts: ListAgentsOptions & {
+    maxAgents?: number;
+}): Promise<ListAgentsResult>;

package/dist/registry-list.js

@@ -5,12 +5,17 @@
  * header (required by the backend protocol-version middleware) and an
  * optional Bearer API key for private/owned listings.
  */
-export const PROTOCOL_VERSION_HEADER = 'Blocks-Protocol-Version';
-export const CURRENT_PROTOCOL_VERSION = '2026-05-01';
+import { PROTOCOL_VERSION_HEADER, CURRENT_PROTOCOL_VERSION, } from './protocol-headers.js';
+/** Backend maximum page size for GET /api/v1/registry/agents. */
+export const REGISTRY_PAGE_SIZE = 100;
+/** Safety backstop so a misbehaving (never-null) cursor can't loop forever. */
+const MAX_PAGES = 1000;
 export async function listAgentsAuthenticated(opts) {
     const params = new URLSearchParams({ include: 'full' });
-    if (opts.skill)
-        params.set('skill', opts.skill);
+    if (opts.q)
+        params.set('q', opts.q);
+    if (opts.tag)
+        params.set('tag', opts.tag);
     if (opts.listing) {
         params.set('listing', opts.listing);
         if (opts.listing === 'private')
@@ -18,6 +23,8 @@ export async function listAgentsAuthenticated(opts) {
     }
     if (opts.limit)
         params.set('limit', String(opts.limit));
+    if (opts.cursor)
+        params.set('cursor', opts.cursor);
     const url = `${opts.baseUrl.replace(/\/+$/, '')}/api/v1/registry/agents?${params}`;
     const headers = {
         [PROTOCOL_VERSION_HEADER]: CURRENT_PROTOCOL_VERSION,
@@ -31,3 +38,42 @@ export async function listAgentsAuthenticated(opts) {
     }
     return (await response.json());
 }
+/**
+ * Fetch every agent by following the `next` cursor until it's null/absent.
+ *
+ * Uses the backend's maximum page size (100) to minimise round-trips. The
+ * optional `maxAgents` cap bounds the total number of agents collected and
+ * shrinks the final page request so we never over-fetch. The latest
+ * `totalCount`/`totalOnlineCount` seen are carried forward to the result.
+ */
+export async function listAllAgentsAuthenticated(opts) {
+    const agents = [];
+    let cursor = opts.cursor;
+    let totalCount;
+    let totalOnlineCount;
+    const cap = opts.maxAgents;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const remaining = cap !== undefined ? cap - agents.length : undefined;
+        if (remaining !== undefined && remaining <= 0)
+            break;
+        const pageSize = remaining !== undefined
+            ? Math.min(REGISTRY_PAGE_SIZE, remaining)
+            : REGISTRY_PAGE_SIZE;
+        const result = await listAgentsAuthenticated({
+            ...opts,
+            limit: pageSize,
+            cursor,
+        });
+        agents.push(...result.agents);
+        if (result.totalCount !== undefined)
+            totalCount = result.totalCount;
+        if (result.totalOnlineCount !== undefined) {
+            totalOnlineCount = result.totalOnlineCount;
+        }
+        cursor = result.next ?? undefined;
+        if (!cursor)
+            break;
+    }
+    const trimmed = cap !== undefined ? agents.slice(0, cap) : agents;
+    return { agents: trimmed, totalCount, totalOnlineCount, next: null };
+}