@hivemind-os/collective-mcp-server 0.2.0

package/src/tools/dispute.ts

@@ -0,0 +1,135 @@
+import { DisputeClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshDisputeParams {
+  action: 'open' | 'respond' | 'accept' | 'status';
+  task_id?: string;
+  dispute_id?: string;
+  evidence?: string;
+  evidence_blob_id?: string;
+  proposed_split_mist?: string | number;
+  arbitrator_address?: string;
+}
+
+export const meshDisputeTool = {
+  name: 'collective_dispute',
+  description: 'Open, respond to, accept, or inspect on-chain task disputes',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string', enum: ['open', 'respond', 'accept', 'status'] },
+      task_id: { type: 'string', description: 'Task object id' },
+      dispute_id: { type: 'string', description: 'Dispute object id' },
+      evidence: { type: 'string', description: 'Plain text or JSON-encoded evidence to store before opening/responding' },
+      evidence_blob_id: { type: 'string', description: 'Existing Walrus/blobstore blob id containing dispute evidence' },
+      proposed_split_mist: { type: 'string', description: 'Amount, in MIST, to allocate back to the requester' },
+      arbitrator_address: { type: 'string', description: 'Optional arbitrator address for open actions' },
+    },
+    required: ['action'],
+  },
+};
+
+export async function runMeshDispute(params: MeshDisputeParams, context: MeshToolContext): Promise<Record<string, unknown>> {
+  const client = context.disputeClient ?? new DisputeClient(context.suiClient, context.networkConfig);
+
+  switch (params.action) {
+    case 'open': {
+      if (!params.task_id) {
+        throw new Error('task_id is required when action=open');
+      }
+      const evidenceBlobId = await resolveEvidenceBlobId(params, context);
+      const result = await client.openDispute({
+        taskId: params.task_id,
+        evidenceBlobId,
+        proposedSplitMist: parseMist(params.proposed_split_mist, 'proposed_split_mist'),
+        arbitratorAddress: params.arbitrator_address,
+        signer: context.keypair as never,
+      });
+      return {
+        action: 'open',
+        dispute_id: result.disputeId,
+        task_id: params.task_id,
+        evidence_blob_id: evidenceBlobId,
+        tx_digest: result.txDigest,
+      };
+    }
+    case 'respond': {
+      if (!params.dispute_id) {
+        throw new Error('dispute_id is required when action=respond');
+      }
+      const evidenceBlobId = await resolveEvidenceBlobId(params, context);
+      const result = await client.respondToDispute({
+        disputeId: params.dispute_id,
+        evidenceBlobId,
+        proposedSplitMist: parseMist(params.proposed_split_mist, 'proposed_split_mist'),
+        signer: context.keypair as never,
+      });
+      return {
+        action: 'respond',
+        dispute_id: params.dispute_id,
+        evidence_blob_id: evidenceBlobId,
+        tx_digest: result.txDigest,
+      };
+    }
+    case 'accept': {
+      if (!params.dispute_id || !params.task_id) {
+        throw new Error('dispute_id and task_id are required when action=accept');
+      }
+      const result = await client.acceptResolution({
+        disputeId: params.dispute_id,
+        taskId: params.task_id,
+        signer: context.keypair as never,
+      });
+      return {
+        action: 'accept',
+        dispute_id: params.dispute_id,
+        task_id: params.task_id,
+        requester_amount_mist: result.requesterAmount.toString(),
+        provider_amount_mist: result.providerAmount.toString(),
+        tx_digest: result.txDigest,
+      };
+    }
+    case 'status': {
+      if ((params.dispute_id ? 1 : 0) + (params.task_id ? 1 : 0) !== 1) {
+        throw new Error('Provide exactly one of dispute_id or task_id when action=status');
+      }
+      const dispute = params.dispute_id
+        ? await client.getDispute(params.dispute_id)
+        : await client.getDisputeByTask(params.task_id as string);
+      if (!dispute) {
+        throw new Error(params.task_id ? `No dispute found for task ${params.task_id}.` : `Dispute ${params.dispute_id ?? ''} was not found.`);
+      }
+      return {
+        action: 'status',
+        dispute,
+      };
+    }
+    default:
+      throw new Error(`Unknown dispute action: ${String(params.action)}`);
+  }
+}
+
+async function resolveEvidenceBlobId(params: MeshDisputeParams, context: MeshToolContext): Promise<string> {
+  if ((params.evidence_blob_id ? 1 : 0) + (params.evidence ? 1 : 0) !== 1) {
+    throw new Error('Provide exactly one of evidence or evidence_blob_id for dispute open/respond actions');
+  }
+  if (params.evidence_blob_id) {
+    return params.evidence_blob_id;
+  }
+  if (!params.evidence) {
+    throw new Error('evidence or evidence_blob_id is required for dispute open/respond actions');
+  }
+  const stored = await context.blobStore.store(new TextEncoder().encode(params.evidence));
+  return stored.blobId;
+}
+
+function parseMist(value: string | number | undefined, field: string): bigint {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    return BigInt(value.trim());
+  }
+  throw new Error(`${field} must be a non-negative integer string.`);
+}

package/src/tools/execute-async.ts

@@ -0,0 +1,39 @@
+import type { MeshToolContext } from '../context.js';
+import { prepareMeshExecution, type MeshExecuteParams } from './execute.js';
+
+export interface MeshExecuteAsyncParams
+  extends Pick<MeshExecuteParams, 'capability' | 'provider_did' | 'input' | 'max_price_mist'> {}
+
+export const meshExecuteAsyncTool = {
+  name: 'collective_execute_async',
+  description: 'Submit a mesh task and return immediately',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      capability: { type: 'string', description: 'Capability name to execute' },
+      provider_did: { type: 'string', description: 'Specific provider DID to use' },
+      input: { type: 'string', description: 'Task input payload' },
+      max_price_mist: { type: 'number', description: 'Maximum spend in MIST' },
+    },
+    required: ['capability', 'input'],
+  },
+};
+
+export async function runMeshExecuteAsync(
+  params: MeshExecuteAsyncParams,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  provider_did: string;
+  price_mist: string;
+  status: 'OPEN';
+}> {
+  const prepared = await prepareMeshExecution(params, context);
+
+  return {
+    task_id: prepared.taskId,
+    provider_did: prepared.providerDid,
+    price_mist: prepared.priceMist.toString(),
+    status: 'OPEN',
+  };
+}

package/src/tools/execute.ts

@@ -0,0 +1,418 @@
+import { PaymentRail, TaskStatus, type AgentCard, type Capability, type Task } from '@hivemind-os/collective-types';
+import { PaymentRailSelector, RelayConsumerClient, ReputationEventPublisher, type SelectedPaymentRail } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+import { fetchMeshBlob, hexToBytes, supportsEncryptedBlobs } from '../encryption.js';
+import { resolveProviderCapability } from './discover.js';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const DEFAULT_TIMEOUT_SECONDS = 120;
+const DEFAULT_DISPUTE_WINDOW_MS = 5 * 60_000;
+const DEFAULT_EXPIRY_HOURS = 24;
+
+export interface MeshExecuteParams {
+  capability: string;
+  provider_did?: string;
+  input: string;
+  max_price_mist?: number;
+  timeout_seconds?: number;
+  mode?: 'auto' | 'sync' | 'async';
+}
+
+export const meshExecuteTool = {
+  name: 'collective_execute',
+  description: 'Execute a mesh task. Returns a task handle (async) if the client supports MCP Tasks, otherwise blocks until completion.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      capability: { type: 'string', description: 'Capability name to execute' },
+      provider_did: { type: 'string', description: 'Specific provider DID to use' },
+      input: { type: 'string', description: 'Task input payload' },
+      max_price_mist: { type: 'number', description: 'Maximum spend in MIST' },
+      timeout_seconds: { type: 'number', description: 'Polling timeout in seconds (default 120)' },
+      mode: { type: 'string', enum: ['auto', 'sync', 'async'], description: 'Execution preference (default auto)' },
+    },
+    required: ['capability', 'input'],
+  },
+};
+
+export async function runMeshExecute(
+  params: MeshExecuteParams,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  result: string;
+  provider_did: string;
+  price_mist: string;
+  status: string;
+  execution_mode: 'sync' | 'async';
+  payment_rail: PaymentRail;
+  payment_receipt?: string;
+  latency_ms?: number;
+}> {
+  const resolved = await resolveProviderCapability(params.capability, context, params.provider_did);
+  const priceMist = resolved.capability.pricing.amount;
+  const maxPrice = toOptionalBigInt(params.max_price_mist);
+
+  if (maxPrice !== undefined && priceMist > maxPrice) {
+    throw new Error(`Provider price ${priceMist.toString()} exceeds max_price_mist ${maxPrice.toString()}.`);
+  }
+
+  const mode = params.mode ?? 'auto';
+  if (mode !== 'async') {
+    const relayResult = await tryRelayExecution(params, context, resolved, priceMist);
+    if (relayResult) {
+      await publishSuccessfulReputationEvent(context, {
+        providerDid: relayResult.provider_did,
+        taskId: relayResult.task_id,
+        capability: resolved.capability.name,
+        priceMist,
+        latencyMs: relayResult.latency_ms,
+      });
+      return relayResult;
+    }
+  }
+
+  const prepared = await prepareAsyncExecution(params, context, resolved, priceMist);
+  const task = await waitForTaskCompletion(prepared.taskId, context, params.timeout_seconds);
+
+  if (!task.resultBlobId) {
+    throw new Error(`Task ${prepared.taskId} completed without a result blob.`);
+  }
+
+  const resultBytes = await fetchMeshBlob(context.blobStore, task.resultBlobId);
+  if (!resultBytes) {
+    throw new Error(`Result blob ${task.resultBlobId} was not found.`);
+  }
+
+  await context.taskClient.releasePayment({
+    taskId: prepared.taskId,
+    keypair: context.keypair,
+  });
+  context.spendingPolicy.record({
+    amountMist: prepared.priceMist,
+    rail: prepared.rail,
+    taskId: prepared.taskId,
+    appId: prepared.providerDid,
+    originAppName: context.originAppName,
+  });
+
+  await publishSuccessfulReputationEvent(context, {
+    providerDid: prepared.providerDid,
+    taskId: prepared.taskId,
+    capability: resolved.capability.name,
+    priceMist: prepared.priceMist,
+    latencyMs: task.acceptedAt && task.completedAt ? task.completedAt - task.acceptedAt : undefined,
+  });
+
+  return {
+    task_id: prepared.taskId,
+    result: decoder.decode(resultBytes),
+    provider_did: prepared.providerDid,
+    price_mist: prepared.priceMist.toString(),
+    status: TaskStatus[TaskStatus.RELEASED],
+    execution_mode: 'async',
+    payment_rail: prepared.rail,
+  };
+}
+
+export async function prepareMeshExecution(
+  params: Pick<MeshExecuteParams, 'capability' | 'provider_did' | 'input' | 'max_price_mist'>,
+  context: MeshToolContext,
+): Promise<{
+  taskId: string;
+  providerDid: string;
+  priceMist: bigint;
+  rail: PaymentRail;
+}> {
+  const resolved = await resolveProviderCapability(params.capability, context, params.provider_did);
+  return prepareAsyncExecution(params, context, resolved, resolved.capability.pricing.amount);
+}
+
+async function prepareAsyncExecution(
+  params: Pick<MeshExecuteParams, 'input' | 'max_price_mist'>,
+  context: MeshToolContext,
+  resolved: Awaited<ReturnType<typeof resolveProviderCapability>>,
+  priceMist: bigint,
+): Promise<{
+  taskId: string;
+  providerDid: string;
+  priceMist: bigint;
+  rail: PaymentRail;
+}> {
+  if (resolved.capability.pricing.rail !== PaymentRail.SUI_ESCROW) {
+    throw new Error(`Capability ${resolved.capability.name} does not support SUI escrow execution.`);
+  }
+
+  approveSpend(context, priceMist, resolved.capability.pricing.rail, resolved.agent.did);
+
+  const { blobId } = await storeTaskInput(context, resolved.agent, encoder.encode(params.input));
+  const posted = await context.taskClient.postTask({
+    capability: resolved.capability.name,
+    category: 'general',
+    inputBlobId: blobId,
+    priceMist,
+    disputeWindowMs: DEFAULT_DISPUTE_WINDOW_MS,
+    expiryHours: DEFAULT_EXPIRY_HOURS,
+    keypair: context.keypair,
+  });
+
+  return {
+    taskId: posted.taskId,
+    providerDid: resolved.agent.did,
+    priceMist,
+    rail: resolved.capability.pricing.rail,
+  };
+}
+
+async function tryRelayExecution(
+  params: MeshExecuteParams,
+  context: MeshToolContext,
+  resolved: Awaited<ReturnType<typeof resolveProviderCapability>>,
+  priceMist: bigint,
+) {
+  const relayUrl = getRelayUrl(resolved.agent);
+  if (!relayUrl || !context.relayAuthProvider) {
+    return null;
+  }
+
+  try {
+    const selector = context.paymentRailSelector ?? new PaymentRailSelector();
+    const selectedRail = selector.selectRail({
+      executionMode: 'sync',
+      consumerHasSuiWallet: Boolean(context.relayAuthProvider),
+      consumerHasEvmWallet: Boolean(context.x402Client),
+      providerAcceptsSui: providerAcceptsSui(resolved.capability),
+      providerAcceptsX402: providerAcceptsX402(resolved.agent, resolved.capability),
+      amount: priceMist,
+      currency: resolved.capability.pricing.currency,
+    });
+    const rail = toPaymentRail(selectedRail);
+
+    approveSpend(context, priceMist, rail, resolved.agent.did);
+
+    const client = new RelayConsumerClient(context.x402Client ?? null, context.relayAuthProvider, { relayUrl });
+    const response = await client.executeSync({
+      providerDid: resolved.agent.did,
+      capability: resolved.capability.name,
+      input: params.input,
+      paymentRail: rail,
+      timeoutMs: normalizeTimeoutMs(params.timeout_seconds),
+    });
+
+    const taskId = response.taskId ?? `relay-${resolved.agent.did}-${Date.now()}`;
+    context.spendingPolicy.record({
+      amountMist: priceMist,
+      rail,
+      taskId,
+      appId: resolved.agent.did,
+      originAppName: context.originAppName,
+    });
+
+    return {
+      task_id: taskId,
+      result: stringifyRelayResult(response.result),
+      provider_did: response.providerDid ?? resolved.agent.did,
+      price_mist: priceMist.toString(),
+      status: 'COMPLETED',
+      execution_mode: 'sync' as const,
+      payment_rail: rail,
+      payment_receipt: response.paymentReceipt,
+      latency_ms: response.latencyMs,
+    };
+  } catch (error) {
+    if (!shouldFallbackToAsync(error)) {
+      throw error;
+    }
+
+    context.logger?.warn?.(
+      { err: error, providerDid: resolved.agent.did, capability: resolved.capability.name },
+      'Relay execution unavailable; falling back to async Sui flow.',
+    );
+    return null;
+  }
+}
+
+export async function waitForTaskCompletion(
+  taskId: string,
+  context: MeshToolContext,
+  timeoutSeconds = DEFAULT_TIMEOUT_SECONDS,
+): Promise<Task> {
+  const timeoutMs = normalizeTimeoutMs(timeoutSeconds);
+  const startedAt = Date.now();
+
+  while (true) {
+    const task = await context.taskClient.getTask(taskId);
+    if (!task) {
+      throw new Error(`Task ${taskId} was not found.`);
+    }
+
+    if (task.status === TaskStatus.COMPLETED || task.status === TaskStatus.RELEASED) {
+      return task;
+    }
+
+    if (task.status === TaskStatus.CANCELLED || task.status === TaskStatus.DISPUTED) {
+      throw new Error(`Task ${taskId} ended with status ${taskStatusLabel(task.status)}.`);
+    }
+
+    const elapsedMs = Date.now() - startedAt;
+    if (elapsedMs >= timeoutMs) {
+      throw new Error(`Timed out waiting for task ${taskId} to complete.`);
+    }
+
+    const remainingMs = timeoutMs - elapsedMs;
+    await delay(Math.min(remainingMs, 1_000));
+  }
+}
+
+function approveSpend(context: MeshToolContext, amountMist: bigint, rail: PaymentRail, appId: string): void {
+  const decision = context.spendingPolicy.evaluate({
+    amountMist,
+    rail,
+    appId,
+    originAppName: context.originAppName,
+  });
+  if (!decision.approved) {
+    throw new Error(decision.reason ?? 'Spending policy rejected the request.');
+  }
+}
+
+function getRelayUrl(agent: AgentCard): string | undefined {
+  const relayEndpoint = agent.relayEndpoints?.find((endpoint) => !endpoint.modes || endpoint.modes.includes('sync'));
+  if (relayEndpoint?.endpoint) {
+    return relayEndpoint.endpoint;
+  }
+
+  if (agent.endpoint && /^(https?|wss?):\/\//i.test(agent.endpoint)) {
+    return agent.endpoint;
+  }
+
+  return undefined;
+}
+
+function providerAcceptsSui(capability: Capability): boolean {
+  return capability.paymentRails?.includes(PaymentRail.SUI_TRANSFER) ?? capability.pricing.rail !== PaymentRail.X402_BASE;
+}
+
+function providerAcceptsX402(agent: AgentCard, capability: Capability): boolean {
+  return capability.paymentRails?.includes(PaymentRail.X402_BASE) ?? Boolean(getRelayUrl(agent));
+}
+
+function toPaymentRail(selectedRail: SelectedPaymentRail): PaymentRail {
+  switch (selectedRail) {
+    case 'sui-escrow':
+      return PaymentRail.SUI_ESCROW;
+    case 'sui-transfer':
+      return PaymentRail.SUI_TRANSFER;
+    case 'x402-base':
+      return PaymentRail.X402_BASE;
+  }
+}
+
+function shouldFallbackToAsync(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return /relay request timed out|fetch failed|provider .* is not connected to the relay|provider not found|payment challenge required|relay execution unavailable/i.test(
+    error.message,
+  );
+}
+
+function stringifyRelayResult(result: unknown): string {
+  return typeof result === 'string' ? result : JSON.stringify(result);
+}
+
+function normalizeTimeoutMs(timeoutSeconds?: number): number {
+  if (typeof timeoutSeconds !== 'number' || Number.isNaN(timeoutSeconds)) {
+    return DEFAULT_TIMEOUT_SECONDS * 1_000;
+  }
+
+  return Math.max(0, Math.floor(timeoutSeconds * 1_000));
+}
+
+function toOptionalBigInt(value?: number): bigint | undefined {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    return undefined;
+  }
+
+  return BigInt(Math.max(0, Math.floor(value)));
+}
+
+async function storeTaskInput(
+  context: MeshToolContext,
+  provider: AgentCard,
+  input: Uint8Array,
+): Promise<{ blobId: string }> {
+  const providerEncryptionKey = hexToBytes(provider.encryptionPublicKey);
+  const encryptionEnabled = context.encryption?.enabled ?? supportsEncryptedBlobs(context.blobStore);
+  const requireEncryption = context.encryption?.requireEncryption ?? false;
+
+  if (encryptionEnabled && providerEncryptionKey) {
+    if (!supportsEncryptedBlobs(context.blobStore)) {
+      throw new Error('Encryption is enabled, but the configured blobstore does not support encrypted payloads.');
+    }
+
+    return await context.blobStore.storeEncrypted(input, providerEncryptionKey);
+  }
+
+  if (requireEncryption) {
+    throw new Error(`Provider ${provider.did} does not publish an encryption key.`);
+  }
+
+  return await context.blobStore.store(input);
+}
+
+function taskStatusLabel(status: TaskStatus): string {
+  return TaskStatus[status] ?? 'UNKNOWN';
+}
+
+async function publishSuccessfulReputationEvent(
+  context: MeshToolContext,
+  params: {
+    providerDid: string;
+    taskId: string;
+    capability: string;
+    priceMist: bigint;
+    latencyMs?: number;
+  },
+): Promise<void> {
+  const publisher = context.reputationPublisher ?? (
+    hasSigningIdentity(context.relayAuthProvider)
+      ? new ReputationEventPublisher(context.blobStore, context.relayAuthProvider)
+      : null
+  );
+  if (!publisher) {
+    return;
+  }
+
+  try {
+    const event = await publisher.createEvent({
+      type: 'task_completion',
+      subject: params.providerDid,
+      taskId: params.taskId,
+      outcome: 'success',
+      capability: params.capability,
+      latencyMs: params.latencyMs,
+      paymentAmount: {
+        amount: params.priceMist.toString(),
+        currency: 'MIST',
+      },
+    });
+    await context.reputationStore?.addEvent(event);
+    await publisher.publishEvent(event);
+  } catch (error) {
+    context.logger?.warn?.({ err: error, taskId: params.taskId }, 'Failed to publish reputation event.');
+  }
+}
+
+function hasSigningIdentity(identity: MeshToolContext['relayAuthProvider']): identity is NonNullable<MeshToolContext['relayAuthProvider']> {
+  return Boolean(identity && typeof identity.getDID === 'function' && typeof identity.signPersonalMessage === 'function');
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}