@agentmesh-p2p/sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -16,7 +16,7 @@ export { Identity, canonicalPeerId, peerIdFromPublicKey, libp2pPublicKey, verify
 export { ControlPlaneClient, ControlPlaneError, EnrollmentRejectedError, InsecureControlPlaneURLError, KeysNotTrustedError, ROLE_NODE, validateControlPlaneURL, verifyKeysResponse, } from "./controlplane.js";
 export { attenuateCredential, credentialFromJSON, credentialTimeToLiveSeconds, credentialToJSON, decodeAuthResponse, encodeAuthFrame, sealCredential, withCredentialMethods, } from "./credential.js";
 export { egressChallenge, enrollChallenge, enrollStatusChallenge, nodesCatalogChallenge, policiesChallenge, refreshChallenge, registerChallenge, revocationsChallenge, } from "./challenges.js";
-export { DEFAULT_ROUTERS, MeshSession, ROUTER_REDIAL_BACKOFFS_MS, candidatesFromRouterInfos, selectRouters, } from "./session.js";
+export { DEFAULT_ROUTERS, JOIN_TIMEOUT_MS, MeshSession, ROUTER_REDIAL_BACKOFFS_MS, candidatesFromRouterInfos, selectRouters, } from "./session.js";
 export { BiscuitVerificationError, ROLE_ROUTER, attenuateBiscuit, requireRole, sealBiscuit, verifyPeerBiscuit, } from "./biscuit.js";
 export { decodeTARBlockPayload, effectiveTARExpiration, encodeTARBlockFact, encodeTARBlockPayload, evaluateTaskRules, matchHTTPPath, matchServicePattern, matchTaskRule, parseTARBlockSource, validateHTTPGrantPath, validateServicePattern, validateTaskAuthorizationRule, validateTaskRule, } from "./tar.js";
 export { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, GOAWAY_MAX_RETRY_AFTER_MS, GOAWAY_PROTOCOL, GOAWAY_STREAM_TIMEOUT_MS, MAX_GOAWAY_MESSAGE_BYTES, MCP_PROTOCOL, ROUTER_SHUN_DURATION_MS, AuthRejectedError, authenticateWithPeer, authStreamHandler, clampGoAwayRetryAfterMs, goAwayReasonName, goAwayStreamHandler, } from "./auth.js";

package/dist/mcp-server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MeshSession } from "./session.ts";
+type Session = Pick<MeshSession, "peerId" | "routers" | "isHeldRouter" | "discover" | "openMCP"> & {
+    node: Pick<MeshSession["node"], "getPeers">;
+};
+/** The same five caller tools as agentmesh-node; an SDK member hosts no services. */
+export declare function createMeshMCPServer(ready: Session | Promise<Session>, version: string): McpServer;
+export {};

package/dist/mcp-server.js

@@ -0,0 +1,305 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// The local MCP surface for SDK members. All remote operations use the
+// session's authenticated streams and the member's own credential.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { BASELINE_DATALOG } from "./gen/datalog.js";
+import { AuthRejectedError } from "./auth.js";
+import { canonicalPeerId } from "./identity.js";
+const MAX_PROVIDERS = 64;
+const MAX_SERVICES = 256;
+const MAX_TOOLS = 256;
+const MAX_RESULTS = 1024;
+// Bounds enrollment, directory lookups and single-peer queries.
+const REQUEST_TIMEOUT_MS = 10_000;
+// Match agentmesh-node: each provider in a mesh-wide fan-out gets its own
+// deadline, at most 8 at a time, and a slow one only costs its own row.
+const PEER_TIMEOUT_MS = 5_000;
+const FANOUT = 8;
+// Opening a call stream is bounded like the node's dial; the call itself is
+// bounded by the MCP client's cancellation, as tools may run for minutes.
+const OPEN_TIMEOUT_MS = 15_000;
+const CALL_TIMEOUT_MS = 30 * 60_000;
+const serviceSchema = z.object({
+    type: z.number().int(), name: z.string().min(1), description: z.string().optional(),
+});
+const types = { mcp: 1, inference: 2, a2a: 3 };
+function text(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function serviceTarget(name, type = "mcp") {
+    const target = name.includes("://") ? name : `${type}://${name}`;
+    if (!target.startsWith(`${type}://`) || target.slice(type.length + 3).length === 0) {
+        throw new Error(`expected a ${type} service name`);
+    }
+    return target;
+}
+function toolTarget(name) {
+    // Split at the first path slash: MCP tool names themselves can contain '/',
+    // '?' or '#'. Only the service name is a path segment on the wire.
+    const match = /^mcp:\/\/([^/?#]+)\/(.+)$/s.exec(name);
+    if (!match)
+        throw new Error("tool_name must be mcp://<service>/<tool>");
+    return { service: `mcp://${match[1]}`, tool: match[2] };
+}
+function requiredLabels(value) {
+    const labels = Object.create(null);
+    if (value.trim() === "")
+        return labels;
+    for (const pair of value.split(",")) {
+        if (pair.trim() === "")
+            continue;
+        const parts = pair.trim().split("=");
+        if (parts.length !== 2 || !parts[0]?.trim() || !parts[1]?.trim()) {
+            throw new Error("required_labels must contain comma-separated key=value pairs");
+        }
+        const key = parts[0].trim(), val = parts[1].trim();
+        // Match api.ValidateLabelKey / ValidateLabelValue and the node parser.
+        if (!/^[a-zA-Z0-9_.-]{1,63}$/.test(key) || new TextEncoder().encode(val).length > 255 || /[\p{Cc}"\\]/u.test(val)) {
+            throw new Error("invalid required label key or value");
+        }
+        if (Object.hasOwn(labels, key))
+            throw new Error(`duplicate required label: ${key}`);
+        labels[key] = val;
+    }
+    if (Object.keys(labels).length === 0)
+        throw new Error("expected at least one required label");
+    return labels;
+}
+async function call(session, peer, service, name, args, options, request = { signal: options.signal }) {
+    const remote = await session.openMCP(peer, service, options);
+    try {
+        return CallToolResultSchema.parse(await remote.client.callTool({ name, arguments: args }, undefined, request));
+    }
+    finally {
+        await remote.close();
+    }
+}
+async function catalog(session, peer, type, signal) {
+    const result = await call(session, peer, `system://${BASELINE_DATALOG.catalog_target}`, "list_local_services", { type }, { signal });
+    const content = result.content[0];
+    if (result.isError || content?.type !== "text")
+        throw new Error("provider refused its service catalog");
+    return z.array(serviceSchema).max(MAX_SERVICES).parse(JSON.parse(content.text)).filter((s) => s.type === types[type]);
+}
+// Follow MCP cursors, but never accept an unbounded or looping catalog.
+async function tools(session, peer, service, signal) {
+    const remote = await session.openMCP(peer, service, { signal });
+    try {
+        const result = [];
+        const cursors = new Set();
+        let cursor;
+        do {
+            signal.throwIfAborted();
+            const page = await remote.client.listTools(cursor === undefined ? {} : { cursor }, { signal });
+            result.push(...page.tools);
+            if (result.length > MAX_TOOLS)
+                throw new Error(`provider exceeds ${MAX_TOOLS} tools per service`);
+            cursor = page.nextCursor;
+            if (cursor !== undefined) {
+                if (cursors.has(cursor) || cursors.size >= MAX_TOOLS)
+                    throw new Error("provider returned an unbounded tool catalog");
+                cursors.add(cursor);
+            }
+        } while (cursor !== undefined);
+        return result;
+    }
+    finally {
+        await remote.close();
+    }
+}
+// Do not keep a cancelled MCP request waiting for enrollment or directory lookup.
+async function withSignal(value, signal) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => { reject(signal.reason); };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve(value).then(resolve, reject).finally(() => { signal.removeEventListener("abort", abort); });
+    });
+}
+class ResultLimitError extends Error {
+    constructor() { super("too many tools; narrow the search by peer or service"); }
+}
+// Runs fn for each peer, FANOUT at a time, each under its own deadline. Only
+// the caller's cancellation aborts the whole fan-out.
+async function fanOut(peers, signal, fn) {
+    const results = [];
+    let next = 0;
+    const worker = async () => {
+        for (let i = next++; i < peers.length; i = next++) {
+            signal.throwIfAborted();
+            try {
+                results[i] = { status: "fulfilled", value: await fn(peers[i], AbortSignal.any([signal, AbortSignal.timeout(PEER_TIMEOUT_MS)])) };
+            }
+            catch (reason) {
+                results[i] = { status: "rejected", reason };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(FANOUT, peers.length) }, worker));
+    signal.throwIfAborted();
+    return results;
+}
+/** The same five caller tools as agentmesh-node; an SDK member hosts no services. */
+export function createMeshMCPServer(ready, version) {
+    const server = new McpServer({ name: "agentmesh", version }, { instructions: "Use find_remote_tools, then describe_remote_tool to learn the input schema, then call_remote_tool. " +
+            "Calls use this SDK member's identity and mesh policy. This stdio server exposes no local HTTP proxy, inference endpoint or hosted services.",
+    });
+    server.registerTool("get_mesh_info", { description: "Get information about the mesh network", inputSchema: {} }, async (_args, extra) => {
+        const signal = AbortSignal.any([extra.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+        const s = await withSignal(ready, signal);
+        const routers = s.routers.filter((r) => s.isHeldRouter(r.peerId)).map((r) => r.peerId).sort();
+        return text({ peer_id: s.peerId, connected_peers: s.node.getPeers().map((p) => p.toString()).sort(), attached_routers: routers, router_peer_id: routers[0] ?? "" });
+    });
+    server.registerTool("discover_remote_services", {
+        description: "Discover remote services by type and optional name. Returns peer_id, srv_name and srv_description. This SDK member has no local_proxy_url; inference and A2A services require an SDK client or an agentmesh-node HTTP proxy.",
+        inputSchema: {
+            type: z.string().describe("Required. One of: mcp, inference, a2a."),
+            name: z.string().optional().describe("Optional service name. Omit to list all services of the given type."),
+            limit: z.number().int().optional().describe("Optional limit for pagination. Defaults to 20."),
+            offset: z.number().int().optional().describe("Optional offset for pagination. Defaults to 0."),
+        },
+    }, async (args, extra) => {
+        const setup = AbortSignal.any([extra.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+        const s = await withSignal(ready, setup);
+        const type = args.type.toLowerCase();
+        if (types[type] === undefined)
+            throw new Error("type must be mcp, inference or a2a");
+        const name = args.name ? serviceTarget(args.name, type).slice(type.length + 3) : undefined;
+        const peers = await withSignal(s.discover(type, name, { limit: MAX_PROVIDERS }), setup);
+        const rows = [];
+        if (name !== undefined) {
+            // As in agentmesh-node, a named lookup is answered by the directory
+            // alone; no provider is contacted, so none can fail or stall it.
+            for (const peer of peers)
+                rows.push({ peer_id: peer.peerId, srv_name: `${type}://${name}`, srv_description: "" });
+        }
+        else {
+            // A provider that fails or stalls is dropped, as in agentmesh-node.
+            const catalogs = await fanOut(peers, extra.signal, (peer, signal) => catalog(s, peer, type, signal));
+            catalogs.forEach((result, i) => {
+                if (result.status === "rejected") {
+                    console.error(`agentmesh: catalog from ${peers[i].peerId} failed: ${JSON.stringify(String(result.reason))}`);
+                    return;
+                }
+                for (const svc of result.value) {
+                    rows.push({ peer_id: peers[i].peerId, srv_name: serviceTarget(svc.name, type), srv_description: svc.description ?? "" });
+                    if (rows.length > MAX_RESULTS)
+                        throw new Error("too many services; narrow the discovery by name");
+                }
+            });
+        }
+        rows.sort((a, b) => a.peer_id.localeCompare(b.peer_id) || a.srv_name.localeCompare(b.srv_name));
+        const offset = Math.max(0, args.offset ?? 0), limit = (args.limit ?? 0) > 0 ? args.limit : 20;
+        return text(rows.slice(offset, offset + limit));
+    });
+    server.registerTool("find_remote_tools", {
+        description: "Discover MCP tools available on hosted services across the mesh. Optionally narrow by peer_id, service_name, or exact tool_name. intent is accepted but ignored, as in agentmesh-node.",
+        inputSchema: {
+            intent: z.string().optional().describe("Natural-language description of what the caller is looking for. Reserved for future semantic ranking; currently accepted but ignored."),
+            peer_id: z.string().optional().describe("Restrict the search to a single peer. Empty means search the whole mesh."),
+            service_name: z.string().optional().describe("Restrict results to tools whose name starts with this service prefix (e.g. 'code-reviewer'). Empty means no service filter."),
+            tool_name: z.string().optional().describe("Exact (non-namespaced) tool name to locate across the mesh, e.g. 'review_pr'. Empty means list all tools."),
+        },
+    }, async (args, extra) => {
+        const setup = AbortSignal.any([extra.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+        const s = await withSignal(ready, setup);
+        const filter = args.service_name ? serviceTarget(args.service_name) : undefined;
+        const peerId = args.peer_id ? canonicalPeerId(args.peer_id) : undefined;
+        if (peerId === s.peerId)
+            throw new Error("cross-mesh discovery cannot target self");
+        const peers = peerId ? [{ peerId, addrs: [] }] : await withSignal(s.discover("mcp", undefined, { limit: MAX_PROVIDERS }), setup);
+        const rows = [];
+        const append = (row) => {
+            if (rows.length >= MAX_RESULTS)
+                throw new ResultLimitError();
+            rows.push(row);
+        };
+        const results = await fanOut(peers, extra.signal, async (peer, signal) => {
+            const found = [];
+            for (const svc of await catalog(s, peer, "mcp", signal)) {
+                const target = serviceTarget(svc.name);
+                if (filter !== undefined && target !== filter)
+                    continue;
+                try {
+                    for (const tool of await tools(s, peer, target, signal)) {
+                        if (!args.tool_name || tool.name === args.tool_name) {
+                            found.push({ peer_id: peer.peerId, tool_name: `${target}/${tool.name}`, description: tool.description ?? "" });
+                            if (found.length > MAX_RESULTS)
+                                throw new ResultLimitError();
+                        }
+                    }
+                }
+                catch (err) {
+                    // The peer's deadline ends the peer, not just this service.
+                    signal.throwIfAborted();
+                    if (err instanceof ResultLimitError)
+                        throw err;
+                    if (err instanceof AuthRejectedError)
+                        console.error(`agentmesh: discovery refused: ${JSON.stringify(err.message)}`);
+                    else
+                        found.push({ peer_id: peer.peerId, tool_name: target, error: String(err) });
+                }
+            }
+            return found;
+        });
+        results.forEach((result, i) => {
+            if (result.status === "fulfilled") {
+                result.value.forEach(append);
+                return;
+            }
+            const err = result.reason;
+            if (err instanceof ResultLimitError)
+                throw err;
+            if (peerId !== undefined)
+                throw err;
+            if (err instanceof AuthRejectedError)
+                console.error(`agentmesh: discovery refused: ${JSON.stringify(err.message)}`);
+            else
+                append({ peer_id: peers[i].peerId, error: String(err) });
+        });
+        return text(rows.filter((row) => !args.tool_name || !row.error).sort((a, b) => a.peer_id.localeCompare(b.peer_id) || (a.tool_name ?? "").localeCompare(b.tool_name ?? "")));
+    });
+    server.registerTool("describe_remote_tool", {
+        description: "Return the description, input schema, and output schema for a specific MCP tool on a specific peer.",
+        inputSchema: {
+            peer_id: z.string().describe("Peer ID of the node hosting the server. Required."),
+            tool_name: z.string().describe("Namespaced server name as returned by find_remote_tools (e.g. 'mcp://code-reviewer/review_pr'). Required."),
+        },
+    }, async (args, extra) => {
+        const signal = AbortSignal.any([extra.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+        const s = await withSignal(ready, signal), peer = canonicalPeerId(args.peer_id), target = toolTarget(args.tool_name);
+        const tool = (await tools(s, peer, target.service, signal)).find((t) => t.name === target.tool);
+        if (tool === undefined)
+            throw new Error("tool not found on peer");
+        return text({ peer_id: peer, tool_name: args.tool_name, description: tool.description ?? "", input_schema: tool.inputSchema, ...(tool.outputSchema ? { output_schema: tool.outputSchema } : {}) });
+    });
+    server.registerTool("call_remote_tool", {
+        description: "Call an MCP tool on a remote agent",
+        inputSchema: {
+            peer_id: z.string().describe("The Peer ID of the target agent"),
+            tool_name: z.string().describe("The name of the server to call"),
+            arguments: z.record(z.string(), z.unknown()).optional().describe("Server arguments as a JSON object whose keys match the target server's input_schema. Call describe_remote_tool first to learn the schema."),
+            required_labels: z.string().optional().describe("Comma-separated key=value pairs (e.g. 'region=us-east-1,team=platform'). Fails closed: the call is rejected unless the peer attests every one of them. Empty means no requirement."),
+        },
+    }, async (args, extra) => {
+        const s = await withSignal(ready, AbortSignal.any([extra.signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]));
+        const peer = canonicalPeerId(args.peer_id), target = toolTarget(args.tool_name);
+        const open = AbortSignal.any([extra.signal, AbortSignal.timeout(OPEN_TIMEOUT_MS)]);
+        return call(s, peer, target.service, target.tool, args.arguments ?? {}, { signal: open, requiredLabels: requiredLabels(args.required_labels ?? "") }, { signal: extra.signal, timeout: CALL_TIMEOUT_MS, resetTimeoutOnProgress: true });
+    });
+    return server;
+}

package/dist/mcp.js

@@ -21,7 +21,7 @@ import { decodeAuthFrame, decodeAuthResponse } from "./credential.js";
 /** go-msgio's default message cap, which agentmesh-node's StreamTransport uses. */
 export const MAX_MCP_MESSAGE_BYTES = 8 * 1024 * 1024;
 /** The MCP client the SDK identifies itself as. */
-export const MCP_CLIENT_INFO = { name: "agent-mesh-sdk", version: "0.1.0" };
+export const MCP_CLIENT_INFO = { name: "agent-mesh-sdk", version: "0.2.0" };
 /**
  * A Transport for @modelcontextprotocol/sdk over a libp2p stream that has
  * already passed the auth handshake.

package/dist/mesh.d.ts

@@ -117,9 +117,10 @@ export declare class AgentMesh {
      * Trades the current biscuit for a fresh one and persists it. The control
      * plane redeems only the last biscuit it issued, so a lost refresh result
      * means re-enrolling; persisting before returning keeps that rare.
-     * Concurrent calls wait for each other.
+     * Concurrent calls wait for each other. A refresh whose signal has
+     * aborted by the time its turn comes does not start.
      */
-    refresh(): Promise<MeshCredential>;
+    refresh(signal?: AbortSignal): Promise<MeshCredential>;
     /**
      * Adopts a signing key announced by a KEY_ROTATION event, so peers whose
      * credentials the new key signs verify before the next pull confirms it.
@@ -133,8 +134,11 @@ export declare class AgentMesh {
      * addresses and the ban set. Each part is attempted even when another
      * fails; the errors are reported together. Gossip events only bring this
      * forward; they are never the only way state arrives.
+     *
+     * An aborted signal cancels the request in flight and throws its reason:
+     * nothing more is sent and nothing is written to the state directory.
      */
-    syncControlPlane(): Promise<ControlPlaneSync>;
+    syncControlPlane(signal?: AbortSignal): Promise<ControlPlaneSync>;
     /**
      * The frame that opens every stream to a peer: this member's biscuit plus
      * the service it wants (e.g. "mcp://calculator").

package/dist/mesh.js

@@ -194,14 +194,16 @@ export class AgentMesh {
      * Trades the current biscuit for a fresh one and persists it. The control
      * plane redeems only the last biscuit it issued, so a lost refresh result
      * means re-enrolling; persisting before returning keeps that rare.
-     * Concurrent calls wait for each other.
+     * Concurrent calls wait for each other. A refresh whose signal has
+     * aborted by the time its turn comes does not start.
      */
-    async refresh() {
-        const run = this.#refreshChain.then(() => this.#refreshOnce(), () => this.#refreshOnce());
+    async refresh(signal) {
+        const run = this.#refreshChain.then(() => this.#refreshOnce(signal), () => this.#refreshOnce(signal));
         this.#refreshChain = run.then(() => undefined, () => undefined);
         return run;
     }
-    async #refreshOnce() {
+    async #refreshOnce(signal) {
+        signal?.throwIfAborted();
         let jwt;
         if (this.#jwtSource !== undefined) {
             try {
@@ -214,6 +216,10 @@ export class AgentMesh {
                 // Best effort: fall back to session-only refresh if the token source is temporarily unavailable.
             }
         }
+        // The last point to stop. The /refresh request itself is not cut short:
+        // the control plane spends the old biscuit when it answers, so only a
+        // refresh that runs to the end can save the new one.
+        signal?.throwIfAborted();
         const result = await this.controlPlane.refresh({
             identity: this.identity,
             biscuit: this.#credential.biscuit,
@@ -256,33 +262,37 @@ export class AgentMesh {
      * addresses and the ban set. Each part is attempted even when another
      * fails; the errors are reported together. Gossip events only bring this
      * forward; they are never the only way state arrives.
+     *
+     * An aborted signal cancels the request in flight and throws its reason:
+     * nothing more is sent and nothing is written to the state directory.
      */
-    async syncControlPlane() {
+    async syncControlPlane(signal) {
         const errors = [];
         let keysChanged = false;
         let refreshed = false;
         try {
-            const keys = await this.controlPlane.keys(this.#credential.controlPlaneKeys);
+            const keys = await this.controlPlane.keys(this.#credential.controlPlaneKeys, signal);
             if (keys.length === 0) {
                 throw new Error("/keys returned no keys");
             }
             keysChanged = !sameKeySet(keys, this.#credential.controlPlaneKeys);
             this.#credential = withCredentialMethods({ ...this.#credential, controlPlaneKeys: keys });
             if (credentialPredatesRotation(this.#credential)) {
-                await this.refresh();
+                await this.refresh(signal);
                 refreshed = true;
             }
         }
         catch (err) {
             errors.push(`keys: ${err instanceof Error ? err.message : String(err)}`);
         }
+        signal?.throwIfAborted();
         let bannedPeerIds;
         let routers;
         // Taken before the request: a ban recorded after this instant cannot be
         // in the answer, so its absence must not be read as an unban.
         const fetchedAt = new Date();
         try {
-            const info = await this.controlPlane.info();
+            const info = await this.controlPlane.info(signal);
             routers = info.routers;
             this.#routers = info.routers;
             const discovered = info.routerAddresses.length > 0
@@ -296,6 +306,7 @@ export class AgentMesh {
         catch (err) {
             errors.push(`info: ${err instanceof Error ? err.message : String(err)}`);
         }
+        signal?.throwIfAborted();
         if (keysChanged || bannedPeerIds !== undefined) {
             await this.save();
         }

package/dist/session.d.ts

@@ -78,7 +78,12 @@ export interface JoinOptions extends MeshHostOptions {
      * requiredLabels. Held on every call, MCP and HTTP alike; no call waives it.
      */
     egressRequireLabels?: Record<string, string>;
-    /** Bounds the whole join. */
+    /**
+     * Bounds the whole join: the control plane sync, and the dial, auth
+     * handshake and relay reservation with every router tried. Without one the
+     * join is bounded by JOIN_TIMEOUT_MS (60s). A join that stops throws an
+     * error naming each router tried and the step it was in.
+     */
     signal?: AbortSignal;
 }
 export interface AdmittedRouter {
@@ -124,6 +129,17 @@ export interface ToolCallResult {
     /** The raw MCP result. */
     raw: unknown;
 }
+/**
+ * Bounds a join whose caller passed no signal: each step has a timeout of
+ * its own, but a join tries them in turn over every router it is offered.
+ */
+export declare const JOIN_TIMEOUT_MS = 60000;
+/**
+ * Bounds the control plane sync a join starts with. The sync is best effort,
+ * so a control plane that does not answer in time leaves the join to go on
+ * with the stored credential instead of using up the whole join.
+ */
+export declare const JOIN_SYNC_TIMEOUT_MS = 5000;
 /**
  * A member that is on the mesh: a libp2p host authenticated with at least
  * one router, answering the auth handshake for peers that dial it, and
@@ -184,7 +200,7 @@ export declare class MeshSession {
      * the mesh's record TTL. A member with no relayed address announces
      * nothing: there is nothing to reach it at.
      */
-    announce(): Promise<void>;
+    announce(signal?: AbortSignal): Promise<void>;
     /** Whether peerId is currently one of the routers this member holds. */
     isHeldRouter(peerId: string): boolean;
     /** Handles a /mesh/goaway/1.0.0 message from a held router: shuns it, detaches it, and tops up from the catalog. */
@@ -312,5 +328,8 @@ export declare function candidatesFromRouterInfos(routers: readonly RouterInfo[]
  * and orders by matching prefer labels (descending) then load + jitter (ascending).
  */
 export declare function selectRouters(candidates: readonly RouterCandidate[], k: number, options?: SelectRoutersOptions): RouterCandidate[];
-/** Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p. */
-export declare function joinMesh(mesh: AgentMesh, options?: JoinOptions): Promise<MeshSession>;
+/**
+ * Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p.
+ * timeoutMs bounds a join whose caller passed no signal.
+ */
+export declare function joinMesh(mesh: AgentMesh, options?: JoinOptions, timeoutMs?: number): Promise<MeshSession>;