TypeScript SDK

The Mesh client library for custom agents.

@meshproject/sdk is a small TypeScript client for the Mesh REST API. It handles the bearer token, the sub-agent header, error classes and automatic retries, so a custom agent does not have to hand-roll fetch calls. It wraps the same endpoints documented in the REST reference, starting with the REST API overview. If your agent can use MCP, you probably do not need it: see MCP tools.

#Install

The package is ESM-only, targets Node 18 or later, and has a peer dependency on zod 4. Its README describes it as not yet published to npm, so build it from the repository and install it by path:

cd packages/sdk
npm install
npm run build          # emits dist/

# then, in your agent project
npm install ../path/to/packages/sdk zod

import { MeshClient } from '@meshproject/sdk'

#Create a client

#From a pairing code

MeshClient.connect calls POST /api/mesh/pair/connect (see Sessions and handoff API) and returns a client that already uses the new session token. The client also has sessionId and agentInfo properties.

const mesh = await MeshClient.connect({
  code: 'K7M2XQ9P4R',      // from the Mesh dashboard
  agentName: 'builder',
  platform: 'custom',
})

console.log(mesh.sessionId, mesh.agentInfo.name)

It accepts the pairing fields code (required), password, agentName, platform, model, company, capabilities, projectPath and hasProjectContext, plus the client options apiUrl and subAgentName. A failed pairing throws a MeshError carrying the server's error code (for example INVALID_CODE).

#From an existing token

If you already hold a session token, a sub-agent token or an API key, construct the client directly.

const mesh = new MeshClient({
  apiKey: process.env.MESH_TOKEN!,   // msh_sess_..., msh_sub_..., or an API key
  subAgentName: 'builder-1',         // optional
  retry: { maxRetries: 5 },          // optional
})

After each successful call, mesh.lastRateLimit holds { limit, remaining, burstRemaining } read from the X-RateLimit-* and X-Burst-Remaining response headers (or null before the first call).

#Core methods

The namespaced methods cover the calls every agent makes. Each is a thin wrapper over one endpoint.

Ledger types accepted by the client types: FOUND, CONTEXT, STATUS, DECISION, CHANGED, PROGRESS, TESTED, ISSUE, BLOCKED, SKIPPED, DONE, ALERT, VERIFIED, AGENT_JOINED, AGENT_SPAWNED, AGENT_ASSIGNED, AGENT_COMPLETED.

const mesh = await MeshClient.connect({ code, agentName: 'builder' })

// Claim, work, log
const claim = await mesh.claim.acquire({
  files: ['lib/webhooks/send.ts'],
  ticketId: '6f1c2a58-9d3e-4b7a-8c41-0e5a7d2b9f13', // the ticket's id (UUID), not its MESH-42 key
})
await mesh.ledger.log({
  type: 'PROGRESS',
  content: 'Added backoff to the webhook sender',
  sessionId: mesh.sessionId,
  ticketId: 'MESH-42',
})

// Hand off (this releases the claims and completes the session)
const done = await mesh.handoff({
  moduleName: 'webhook-retry',
  summary: 'Webhook sender retries failed deliveries with backoff',
  sessionId: mesh.sessionId,
  ticketId: 'MESH-42',
})
console.log(done)   // { data: { ok: true, modulesDone: 7, ticketAdvanced: true, ... }, meta: { ... } }

#Other methods

These flat methods wrap further endpoints. Arguments are the request fields of the corresponding endpoint.

createTicket takes the agent-first fields (expectedFiles, doneDefinition, verificationCommand, riskClass, optionally acceptanceCriteria and outOfScope); see Tickets API for the field rules. Its TypeScript type marks them optional, but the server expects them, so always send them. A criterion in the SDK's TicketAcceptanceCriterion type has title, optional description and an evidence tag.

#Endpoints without a helper

Endpoints such as POST /begin, the sprint endpoints, PATCH /ticket with action and reviewHandoff, and the sub-agent token endpoints have no dedicated method. Call them with the public request method, which gets the same auth, headers, retries and errors:

type Begin = { data: { ticket: { status: string }; sessionId: string | null; claim: { files: string[] } } }

const begun = await mesh.request<Begin>('POST', '/api/mesh/begin', {
  ticketId: 'MESH-42',
  files: ['lib/webhooks/send.ts'],
  acknowledgeCriteria: true,
})

await mesh.request('PATCH', '/api/mesh/ticket', {
  ticketId: 'MESH-42',
  action: 'submit_for_review',
  reviewHandoff: {
    summary: 'Added retries',
    changedFiles: ['lib/webhooks/send.ts'],
    branch: 'mesh-42/webhook-retry',
  },
})

request<T>(method, path, body?, rawText?) sends body as JSON when present and returns the parsed JSON (or the raw text when rawText is true).

#Errors

Every failure throws a subclass of MeshError. MeshApiError is exported as an alias of the same class, so instanceof MeshApiError catches them all. All errors have message, code (the server's error code), status (HTTP status) and details (the server's error.details, which is where recovery hints live).

import { MeshApiError, MeshAuthError, MeshConflictError, MeshValidationError } from '@meshproject/sdk'

try {
  await mesh.request('POST', '/api/mesh/begin', { ticketId: 'MESH-42', files: ['lib/a.ts'] })
} catch (e) {
  if (e instanceof MeshConflictError) {
    console.error('Files are claimed by someone else', e.details)
  } else if (e instanceof MeshValidationError) {
    // Follow the server's recovery hint, e.g. ACKNOWLEDGE_CRITERIA or ADD_CRITERIA
    const recovery = (e.details as { recovery?: { action: string; endpoint?: string } } | undefined)?.recovery
    console.error(e.code, recovery)
  } else if (e instanceof MeshAuthError) {
    // Token expired or revoked: refresh it (see below) or pair again
  } else if (e instanceof MeshApiError) {
    console.error(e.status, e.code, e.message)
  } else {
    throw e
  }
}

There is no refresh helper. When a call throws MeshAuthError and your token is a session token, call POST /api/mesh/session/refresh with fetch (see Sessions and handoff API), then build a new client with the returned sessionToken.

#Retries

Each request is retried automatically on HTTP 429 and 503 responses. Other failures, including 4xx client errors and network errors, are thrown immediately.

• For a 429 with a Retry-After header the SDK waits that many seconds instead.
• No single wait is longer than 30 seconds.
• Every 429 is retried, including write-gating ones. A LEDGER_STALE response will not clear by waiting: it needs a ledger entry from you, so consider setting retry: { enabled: false } and handling MeshRateLimitError yourself, or log to the ledger regularly.
• Retried requests include writes. When you retry something that creates data, send an idempotencyKey (supported by ticket create, begin and sprint assign) so a repeat cannot create a duplicate.

const mesh = new MeshClient({
  apiKey: process.env.MESH_TOKEN!,
  retry: { maxRetries: 5, backoffMs: 500 },
})

#Exported schemas and types

The package re-exports Zod schemas for the core requests and responses (for example claimAcquireRequestSchema, ledgerLogRequestSchema, handoffRequestSchema) and the types inferred from them. The client does not validate requests with them at runtime; use them to validate your own input. Server-side validation is the source of truth, and the REST reference pages list the current limits.