@hivemind-os/collective-mcp-server 0.2.0

package/tests/metering.test.ts

@@ -0,0 +1,173 @@
+import { createMeteredResultEnvelope, serializeMeteredResultEnvelope, UsageMeter } from '@hivemind-os/collective-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import { PaymentRail, PaymentScheme, TaskStatus, type AgentCard } from '@hivemind-os/collective-types';
+
+import { runMeshMeteredExecute, runMeshVerifyResult } from '../src/tools/metering.js';
+
+function createAgent(): AgentCard {
+  return {
+    id: 'agent-1',
+    owner: 'owner',
+    did: 'did:mesh:provider' as AgentCard['did'],
+    name: 'Provider',
+    description: 'Test provider',
+    active: true,
+    version: 1,
+    registeredAt: Date.now(),
+    updatedAt: Date.now(),
+    endpoint: 'mesh://agent/provider',
+    capabilities: [
+      {
+        name: 'echo',
+        description: 'Echo capability',
+        version: '1.0.0',
+        pricing: {
+          rail: PaymentRail.SUI_ESCROW,
+          amount: 5n,
+          currency: 'MIST',
+        },
+        executionMode: 'async',
+        paymentRails: [PaymentRail.SUI_ESCROW],
+      },
+    ],
+  };
+}
+
+function createMeteredBlob(result: string) {
+  const resultBytes = new TextEncoder().encode(result);
+  const meter = new UsageMeter({ taskId: 'task-1', maxPrice: 10n, unitPrice: 2n });
+  meter.recordUnit(resultBytes);
+  return serializeMeteredResultEnvelope(createMeteredResultEnvelope(resultBytes, meter.getProof(), resultBytes.length));
+}
+
+function createContext(agent: AgentCard) {
+  const resultBlob = createMeteredBlob('verified-result');
+  return {
+    keypair: {} as never,
+    blobStore: {
+      store: vi.fn(async () => ({ blobId: 'blob-in' })),
+      fetch: vi.fn(async () => resultBlob),
+    },
+    taskClient: {
+      postMeteredTask: vi.fn(async () => ({ taskId: 'task-1' })),
+      getTask: vi.fn(async () => ({
+        id: 'task-1',
+        requester: '0xrequester',
+        provider: '0xprovider',
+        capability: 'echo',
+        category: 'general',
+        inputBlobId: 'blob-in',
+        resultBlobId: 'blob-out',
+        price: 2n,
+        paymentScheme: PaymentScheme.UPTO,
+        maxPrice: 10n,
+        meteredUnits: 1,
+        unitPrice: 2n,
+        verificationHash: new UsageMeter({ taskId: 'task-1', maxPrice: 10n, unitPrice: 2n }).getVerificationHash(),
+        status: TaskStatus.COMPLETED,
+        disputeWindowMs: 1,
+        createdAt: 1,
+        expiresAt: 2,
+        agreementHash: 'metered:echo',
+      })),
+      releaseMeteredPayment: vi.fn(async () => undefined),
+    },
+    agentCache: {
+      searchByCapability: vi.fn(() => [agent]),
+      getAgentByDID: vi.fn((did: string) => (did === agent.did ? agent : undefined)),
+      upsertAgent: vi.fn(),
+    },
+    registryClient: {
+      discoverByCapability: vi.fn(async () => []),
+      getAgentCardByOwner: vi.fn(async () => null),
+    },
+    spendingPolicy: {
+      evaluate: vi.fn(() => ({ approved: true })),
+      record: vi.fn(),
+    },
+    relayAuthProvider: undefined,
+    x402Client: undefined,
+    logger: {
+      warn: vi.fn(),
+    },
+    blob: resultBlob,
+  };
+}
+
+describe('metering tools', () => {
+  it('executes a metered task and verifies the result', async () => {
+    const agent = createAgent();
+    const context = createContext(agent);
+    const resultBytes = new TextEncoder().encode('verified-result');
+    const meter = new UsageMeter({ taskId: 'task-1', maxPrice: 10n, unitPrice: 2n });
+    meter.recordUnit(resultBytes);
+    (context.taskClient.getTask as ReturnType<typeof vi.fn>).mockResolvedValue({
+      id: 'task-1',
+      requester: '0xrequester',
+      provider: '0xprovider',
+      capability: 'echo',
+      category: 'general',
+      inputBlobId: 'blob-in',
+      resultBlobId: 'blob-out',
+      price: 2n,
+      paymentScheme: PaymentScheme.UPTO,
+      maxPrice: 10n,
+      meteredUnits: 1,
+      unitPrice: 2n,
+      verificationHash: meter.getVerificationHash(),
+      status: TaskStatus.COMPLETED,
+      disputeWindowMs: 1,
+      createdAt: 1,
+      expiresAt: 2,
+      agreementHash: 'metered:echo',
+    });
+
+    const result = await runMeshMeteredExecute({
+      capability: 'echo',
+      input: 'hello',
+      max_price_mist: 10,
+      unit_price_mist: 2,
+    }, context as never);
+
+    expect(result.task_id).toBe('task-1');
+    expect(result.verified).toBe(true);
+    expect(result.result).toBe('verified-result');
+    expect(context.taskClient.postMeteredTask).toHaveBeenCalledOnce();
+    expect(context.taskClient.releaseMeteredPayment).toHaveBeenCalledOnce();
+  });
+
+  it('verifies stored metered results', async () => {
+    const agent = createAgent();
+    const context = createContext(agent);
+    const resultBytes = new TextEncoder().encode('verified-result');
+    const meter = new UsageMeter({ taskId: 'task-1', maxPrice: 10n, unitPrice: 2n });
+    meter.recordUnit(resultBytes);
+    (context.taskClient.getTask as ReturnType<typeof vi.fn>).mockResolvedValue({
+      id: 'task-1',
+      requester: '0xrequester',
+      provider: '0xprovider',
+      capability: 'echo',
+      category: 'general',
+      inputBlobId: 'blob-in',
+      resultBlobId: 'blob-out',
+      price: 2n,
+      paymentScheme: PaymentScheme.UPTO,
+      maxPrice: 10n,
+      meteredUnits: 1,
+      unitPrice: 2n,
+      verificationHash: meter.getVerificationHash(),
+      status: TaskStatus.COMPLETED,
+      disputeWindowMs: 1,
+      createdAt: 1,
+      expiresAt: 2,
+      agreementHash: 'metered:echo',
+    });
+
+    const result = await runMeshVerifyResult({ task_id: 'task-1' }, context as never);
+
+    expect(result.verified).toBe(true);
+    expect(result.result).toBe('verified-result');
+    expect(result.metered_units).toBe(1);
+  });
+});

package/tests/multi-execute.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { PaymentRail, ProviderSelectionStrategy, type AgentCard } from '@hivemind-os/collective-types';
+
+const runMeshExecuteMock = vi.fn();
+const discoverAgentsByCapabilityMock = vi.fn();
+
+vi.mock('../src/tools/discover.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/tools/discover.js')>();
+  return {
+    ...actual,
+    discoverAgentsByCapability: (...args: unknown[]) => discoverAgentsByCapabilityMock(...args),
+  };
+});
+
+vi.mock('../src/tools/execute.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/tools/execute.js')>();
+  return {
+    ...actual,
+    runMeshExecute: (...args: unknown[]) => runMeshExecuteMock(...args),
+  };
+});
+
+import type { MeshToolContext } from '../src/context.js';
+import { runMeshMultiExecute } from '../src/tools/multi-execute.js';
+
+function createAgent(overrides: Partial<AgentCard> = {}): AgentCard {
+  return {
+    id: 'agent-1',
+    owner: 'owner-1',
+    did: 'did:mesh:agent-1' as AgentCard['did'],
+    name: 'Agent 1',
+    description: 'Test agent',
+    capabilities: [
+      {
+        name: 'echo',
+        description: 'Echo',
+        version: '1.0.0',
+        pricing: {
+          rail: PaymentRail.SUI_ESCROW,
+          amount: 5n,
+          currency: 'MIST',
+        },
+      },
+    ],
+    active: true,
+    version: 1,
+    registeredAt: 1_000,
+    updatedAt: 1_000,
+    ...overrides,
+  };
+}
+
+function createContext(): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {} as MeshToolContext['keypair'],
+    suiClient: {} as MeshToolContext['suiClient'],
+    registryClient: {
+      discoverByCapability: vi.fn().mockResolvedValue([]),
+      getAgentCard: vi.fn(),
+    } as unknown as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {
+      searchByCapability: vi.fn().mockReturnValue([]),
+      getAgentByDID: vi.fn(),
+      getAllActive: vi.fn().mockReturnValue([]),
+      upsertAgent: vi.fn(),
+      removeAgent: vi.fn(),
+    } as unknown as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {
+      evaluate: vi.fn(() => ({ approved: true })),
+      record: vi.fn(),
+    } as unknown as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+  };
+}
+
+describe('runMeshMultiExecute', () => {
+  it('selects multiple providers and aggregates the first successful result', async () => {
+    runMeshExecuteMock.mockImplementation(async (params: { provider_did?: string }) => ({
+      task_id: `task-${params.provider_did}`,
+      result: params.provider_did === 'did:mesh:agent-1' ? 'winner' : 'runner-up',
+      provider_did: params.provider_did ?? 'unknown',
+      price_mist: params.provider_did === 'did:mesh:agent-1' ? '5' : '7',
+      status: 'COMPLETED',
+      execution_mode: 'sync',
+      payment_rail: PaymentRail.SUI_ESCROW,
+    }));
+    const agents = [
+      createAgent(),
+      createAgent({ id: 'agent-2', did: 'did:mesh:agent-2' as AgentCard['did'], totalTasksCompleted: 10, capabilities: [{
+        name: 'echo',
+        description: 'Echo',
+        version: '1.0.0',
+        pricing: { rail: PaymentRail.SUI_ESCROW, amount: 7n, currency: 'MIST' },
+      }] }),
+    ];
+
+    discoverAgentsByCapabilityMock.mockResolvedValueOnce({
+      agents,
+      source: 'cache',
+    });
+
+    const result = await runMeshMultiExecute({
+      capability: 'echo',
+      input: { message: 'hello' },
+      fanOutCount: 2,
+      strategy: ProviderSelectionStrategy.CHEAPEST,
+    }, createContext());
+
+    expect(result.providers).toHaveLength(2);
+    expect(result.aggregated_result).toBe('winner');
+    expect(result.total_cost_mist).toBe('12');
+    expect(runMeshExecuteMock).toHaveBeenCalledTimes(2);
+  });
+});

package/tests/relay-registry.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeshToolContext } from '../src/context.js';
+import { runMeshRelayRegistry } from '../src/tools/relay-registry.js';
+
+function createContext(overrides: Partial<MeshToolContext> = {}): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {
+      getPublicKey: () => ({
+        toSuiAddress: () => '0xabc',
+      }),
+    } as MeshToolContext['keypair'],
+    suiClient: {
+      getBalance: vi.fn(),
+      queryEvents: vi.fn(),
+    } as unknown as MeshToolContext['suiClient'],
+    registryClient: {} as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {} as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {} as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+    relayRegistryClient: {
+      listRelays: vi.fn(),
+      registerRelay: vi.fn(),
+    } as unknown as MeshToolContext['relayRegistryClient'],
+    ...overrides,
+  };
+}
+
+describe('runMeshRelayRegistry', () => {
+  it('lists relays via the relay registry client', async () => {
+    const context = createContext();
+    vi.mocked(context.relayRegistryClient?.listRelays as never).mockResolvedValue([{ id: '0xrelay' }]);
+
+    const result = await runMeshRelayRegistry({ action: 'list' }, context);
+
+    expect(context.relayRegistryClient?.listRelays).toHaveBeenCalled();
+    expect(result).toMatchObject({ action: 'list', count: 1 });
+  });
+
+  it('registers a relay via the relay registry client', async () => {
+    const context = createContext();
+    vi.mocked(context.relayRegistryClient?.registerRelay as never).mockResolvedValue({ relayId: '0xrelay', txDigest: '0xtx' });
+
+    const result = await runMeshRelayRegistry({
+      action: 'register',
+      endpoint: 'wss://relay.mesh.example/ws',
+      stake_id: '0x123',
+      region: 'us-east',
+      routing_fee_bps: 50,
+      capabilities: ['routing', 'streaming'],
+    }, context);
+
+    expect(context.relayRegistryClient?.registerRelay).toHaveBeenCalledWith(expect.objectContaining({
+      endpoint: 'wss://relay.mesh.example/ws',
+      stakeId: '0x123',
+      region: 'us-east',
+      routingFeeBps: 50,
+      capabilities: ['routing', 'streaming'],
+      signer: context.keypair,
+    }));
+    expect(result).toMatchObject({ action: 'register', relay_id: '0xrelay', tx_digest: '0xtx' });
+  });
+});

package/tests/stake.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeshToolContext } from '../src/context.js';
+import { runMeshStake } from '../src/tools/stake.js';
+
+function createContext(overrides: Partial<MeshToolContext> = {}): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {
+      getPublicKey: () => ({
+        toSuiAddress: () => '0xabc',
+      }),
+    } as MeshToolContext['keypair'],
+    suiClient: {
+      getBalance: vi.fn(),
+      queryEvents: vi.fn(),
+    } as unknown as MeshToolContext['suiClient'],
+    registryClient: {} as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {} as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {} as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+    stakingClient: {
+      depositStake: vi.fn(),
+      getStakeByOwner: vi.fn(),
+      startDeactivation: vi.fn(),
+      withdrawStake: vi.fn(),
+    } as unknown as MeshToolContext['stakingClient'],
+    ...overrides,
+  };
+}
+
+describe('runMeshStake', () => {
+  it('deposits stake through the staking client', async () => {
+    const context = createContext();
+    vi.mocked(context.stakingClient?.depositStake as never).mockResolvedValue({ stakeId: '0xstake', txDigest: '0xtx' });
+
+    const result = await runMeshStake({ action: 'deposit', amount_sui: '10', stake_type: 'agent' }, context);
+
+    expect(context.stakingClient?.depositStake).toHaveBeenCalledWith({
+      amountMist: 10_000_000_000n,
+      stakeType: 'agent',
+      signer: context.keypair,
+    });
+    expect(result).toMatchObject({ action: 'deposit', stake_id: '0xstake', tx_digest: '0xtx' });
+  });
+
+  it('returns the current stake status', async () => {
+    const context = createContext();
+    vi.mocked(context.stakingClient?.getStakeByOwner as never).mockResolvedValue({
+      id: '0xstake',
+      owner: '0xabc',
+      stakeType: 'agent',
+      balanceMist: 10_000_000_000n,
+      stakedAt: 1,
+      deactivatedAt: 0,
+      slashedAmount: 0n,
+      isActive: true,
+      meetsMinium: true,
+    });
+
+    const result = await runMeshStake({ action: 'status' }, context);
+
+    expect(result).toMatchObject({ action: 'status', staked: true });
+  });
+
+  it('starts deactivation before withdrawing', async () => {
+    const context = createContext();
+    vi.mocked(context.stakingClient?.getStakeByOwner as never).mockResolvedValue({
+      id: '0xstake',
+      owner: '0xabc',
+      stakeType: 'agent',
+      balanceMist: 10_000_000_000n,
+      stakedAt: 1,
+      deactivatedAt: 0,
+      slashedAmount: 0n,
+    });
+    vi.mocked(context.stakingClient?.startDeactivation as never).mockResolvedValue({ cooldownEndsAt: 1234, txDigest: '0xtx' });
+
+    const result = await runMeshStake({ action: 'withdraw' }, context);
+
+    expect(result).toMatchObject({ action: 'deactivation_started', cooldown_ends_at: 1234 });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts", "tsup.config.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  target: 'es2022',
+});

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    passWithNoTests: false,
+  },
+});