@agentmesh-p2p/sdk 0.1.0 → 0.1.1

package/dist/auth.d.ts

@@ -21,8 +21,9 @@ export declare class AuthRejectedError extends Error {
 /**
  * Client side: presents frame on a new /mesh/auth/1.0.0 stream and returns
  * the peer's verified credential. trustedKeys are the control plane keys.
+ * The handshake has a timeout of its own; outer, when given, can end it sooner.
  */
-export declare function authenticateWithPeer(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[]): Promise<VerifiedBiscuit>;
+export declare function authenticateWithPeer(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[], outer?: AbortSignal): Promise<VerifiedBiscuit>;
 export interface AuthServerOptions {
     /** This member's current biscuit, read per handshake so a refresh takes effect. */
     ownBiscuit(): Uint8Array;

package/dist/auth.js

@@ -45,9 +45,10 @@ function framed(stream) {
 /**
  * Client side: presents frame on a new /mesh/auth/1.0.0 stream and returns
  * the peer's verified credential. trustedKeys are the control plane keys.
+ * The handshake has a timeout of its own; outer, when given, can end it sooner.
  */
-export async function authenticateWithPeer(conn, frame, trustedKeys) {
-    const signal = AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS);
+export async function authenticateWithPeer(conn, frame, trustedKeys, outer) {
+    const signal = outer === undefined ? AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS) : AbortSignal.any([outer, AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS)]);
     // A peer behind a router is reached over a relayed, limited connection.
     const stream = await conn.newStream(AUTH_PROTOCOL, { signal, runOnLimitedConnection: true });
     try {

package/dist/controlplane.d.ts

@@ -95,12 +95,12 @@ export declare class ControlPlaneClient {
     readonly url: URL;
     constructor(options: ControlPlaneClientOptions);
     /** GET /info: OIDC settings, router addresses and the ban list. Unauthenticated. */
-    info(): Promise<ControlPlaneInfoResponse>;
+    info(signal?: AbortSignal): Promise<ControlPlaneInfoResponse>;
     /**
      * GET /keys: every signing key the control plane currently trusts,
      * verified against a key the caller already trusts (the enrollment key).
      */
-    keys(trusted: Uint8Array[]): Promise<Uint8Array[]>;
+    keys(trusted: Uint8Array[], signal?: AbortSignal): Promise<Uint8Array[]>;
     /**
      * POST /enroll with a bootstrap token, then GET /enroll/status until an
      * operator approves the request if the mesh is not on auto-approve.

package/dist/controlplane.js

@@ -164,16 +164,16 @@ export class ControlPlaneClient {
         this.#now = options.now ?? (() => Date.now());
     }
     /** GET /info: OIDC settings, router addresses and the ban list. Unauthenticated. */
-    async info() {
-        const body = await this.#request("GET", "/info");
+    async info(signal) {
+        const body = await this.#request("GET", "/info", undefined, {}, signal);
         return fromBinary(ControlPlaneInfoResponseSchema, body);
     }
     /**
      * GET /keys: every signing key the control plane currently trusts,
      * verified against a key the caller already trusts (the enrollment key).
      */
-    async keys(trusted) {
-        const body = await this.#request("GET", "/keys");
+    async keys(trusted, signal) {
+        const body = await this.#request("GET", "/keys", undefined, {}, signal);
         return verifyKeysResponse(fromBinary(KeysResponseSchema, body), trusted, this.#now());
     }
     /**
@@ -304,14 +304,14 @@ export class ControlPlaneClient {
         }
         throw new ControlPlaneError(path, outcome.status, text);
     }
-    async #fetchOnce(method, path, body, headers = {}) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(new Error(`control plane ${path}: timed out after ${this.#timeoutMs}ms`)), this.#timeoutMs);
+    async #fetchOnce(method, path, body, headers = {}, signal) {
+        // The caller's signal cancels the request itself, not only the wait for it.
+        const timeout = AbortSignal.timeout(this.#timeoutMs);
         try {
             const init = {
                 method,
                 headers: { Accept: PROTOBUF_CONTENT_TYPE, ...headers },
-                signal: controller.signal,
+                signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
             };
             if (body !== undefined) {
                 init.body = new Uint8Array(body);
@@ -324,12 +324,15 @@ export class ControlPlaneClient {
             }
             return { ok: resp.ok, status: resp.status, buf, dateHeader: resp.headers.get("date") };
         }
-        finally {
-            clearTimeout(timer);
+        catch (err) {
+            if (timeout.aborted && signal?.aborted !== true) {
+                throw new Error(`control plane ${path}: timed out after ${this.#timeoutMs}ms`);
+            }
+            throw err;
         }
     }
-    async #request(method, path, body, headers = {}) {
-        const outcome = await this.#fetchOnce(method, path, body, headers);
+    async #request(method, path, body, headers = {}, signal) {
+        const outcome = await this.#fetchOnce(method, path, body, headers, signal);
         if (!outcome.ok) {
             throw new ControlPlaneError(path, outcome.status, new TextDecoder().decode(outcome.buf));
         }

package/dist/discovery.js

@@ -84,7 +84,7 @@ async function ask(conn, req, signal) {
  */
 export async function request(routers, req, signal) {
     const lookup = req.request.case === "findProviders" || req.request.case === "findPeer";
-    let last;
+    const failures = [];
     let asked = 0;
     let empty;
     for (const router of routers) {
@@ -103,7 +103,7 @@ export async function request(routers, req, signal) {
             return resp;
         }
         catch (err) {
-            last = err;
+            failures.push(`${router.peerId}: ${err instanceof Error ? err.message : String(err)}`);
             if (signal?.aborted === true) {
                 break;
             }
@@ -115,7 +115,7 @@ export async function request(routers, req, signal) {
     if (asked === 0) {
         throw new DirectoryError("no held router to ask");
     }
-    throw new DirectoryError(`no held router answered: ${last instanceof Error ? last.message : String(last)}`);
+    throw new DirectoryError(`no held router answered: ${failures.join("; ")}`);
 }
 /**
  * Announces this member as a provider of key, reached at addrs, to a held

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { Identity, canonicalPeerId, peerIdFromPublicKey, libp2pPublicKey, verify
 export { ControlPlaneClient, ControlPlaneError, EnrollmentRejectedError, InsecureControlPlaneURLError, KeysNotTrustedError, ROLE_NODE, validateControlPlaneURL, verifyKeysResponse, type ControlPlaneClientOptions, type Enrollment, type EnrollBootstrapParams, type PolicyRulesParams, type RegisterParams, type RefreshParams, type RefreshResult, } from "./controlplane.ts";
 export { attenuateCredential, credentialFromJSON, credentialTimeToLiveSeconds, credentialToJSON, decodeAuthResponse, encodeAuthFrame, sealCredential, withCredentialMethods, type MeshCredential, } from "./credential.ts";
 export { egressChallenge, enrollChallenge, enrollStatusChallenge, nodesCatalogChallenge, policiesChallenge, refreshChallenge, registerChallenge, revocationsChallenge, } from "./challenges.ts";
-export { DEFAULT_ROUTERS, MeshSession, ROUTER_REDIAL_BACKOFFS_MS, candidatesFromRouterInfos, selectRouters, type AdmittedRouter, type DiscoveredProvider, type JoinOptions, type Peer, type RouterCandidate, type SelectRoutersOptions, type ToolCallResult, } from "./session.ts";
+export { DEFAULT_ROUTERS, JOIN_TIMEOUT_MS, MeshSession, ROUTER_REDIAL_BACKOFFS_MS, candidatesFromRouterInfos, selectRouters, type AdmittedRouter, type DiscoveredProvider, type JoinOptions, type Peer, type RouterCandidate, type SelectRoutersOptions, type ToolCallResult, } from "./session.ts";
 export { BiscuitVerificationError, ROLE_ROUTER, attenuateBiscuit, requireRole, sealBiscuit, verifyPeerBiscuit, type VerifiedBiscuit, } from "./biscuit.ts";
 export { decodeTARBlockPayload, effectiveTARExpiration, encodeTARBlockFact, encodeTARBlockPayload, evaluateTaskRules, matchHTTPPath, matchServicePattern, matchTaskRule, parseTARBlockSource, validateHTTPGrantPath, validateServicePattern, validateTaskAuthorizationRule, validateTaskRule, type TaskRequestContext, } from "./tar.ts";
 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, type GoAwayServerOptions, } from "./auth.ts";

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.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.1.1" };
 /**
  * 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>;

package/dist/session.js

@@ -51,6 +51,17 @@ const DEFAULT_RELAY_CHECK_MS = 30 * 1000;
 const DEFAULT_ANNOUNCE_MS = 5 * 60 * 1000;
 /** What close() waits for the member's record to be withdrawn. */
 const WITHDRAW_TIMEOUT_MS = 2 * 1000;
+/**
+ * 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 const JOIN_TIMEOUT_MS = 60_000;
+/**
+ * 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 const JOIN_SYNC_TIMEOUT_MS = 5_000;
 /** How long a provider's positive egress verdict is kept; agentmesh-node's labelGateTTL. */
 const EGRESS_VERDICT_TTL_MS = 5 * 60 * 1000;
 /**
@@ -220,7 +231,7 @@ export class MeshSession {
      * the mesh's record TTL. A member with no relayed address announces
      * nothing: there is nothing to reach it at.
      */
-    async announce() {
+    async announce(signal) {
         if (this.#closed || this.#isTaskView) {
             return;
         }
@@ -228,7 +239,7 @@ export class MeshSession {
         if (addrs.length === 0) {
             return;
         }
-        await provide(this.#directoryRouters(), await peerKey(this.peerId), addrs);
+        await provide(this.#directoryRouters(), await peerKey(this.peerId), addrs, signal);
         this.#announced = addrs;
     }
     /** Whether peerId is currently one of the routers this member holds. */
@@ -372,14 +383,15 @@ export class MeshSession {
     /**
      * Runs the handshake on a router connection once: the connection:open
      * listener and an explicit admission both call this, and the second waits
-     * for the first instead of running a second handshake.
+     * for the first instead of running a second handshake. The signal applies
+     * to a handshake this call starts; one already running keeps its own.
      */
-    #authenticateRouter(conn) {
+    #authenticateRouter(conn, signal) {
         const pending = this.#routerHandshakes.get(conn.id);
         if (pending !== undefined) {
             return pending;
         }
-        const run = authenticateWithPeer(conn, this.mesh.authFrame(), this.mesh.credential.controlPlaneKeys).finally(() => {
+        const run = authenticateWithPeer(conn, this.mesh.authFrame(), this.mesh.credential.controlPlaneKeys, signal).finally(() => {
             this.#routerHandshakes.delete(conn.id);
         });
         this.#routerHandshakes.set(conn.id, run);
@@ -496,6 +508,8 @@ export class MeshSession {
      */
     async topUpRouters(signal) {
         const failures = [];
+        // A function, not a narrowed value: the signal aborts across the awaits below.
+        const aborted = () => signal?.aborted === true;
         const want = this.#wantRouters();
         const candidates = this.#candidatesForHolding();
         const tried = new Set();
@@ -513,22 +527,37 @@ export class MeshSession {
             }
             let progress = false;
             for (const cand of picks) {
+                // A router not dialed yet is not tried under a signal that has
+                // already aborted: it would fail at once and be shunned for nothing.
+                if (aborted()) {
+                    return failures;
+                }
                 tried.add(cand.peerId);
+                // Each step has a timeout of its own; the failure names the one the
+                // router was in, so a join that hangs says where.
+                let step = `dial ${cand.addresses.map(String).join(", ")}`;
                 try {
                     const conn = await this.node.dial(cand.addresses, signal !== undefined ? { signal } : {});
-                    const credential = await this.#authenticateRouter(conn);
+                    step = "auth handshake";
+                    const credential = await this.#authenticateRouter(conn, signal);
                     requireRole(credential, ROLE_ROUTER);
                     const addr = connectedAddress(conn, cand.peerId);
                     if (this.#reserveRelay) {
+                        step = "relay reservation";
                         await this.#reserveOnRouter(cand.peerId, addr);
                     }
                     this.#upsertHeldRouter({ peerId: cand.peerId, addr, credential });
                     progress = true;
                 }
                 catch (err) {
-                    this.#shunRouter(cand.peerId, ROUTER_SHUN_DURATION_MS);
+                    failures.push(`${cand.peerId}: ${step}: ${errorText(err)}`);
                     await this.node.hangUp(peerIdFromString(cand.peerId)).catch(() => { });
-                    failures.push(`${cand.peerId}: ${err instanceof Error ? err.message : String(err)}`);
+                    // A router cut off by the signal did not fail on its own, so it is
+                    // not shunned.
+                    if (aborted()) {
+                        return failures;
+                    }
+                    this.#shunRouter(cand.peerId, ROUTER_SHUN_DURATION_MS);
                 }
             }
             if (!progress && picks.length < need) {
@@ -1187,8 +1216,14 @@ export function selectRouters(candidates, k, options = {}) {
     });
     return scored.slice(0, k).map((s) => s.candidate);
 }
-/** Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p. */
-export async function joinMesh(mesh, options = {}) {
+/**
+ * Implements AgentMesh.join(); lives here to keep mesh.ts free of libp2p.
+ * timeoutMs bounds a join whose caller passed no signal.
+ */
+export async function joinMesh(mesh, options = {}, timeoutMs = JOIN_TIMEOUT_MS) {
+    const signal = options.signal ?? AbortSignal.timeout(timeoutMs);
+    // Why the join stopped: the caller's reason, or its own timeout.
+    const stopReason = () => (options.signal !== undefined ? errorText(signal.reason) : `timed out after ${timeoutMs}ms`);
     // The pull agentmesh-node makes before it starts: a member resuming from its
     // state directory after a key rotation would otherwise verify the routers,
     // which already hold credentials under the new key, against the keys it
@@ -1196,10 +1231,14 @@ export async function joinMesh(mesh, options = {}) {
     // once joined. Best effort; the stored credential serves when the control
     // plane cannot be reached.
     try {
-        await mesh.syncControlPlane();
+        await mesh.syncControlPlane(AbortSignal.any([signal, AbortSignal.timeout(JOIN_SYNC_TIMEOUT_MS)]));
     }
     catch {
-        // Joining goes on with what the credential holds.
+        // Joining goes on with what the credential holds, unless the caller
+        // stopped the join while the control plane kept it waiting.
+        if (signal.aborted) {
+            throw new Error(`join stopped while syncing with the control plane: ${stopReason()}`);
+        }
     }
     const rawAddrs = options.routerAddresses ?? mesh.credential.routerAddresses;
     if (rawAddrs.length === 0 && mesh.routers.length === 0) {
@@ -1225,14 +1264,18 @@ export async function joinMesh(mesh, options = {}) {
             onGoAway: (peerId, msg, retryAfterMs) => session?.handleGoAway(peerId, msg, retryAfterMs),
         }), AUTH_HANDLER_OPTIONS);
         session = new MeshSession(mesh, node, [], authenticatedPeers, banned, options);
-        const failures = await session.topUpRouters(options.signal);
-        if (session.routers.length === 0) {
+        const failures = await session.topUpRouters(signal);
+        // One admitted router is enough to be on the mesh; only the caller's own
+        // signal turns that into a failure.
+        if (options.signal?.aborted === true || session.routers.length === 0) {
             const detail = failures.length > 0 ? `:\n  ${failures.join("\n  ")}` : "";
-            throw new Error(`no router admitted this member${detail}`);
+            throw new Error(signal.aborted ? `join stopped: ${stopReason()}${detail}` : `no router admitted this member${detail}`);
         }
         // Best effort: a router that does not take the record is a warning the
-        // next announcement retries; the member is on the mesh regardless.
-        await session.announce().catch(() => { });
+        // next announcement retries; the member is on the mesh regardless. Under
+        // the caller's signal only: a join that ran out of its own time still
+        // announces the routers it holds.
+        await session.announce(options.signal).catch(() => { });
         return session;
     }
     catch (err) {
@@ -1245,6 +1288,9 @@ export async function joinMesh(mesh, options = {}) {
         throw err;
     }
 }
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /** The peer a multiaddr ends at, in canonical form: its trailing `/p2p/<id>`, or undefined for a relay address with no target yet. */
 function targetPeerOf(ma) {
     const last = ma.getComponents().at(-1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmesh-p2p/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Native SDK for joining an Agent Mesh from a Node.js agent process or a browser page",
   "license": "Apache-2.0",
   "repository": {