dsh-mesh-node 0.0.0-stage → 0.0.1

package/src/core/jobs.js

@@ -0,0 +1,259 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
+import { nowIso, readJsonFile, short } from './util.js'
+
+export const TERMINAL_STATES = ['succeeded', 'failed', 'cancelled']
+
+export function jobsDir(home) {
+  const dir = join(home, 'jobs')
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+function jobPath(home, id) {
+  return join(jobsDir(home), `${id}.json`)
+}
+
+export function newJobId() {
+  return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`
+}
+
+function writeJob(home, job) {
+  writeFileSync(jobPath(home, job.id), JSON.stringify(job, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+}
+
+function readJob(home, id) {
+  const p = jobPath(home, id)
+  if (!existsSync(p)) return null
+  try {
+    return readJsonFile(p)
+  } catch {
+    return null
+  }
+}
+
+function allJobs(home) {
+  const dir = jobsDir(home)
+  const out = []
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue
+    try {
+      out.push(readJsonFile(join(dir, name)))
+    } catch {
+      /* skip corrupt job file */
+    }
+  }
+  return out.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
+}
+
+/** Trim old jobs so the jobs dir cannot grow without bound. */
+export function pruneJobs(home, { ttlSec = 7 * 24 * 3600, maxJobs = 500 } = {}) {
+  const jobs = allJobs(home)
+  const cutoff = Date.now() - ttlSec * 1000
+  const keep = []
+  for (const job of jobs) {
+    const created = Date.parse(job.createdAt || 0)
+    const terminal = TERMINAL_STATES.includes(job.state)
+    if (terminal && Number.isFinite(created) && created < cutoff) {
+      try {
+        rmSync(jobPath(home, job.id), { force: true })
+      } catch {
+        /* ignore */
+      }
+      continue
+    }
+    keep.push(job)
+  }
+  for (const job of keep.slice(maxJobs)) {
+    if (!TERMINAL_STATES.includes(job.state)) continue
+    try {
+      rmSync(jobPath(home, job.id), { force: true })
+    } catch {
+      /* ignore */
+    }
+  }
+  return { scanned: jobs.length, kept: Math.min(keep.length, maxJobs) }
+}
+
+/**
+ * Async job runner: `task_submit` persists a job, runs it in-process and lets the caller
+ * poll `task_status`. Jobs survive a server restart as records (running ones are marked
+ * interrupted on load, so a client never waits forever).
+ *
+ * Idempotency: `task_submit` with the same `idem` key returns the original job instead of
+ * creating a second one — that is what makes retries after a dropped connection safe.
+ */
+export class JobRunner {
+  constructor({ home, exec, audit, log = console, limits = {} }) {
+    this.home = home
+    this.exec = exec
+    this.audit = audit
+    this.log = log
+    this.limits = limits
+    this.running = new Map()
+    this.recoverInterrupted()
+  }
+
+  recoverInterrupted() {
+    let recovered = 0
+    for (const job of allJobs(this.home)) {
+      if (job.state === 'running' || job.state === 'queued') {
+        job.state = 'failed'
+        job.error = { code: 'E_INTERRUPTED', message: 'node restarted while the job was running', retryable: true }
+        job.finishedAt = nowIso()
+        try {
+          writeJob(this.home, job)
+          recovered += 1
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    if (recovered > 0) this.log?.info?.(`[dsh-mesh] marked ${recovered} interrupted job(s) as failed`)
+    return recovered
+  }
+
+  findByIdem(idem) {
+    if (!idem) return null
+    return allJobs(this.home).find((j) => j.idem === idem) || null
+  }
+
+  submit({ tool, arguments: args = {}, idem, peer, timeoutMs }) {
+    if (idem) {
+      const existing = this.findByIdem(idem)
+      if (existing) return { job: existing, idempotent: true }
+    }
+    const job = {
+      id: newJobId(),
+      idem: idem || null,
+      tool,
+      arguments: args,
+      state: 'queued',
+      createdAt: nowIso(),
+      startedAt: null,
+      finishedAt: null,
+      peer: peer || null,
+      result: null,
+      error: null
+    }
+    writeJob(this.home, job)
+    this.#start(job, timeoutMs)
+    return { job: this.#public(job), idempotent: false }
+  }
+
+  #start(job, timeoutMs) {
+    const controller = new AbortController()
+    const timer = timeoutMs
+      ? setTimeout(() => controller.abort(new Error(`job timed out after ${timeoutMs}ms`)), timeoutMs)
+      : null
+    timer?.unref?.()
+    this.running.set(job.id, { controller, job })
+
+    setImmediate(async () => {
+      job.state = 'running'
+      job.startedAt = nowIso()
+      try {
+        writeJob(this.home, job)
+      } catch {
+        /* ignore */
+      }
+      try {
+        const result = await this.exec(job.tool, job.arguments, { signal: controller.signal, jobId: job.id })
+        job.result = result
+        if (result?.isError) {
+          job.state = controller.signal.aborted ? 'cancelled' : 'failed'
+          try {
+            job.error = JSON.parse(result.content?.[0]?.text || '{}')
+          } catch {
+            job.error = { code: 'E_INTERNAL', message: 'tool returned an error' }
+          }
+        } else {
+          job.state = controller.signal.aborted ? 'cancelled' : 'succeeded'
+        }
+      } catch (error) {
+        job.state = controller.signal.aborted ? 'cancelled' : 'failed'
+        job.error = { code: controller.signal.aborted ? 'E_CANCELLED' : 'E_INTERNAL', message: short(error?.message || error) }
+      } finally {
+        if (timer) clearTimeout(timer)
+        job.finishedAt = nowIso()
+        this.running.delete(job.id)
+        try {
+          writeJob(this.home, job)
+        } catch {
+          /* ignore */
+        }
+        this.audit?.({
+          peer: job.peer,
+          tool: job.tool,
+          jobId: job.id,
+          ok: job.state === 'succeeded',
+          state: job.state,
+          args: Object.keys(job.arguments || {})
+        })
+      }
+    })
+  }
+
+  get(id) {
+    const job = readJob(this.home, id)
+    return job ? this.#public(job) : null
+  }
+
+  list({ state, limit = 20 } = {}) {
+    let jobs = allJobs(this.home)
+    if (state) jobs = jobs.filter((j) => j.state === state)
+    return jobs.slice(0, Math.min(Math.max(1, limit), 100)).map((j) => this.#public(j))
+  }
+
+  cancel(id) {
+    const job = readJob(this.home, id)
+    if (!job) return { ok: false, code: 'E_NOT_FOUND', message: `no such job: ${id}` }
+    if (TERMINAL_STATES.includes(job.state)) {
+      return { ok: false, code: 'E_INVALID_ARG', message: `job already ${job.state}` }
+    }
+    const live = this.running.get(id)
+    if (live) {
+      live.controller.abort(new Error('cancelled by client'))
+      return { ok: true, job: this.#public({ ...job, cancelRequested: true }) }
+    }
+    job.state = 'cancelled'
+    job.finishedAt = nowIso()
+    writeJob(this.home, job)
+    return { ok: true, job: this.#public(job) }
+  }
+
+  stats() {
+    const jobs = allJobs(this.home)
+    const byState = {}
+    for (const job of jobs) byState[job.state] = (byState[job.state] || 0) + 1
+    return { total: jobs.length, byState, running: this.running.size, dir: jobsDir(this.home) }
+  }
+
+  #public(job) {
+    return {
+      id: job.id,
+      idem: job.idem || null,
+      tool: job.tool,
+      arguments: job.arguments,
+      state: job.state,
+      createdAt: job.createdAt,
+      startedAt: job.startedAt,
+      finishedAt: job.finishedAt,
+      durationMs:
+        job.startedAt && job.finishedAt ? Date.parse(job.finishedAt) - Date.parse(job.startedAt) : null,
+      cancelRequested: Boolean(job.cancelRequested),
+      error: job.error,
+      result: job.result,
+      resultBytes: job.result ? Buffer.byteLength(JSON.stringify(job.result), 'utf8') : 0
+    }
+  }
+}

package/src/core/pairing.js

@@ -0,0 +1,141 @@
+import { createHash, randomInt, timingSafeEqual } from 'node:crypto'
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { meshHome, pairingPath, peersPath, ensureHome } from './config.js'
+
+/**
+ * One-time pairing codes.
+ *
+ * Flow:
+ *   1. On the node being reached: `dsh-mesh pair --code` → "7KQ2-M9XD" (TTL 5 min, one use).
+ *   2. The human tells the code to the peer machine.
+ *   3. The peer runs `dsh-mesh peer add --url <url> --code 7KQ2-M9XD` → POST /pair.
+ *   4. The node verifies the code and hands back a *unique* bearer token for that peer.
+ *
+ * Only the sha256 of the code is stored, so a leaked pairing.json cannot be replayed.
+ */
+
+/** Crockford-ish alphabet: no 0/O/1/I/L to keep it readable when typed by a human. */
+const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'
+const CODE_LEN = 8
+
+export function normalizeCode(raw) {
+  const compact = String(raw || '')
+    .toUpperCase()
+    .replace(/[^A-Z0-9]/g, '')
+  return compact
+}
+
+export function hashCode(code) {
+  return createHash('sha256').update(`dsh-mesh-pair:${normalizeCode(code)}`).digest('hex')
+}
+
+export function formatCode(compact) {
+  const s = normalizeCode(compact)
+  return `${s.slice(0, 4)}-${s.slice(4)}`
+}
+
+function randomCode() {
+  let out = ''
+  for (let i = 0; i < CODE_LEN; i += 1) out += ALPHABET[randomInt(ALPHABET.length)]
+  return out
+}
+
+function writeJson0600(file, value) {
+  const tmp = `${file}.tmp-${process.pid}`
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+  renameSync(tmp, file)
+}
+
+function readJsonSafe(file) {
+  try {
+    if (!existsSync(file)) return null
+    const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '')
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Create (and persist) a one-time code. Only one code is valid at a time:
+ * creating a new one invalidates the previous one.
+ */
+export function createPairingCode({ home = meshHome(), ttlSec = 300, note } = {}) {
+  ensureHome(home)
+  const compact = randomCode()
+  const now = Date.now()
+  const record = {
+    version: 1,
+    codeHash: hashCode(compact),
+    createdAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + Math.max(30, ttlSec) * 1000).toISOString(),
+    attempts: 0,
+    used: false,
+    note: note || undefined
+  }
+  writeJson0600(pairingPath(home), record)
+  return { code: formatCode(compact), expiresAt: record.expiresAt, ttlSec }
+}
+
+export function readPairingState(home = meshHome()) {
+  const record = readJsonSafe(pairingPath(home))
+  if (!record) return null
+  return {
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+    attempts: record.attempts || 0,
+    used: record.used === true,
+    expired: new Date(record.expiresAt).getTime() <= Date.now(),
+    note: record.note
+  }
+}
+
+function sameHash(a, b) {
+  const ab = Buffer.from(String(a), 'hex')
+  const bb = Buffer.from(String(b), 'hex')
+  if (ab.length !== bb.length || ab.length === 0) return false
+  return timingSafeEqual(ab, bb)
+}
+
+/**
+ * Verify a presented code and consume it.
+ * Returns { ok:true } once; every failure carries a stable code so the server can
+ * answer 401 without leaking whether the code exists (all failures look the same
+ * except E_MAX_ATTEMPTS, which is only reachable by someone who keeps guessing).
+ */
+export function claimPairingCode({ home = meshHome(), code, maxAttempts = 5 } = {}) {
+  const record = readJsonSafe(pairingPath(home))
+  if (!record) return { ok: false, reason: 'E_NO_CODE' }
+  if (record.used) return { ok: false, reason: 'E_CODE_USED' }
+  if (new Date(record.expiresAt).getTime() <= Date.now()) return { ok: false, reason: 'E_CODE_EXPIRED' }
+  if ((record.attempts || 0) >= maxAttempts) return { ok: false, reason: 'E_MAX_ATTEMPTS' }
+
+  if (!sameHash(hashCode(code), record.codeHash)) {
+    record.attempts = (record.attempts || 0) + 1
+    if (record.attempts >= maxAttempts) {
+      record.used = true // burn it: no more guesses
+      writeJson0600(pairingPath(home), record)
+      return { ok: false, reason: 'E_MAX_ATTEMPTS', attemptsLeft: 0 }
+    }
+    writeJson0600(pairingPath(home), record)
+    return { ok: false, reason: 'E_BAD_CODE', attemptsLeft: Math.max(0, maxAttempts - record.attempts) }
+  }
+
+  record.used = true
+  record.usedAt = new Date().toISOString()
+  writeJson0600(pairingPath(home), record)
+  return { ok: true }
+}
+
+/** Peer bookkeeping on the *client* side: who we can talk to, and with which token. */
+export function loadPeers(home = meshHome()) {
+  const raw = readJsonSafe(peersPath(home))
+  return raw && Array.isArray(raw.items) ? raw : { version: 1, items: [] }
+}
+
+export function savePeers(peers, home = meshHome()) {
+  ensureHome(home)
+  const file = peersPath(home)
+  writeJson0600(file, peers)
+  return file
+}

package/src/core/peer-client.js

@@ -0,0 +1,273 @@
+/**
+ * Outbound peer client (M7 step 4: cluster_exec).
+ *
+ * `cluster_status` only probes peers over /health; this module is what lets a
+ * node ACT on a paired peer — call one MCP tool on the other machine. The trust
+ * model stays TOFU: the peer's stored certificate pin is checked on EVERY https
+ * connection (we cannot rely on NODE_EXTRA_CA_CERTS at runtime), so a changed
+ * certificate fails loudly instead of silently accepting a new one.
+ *
+ * The MCP SDK's transport takes a `fetch` option; we supply a small node:https
+ * based implementation because Node's global fetch cannot talk to a self-signed
+ * peer without adding its CA to the process trust store.
+ */
+import { request as httpRequest } from 'node:http'
+import { Agent as HttpsAgent, request as httpsRequest } from 'node:https'
+import { Client } from '@modelcontextprotocol/client'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { MESH_VERSION } from './config.js'
+import { assertFingerprint, fingerprintOfSocket, normalizeFingerprint } from './tls.js'
+
+const DEFAULT_TIMEOUT_MS = 30000
+
+export function peerError(code, message, extra = {}) {
+  const error = new Error(message)
+  error.code = code
+  Object.assign(error, extra)
+  return error
+}
+
+/** `https://host:port/mcp` -> `https://host:port` (peer records store the base URL). */
+export function baseUrlOf(url) {
+  return String(url || '')
+    .trim()
+    .replace(/\/+$/, '')
+    .replace(/\/mcp$/, '')
+}
+
+/**
+ * Read the piece of a `mesh-peer pair` output file that mesh needs to call the
+ * peer: the bearer token and base URL live in the generated DSH overlay (the
+ * `<name>.json` metadata intentionally has no token). Also accepts the metadata
+ * file for URL/fingerprint hints.
+ */
+export function parsePeerOverlay(text, { meta = null } = {}) {
+  const source = String(text || '')
+  const tokenMatch = source.match(/Authorization:\s*['"]?Bearer\s+([A-Za-z0-9._~+/=-]+)['"]?/)
+  const token = tokenMatch ? tokenMatch[1] : ''
+  if (!token) {
+    throw peerError('E_INVALID_ARG', 'no Bearer token found — pass the <name>.yml overlay written by `mesh-peer pair`')
+  }
+  const urlMatch = source.match(/^\s*url:\s*['"]?([^'"\s]+)['"]?\s*$/m)
+  const nameMatch = source.match(/^\s*serverName:\s*['"]?([^'"\s]+)['"]?\s*$/m)
+  const rawUrl = meta?.url || (urlMatch ? urlMatch[1] : '')
+  if (!rawUrl) throw peerError('E_INVALID_ARG', 'no peer url found — pass --url or the <name>.json metadata')
+  const fallbackName = meta?.node || ''
+  const serverName = nameMatch ? nameMatch[1] : ''
+  const suggestedName = String(fallbackName || serverName || 'peer')
+    .replace(/-mesh$/, '')
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .slice(0, 40)
+  const certFingerprint = meta?.certFingerprint || null
+  return {
+    token,
+    url: baseUrlOf(rawUrl),
+    tokenId: meta?.tokenId || suggestedName,
+    certFingerprint,
+    suggestedName
+  }
+}
+
+/**
+ * node:https implementation of the WHATWG fetch subset the MCP transport needs.
+ * TLS verification is replaced by the stored pin: `rejectUnauthorized:false` is
+ * only acceptable because the socket certificate is compared to the pin before
+ * a single byte of the response is handed to the SDK.
+ */
+export function makePinnedFetch({ certFingerprint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const expected = certFingerprint ? normalizeFingerprint(certFingerprint) : null
+  // No TLS session caching: a resumed session would skip the certificate check.
+  const pinnedAgent = new HttpsAgent({ keepAlive: false, maxCachedSessions: 0, rejectUnauthorized: false })
+
+  return function pinnedFetch(input, init = {}) {
+    return new Promise((resolvePromise, rejectPromise) => {
+      let url
+      try {
+        url = new URL(String(input))
+      } catch {
+        rejectPromise(peerError('E_INVALID_ARG', `invalid peer url: ${input}`))
+        return
+      }
+      const secure = url.protocol === 'https:'
+      if (secure && !expected) {
+        rejectPromise(peerError('E_PEER_NO_PIN', 'refusing to talk to an https peer without a stored certificate fingerprint'))
+        return
+      }
+      const body = init.body
+      // The SDK passes a Headers instance; spreading it would silently drop every
+      // header (including Authorization) because Headers is not enumerable.
+      const rawHeaders = init.headers
+      const headers =
+        typeof Headers !== 'undefined' && rawHeaders instanceof Headers
+          ? Object.fromEntries(rawHeaders.entries())
+          : Array.isArray(rawHeaders)
+            ? Object.fromEntries(rawHeaders)
+            : { ...(rawHeaders || {}) }
+      const request = (secure ? httpsRequest : httpRequest)(
+        {
+          protocol: url.protocol,
+          hostname: url.hostname,
+          port: url.port || (secure ? 443 : 80),
+          path: `${url.pathname}${url.search}`,
+          method: init.method || 'GET',
+          headers,
+          ...(secure ? { rejectUnauthorized: false, agent: pinnedAgent } : {}),
+          timeout: timeoutMs
+        },
+        (res) => {
+          const status = res.statusCode || 0
+          const stream = new ReadableStream({
+            start(controller) {
+              res.on('data', (chunk) => controller.enqueue(new Uint8Array(chunk)))
+              res.on('end', () => controller.close())
+              res.on('error', (error) => controller.error(error))
+            }
+          })
+          if (status === 204 || status === 304) {
+            res.resume()
+            resolvePromise(new Response(null, { status, statusText: res.statusMessage || '' }))
+            return
+          }
+          resolvePromise(new Response(stream, { status, statusText: res.statusMessage || '', headers: res.headers }))
+        }
+      )
+      if (secure) {
+        // Verify the pin at handshake time. Checking it on the response is too late
+        // and unreliable: by then the socket may already be destroyed/kept alive.
+        request.on('socket', (socket) => {
+          const verify = () => {
+            try {
+              assertFingerprint(expected, fingerprintOfSocket(socket))
+            } catch (error) {
+              request.destroy(
+                peerError('E_PEER_PIN_MISMATCH', `peer certificate does not match the stored fingerprint (${error?.code || 'unknown'})`, {
+                  cause: error
+                })
+              )
+            }
+          }
+          if (socket.connecting || socket.secureConnecting) socket.once('secureConnect', verify)
+          else verify()
+        })
+      }
+      request.on('timeout', () => request.destroy(peerError('E_PEER_TIMEOUT', `peer did not answer within ${timeoutMs} ms`)))
+      request.on('error', (error) => rejectPromise(error))
+      if (init.signal) {
+        if (init.signal.aborted) {
+          request.destroy(peerError('E_PEER_ABORTED', 'request aborted'))
+          return
+        }
+        init.signal.addEventListener('abort', () => request.destroy(peerError('E_PEER_ABORTED', 'request aborted')), { once: true })
+      }
+      if (body !== undefined && body !== null) {
+        if (typeof body === 'string' || body instanceof Uint8Array || body instanceof URLSearchParams) request.write(body)
+        else if (body instanceof ArrayBuffer) request.write(new Uint8Array(body))
+        else request.write(String(body))
+      }
+      request.end()
+    })
+  }
+}
+
+/** Close a client + transport pair; the connection is already unusable if this fails. */
+async function closeConnection(client, transport) {
+  try {
+    await client.close()
+  } catch {
+    /* already closed */
+  }
+  try {
+    await transport.close?.()
+  } catch {
+    /* already closed */
+  }
+}
+
+/**
+ * Keep the peer's own error code (E_PEER_PIN_MISMATCH and friends) so callers can
+ * react per failure mode; only map the transport's HTTP 401 to E_PEER_AUTH.
+ */
+function peerFailureCode(error, fallback) {
+  const message = error?.message || String(error)
+  const ownCode = typeof error?.code === 'string' && /^E_[A-Z0-9_]+$/.test(error.code) ? error.code : null
+  return ownCode || (/401|unauthori[sz]ed/i.test(message) ? 'E_PEER_AUTH' : fallback)
+}
+
+/**
+ * Open a pinned MCP connection to a paired peer and keep it for several calls
+ * (tools/list followed by tools/call). TLS trust comes from the stored pin, not
+ * from NODE_EXTRA_CA_CERTS, so this works in any process — including a stdio
+ * bridge child that DSH spawned with a scrubbed environment. The caller owns
+ * `close()`.
+ */
+export async function connectPeer(peer, { timeoutMs = DEFAULT_TIMEOUT_MS, clientName = 'dsh-mesh-peer' } = {}) {
+  const name = String(peer?.name || peer?.id || 'peer')
+  if (!peer?.url) throw peerError('E_INVALID_ARG', `peer "${name}" has no url`)
+  if (!peer?.token) throw peerError('E_PEER_NO_TOKEN', `peer "${name}" has no outbound token — run \`node src/cli.js peer import --file <name>.yml\``)
+  const endpoint = `${baseUrlOf(peer.url)}/mcp`
+  const client = new Client({ name: clientName, version: MESH_VERSION })
+  const transport = new StreamableHTTPClientTransport(new URL(endpoint), {
+    fetch: makePinnedFetch({ certFingerprint: peer.certFingerprint, timeoutMs }),
+    requestInit: { headers: { Authorization: `Bearer ${peer.token}` } }
+  })
+  try {
+    await client.connect(transport)
+  } catch (error) {
+    await closeConnection(client, transport)
+    throw error
+  }
+  return { peer: name, client, transport, close: () => closeConnection(client, transport) }
+}
+
+/**
+ * Call one tool on a paired peer. `peer` = {name, url, token, certFingerprint}
+ * (as stored by `peer import`). Returns a compact result — never the token.
+ */
+export async function callPeerTool(peer, { tool, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const name = String(peer?.name || peer?.id || 'peer')
+  const started = Date.now()
+  let connection
+  try {
+    connection = await connectPeer(peer, { timeoutMs, clientName: 'dsh-mesh-cluster-exec' })
+    const result = await connection.client.callTool({ name: tool, arguments: args })
+    return {
+      peer: name,
+      tool,
+      ok: result?.isError !== true,
+      ms: Date.now() - started,
+      result
+    }
+  } catch (error) {
+    const message = error?.message || String(error)
+    throw peerError(peerFailureCode(error, 'E_PEER_CALL_FAILED'), `peer "${name}" tool "${tool}" failed: ${message}`)
+  } finally {
+    if (connection) await connection.close()
+  }
+}
+
+/**
+ * List the tools a paired peer exposes (same pinned transport as callPeerTool).
+ * Used by `peer tools`/`peer call` and by the stdio bridge, which republishes
+ * this list locally so the tool surface stays in sync with the peer.
+ */
+export async function listPeerTools(peer, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const name = String(peer?.name || peer?.id || 'peer')
+  const started = Date.now()
+  let connection
+  try {
+    connection = await connectPeer(peer, { timeoutMs, clientName: 'dsh-mesh-peer-tools' })
+    const listed = await connection.client.listTools()
+    const tools = listed?.tools ?? []
+    return {
+      peer: name,
+      ok: true,
+      ms: Date.now() - started,
+      count: tools.length,
+      tools: tools.map((tool) => ({ name: tool.name, description: tool.description || '' }))
+    }
+  } catch (error) {
+    throw peerError(peerFailureCode(error, 'E_PEER_CALL_FAILED'), `peer "${name}" tools/list failed: ${error?.message || error}`)
+  } finally {
+    if (connection) await connection.close()
+  }
+}