@agentmesh-p2p/sdk 0.1.0 → 0.2.0

package/README.md

@@ -24,6 +24,66 @@ Requires Node.js 22.18 or later. In a browser, bundle it with the page
 [In a browser](https://google.github.io/agentmesh/docs/guides/native-sdks/#in-a-browser)
 section has the details and an example page.
 
+## MCP client over stdio
+
+The package's `agentmesh` executable joins as its own mesh member and exposes
+five MCP tools: `get_mesh_info`, `discover_remote_services`, `find_remote_tools`,
+`describe_remote_tool` and `call_remote_tool`. A stdio-capable MCP client starts
+and stops the process; no node daemon is needed for this caller. Providers still
+publish their services through `agentmesh-node`.
+
+To try the executable from a source checkout:
+
+```bash
+cd sdk/js
+npm ci
+npm run build
+```
+
+Use absolute paths in your MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "agentmesh": {
+      "command": "node",
+      "args": ["/absolute/path/to/agentmesh/sdk/js/dist/cli.js"],
+      "env": {
+        "AGENTMESH_CONTROL_PLANE_URL": "https://your-control-plane.example",
+        "AGENTMESH_BOOTSTRAP_TOKEN_PATH": "/absolute/path/to/join-token",
+        "AGENTMESH_STATE_DIR": "/absolute/path/to/this-client-identity"
+      }
+    }
+  }
+}
+```
+
+Get the control plane URL and token file from your mesh operator or
+[`agentmesh-one`](https://google.github.io/agentmesh/docs/guides/native-sdks/).
+Alternatively, set `AGENTMESH_JWT_PATH` to a workload/OIDC token file; do not set
+both token paths. Credentials are read from files, never command-line values.
+
+The first run enrolls and saves its identity; later runs resume from the state
+directory without the bootstrap token. JWT enrollment rereads the token file
+when refreshing. Use a distinct state directory for each client identity and
+mesh; do not run multiple processes against the same directory. The default is
+`~/.config/agentmesh/mcp`. Plain HTTP is allowed on loopback only unless
+`AGENTMESH_INSECURE_CONTROL_PLANE=true` explicitly permits it elsewhere.
+
+Stdout contains only MCP messages; diagnostics go to stderr. Closing stdin or
+sending SIGINT/SIGTERM shuts down the mesh session. Tool calls use the member's
+existing authenticated streams and policy, including provider label checks.
+Remote tool results retain text, non-text content, structured output and errors.
+Discovery follows tool pagination, rejects looping catalogs and bounds each
+search to 64 providers, 256 services per provider, 256 tools per service and
+1024 results. Requests have a 10-second deadline; narrow a large search by peer
+or service. `intent` is accepted but ignored, matching the node's current tool.
+
+This member publishes no services, so it has no `list_local_services` tool.
+Inference and A2A discovery return metadata, but this executable provides no
+HTTP proxy, `/v1` endpoint, local socket or `local_proxy_url`. Use an SDK client
+or an `agentmesh-node` HTTP proxy to invoke those protocols.
+
 ## Use
 
 Both programs below are in

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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// 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.
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AgentMesh } from "./mesh.js";
+import { createMeshMCPServer } from "./mcp-server.js";
+function options() {
+    const env = process.env;
+    const controlPlaneUrl = env.AGENTMESH_CONTROL_PLANE_URL?.trim();
+    if (!controlPlaneUrl)
+        throw new Error("AGENTMESH_CONTROL_PLANE_URL is required");
+    if (env.AGENTMESH_BOOTSTRAP_TOKEN_PATH && env.AGENTMESH_JWT_PATH) {
+        throw new Error("set only one of AGENTMESH_BOOTSTRAP_TOKEN_PATH and AGENTMESH_JWT_PATH");
+    }
+    if (env.AGENTMESH_INSECURE_CONTROL_PLANE && !["true", "false"].includes(env.AGENTMESH_INSECURE_CONTROL_PLANE)) {
+        throw new Error("AGENTMESH_INSECURE_CONTROL_PLANE must be true or false");
+    }
+    // A client launches this from any working directory; a relative path would
+    // silently read credentials or enrol an identity somewhere unexpected.
+    for (const name of ["AGENTMESH_BOOTSTRAP_TOKEN_PATH", "AGENTMESH_JWT_PATH", "AGENTMESH_STATE_DIR"]) {
+        if (env[name] && !isAbsolute(env[name]))
+            throw new Error(`${name} must be an absolute path`);
+    }
+    return {
+        controlPlaneUrl,
+        bootstrapTokenPath: env.AGENTMESH_BOOTSTRAP_TOKEN_PATH || undefined,
+        jwtPath: env.AGENTMESH_JWT_PATH || undefined,
+        stateDir: env.AGENTMESH_STATE_DIR || join(homedir(), ".config", "agentmesh", "mcp"),
+        allowInsecure: env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
+    };
+}
+async function main() {
+    if (process.argv.length > 2) {
+        if (process.argv.length !== 3 || !["--help", "-h"].includes(process.argv[2])) {
+            throw new Error("agentmesh accepts no arguments other than --help; configure it through AGENTMESH_* environment variables");
+        }
+        console.error("agentmesh: MCP over stdio\n" +
+            "AGENTMESH_CONTROL_PLANE_URL      Mesh control plane URL (required)\n" +
+            "AGENTMESH_BOOTSTRAP_TOKEN_PATH   Bootstrap token file for first enrollment\n" +
+            "AGENTMESH_JWT_PATH               OIDC/workload token file, read again on refresh\n" +
+            "AGENTMESH_STATE_DIR              Identity directory (default: ~/.config/agentmesh/mcp)\n" +
+            "AGENTMESH_INSECURE_CONTROL_PLANE  true permits plaintext HTTP beyond loopback (default: false)");
+        return;
+    }
+    const config = options();
+    const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const abort = new AbortController();
+    let stop;
+    const stopped = new Promise((resolve) => { stop = () => { abort.abort(); resolve(); }; });
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    process.stdin.once("end", stop);
+    let session;
+    const ready = AgentMesh.enroll({
+        ...config,
+        signal: abort.signal,
+        // EnrollOptions.signal bounds pending approval, not every HTTP request.
+        // The executable owns this client: shutdown must also cancel enrollment,
+        // credential resume and key fetches while the control plane is silent.
+        fetch: (input, init) => fetch(input, {
+            ...init,
+            signal: AbortSignal.any([abort.signal, ...(init?.signal ? [init.signal] : [])]),
+        }),
+    }).then(async (mesh) => {
+        session = await mesh.join({ signal: abort.signal });
+        return session;
+    });
+    // Handle startup failure immediately, including before a client calls a tool.
+    void ready.catch((err) => {
+        if (!abort.signal.aborted) {
+            console.error(`agentmesh: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = 1;
+        }
+        stop();
+    });
+    const server = createMeshMCPServer(ready, version);
+    server.server.onclose = stop;
+    try {
+        await server.connect(new StdioServerTransport());
+        await stopped;
+    }
+    finally {
+        stop();
+        try {
+            await server.close();
+        }
+        finally {
+            await ready.catch(() => undefined);
+            try {
+                await session?.close();
+            }
+            finally {
+                process.removeListener("SIGINT", stop);
+                process.removeListener("SIGTERM", stop);
+                process.stdin.removeListener("end", stop);
+            }
+        }
+    }
+}
+void main().catch((err) => {
+    console.error(`agentmesh: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});

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/gen/agentmesh_pb.d.ts

@@ -344,6 +344,37 @@ export type BootstrapEnrollResponse = Message<"agentmesh.v1.BootstrapEnrollRespo
  * Use `create(BootstrapEnrollResponseSchema)` to create a new message.
  */
 export declare const BootstrapEnrollResponseSchema: GenMessage<BootstrapEnrollResponse>;
+/**
+ * ServiceIngress configures external router HTTP ingress for an inbound service
+ * (a2a, mcp, or inference). Absent means the service is reachable only inside
+ * the mesh.
+ *
+ * @generated from message agentmesh.v1.ServiceIngress
+ */
+export type ServiceIngress = Message<"agentmesh.v1.ServiceIngress"> & {
+    /**
+     * Defaults to INGRESS_AUTH_MODE_EDGE when UNSPECIFIED.
+     *
+     * @generated from field: agentmesh.v1.IngressAuthMode auth_mode = 1;
+     */
+    authMode: IngressAuthMode;
+    /**
+     * Optional caller narrowing in PolicyBinding.members syntax
+     * (e.g. "email:alice@example.com", "email:*@example.com", "group:eng").
+     * Intersected (AND) with mesh Datalog policy: when empty, any caller
+     * authorized by mesh policy for this service may invoke it; when non-empty,
+     * the verified caller must also match at least one entry here. Only allowed
+     * in INGRESS_AUTH_MODE_EDGE.
+     *
+     * @generated from field: repeated string allow = 2;
+     */
+    allow: string[];
+};
+/**
+ * Describes the message agentmesh.v1.ServiceIngress.
+ * Use `create(ServiceIngressSchema)` to create a new message.
+ */
+export declare const ServiceIngressSchema: GenMessage<ServiceIngress>;
 /**
  * @generated from message agentmesh.v1.ServiceInfo
  */
@@ -360,6 +391,12 @@ export type ServiceInfo = Message<"agentmesh.v1.ServiceInfo"> & {
      * @generated from field: string description = 3;
      */
     description: string;
+    /**
+     * Optional external ingress exposure for this service.
+     *
+     * @generated from field: agentmesh.v1.ServiceIngress ingress = 4;
+     */
+    ingress?: ServiceIngress | undefined;
 };
 /**
  * Describes the message agentmesh.v1.ServiceInfo.
@@ -621,6 +658,14 @@ export type DirectoryProvide = Message<"agentmesh.v1.DirectoryProvide"> & {
      * @generated from field: string service = 4;
      */
     service: string;
+    /**
+     * Optional external ingress metadata for a named service record. When set,
+     * the router verifies that the provider's credential grants exposing this
+     * service with the requested auth_mode before storing or replicating it.
+     *
+     * @generated from field: agentmesh.v1.ServiceIngress ingress = 5;
+     */
+    ingress?: ServiceIngress | undefined;
 };
 /**
  * Describes the message agentmesh.v1.DirectoryProvide.
@@ -727,6 +772,12 @@ export type PeerRecord = Message<"agentmesh.v1.PeerRecord"> & {
      * @generated from field: repeated string addrs = 2;
      */
     addrs: string[];
+    /**
+     * Present on service provider records that opted into external ingress.
+     *
+     * @generated from field: agentmesh.v1.ServiceIngress ingress = 3;
+     */
+    ingress?: ServiceIngress | undefined;
 };
 /**
  * Describes the message agentmesh.v1.PeerRecord.
@@ -753,8 +804,8 @@ export type RouterInfo = Message<"agentmesh.v1.RouterInfo"> & {
      * The router's labels, the same labels as a node's: declared at
      * enrollment (agentmesh-router --label), signed by the control plane only
      * if the router's role allows them (PolicyRole.allowed_labels), and
-     * carried as label() facts in the router's credential, where a member
-     * verifies them at the handshake. A member selects routers by them
+     * carried as label() facts in the router's credential. A member selects
+     * routers by the labels listed here, before it connects
      * (--router-selector, every pair must match) or prefers routers by them
      * (--router-prefer). They place a router; they grant it nothing.
      *
@@ -775,6 +826,14 @@ export type RouterInfo = Message<"agentmesh.v1.RouterInfo"> & {
      * @generated from field: int32 connection_limit = 5;
      */
     connectionLimit: number;
+    /**
+     * Base HTTPS/HTTP URL where this router serves external ingress, without a
+     * trailing slash (e.g. "https://bananas.sam-mesh.dev/ingress"). Empty when
+     * external ingress is disabled on this router.
+     *
+     * @generated from field: string ingress_url = 6;
+     */
+    ingressUrl: string;
 };
 /**
  * Describes the message agentmesh.v1.RouterInfo.
@@ -840,6 +899,12 @@ export type RouterLeaseRequest = Message<"agentmesh.v1.RouterLeaseRequest"> & {
      * @generated from field: int32 connection_limit = 10;
      */
     connectionLimit: number;
+    /**
+     * Optional base URL where this router serves external HTTP ingress.
+     *
+     * @generated from field: string ingress_url = 11;
+     */
+    ingressUrl: string;
 };
 /**
  * Describes the message agentmesh.v1.RouterLeaseRequest.
@@ -914,12 +979,46 @@ export type PolicyRole = Message<"agentmesh.v1.PolicyRole"> & {
      * @generated from field: repeated string allowed_publish = 7;
      */
     allowedPublish: string[];
+    /**
+     * Inbound services a member with this role may expose on router HTTP
+     * ingress, together with the permitted IngressAuthModes. Empty denies all
+     * external ingress exposure for this role.
+     *
+     * @generated from field: repeated agentmesh.v1.IngressGrant allowed_ingress = 8;
+     */
+    allowedIngress: IngressGrant[];
 };
 /**
  * Describes the message agentmesh.v1.PolicyRole.
  * Use `create(PolicyRoleSchema)` to create a new message.
  */
 export declare const PolicyRoleSchema: GenMessage<PolicyRole>;
+/**
+ * IngressGrant permits a role to expose matching inbound services on router
+ * HTTP ingress under the listed authentication modes.
+ *
+ * @generated from message agentmesh.v1.IngressGrant
+ */
+export type IngressGrant = Message<"agentmesh.v1.IngressGrant"> & {
+    /**
+     * Inbound service patterns ("a2a://*", "mcp://calc", "*"). Egress
+     * destinations ("egress://...") cannot be exposed as ingress.
+     *
+     * @generated from field: repeated string services = 1;
+     */
+    services: string[];
+    /**
+     * Permitted auth modes. Empty grants ONLY INGRESS_AUTH_MODE_EDGE.
+     *
+     * @generated from field: repeated agentmesh.v1.IngressAuthMode allowed_auth_modes = 2;
+     */
+    allowedAuthModes: IngressAuthMode[];
+};
+/**
+ * Describes the message agentmesh.v1.IngressGrant.
+ * Use `create(IngressGrantSchema)` to create a new message.
+ */
+export declare const IngressGrantSchema: GenMessage<IngressGrant>;
 /**
  * HTTPGrant narrows one allowed_services entry to HTTP methods and paths.
  * The control plane compiles it into granted_method and granted_path_* facts
@@ -2037,6 +2136,10 @@ export type RouterLease = Message<"agentmesh.v1.RouterLease"> & {
      * @generated from field: int32 dht_size = 6;
      */
     dhtSize: number;
+    /**
+     * @generated from field: string ingress_url = 7;
+     */
+    ingressUrl: string;
 };
 /**
  * Describes the message agentmesh.v1.RouterLease.
@@ -2704,6 +2807,34 @@ export declare enum ServiceType {
  * Describes the enum agentmesh.v1.ServiceType.
  */
 export declare const ServiceTypeSchema: GenEnum<ServiceType>;
+/**
+ * @generated from enum agentmesh.v1.IngressAuthMode
+ */
+export declare enum IngressAuthMode {
+    /**
+     * Defaults to INGRESS_AUTH_MODE_EDGE.
+     *
+     * @generated from enum value: INGRESS_AUTH_MODE_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * Router and provider node verify a delegated Mesh Biscuit + mesh policy.
+     *
+     * @generated from enum value: INGRESS_AUTH_MODE_EDGE = 1;
+     */
+    EDGE = 1,
+    /**
+     * Backend authenticates its own requests; requires an explicit PASSTHROUGH
+     * grant on the serving node's PolicyRole.allowed_ingress.
+     *
+     * @generated from enum value: INGRESS_AUTH_MODE_PASSTHROUGH = 2;
+     */
+    PASSTHROUGH = 2
+}
+/**
+ * Describes the enum agentmesh.v1.IngressAuthMode.
+ */
+export declare const IngressAuthModeSchema: GenEnum<IngressAuthMode>;
 /**
  * @generated from enum agentmesh.v1.EgressMode
  */