@blocks-network/mcp-server 0.1.62 → 0.1.65

package/tests/download-artifact.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { downloadArtifact } from '../src/tools.js';
+import { makeFakeDeps, makeFakeClient, makeFakeSession } from './helpers.js';
+
+describe('download_artifact', () => {
+  it('returns inline text content for a text artifact when savePath is omitted', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'output.json',
+          mimeType: 'application/json',
+          data: new TextEncoder().encode('{"ok":true}'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't1', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't1', fileName: 'output.json' },
+      deps,
+    );
+
+    expect(client.connectMock).toHaveBeenCalledWith({ taskId: 't1' });
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0].text).toContain('[artifact: output.json]');
+    expect(res.content[0].text).toContain('{"ok":true}');
+    expect(session.closeMock).toHaveBeenCalledOnce();
+  });
+
+  it('returns base64 content for binary artifacts when savePath is omitted', async () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+    const session = makeFakeSession({
+      artifacts: [{ fileName: 'image.png', mimeType: 'image/png', data: bytes }],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't2', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't2', fileName: 'image.png' },
+      deps,
+    );
+
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0].text).toContain('image/png');
+    expect(res.content[0].text).toContain('base64');
+    expect(res.content[0].text).toContain(Buffer.from(bytes).toString('base64'));
+  });
+
+  it('writes to disk when savePath is provided', async () => {
+    const bytes = new TextEncoder().encode('hello');
+    const session = makeFakeSession({
+      artifacts: [{ fileName: 'note.txt', mimeType: 'text/plain', data: bytes }],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't3', state: 'completed' },
+      session,
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't3', fileName: 'note.txt', savePath: 'out/note.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBeUndefined();
+    expect(mocks.resolveSavePath).toHaveBeenCalledWith('out/note.txt');
+    expect(mocks.writeFile).toHaveBeenCalledWith('out/note.txt', bytes);
+    expect(res.content[0].text).toContain('Saved 5 bytes to out/note.txt');
+  });
+
+  it('returns an error when the requested artifact is not found', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'other.txt',
+          mimeType: 'text/plain',
+          data: new TextEncoder().encode('x'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't4', state: 'completed' },
+      session,
+    });
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't4', fileName: 'missing.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('"missing.txt" not found');
+    expect(res.content[0].text).toContain('other.txt');
+    expect(session.closeMock).toHaveBeenCalledOnce();
+  });
+
+  it('uses paid TaskClient for paid tasks', async () => {
+    const session = makeFakeSession({
+      artifacts: [
+        {
+          fileName: 'a.txt',
+          mimeType: 'text/plain',
+          data: new TextEncoder().encode('a'),
+        },
+      ],
+    });
+    const client = makeFakeClient({
+      task: { taskId: 't5', state: 'completed', billingMode: 'paid' },
+      session,
+    });
+    const { deps, mocks } = makeFakeDeps({ client });
+
+    await downloadArtifact({ taskId: 't5', fileName: 'a.txt' }, deps);
+
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('free');
+    expect(mocks.getTaskClient).toHaveBeenCalledWith('paid');
+  });
+
+  it('returns an error when connect fails', async () => {
+    const client = makeFakeClient({
+      task: { taskId: 't6', state: 'completed' },
+    });
+    client.connectMock.mockRejectedValueOnce(new Error('connect refused'));
+    const { deps } = makeFakeDeps({ client });
+
+    const res = await downloadArtifact(
+      { taskId: 't6', fileName: 'x.txt' },
+      deps,
+    );
+
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain('connect refused');
+  });
+});

package/tests/get-agent-status.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getAgentStatus } from '../src/tools.js';
+import {
+  fetchAgentStatus,
+  type AgentStatusResponse,
+} from '../src/agent-status.js';
+import {
+  PROTOCOL_VERSION_HEADER,
+  CURRENT_PROTOCOL_VERSION,
+} from '../src/protocol-headers.js';
+import { makeFakeDeps } from './helpers.js';
+
+function mockResponse(body: unknown, ok = true, status = 200): Response {
+  return { ok, status, json: async () => body } as Response;
+}
+
+describe('get_agent_status (handler)', () => {
+  it('forwards baseUrl, apiKey and agentNames to fetchAgentStatus and emits JSON', async () => {
+    const result: AgentStatusResponse = {
+      agents: {
+        alice: {
+          agentName: 'alice',
+          instances: [],
+          onlineCount: 2,
+          totalActiveTasks: 1,
+          taskCount: 1,
+        },
+      },
+    };
+    const { deps, mocks } = makeFakeDeps({
+      apiKey: 'bk_test',
+      agentStatusResult: result,
+    });
+
+    const res = await getAgentStatus({ agentNames: ['alice'] }, deps);
+
+    expect(mocks.fetchAgentStatus).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: 'bk_test',
+      agentNames: ['alice'],
+    });
+    const parsed = JSON.parse(res.content[0].text);
+    expect(parsed.agents.alice.onlineCount).toBe(2);
+  });
+});
+
+describe('fetchAgentStatus (HTTP helper)', () => {
+  it('builds /api/v1/agent-status URL with agentNames csv and protocol header', async () => {
+    const fetchImpl = vi
+      .fn()
+      .mockResolvedValue(mockResponse({ agents: {} }));
+
+    await fetchAgentStatus({
+      baseUrl: 'http://api.test/',
+      agentNames: ['alice', 'bob'],
+      apiKey: 'bk_test',
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    const [url, init] = fetchImpl.mock.calls[0];
+    const parsed = new URL(String(url));
+    expect(parsed.pathname).toBe('/api/v1/agent-status');
+    expect(parsed.searchParams.get('agentNames')).toBe('alice,bob');
+    const headers = init?.headers as Record<string, string>;
+    expect(headers[PROTOCOL_VERSION_HEADER]).toBe(CURRENT_PROTOCOL_VERSION);
+    expect(headers['Authorization']).toBe('Bearer bk_test');
+  });
+
+  it('rejects empty input', async () => {
+    await expect(
+      fetchAgentStatus({
+        baseUrl: 'http://api.test',
+        agentNames: [],
+      }),
+    ).rejects.toThrow(/at least one/);
+  });
+
+  it('rejects more than 50 names', async () => {
+    const names = Array.from({ length: 51 }, (_, i) => `a${i}`);
+    await expect(
+      fetchAgentStatus({
+        baseUrl: 'http://api.test',
+        agentNames: names,
+      }),
+    ).rejects.toThrow(/at most 50/);
+  });
+
+  it('rejects names with invalid characters', async () => {
+    await expect(
+      fetchAgentStatus({
+        baseUrl: 'http://api.test',
+        agentNames: ['has-a-hyphen'],
+      }),
+    ).rejects.toThrow(/Invalid agent name/);
+  });
+
+  it('throws on non-OK responses', async () => {
+    const fetchImpl = vi.fn().mockResolvedValue(mockResponse({}, false, 500));
+
+    await expect(
+      fetchAgentStatus({
+        baseUrl: 'http://api.test',
+        agentNames: ['alice'],
+        fetchImpl: fetchImpl as unknown as typeof fetch,
+      }),
+    ).rejects.toThrow('HTTP 500');
+  });
+});

package/tests/helpers.ts

@@ -89,6 +89,9 @@ export interface FakeClientConfig {
 export function makeFakeClient(cfg: FakeClientConfig = {}): TaskClientLike & {
   sendMessageMock: ReturnType<typeof vi.fn>;
   cancelTaskMock: ReturnType<typeof vi.fn>;
+  pauseTaskMock: ReturnType<typeof vi.fn>;
+  resumeTaskMock: ReturnType<typeof vi.fn>;
+  retryTaskMock: ReturnType<typeof vi.fn>;
   connectMock: ReturnType<typeof vi.fn>;
   listTasksMock: ReturnType<typeof vi.fn>;
   getTaskMock: ReturnType<typeof vi.fn>;
@@ -97,6 +100,9 @@ export function makeFakeClient(cfg: FakeClientConfig = {}): TaskClientLike & {
   const sendMessageMock = vi.fn().mockResolvedValue(session);
   const connectMock = vi.fn().mockResolvedValue(session);
   const cancelTaskMock = vi.fn().mockResolvedValue(undefined);
+  const pauseTaskMock = vi.fn().mockResolvedValue(undefined);
+  const resumeTaskMock = vi.fn().mockResolvedValue(undefined);
+  const retryTaskMock = vi.fn().mockResolvedValue(undefined);
   const listTasksMock = vi.fn().mockResolvedValue(
     cfg.listResult ?? { tasks: [], totalCount: 0 },
   );
@@ -105,11 +111,17 @@ export function makeFakeClient(cfg: FakeClientConfig = {}): TaskClientLike & {
   return {
     sendMessage: sendMessageMock,
     cancelTask: cancelTaskMock,
+    pauseTask: pauseTaskMock,
+    resumeTask: resumeTaskMock,
+    retryTask: retryTaskMock,
     connect: connectMock,
     listTasks: listTasksMock,
     getTask: getTaskMock,
     sendMessageMock,
     cancelTaskMock,
+    pauseTaskMock,
+    resumeTaskMock,
+    retryTaskMock,
     connectMock,
     listTasksMock,
     getTaskMock,
@@ -119,9 +131,13 @@ export function makeFakeClient(cfg: FakeClientConfig = {}): TaskClientLike & {
 export interface FakeDepsOverrides {
   baseUrl?: string;
   apiKey?: string;
+  orgId?: string;
   client?: TaskClientLike;
   agentEntry?: AgentEntryLike | null;
   listAgentsResult?: ListAgentsResult;
+  agentStatusResult?: { agents: Record<string, unknown> };
+  balance?: Record<string, unknown>;
+  topUpSession?: Record<string, unknown>;
   maxUploadBytes?: number;
   fileSize?: number;
 }
@@ -130,36 +146,76 @@ export function makeFakeDeps(overrides: FakeDepsOverrides = {}) {
   const client = overrides.client ?? makeFakeClient();
   const getBaseUrl = vi.fn().mockResolvedValue(overrides.baseUrl ?? 'http://api.test');
   const getApiKey = vi.fn().mockReturnValue(overrides.apiKey);
+  const getOrgId = vi.fn().mockReturnValue(overrides.orgId);
   const getTaskClient = vi.fn().mockResolvedValue(client);
   const getAgentByName = vi.fn().mockResolvedValue(overrides.agentEntry ?? null);
   const listAgents = vi
     .fn()
     .mockResolvedValue(overrides.listAgentsResult ?? { agents: [], totalCount: 0 });
+  const fetchAgentStatus = vi
+    .fn<ToolDeps['fetchAgentStatus']>()
+    .mockResolvedValue(
+      (overrides.agentStatusResult ?? { agents: {} }) as Awaited<
+        ReturnType<ToolDeps['fetchAgentStatus']>
+      >,
+    );
+  const getConsumerBalance = vi
+    .fn<ToolDeps['getConsumerBalance']>()
+    .mockResolvedValue(
+      (overrides.balance ?? {
+        balance: '0',
+        reservedBalance: '0',
+        availableBalance: '0',
+        updatedAt: '2026-05-28T00:00:00Z',
+      }) as Awaited<ReturnType<ToolDeps['getConsumerBalance']>>,
+    );
+  const createConsumerTopUp = vi
+    .fn<ToolDeps['createConsumerTopUp']>()
+    .mockResolvedValue(
+      (overrides.topUpSession ?? {
+        checkoutUrl: 'https://stripe.test/checkout/abc',
+        sessionId: 'cs_test_default',
+      }) as Awaited<ReturnType<ToolDeps['createConsumerTopUp']>>,
+    );
   const validateFilePath = vi.fn((p: string) => p);
+  const resolveSavePath = vi.fn((p: string) => p);
+  const writeFile = vi.fn();
   const fileSize = vi.fn().mockReturnValue(overrides.fileSize ?? 100);
-  const filePartFromPath = vi.fn(async (path: string, opts: { partId?: string; contentType?: string }) => ({
-    type: 'file' as const,
-    partId: opts.partId ?? 'file',
-    file: { id: 'file-id', mimeType: opts.contentType ?? 'application/octet-stream' },
-    _path: path,
-  }));
-  const textPart = vi.fn((text: string, partId: string) => ({
-    type: 'text' as const,
-    partId,
-    text,
-  }));
+  const filePartFromPath = vi.fn<ToolDeps['filePartFromPath']>(
+    async (path, opts) =>
+      ({
+        type: 'file' as const,
+        partId: opts?.partId ?? 'file',
+        file: { id: 'file-id', mimeType: opts?.contentType ?? 'application/octet-stream' },
+        _path: path,
+      }) as Awaited<ReturnType<ToolDeps['filePartFromPath']>>,
+  );
+  const textPart = vi.fn<ToolDeps['textPart']>(
+    (text, partId) =>
+      ({
+        type: 'text' as const,
+        partId,
+        text,
+      }) as ReturnType<ToolDeps['textPart']>,
+  );
 
   const deps: ToolDeps = {
     getBaseUrl,
     getApiKey,
+    getOrgId,
     getTaskClient,
     getAgentByName,
     listAgents,
+    fetchAgentStatus,
+    getConsumerBalance,
+    createConsumerTopUp,
     validateFilePath,
+    resolveSavePath,
+    writeFile,
     fileSize,
     maxUploadBytes: overrides.maxUploadBytes ?? 25 * 1024 * 1024,
-    filePartFromPath: filePartFromPath as unknown as ToolDeps['filePartFromPath'],
-    textPart: textPart as unknown as ToolDeps['textPart'],
+    filePartFromPath,
+    textPart,
   };
 
   return {
@@ -168,10 +224,16 @@ export function makeFakeDeps(overrides: FakeDepsOverrides = {}) {
     mocks: {
       getBaseUrl,
       getApiKey,
+      getOrgId,
       getTaskClient,
       getAgentByName,
       listAgents,
+      fetchAgentStatus,
+      getConsumerBalance,
+      createConsumerTopUp,
       validateFilePath,
+      resolveSavePath,
+      writeFile,
       fileSize,
       filePartFromPath,
       textPart,

package/tests/list-agents.test.ts

@@ -2,8 +2,18 @@ import { describe, it, expect } from 'vitest';
 import { listAgents } from '../src/tools.js';
 import { makeFakeDeps } from './helpers.js';
 
+// A status response where every named agent has one online instance, so the
+// default online-only filter is a no-op for these agents.
+function allOnline(...names: string[]) {
+  const agents: Record<string, unknown> = {};
+  for (const name of names) {
+    agents[name] = { agentName: name, instances: [], onlineCount: 1, taskCount: 0 };
+  }
+  return { agents };
+}
+
 describe('list_agents', () => {
-  it('renders one row per agent with skill names joined by commas', async () => {
+  it('renders one row per agent with tag names joined by commas', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: {
         agents: [
@@ -11,7 +21,7 @@ describe('list_agents', () => {
             agentName: 'alice',
             name: 'Alice',
             listing: 'public',
-            skills: [
+            tags: [
               { id: 'translate', name: 'Translate' },
               { id: 'summarize', name: 'Summarize' },
             ],
@@ -20,55 +30,142 @@ describe('list_agents', () => {
         ],
         totalCount: 2,
       },
+      agentStatusResult: allOnline('alice', 'bob'),
     });
 
     const res = await listAgents({}, deps);
     const lines = res.content[0].text.split('\n');
     expect(lines).toEqual([
-      'Agents (2):',
+      'Agents (2 online of 2 total):',
       'alice | Alice | public | Translate, Summarize',
       'bob | bob | private | ',
     ]);
   });
 
-  it('forwards baseUrl, apiKey, skill, listing, limit to the registry helper', async () => {
+  it('forwards baseUrl, apiKey, tag, listing, limit (as maxAgents) to the registry helper', async () => {
     const { deps, mocks } = makeFakeDeps({
       apiKey: 'sk-test',
       baseUrl: 'http://api.test',
     });
 
     await listAgents(
-      { skill: 'translate', listing: 'private', limit: 25 },
+      { tag: 'translate', listing: 'private', limit: 25 },
       deps,
     );
 
     expect(mocks.listAgents).toHaveBeenCalledWith({
       baseUrl: 'http://api.test',
       apiKey: 'sk-test',
-      skill: 'translate',
+      tag: 'translate',
       listing: 'private',
-      limit: 25,
+      maxAgents: 25,
     });
   });
 
   it('defaults to "public" for missing listing and uses agentName when name is absent', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: {
-        agents: [{ agentName: 'naked', skills: [] }],
+        agents: [{ agentName: 'naked', tags: [] }],
         totalCount: 1,
       },
+      agentStatusResult: allOnline('naked'),
     });
 
     const res = await listAgents({}, deps);
     expect(res.content[0].text).toContain('naked | naked | public |');
   });
 
-  it('uses agents.length as the count when totalCount is omitted', async () => {
+  it('uses the online agent count for the header, falling back to length for total', async () => {
     const { deps } = makeFakeDeps({
       listAgentsResult: { agents: [{ agentName: 'a' }, { agentName: 'b' }] },
+      agentStatusResult: allOnline('a', 'b'),
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2 online of 2 total):');
+  });
+
+  it('reports the registry total separately from the online count', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [{ agentName: 'online' }, { agentName: 'offline' }],
+        totalCount: 50,
+      },
+      agentStatusResult: {
+        agents: {
+          online: { agentName: 'online', instances: [], onlineCount: 1, taskCount: 0 },
+          offline: { agentName: 'offline', instances: [], onlineCount: 0, taskCount: 0 },
+        },
+      },
+    });
+
+    const res = await listAgents({}, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (1 online of 50 total):');
+  });
+
+  it('drops offline agents by default, keeping only those with online instances', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'online', name: 'Online' },
+          { agentName: 'offline', name: 'Offline' },
+        ],
+        totalCount: 2,
+      },
+      agentStatusResult: {
+        agents: {
+          online: { agentName: 'online', instances: [], onlineCount: 1, taskCount: 0 },
+          offline: { agentName: 'offline', instances: [], onlineCount: 0, taskCount: 0 },
+        },
+      },
     });
 
     const res = await listAgents({}, deps);
-    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2):');
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents (1 online of 2 total):',
+      'online | Online | public | ',
+    ]);
+    expect(mocks.fetchAgentStatus).toHaveBeenCalledWith({
+      baseUrl: 'http://api.test',
+      apiKey: undefined,
+      agentNames: ['online', 'offline'],
+    });
+  });
+
+  it('includes offline agents and skips the status check when includeOffline is true', async () => {
+    const { deps, mocks } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'online' },
+          { agentName: 'offline' },
+        ],
+        totalCount: 2,
+      },
+    });
+
+    const res = await listAgents({ includeOffline: true }, deps);
+    expect(res.content[0].text.split('\n')[0]).toBe('Agents (2 of 2 total):');
+    expect(mocks.fetchAgentStatus).not.toHaveBeenCalled();
+  });
+
+  it('drops agents whose names the status endpoint cannot query', async () => {
+    const { deps } = makeFakeDeps({
+      listAgentsResult: {
+        agents: [
+          { agentName: 'valid_name' },
+          { agentName: 'has-dash' },
+        ],
+        totalCount: 2,
+      },
+      agentStatusResult: allOnline('valid_name'),
+    });
+
+    const res = await listAgents({}, deps);
+    const lines = res.content[0].text.split('\n');
+    expect(lines).toEqual([
+      'Agents (1 online of 2 total):',
+      'valid_name | valid_name | public | ',
+    ]);
   });
 });