@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/dist/platform/ingress.browser.js

@@ -0,0 +1,16 @@
+// 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 /libp2p-http ingress in a browser: a fetch handler or a URL; a Node
+// request listener is answered 501, there is no Node HTTP server to run it.
+export { httpIngressHandler as ingressHandler } from "../libp2p-http.js";

package/dist/platform/ingress.d.ts

@@ -0,0 +1 @@
+export { nodeIngressHandler as ingressHandler } from "../libp2p-http-node.ts";

package/dist/platform/ingress.js

@@ -0,0 +1,15 @@
+// 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 /libp2p-http ingress on Node serves a Node request listener too.
+export { nodeIngressHandler as ingressHandler } from "../libp2p-http-node.js";

package/dist/platform/state.browser.d.ts

@@ -0,0 +1,5 @@
+import type { StateStore } from "./types.ts";
+/** The store for a state location: a database named after it. */
+export declare function openState(location: string): StateStore;
+/** A browser has no file system a page may read; give the token itself. */
+export declare function readTextFile(path: string): Promise<string>;

package/dist/platform/state.browser.js

@@ -0,0 +1,47 @@
+// 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.
+const STORE = "state";
+function request(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error ?? new Error("IndexedDB request failed"));
+    });
+}
+function openDatabase(name) {
+    const req = indexedDB.open(`agentmesh:${name}`, 1);
+    req.onupgradeneeded = () => {
+        req.result.createObjectStore(STORE);
+    };
+    return request(req);
+}
+/** The store for a state location: a database named after it. */
+export function openState(location) {
+    let db;
+    const open = () => (db ??= openDatabase(location));
+    return {
+        async read(name) {
+            const tx = (await open()).transaction(STORE, "readonly");
+            const value = await request(tx.objectStore(STORE).get(name));
+            return value instanceof Uint8Array ? value : undefined;
+        },
+        async write(name, data) {
+            const tx = (await open()).transaction(STORE, "readwrite");
+            await request(tx.objectStore(STORE).put(new Uint8Array(data), name));
+        },
+    };
+}
+/** A browser has no file system a page may read; give the token itself. */
+export async function readTextFile(path) {
+    throw new Error(`cannot read ${path}: a browser has no files to read a token from; pass the value instead`);
+}

package/dist/platform/state.d.ts

@@ -0,0 +1,5 @@
+import type { StateStore } from "./types.ts";
+/** The store for a state location: a directory, created on first write. */
+export declare function openState(location: string): StateStore;
+/** A text file, for a token an operator or a platform placed on disk. */
+export declare function readTextFile(path: string): Promise<string>;

package/dist/platform/state.js

@@ -0,0 +1,44 @@
+// 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.
+// State on Node: a directory, one file per name, owner-only, written to a
+// temporary name and renamed into place. Where a token file is read from.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The store for a state location: a directory, created on first write. */
+export function openState(location) {
+    return {
+        async read(name) {
+            try {
+                return new Uint8Array(await readFile(join(location, name)));
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    return undefined;
+                }
+                throw err;
+            }
+        },
+        async write(name, data) {
+            await mkdir(location, { recursive: true, mode: 0o700 });
+            const path = join(location, name);
+            const tmp = `${path}.tmp`;
+            await writeFile(tmp, data, { mode: 0o600 });
+            await rename(tmp, path);
+        },
+    };
+}
+/** A text file, for a token an operator or a platform placed on disk. */
+export async function readTextFile(path) {
+    return readFile(path, "utf8");
+}

package/dist/platform/transports.browser.d.ts

@@ -0,0 +1,3 @@
+import type { Libp2pOptions } from "libp2p";
+export declare function transports(): NonNullable<Libp2pOptions["transports"]>;
+export declare function connectionEncrypters(): NonNullable<Libp2pOptions["connectionEncrypters"]>;

package/dist/platform/transports.browser.js

@@ -0,0 +1,27 @@
+// 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.
+// How a member in a browser reaches the mesh: WebSocket, the one transport a
+// page can open to a router (agentmesh-one's single port, or a router behind a
+// TLS-terminating proxy as wss), secured with Noise. A browser cannot run
+// libp2p's TLS, which needs a self-signed certificate over a raw socket;
+// routers and nodes accept Noise beside TLS, and both bind the connection to
+// the peer ID.
+import { noise } from "@chainsafe/libp2p-noise";
+import { webSockets } from "@libp2p/websockets";
+export function transports() {
+    return [webSockets()];
+}
+export function connectionEncrypters() {
+    return [noise()];
+}

package/dist/platform/transports.d.ts

@@ -0,0 +1,3 @@
+import type { Libp2pOptions } from "libp2p";
+export declare function transports(): NonNullable<Libp2pOptions["transports"]>;
+export declare function connectionEncrypters(): NonNullable<Libp2pOptions["connectionEncrypters"]>;

package/dist/platform/transports.js

@@ -0,0 +1,27 @@
+// 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.
+// How a member on Node reaches the mesh: TCP and WebSocket, the transports
+// the routers listen on. TLS 1.3 first, as every Go peer and the Python SDK
+// offer it (internal/node/node.go); Noise accepted, so a member in a
+// browser, which speaks Noise alone, is reached end to end through a relay.
+import { noise } from "@chainsafe/libp2p-noise";
+import { tcp } from "@libp2p/tcp";
+import { tls } from "@libp2p/tls";
+import { webSockets } from "@libp2p/websockets";
+export function transports() {
+    return [tcp(), webSockets()];
+}
+export function connectionEncrypters() {
+    return [tls(), noise()];
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,7 @@
+/** Where a member keeps its identity and credential between runs. */
+export interface StateStore {
+    /** The bytes under a name, or undefined when nothing was written yet. */
+    read(name: string): Promise<Uint8Array | undefined>;
+    /** Writes the bytes under a name so that a reader sees the old or the new value, never a mix. */
+    write(name: string, data: Uint8Array): Promise<void>;
+}

package/dist/platform/types.js

@@ -0,0 +1,14 @@
+// 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.
+export {};

package/dist/platform/wasm.browser.d.ts

@@ -0,0 +1,2 @@
+export type BiscuitWasm = typeof import("@biscuit-auth/biscuit-wasm");
+export declare function loadBiscuitWasm(): Promise<BiscuitWasm>;

package/dist/platform/wasm.browser.js

@@ -0,0 +1,16 @@
+// 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.
+export async function loadBiscuitWasm() {
+    return import("@biscuit-auth/biscuit-wasm");
+}

package/dist/platform/wasm.d.ts

@@ -0,0 +1,2 @@
+export type BiscuitWasm = typeof import("@biscuit-auth/biscuit-wasm");
+export declare function loadBiscuitWasm(): Promise<BiscuitWasm>;

package/dist/platform/wasm.js

@@ -0,0 +1,56 @@
+// 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.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// biscuit-wasm is built for bundlers and imports its .wasm as a module,
+// which Node only does behind a flag. Instantiating it by hand avoids the
+// flag; the module's import list says what it needs.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+export async function loadBiscuitWasm() {
+    const dir = new URL("./", import.meta.resolve("@biscuit-auth/biscuit-wasm"));
+    const bindings = (await import(__rewriteRelativeImportExtension(new URL("biscuit_bg.js", dir).href)));
+    const module = await WebAssembly.compile(await readFile(fileURLToPath(new URL("biscuit_bg.wasm", dir))));
+    const imports = {};
+    for (const imp of WebAssembly.Module.imports(module)) {
+        const ns = (imports[imp.module] ??= {});
+        if (imp.module === "./biscuit_bg.js") {
+            ns[imp.name] = bindings[imp.name];
+        }
+        else if (imp.name === "performance_now") {
+            ns[imp.name] = () => performance.now();
+        }
+        else {
+            throw new Error(`biscuit-wasm needs an unknown import ${imp.module}:${imp.name}`);
+        }
+    }
+    const instance = await WebAssembly.instantiate(module, imports);
+    bindings.__wbg_set_wasm(instance.exports);
+    // The module's start hook logs a greeting to the console.
+    const log = console.log;
+    console.log = () => { };
+    try {
+        instance.exports.__wbindgen_start();
+    }
+    finally {
+        console.log = log;
+    }
+    return bindings;
+}

package/dist/session.d.ts

@@ -0,0 +1,316 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import type { Connection } from "@libp2p/interface";
+import { type Multiaddr } from "@multiformats/multiaddr";
+import { type VerifiedBiscuit } from "./biscuit.ts";
+import type { RouterGoAway, RouterInfo, TaskAuthorizationRuleSchema } from "./gen/agentmesh_pb.ts";
+import { type MeshHost, type MeshHostOptions, type RelayListener } from "./host.ts";
+import { type MCPSession, type MCPSessionOptions } from "./mcp.ts";
+import type { AgentMesh, ControlPlaneSync } from "./mesh.ts";
+import { type A2AEndpoint, type A2AEndpointSpec, type HTTPRequestOptions, type HTTPResponse } from "./libp2p-http.ts";
+import { BanSet } from "./sync.ts";
+/** Default number of routers a member attaches to and reserves on at join. */
+export declare const DEFAULT_ROUTERS = 2;
+/** Default backoff delays before replacing a dropped held router. */
+export declare const ROUTER_REDIAL_BACKOFFS_MS: readonly number[];
+export interface JoinOptions extends MeshHostOptions {
+    /**
+     * The routers to join through, `/…/p2p/<router>` multiaddrs, instead of
+     * the ones the credential lists. A peer behind a router not named here is
+     * still reached: connect() finds it through the routers' DHT and
+     * authenticates with the router that relays for it.
+     */
+    routerAddresses?: string[];
+    /**
+     * Number of routers to hold and reserve on at a time (agentmesh-node's --routers).
+     * Defaults to DEFAULT_ROUTERS (2).
+     */
+    routers?: number;
+    /**
+     * Required router labels (agentmesh-node's --router-selector): every pair must
+     * match the router's labels in ControlPlaneInfoResponse.routers.
+     */
+    routerSelector?: Record<string, string>;
+    /**
+     * Preferred router labels (agentmesh-node's --router-prefer): routers matching
+     * more pairs are chosen ahead of others before comparing load.
+     */
+    routerPrefer?: Record<string, string>;
+    /**
+     * Backoff delays (ms) when redialing a held router whose connection dropped
+     * before shunning it and failing over to another router from the catalog.
+     * Defaults to ROUTER_REDIAL_BACKOFFS_MS ([2000, 4000, 8000]).
+     */
+    routerRedialBackoffsMs?: readonly number[];
+    /**
+     * Reserve a relay slot on each held router that admits us, so peers can
+     * reach this member through the routers. On by default; a member that
+     * only calls out can turn it off.
+     */
+    reserveRelay?: boolean;
+    /** Refresh the credential this long before it expires. */
+    refreshLeadMs?: number;
+    /** Retry a failed refresh after this long. */
+    refreshRetryMs?: number;
+    /** How often the mesh policy is re-read from the control plane while accepting callers. */
+    policySyncIntervalMs?: number;
+    /**
+     * How often keys, bans and router addresses are pulled from the control
+     * plane (agentmesh-node's --control-plane-sync-interval). Gossip events bring a
+     * pull forward; 0 disables the loop.
+     */
+    controlPlaneSyncIntervalMs?: number;
+    /** Upper bound of the random delay before a pull an event triggered. */
+    controlPlaneSyncJitterMs?: number;
+    /**
+     * How often the relay reservation is checked while reserveRelay is on: a
+     * router that restarted or trimmed the connection dropped it, and this is
+     * how long the member is unreachable at most before it reserves again.
+     */
+    relayCheckIntervalMs?: number;
+    /**
+     * How often this member announces where it is reached under its peer
+     * key (default 5 minutes, agentmesh-node's reprovide interval).
+     */
+    announceIntervalMs?: number;
+    /**
+     * agentmesh-node's egress.require_labels for an SDK member: every provider this
+     * session calls must attest all of these pairs, on top of a call's
+     * requiredLabels. Held on every call, MCP and HTTP alike; no call waives it.
+     */
+    egressRequireLabels?: Record<string, string>;
+    /** Bounds the whole join. */
+    signal?: AbortSignal;
+}
+export interface AdmittedRouter {
+    peerId: string;
+    /**
+     * The address the connection to the router was made on, resolved: a
+     * `/ip4` or `/ip6` address ending in `/p2p/<router>`. Relay addresses
+     * are built on it. The control plane may hand a router out as
+     * `/dnsaddr/<host>/p2p/<router>`; js-libp2p resolves such an address to
+     * the TXT records themselves and drops what follows it, so a
+     * `/dnsaddr/.../p2p-circuit/p2p/<peer>` address reaches nobody.
+     */
+    addr: Multiaddr;
+    credential: VerifiedBiscuit;
+}
+/** One router candidate from the control plane's /info catalog. */
+export interface RouterCandidate {
+    peerId: string;
+    addresses: Multiaddr[];
+    labels: Record<string, string>;
+    connections: number;
+    connectionLimit: number;
+}
+/** A peer the DHT names as offering a service. */
+export interface DiscoveredProvider {
+    peerId: string;
+    /** Addresses the provider advertised; may be empty when the record carried none. */
+    addrs: string[];
+}
+/**
+ * How a caller names the peer it wants to reach: a provider `discover`
+ * returned, a peer id, or a multiaddr. For a provider or a peer id the SDK
+ * dials the addresses the peer advertised and the relayed path through
+ * every router that admitted this member, so the caller never assembles a
+ * `/p2p-circuit` address. A multiaddr is dialed as given.
+ */
+export type Peer = DiscoveredProvider | string | Multiaddr;
+/** A tool call's outcome, as MCP reports it. */
+export interface ToolCallResult {
+    isError: boolean;
+    /** Text content blocks, in order; other block types are left out. */
+    text: string[];
+    /** The raw MCP result. */
+    raw: unknown;
+}
+/**
+ * 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
+ * keeping its credential fresh. Close it to leave.
+ */
+export declare class MeshSession {
+    #private;
+    readonly mesh: AgentMesh;
+    readonly node: MeshHost;
+    readonly routers: AdmittedRouter[];
+    /** Peers that passed the inbound auth handshake, with their credential's expiration. */
+    readonly authenticatedPeers: Map<string, Date>;
+    /** Peers the control plane has banned; connections to and from them are refused. */
+    readonly banned: BanSet;
+    /** Count of /mesh/goaway/1.0.0 frames received from held routers, keyed by reason name (DRAINING, OVERLOADED, REASON_UNSPECIFIED). */
+    readonly goAwayReceived: Map<string, number>;
+    /** Routers currently shunned (after a go-away or failed redial), mapped to the unix ms when the shun expires. */
+    readonly shunnedRouters: Map<string, number>;
+    /** This member's agent, once acceptA2A was called. */
+    endpoint: A2AEndpoint | undefined;
+    constructor(mesh: AgentMesh, node: MeshHost, routers: AdmittedRouter[], authenticatedPeers: Map<string, Date>, banned: BanSet, options: JoinOptions, relayListeners?: Map<string, RelayListener>, taskBiscuit?: Uint8Array, sharedState?: {
+        heldRouterIds: Set<string>;
+        freeRelayListeners: RelayListener[];
+        goAwayReceived: Map<string, number>;
+        shunnedRouters: Map<string, number>;
+    });
+    get peerId(): string;
+    /** The Biscuit presented on outbound service calls (task-attenuated when derived via attenuate()). */
+    get biscuit(): Uint8Array;
+    /**
+     * Returns a task-scoped MeshSession view sharing the underlying libp2p host
+     * whose outbound MCP and HTTP service calls carry a Biscuit attenuated offline
+     * in memory with rule.
+     */
+    attenuate(rule: MessageInitShape<typeof TaskAuthorizationRuleSchema>): Promise<MeshSession>;
+    /**
+     * Returns a MeshSession view whose outbound Biscuit is sealed so downstream
+     * holders cannot append any further blocks.
+     */
+    seal(): Promise<MeshSession>;
+    /**
+     * The URL a fetch bound to this session (fetch()) takes for a service on a
+     * peer: http://mesh/mesh/<peer-id>/<type>/<name>/<path>, the shape of
+     * agentmesh-node's egress proxy and of an agent card it rewrote.
+     */
+    static meshURL(peerId: string, targetService: string, path?: string): string;
+    /** The mesh URL of this member's own agent, once acceptA2A was called. */
+    get agentURL(): string | undefined;
+    /** Addresses peers can dial this member on, including relayed ones. */
+    get addresses(): Multiaddr[];
+    /** The `.../p2p-circuit/p2p/<self>` addresses reserved on held routers. */
+    get relayAddresses(): Multiaddr[];
+    /**
+     * Announces where this member is reached, its relayed addresses on the
+     * routers it holds, under its peer key, so that a peer attached to other
+     * routers finds it by ID. Runs after join, when the addresses change and
+     * every announceIntervalMs; the record outlives its last announcement by
+     * the mesh's record TTL. A member with no relayed address announces
+     * nothing: there is nothing to reach it at.
+     */
+    announce(): 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. */
+    handleGoAway(peerId: string, msg: RouterGoAway, retryAfterMs: number): Promise<void>;
+    /**
+     * Maintains held routers and relay reservations: when a held router's
+     * connection or reservation drops, redials it first (2s, 4s, 8s by default)
+     * using its current address from the catalog; if it does not recover or
+     * refuses auth, shuns it and tops up from the catalog. Runs on
+     * relayCheckIntervalMs and immediately after a /mesh/goaway/1.0.0 frame.
+     */
+    keepRelay(): Promise<void>;
+    /**
+     * Attaches and reserves on additional routers from the catalog until this
+     * session holds wantRouters() routers or no more eligible candidates remain.
+     */
+    topUpRouters(signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Connects to a peer; see Peer for how it is named. Returns the
+     * connection, reused if one is already open. A banned peer is refused
+     * here and by the connection gater. A peer named by ID that no admitted
+     * router relays for is looked up in the routers' DHT, and failing that
+     * tried through every router the control plane lists that this member
+     * has not joined through; a relay opens a circuit only for a source it
+     * authenticated, so each such router is admitted first. Which router each
+     * side joined through does not decide whether they can talk.
+     */
+    connect(peer: Peer, signal?: AbortSignal): Promise<Connection>;
+    /** The addresses connect() dials for a peer, in the order libp2p tries them. */
+    dialTargets(peer: Peer): {
+        peerId: string | undefined;
+        addrs: Multiaddr[];
+    };
+    /** `<router>/p2p-circuit/p2p/<peer>` through every router that admitted this member. */
+    relayedAddresses(peerId: string): Multiaddr[];
+    /** Connects to a peer and runs the mutual auth handshake, returning its verified credential. */
+    authenticate(peer: Peer, signal?: AbortSignal): Promise<VerifiedBiscuit>;
+    /**
+     * Asks the directory for peers offering a service: `"mcp://calc"`, the
+     * same string callTool and request take, or a type alone (`"mcp"`) for
+     * every service of that type, or (type, name). A router this member holds
+     * answers; bounded by the timeout.
+     */
+    discover(service: string, name?: string, options?: {
+        timeoutMs?: number;
+        limit?: number;
+    }): Promise<DiscoveredProvider[]>;
+    /**
+     * Opens an MCP session with a provider for targetService ("mcp://<name>",
+     * or "" for the provider's own catalog tools).
+     */
+    openMCP(peer: Peer, targetService: string, options?: MCPSessionOptions): Promise<MCPSession>;
+    /** Lists the tools a provider serves for a service. */
+    listTools(peer: Peer, targetService: string, options?: MCPSessionOptions): Promise<{
+        name: string;
+        description?: string;
+    }[]>;
+    /** Calls one tool on a provider's service. */
+    callTool(peer: Peer, targetService: string, tool: string, args?: Record<string, unknown>, options?: MCPSessionOptions): Promise<ToolCallResult>;
+    /** Refreshes now and reschedules; exposed so a caller can force it. */
+    refresh(): Promise<void>;
+    /**
+     * Pulls keys, bans and router addresses from the control plane now, and
+     * the mesh policy when accepting callers, then applies them: a newly
+     * banned peer is hung up on and dropped from the admitted set. Concurrent
+     * calls share one pull. Errors of individual parts are in the result, not
+     * thrown.
+     */
+    sync(): Promise<ControlPlaneSync>;
+    /** Asks for a pull soon, after a random delay so a fleet told at once does not pull at once. */
+    triggerSync(): void;
+    /**
+     * The mesh policy rules this member evaluates for callers, as the control
+     * plane rendered them (PolicyConfigGetResponse.datalog_rules). Empty until
+     * the first control plane sync, acceptA2A() or syncPolicy().
+     */
+    get policyRules(): string[];
+    /** Re-reads the mesh policy from the control plane. */
+    syncPolicy(): Promise<void>;
+    /**
+     * Calls an inference or A2A service on a provider over /libp2p-http, the
+     * way agentmesh-node's egress proxy does for /mesh/<peer>/<type>/<name>/<path>.
+     */
+    request(peer: Peer, targetService: string, path: string, options?: HTTPRequestOptions): Promise<HTTPResponse>;
+    /**
+     * A `fetch` bound to the mesh, for clients built on fetch such as the A2A
+     * SDK's (`fetchImpl`): a request to http://mesh/mesh/<peer-id>/<type>/<name>/<path>
+     * is carried to that peer over /libp2p-http with this member's credential.
+     * Response bodies stream, so message/stream works. See MeshSession.meshURL.
+     */
+    fetch(): typeof fetch;
+    /**
+     * Makes this member's agent reachable: other members call it as
+     * `a2a://<name>` by peer ID, through a router, and the SDK answers
+     * /libp2p-http with the spec's url (an A2A server beside this process),
+     * handler or listener (in this process; an Express app with the A2A SDK's
+     * handlers is a listener). Nothing is announced: no DHT record, no
+     * catalog entry. A tool, a model or a service others should find by name
+     * is published by a agentmesh-node. Fetches the mesh policy first and keeps it
+     * current; a policy that cannot be read fails the call, since an agent
+     * without it could only authorize what callers carry in their own tokens.
+     * Returns the service target callers use. One agent per session.
+     */
+    acceptA2A(spec: A2AEndpointSpec): Promise<string>;
+    close(): Promise<void>;
+}
+export interface SelectRoutersOptions {
+    selector?: Record<string, string>;
+    prefer?: Record<string, string>;
+    attached?: ReadonlySet<string>;
+    shunned?: ReadonlyMap<string, number>;
+    nowMs?: number;
+    random?: () => number;
+}
+/**
+ * Builds router candidates from ControlPlaneInfoResponse.routers, falling back
+ * to router_addresses when routers is empty (an older control plane). When
+ * routerMetadata is provided alongside explicit fallbackAddresses, labels and
+ * load from routerMetadata are attached by peerId.
+ */
+export declare function candidatesFromRouterInfos(routers: readonly RouterInfo[], fallbackAddresses: readonly string[], routerMetadata?: readonly RouterInfo[]): RouterCandidate[];
+/**
+ * Picks up to k routers from candidates, mirroring agentmesh-node's selectRouters:
+ * filters by selector, excludes already-attached and currently-shunned routers,
+ * 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>;