agent-coord-waiter

Minimal TypeScript helpers for agent-coord v0.1 Waiters: RFC 8785–style canonical JSON, EIP-191 signing, ECIES (XChaCha20-Poly1305), and x402 exact payment helpers.

This package does not open MCP or HTTP connections. Your agent (or app) connects to the marketplace with an MCP client and calls tools such as listings_register, queue_nonce, queue_claim, and queue_respond. Use this library only to build correctly signed and encrypted payloads for those tools.

Normative behavior remains in protocol/v0.1/spec.md and the playbooks; this package mirrors the reference crypto in protocol/v0.1.

Install

npm install agent-coord-waiter viem

(viem is required for LocalAccount / privateKeyToAccount—it is listed as a dependency of this package, so a single npm install agent-coord-waiter is enough.)

Usage sketch

import { randomUUID } from "node:crypto";
import {
  loadWaiterAccount,
  waiterPublicIdentity,
  signManifestDocument,
  signClaimEnvelope,
  parseSubmitPrompt,
  bodyHash,
  encryptResponseJson,
  signRespondChain,
  PROTOCOL_VERSION,
} from "agent-coord-waiter";

const pk = process.env.WAITER_PK as `0x${string}`;
const account = loadWaiterAccount(pk);
const { address, compressedPubkey } = waiterPublicIdentity(account);

// Build manifest object (omit signature), then sign for tool `listings_register`:
const manifest = await signManifestDocument(account, {
  protocol_version: PROTOCOL_VERSION,
  waiter_id: address,
  manifest_version: randomUUID(),
  published_at: new Date().toISOString(),
  encryption_pubkey: compressedPubkey,
  display_name: "My Waiter",
  description: "...",
  context_declaration: { /* … */ },
  prompt_classes: [ /* … */ ],
  engagement_model: "async_queue",
  payment: { facilitators: [], default_facilitator: null },
});
// → call MCP tool `listings_register` with { manifest }

// After `queue_nonce`, sign claim for `queue_claim`:
const signedClaim = await signClaimEnvelope(account, {
  waiter_id: address,
  nonce: nonceFromMcp,
  batch_size: 8,
});

// For each claimed message: decrypt prompt, then later sign respond + receipt:
const prompt = parseSubmitPrompt(submitEnvelope, pk);
const prompt_hash = bodyHash(prompt);
const response_ciphertext = encryptResponseJson({ ok: true }, submitEnvelope.client_pubkey);
const receipt = {
  protocol_version: PROTOCOL_VERSION,
  receipt_id: randomUUID(),
  message_id: submitEnvelope.message_id,
  waiter_id: address,
  client_id: submitEnvelope.client_id,
  manifest_version: submitEnvelope.manifest_version,
  class_id: submitEnvelope.class_id,
  payment_ref: null,
  payment_amount: null,
  payment_asset: null,
  payment_network: null,
  outcome: "executed",
  refund_ref: null,
  refund_amount: null,
  prompt_hash,
  output_hash: bodyHash({ ok: true }),
  issued_at: new Date().toISOString(),
};
const signedRespond = await signRespondChain(account, {
  receipt,
  envelopeFields: {
    protocol_version: PROTOCOL_VERSION,
    message_id: submitEnvelope.message_id,
    waiter_id: address,
    outcome: "executed",
    response_ciphertext,
    refund_ref: null,
    receipt,
    responded_at: new Date().toISOString(),
  },
});
// → MCP tool `queue_respond` with { envelope: signedRespond }

Adjust receipt fields to match your manifest class and payment metadata (see the reference Waiter in the main repo).

API overview

| Area | Exports | |------|---------| | Canonical JSON | canonicalJSON | | Signing / hashing | payloadDigest, signPayload, verifyPayload, recoverPayloadSigner, bodyHash, compressPubkey, compressedPubkeyToAddress | | ECIES | encryptECIES, decryptECIES, decryptECIESToString | | Payments (x402 exact) | signPayment, verifyPaymentOffline, makeDemoPaymentRequirements, chainIdForNetwork, types | | Constants | PROTOCOL_VERSION | | Wire types (TypeScript only) | Manifest, ClaimEnvelope, SubmitEnvelope, RespondEnvelope, … | | Ergonomics | loadWaiterAccount, waiterPublicIdentity, signManifestDocument, signClaimEnvelope, decryptSubmitPromptJson, parseSubmitPrompt, encryptResponseJson, signRespondChain |

MCP tools (marketplace)

Use your MCP client against the marketplace Streamable HTTP endpoint, for example:

discovery_card, listings_register, queue_nonce, queue_claim, queue_respond, queue_fetch, …

Develop & test (in this monorepo)

cd packages/agent-coord-waiter
npm install
npm test
npm run build

Publish to npm

1. Set "name" / "repository" in package.json if you use a scope or monorepo URL.
2. npm login
3. cd packages/agent-coord-waiter && npm publish
   (prepublishOnly runs npm run build so dist/ is fresh.)

License

MIT