@hivemind-os/collective-mcp-server 0.2.0

package/src/tools/metering.ts

@@ -0,0 +1,214 @@
+import { decodeMeteredResult, getMeteredResultUnits, parseMeteredResultEnvelope, ResultVerifier } from '@hivemind-os/collective-core';
+import { PaymentRail, PaymentScheme, TaskStatus } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+import { fetchMeshBlob, hexToBytes, supportsEncryptedBlobs } from '../encryption.js';
+import { resolveProviderCapability } from './discover.js';
+import { waitForTaskCompletion } from './execute.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 MeshMeteredExecuteParams {
+  capability: string;
+  provider_did?: string;
+  input: string;
+  max_price_mist: number;
+  unit_price_mist: number;
+  timeout_seconds?: number;
+}
+
+export interface MeshVerifyResultParams {
+  task_id: string;
+}
+
+export const meshMeteredExecuteTool = {
+  name: 'collective_metered_execute',
+  description: 'Execute a metered mesh task with capped escrow and result verification',
+  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 escrow in MIST' },
+      unit_price_mist: { type: 'number', description: 'Price per metered unit in MIST' },
+      timeout_seconds: { type: 'number', description: 'Polling timeout in seconds (default 120)' },
+    },
+    required: ['capability', 'input', 'max_price_mist', 'unit_price_mist'],
+  },
+};
+
+export const meshVerifyResultTool = {
+  name: 'collective_verify_result',
+  description: 'Verify a metered task result blob against its on-chain hash chain root',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: { type: 'string', description: 'Task object id' },
+    },
+    required: ['task_id'],
+  },
+};
+
+export async function runMeshMeteredExecute(
+  params: MeshMeteredExecuteParams,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  provider_did: string;
+  result: string;
+  status: string;
+  payment_rail: PaymentRail;
+  payment_scheme: PaymentScheme.UPTO;
+  max_price_mist: string;
+  actual_price_mist: string;
+  unit_price_mist: string;
+  metered_units: number;
+  verification_hash: string;
+  verified: boolean;
+}> {
+  const resolved = await resolveProviderCapability(params.capability, context, params.provider_did);
+  if (resolved.capability.pricing.rail !== PaymentRail.SUI_ESCROW) {
+    throw new Error(`Capability ${resolved.capability.name} does not support SUI escrow execution.`);
+  }
+
+  const maxPriceMist = toRequiredBigInt(params.max_price_mist, 'max_price_mist');
+  const unitPriceMist = toRequiredBigInt(params.unit_price_mist, 'unit_price_mist');
+  const spendingDecision = context.spendingPolicy.evaluate({
+    amountMist: maxPriceMist,
+    rail: PaymentRail.SUI_ESCROW,
+    appId: resolved.agent.did,
+    originAppName: context.originAppName,
+  });
+  if (!spendingDecision.approved) {
+    throw new Error(spendingDecision.reason ?? 'Spending policy rejected the request.');
+  }
+
+  const inputBlob = await storeTaskInput(context, resolved.agent, encoder.encode(params.input));
+  const posted = await context.taskClient.postMeteredTask({
+    capability: resolved.capability.name,
+    category: 'general',
+    inputBlobId: inputBlob.blobId,
+    agreementHash: `metered:${resolved.capability.name}`,
+    maxPriceMist,
+    unitPriceMist,
+    disputeWindowMs: DEFAULT_DISPUTE_WINDOW_MS,
+    expiryHours: DEFAULT_EXPIRY_HOURS,
+    keypair: context.keypair,
+  });
+  const task = await waitForTaskCompletion(posted.taskId, context, params.timeout_seconds ?? DEFAULT_TIMEOUT_SECONDS);
+  const verification = await verifyMeteredTaskResult(task.id, context);
+
+  await context.taskClient.releaseMeteredPayment({
+    taskId: task.id,
+    keypair: context.keypair,
+  });
+  context.spendingPolicy.record({
+    amountMist: task.price,
+    rail: PaymentRail.SUI_ESCROW,
+    taskId: task.id,
+    appId: resolved.agent.did,
+    originAppName: context.originAppName,
+  });
+
+  return {
+    task_id: task.id,
+    provider_did: resolved.agent.did,
+    result: verification.result,
+    status: TaskStatus[TaskStatus.RELEASED],
+    payment_rail: PaymentRail.SUI_ESCROW,
+    payment_scheme: PaymentScheme.UPTO,
+    max_price_mist: (task.maxPrice ?? maxPriceMist).toString(),
+    actual_price_mist: task.price.toString(),
+    unit_price_mist: (task.unitPrice ?? unitPriceMist).toString(),
+    metered_units: task.meteredUnits ?? verification.metered_units,
+    verification_hash: verification.verification_hash,
+    verified: verification.verified,
+  };
+}
+
+export async function runMeshVerifyResult(
+  params: MeshVerifyResultParams,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  verified: boolean;
+  verification_hash: string;
+  metered_units: number;
+  result: string;
+}> {
+  return await verifyMeteredTaskResult(params.task_id, context);
+}
+
+async function verifyMeteredTaskResult(
+  taskId: string,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  verified: boolean;
+  verification_hash: string;
+  metered_units: number;
+  result: string;
+}> {
+  const task = await context.taskClient.getTask(taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} was not found.`);
+  }
+  if (!task.resultBlobId) {
+    throw new Error(`Task ${taskId} does not have a result blob.`);
+  }
+
+  const resultBytes = await fetchMeshBlob(context.blobStore, task.resultBlobId);
+  if (!resultBytes) {
+    throw new Error(`Result blob ${task.resultBlobId} was not found.`);
+  }
+
+  const envelope = parseMeteredResultEnvelope(resultBytes);
+  if (!envelope) {
+    throw new Error(`Result blob ${task.resultBlobId} is not a metered result envelope.`);
+  }
+
+  const verifier = new ResultVerifier();
+  const verified = verifier.verify(task, envelope.proof, getMeteredResultUnits(envelope));
+  return {
+    task_id: task.id,
+    verified,
+    verification_hash: task.verificationHash ?? envelope.proof.root,
+    metered_units: task.meteredUnits ?? envelope.proof.unitCount,
+    result: decoder.decode(decodeMeteredResult(envelope)),
+  };
+}
+
+function toRequiredBigInt(value: number, name: string): bigint {
+  if (typeof value !== 'number' || Number.isNaN(value) || value < 0) {
+    throw new Error(`Invalid ${name}.`);
+  }
+
+  return BigInt(Math.floor(value));
+}
+
+async function storeTaskInput(
+  context: MeshToolContext,
+  provider: Awaited<ReturnType<typeof resolveProviderCapability>>['agent'],
+  input: Uint8Array,
+): Promise<{ blobId: string }> {
+  const providerEncryptionKey = hexToBytes(provider.encryptionPublicKey) ?? undefined;
+  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);
+}

package/src/tools/multi-execute.ts

@@ -0,0 +1,218 @@
+import {
+  AggregationMode,
+  ProviderSelectionStrategy,
+  type AgentCard,
+  type MultiProviderRequest,
+} from '@hivemind-os/collective-types';
+import {
+  CircuitBreaker,
+  FanOutExecutor,
+  PerformanceTracker,
+  ProviderSelector,
+} from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+import { discoverAgentsByCapability } from './discover.js';
+import { runMeshExecute } from './execute.js';
+
+const routingCircuitBreaker = new CircuitBreaker();
+const routingPerformanceTracker = new PerformanceTracker();
+const providerSelector = new ProviderSelector({
+  circuitBreaker: routingCircuitBreaker,
+  performanceTracker: routingPerformanceTracker,
+});
+
+export interface MeshMultiExecuteParams {
+  capability: string;
+  input: unknown;
+  fanOutCount?: number;
+  strategy?: ProviderSelectionStrategy | `${ProviderSelectionStrategy}`;
+  aggregation?: AggregationMode | `${AggregationMode}`;
+  timeout?: number;
+  maxPricePerProvider?: number;
+}
+
+export const meshMultiExecuteTool = {
+  name: 'collective_multi_execute',
+  description: 'Execute a mesh task across multiple providers and aggregate the results',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      capability: { type: 'string', description: 'Capability name to execute' },
+      input: { description: 'Task input payload' },
+      fanOutCount: { type: 'number', description: 'How many providers to fan out to (default 3)' },
+      strategy: {
+        type: 'string',
+        enum: Object.values(ProviderSelectionStrategy),
+        description: 'Provider selection strategy (default weighted)',
+      },
+      aggregation: {
+        type: 'string',
+        enum: Object.values(AggregationMode),
+        description: 'Aggregation mode (default first_success)',
+      },
+      timeout: { type: 'number', description: 'Per-provider timeout in milliseconds' },
+      maxPricePerProvider: { type: 'number', description: 'Maximum price per provider in MIST' },
+    },
+    required: ['capability', 'input'],
+  },
+};
+
+export interface MeshMultiExecuteResult {
+  capability: string;
+  strategy: ProviderSelectionStrategy;
+  aggregation: AggregationMode;
+  providers: Array<{
+    did: string;
+    price_mist: string;
+    reputation: number;
+    estimated_latency_ms?: number;
+    composite_score: number;
+  }>;
+  results: Array<{
+    provider: string;
+    status: 'success' | 'failure' | 'timeout';
+    result?: unknown;
+    duration_ms: number;
+    error?: string;
+  }>;
+  aggregated_result?: unknown;
+  total_cost_mist: string;
+}
+
+export async function runMeshMultiExecute(
+  params: MeshMultiExecuteParams,
+  context: MeshToolContext,
+): Promise<MeshMultiExecuteResult> {
+  const capability = params.capability.trim();
+  if (!capability) {
+    throw new Error('Capability is required.');
+  }
+
+  const fanOutCount = normalizePositiveInteger(params.fanOutCount, 3);
+  const strategy = parseSelectionStrategy(params.strategy);
+  const aggregation = parseAggregation(params.aggregation);
+  const request: MultiProviderRequest = {
+    capability,
+    input: params.input,
+    fanOutCount,
+    strategy,
+    aggregation,
+    timeout: normalizeOptionalInteger(params.timeout),
+    maxPricePerProvider: toOptionalBigInt(params.maxPricePerProvider),
+  };
+
+  const { agents: discoveredAgents } = await discoverAgentsByCapability(
+    capability,
+    context,
+    Math.max(fanOutCount * 3, fanOutCount),
+    'reputation',
+  );
+  const candidates = filterByMaxPrice(discoveredAgents, capability, request.maxPricePerProvider);
+  const selected = providerSelector.selectProviders(candidates, capability, strategy, fanOutCount);
+  if (selected.length === 0) {
+    throw new Error(`No eligible providers found for capability ${capability}.`);
+  }
+
+  const executor = new FanOutExecutor({
+    circuitBreaker: routingCircuitBreaker,
+    performanceTracker: routingPerformanceTracker,
+    executeProvider: async (provider, executionRequest, executionContext) => {
+      if (executionContext.signal.aborted) {
+        throw executionContext.signal.reason ?? new Error('Provider execution aborted.');
+      }
+
+      const value = await runMeshExecute({
+        capability: executionRequest.capability,
+        provider_did: provider.did,
+        input: serializeInput(executionRequest.input),
+        timeout_seconds: executionRequest.timeout ? Math.max(1, Math.ceil(executionRequest.timeout / 1_000)) : undefined,
+      }, context);
+      return {
+        value,
+        aggregateValue: value.result,
+        cost: BigInt(value.price_mist),
+      };
+    },
+  });
+
+  const result = await executor.execute(request, selected);
+
+  return {
+    capability,
+    strategy,
+    aggregation,
+    providers: selected.map((provider) => ({
+      did: provider.did,
+      price_mist: provider.price.toString(),
+      reputation: provider.reputation,
+      estimated_latency_ms: provider.estimatedLatency,
+      composite_score: provider.compositeScore,
+    })),
+    results: result.results.map((entry) => ({
+      provider: entry.provider,
+      status: entry.status,
+      result: entry.result,
+      duration_ms: entry.durationMs,
+      error: entry.error,
+    })),
+    aggregated_result: result.aggregatedResult,
+    total_cost_mist: result.totalCost.toString(),
+  };
+}
+
+function filterByMaxPrice(agents: AgentCard[], capability: string, maxPricePerProvider?: bigint): AgentCard[] {
+  if (maxPricePerProvider === undefined) {
+    return agents;
+  }
+
+  return agents.filter((agent) => {
+    const matched = agent.capabilities.find((entry) => entry.name.toLowerCase() === capability.toLowerCase());
+    return matched ? matched.pricing.amount <= maxPricePerProvider : false;
+  });
+}
+
+function parseSelectionStrategy(strategy?: MeshMultiExecuteParams['strategy']): ProviderSelectionStrategy {
+  if (!strategy) {
+    return ProviderSelectionStrategy.WEIGHTED;
+  }
+  if (Object.values(ProviderSelectionStrategy).includes(strategy as ProviderSelectionStrategy)) {
+    return strategy as ProviderSelectionStrategy;
+  }
+  throw new Error(`Unsupported provider selection strategy: ${String(strategy)}.`);
+}
+
+function parseAggregation(aggregation?: MeshMultiExecuteParams['aggregation']): AggregationMode {
+  if (!aggregation) {
+    return AggregationMode.FIRST_SUCCESS;
+  }
+  if (Object.values(AggregationMode).includes(aggregation as AggregationMode)) {
+    return aggregation as AggregationMode;
+  }
+  throw new Error(`Unsupported aggregation mode: ${String(aggregation)}.`);
+}
+
+function normalizePositiveInteger(value: number | undefined, fallback: number): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    return fallback;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function normalizeOptionalInteger(value?: number): number | undefined {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    return undefined;
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+function toOptionalBigInt(value?: number): bigint | undefined {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    return undefined;
+  }
+  return BigInt(Math.max(0, Math.floor(value)));
+}
+
+function serializeInput(input: unknown): string {
+  return typeof input === 'string' ? input : JSON.stringify(input);
+}

package/src/tools/policy-update.ts

@@ -0,0 +1,94 @@
+import { PaymentRail, type SpendingPolicy } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshPolicyUpdateParams {
+  daily_limit_mist?: number;
+  monthly_limit_mist?: number;
+  per_task_limit_mist?: number;
+}
+
+export const meshPolicyUpdateTool = {
+  name: 'collective_policy_update',
+  description: 'Update local spending policy limits',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      daily_limit_mist: { type: 'number', description: 'Daily MIST limit' },
+      monthly_limit_mist: { type: 'number', description: 'Monthly MIST limit' },
+      per_task_limit_mist: { type: 'number', description: 'Per-task MIST limit' },
+    },
+    required: [],
+  },
+};
+
+export async function runMeshPolicyUpdate(
+  params: MeshPolicyUpdateParams,
+  context: MeshToolContext,
+): Promise<{
+  updated: true;
+  limits: Array<{ interval: string; amount_mist: string; rail: string }>;
+}> {
+  const currentPolicy = clonePolicy(readPolicySnapshot(context));
+  const nextLimits = [...currentPolicy.limits];
+
+  applyLimit(nextLimits, 'transaction', params.per_task_limit_mist);
+  applyLimit(nextLimits, 'day', params.daily_limit_mist);
+  applyLimit(nextLimits, 'month', params.monthly_limit_mist);
+
+  const updatedPolicy: SpendingPolicy = {
+    ...currentPolicy,
+    limits: nextLimits,
+  };
+
+  context.spendingPolicy.updatePolicy(updatedPolicy);
+
+  return {
+    updated: true,
+    limits: updatedPolicy.limits.map((limit) => ({
+      interval: limit.interval,
+      amount_mist: limit.amount.toString(),
+      rail: limit.rail ?? PaymentRail.SUI_ESCROW,
+    })),
+  };
+}
+
+function readPolicySnapshot(context: MeshToolContext): SpendingPolicy {
+  const engineWithPolicy = context.spendingPolicy as unknown as { policy?: SpendingPolicy };
+  return engineWithPolicy.policy ?? { limits: [] };
+}
+
+function clonePolicy(policy: SpendingPolicy): SpendingPolicy {
+  return {
+    ...policy,
+    limits: policy.limits.map((limit) => ({ ...limit })),
+    allowlist: policy.allowlist ? [...policy.allowlist] : undefined,
+    denylist: policy.denylist ? [...policy.denylist] : undefined,
+  };
+}
+
+function applyLimit(
+  limits: SpendingPolicy['limits'],
+  interval: 'transaction' | 'day' | 'month',
+  amount?: number,
+): void {
+  if (typeof amount !== 'number' || Number.isNaN(amount)) {
+    return;
+  }
+
+  const nextLimit = {
+    amount: BigInt(Math.max(0, Math.floor(amount))),
+    interval,
+    rail: PaymentRail.SUI_ESCROW,
+  } as const;
+  const index = limits.findIndex(
+    (entry) => entry.interval === interval && (entry.rail ?? PaymentRail.SUI_ESCROW) === PaymentRail.SUI_ESCROW,
+  );
+
+  if (index >= 0) {
+    limits[index] = nextLimit;
+    return;
+  }
+
+  limits.push(nextLimit);
+}

package/src/tools/register.ts

@@ -0,0 +1,78 @@
+import { PaymentRail, type Capability } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+import { hexToBytes } from '../encryption.js';
+
+export interface MeshRegisterParams {
+  name: string;
+  description: string;
+  capabilities: Array<{
+    name: string;
+    description: string;
+    version: string;
+    price_mist: number;
+  }>;
+}
+
+export const meshRegisterTool = {
+  name: 'collective_register',
+  description: 'Register the current daemon identity as a provider',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      name: { type: 'string', description: 'Display name for the agent' },
+      description: { type: 'string', description: 'Agent description' },
+      capabilities: {
+        type: 'array' as const,
+        items: {
+          type: 'object' as const,
+          properties: {
+            name: { type: 'string' },
+            description: { type: 'string' },
+            version: { type: 'string' },
+            price_mist: { type: 'number' },
+          },
+          required: ['name', 'description', 'version', 'price_mist'],
+        },
+      },
+    },
+    required: ['name', 'description', 'capabilities'],
+  },
+};
+
+export async function runMeshRegister(
+  params: MeshRegisterParams,
+  context: MeshToolContext,
+): Promise<{ agent_card_id: string; did: string; tx_digest: string }> {
+  const capabilities: Capability[] = params.capabilities.map((entry) => ({
+    name: entry.name,
+    description: entry.description,
+    version: entry.version,
+    pricing: {
+      rail: PaymentRail.SUI_ESCROW,
+      amount: BigInt(Math.max(0, Math.floor(entry.price_mist))),
+      currency: 'MIST',
+    },
+  }));
+
+  const result = await context.registryClient.registerAgent({
+    name: params.name,
+    did: context.did,
+    description: params.description,
+    capabilities,
+    endpoint: `mesh://agent/${context.did}`,
+    encryptionPublicKey: context.encryption?.enabled ? (hexToBytes(context.encryption.publicKey) ?? undefined) : undefined,
+    keypair: context.keypair,
+  });
+
+  const card = await context.registryClient.getAgentCard(result.agentCardId);
+  if (card) {
+    context.agentCache.upsertAgent(card);
+  }
+
+  return {
+    agent_card_id: result.agentCardId,
+    did: context.did,
+    tx_digest: result.txDigest,
+  };
+}

package/src/tools/relay-registry.ts

@@ -0,0 +1,95 @@
+import { RelayRegistryClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshRelayRegistryParams {
+  action: 'list' | 'register';
+  endpoint?: string;
+  stake_id?: string;
+  region?: string;
+  routing_fee_bps?: number;
+  capabilities?: string[];
+}
+
+export const meshRelayRegistryTool = {
+  name: 'collective_relay_registry',
+  description: 'List registered community relays or register this node as a relay operator',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string', enum: ['list', 'register'] },
+      endpoint: { type: 'string', description: 'Relay websocket or HTTPS endpoint when action=register' },
+      stake_id: { type: 'string', description: 'Relay stake position object id when action=register' },
+      region: { type: 'string', description: 'Relay region label when action=register' },
+      routing_fee_bps: { type: 'number', description: 'Routing fee in basis points when action=register' },
+      capabilities: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Optional relay capabilities when action=register (defaults to ["routing"])',
+      },
+    },
+    required: ['action'],
+  },
+};
+
+export async function runMeshRelayRegistry(
+  params: MeshRelayRegistryParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const client = context.relayRegistryClient ?? new RelayRegistryClient(context.suiClient, context.networkConfig);
+
+  switch (params.action) {
+    case 'list': {
+      const relays = await client.listRelays();
+      return {
+        action: 'list',
+        count: relays.length,
+        relays,
+      };
+    }
+    case 'register': {
+      const endpoint = requireNonEmpty(params.endpoint, 'endpoint');
+      const stakeId = requireNonEmpty(params.stake_id, 'stake_id');
+      const region = requireNonEmpty(params.region, 'region');
+      if (params.routing_fee_bps === undefined) {
+        throw new Error('routing_fee_bps is required when action=register');
+      }
+      if (!Number.isInteger(params.routing_fee_bps) || params.routing_fee_bps < 0 || params.routing_fee_bps > 10_000) {
+        throw new Error('routing_fee_bps must be an integer between 0 and 10000');
+      }
+      const capabilities = normalizeCapabilities(params.capabilities);
+      const result = await client.registerRelay({
+        endpoint,
+        stakeId,
+        region,
+        routingFeeBps: params.routing_fee_bps,
+        capabilities,
+        signer: context.keypair as never,
+      });
+      return {
+        action: 'register',
+        relay_id: result.relayId,
+        tx_digest: result.txDigest,
+        endpoint,
+        region,
+        routing_fee_bps: params.routing_fee_bps,
+        capabilities,
+      };
+    }
+    default:
+      throw new Error(`Unknown relay registry action: ${String(params.action)}`);
+  }
+}
+
+function requireNonEmpty(value: string | undefined, field: string): string {
+  const normalized = value?.trim();
+  if (!normalized) {
+    throw new Error(`${field} is required when action=register`);
+  }
+  return normalized;
+}
+
+function normalizeCapabilities(capabilities: string[] | undefined): string[] {
+  const normalized = capabilities?.map((capability) => capability.trim()).filter(Boolean) ?? [];
+  return normalized.length > 0 ? [...new Set(normalized)] : ['routing'];
+}