Skip to content

Agent Mesh

12.8 KB
Raw Blame
// 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.

// Mesh member driven by tests/integration/sdk_mesh_test.go: enrolls, joins
// the mesh through a real router, prints one JSON line describing the
// session, then takes JSON commands on stdin, one per line, until stdin
// closes:
//
//   {"cmd": "auth", "addr": "<multiaddr>"}  connect (through a relay when the
//                                            address says /p2p-circuit) and
//                                            run the auth handshake
//   {"cmd": "discover", "type": "mcp", "name": "calc"}
//                                            DHT lookup for a service's providers
//   {"cmd": "tools", "addr": "<multiaddr>", "service": "mcp://calc",
//    "required_labels": {"region": "eu"}}   list a provider's tools; the labels,
//                                            if given, must be on its credential
//   {"cmd": "call", "addr": "<multiaddr>", "service": "mcp://calc",
//    "tool": "add", "args": {...}, "required_labels": {...}}
//                                            call one tool
//   {"cmd": "accept", "name": "agent", "target": "<url>"}
//                                            accept A2A requests for this
//                                            member's agent; without target,
//                                            a handler in this process answers
//   {"cmd": "http", "addr": "<multiaddr>", "service": "a2a://agent",
//    "path": "/card", "method": "GET", "body": "..."}
//                                            call an HTTP service over the mesh
//   {"cmd": "peers"}                          peers that authenticated to us
//   {"cmd": "sync"}                           pull keys, bans and routers from
//                                            the control plane now
//   {"cmd": "banned"}                         peers banned by the control plane
//   {"cmd": "quit"}                           leave the mesh and exit
//
// Each command gets one JSON line back. Same environment as conformance.ts;
// the Python SDK ships the same runner (python -m agent_mesh.conformance_join).

import { createInterface } from "node:readline";
import type { ServiceType } from "./discovery.ts";
import { DEFAULT_A2A_NAME, type A2AEndpointSpec } from "./libp2p-http.ts";
import { AgentMesh } from "./mesh.ts";
import type { MeshSession } from "./session.ts";

interface Command {
  cmd?: string;
  addr?: string;
  type?: string;
  name?: string;
  service?: string;
  tool?: string;
  args?: Record<string, unknown>;
  target?: string;
  path?: string;
  method?: string;
  body?: string;
  headers?: Record<string, string>;
  required_labels?: Record<string, string>;
  timeout_ms?: string | number;
}

function requireEnv(name: string): string {
  const v = process.env[name];
  if (!v) {
    throw new Error(`${name} is required`);
  }
  return v;
}

function emit(obj: unknown): void {
  process.stdout.write(JSON.stringify(obj) + "\n");
}

/**
 * Labels from an environment variable written "k=v,k2=v2"; a pair without
 * "=" is refused (parseRequiredLabels), so a typo never switches a floor off.
 */
function labelsFromEnv(name: string): Record<string, string> {
  const out: Record<string, string> = {};
  for (const pair of (process.env[name] ?? "").split(",")) {
    if (pair.trim() === "") {
      continue;
    }
    const eq = pair.indexOf("=");
    if (eq === -1) {
      throw new Error(`${name}: invalid label ${JSON.stringify(pair.trim())}: expected key=value`);
    }
    out[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
  }
  return out;
}

function failure(cmd: string | undefined, err: unknown): unknown {
  return { cmd, ok: false, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) };
}

function requiredLabelsOf(command: Command): { requiredLabels?: Record<string, string> } {
  return command.required_labels !== undefined ? { requiredLabels: command.required_labels } : {};
}

async function handle(session: MeshSession, command: Command): Promise<unknown> {
  try {
    switch (command.cmd) {
      case "auth": {
        const timeoutMs = command.timeout_ms !== undefined ? Number(command.timeout_ms) : 15_000;
        const verified = await session.authenticate(command.addr ?? "", AbortSignal.timeout(timeoutMs));
        return {
          cmd: "auth",
          ok: true,
          peer_id: verified.peerId,
          roles: verified.roles,
          labels: verified.labels,
          expiration: Math.floor(verified.expiration.getTime() / 1000),
        };
      }
      case "discover": {
        const providers = await session.discover((command.type ?? "mcp") as ServiceType, command.name);
        return { cmd: "discover", ok: true, providers: providers.map((p) => ({ peer_id: p.peerId, addrs: p.addrs })) };
      }
      case "tools": {
        const tools = await session.listTools(command.addr ?? "", command.service ?? "", { signal: AbortSignal.timeout(15_000), ...requiredLabelsOf(command) });
        return { cmd: "tools", ok: true, tools: tools.map((t) => t.name) };
      }
      case "call": {
        const result = await session.callTool(command.addr ?? "", command.service ?? "", command.tool ?? "", command.args ?? {}, {
          signal: AbortSignal.timeout(15_000),
          ...requiredLabelsOf(command),
        });
        return { cmd: "call", ok: true, is_error: result.isError, text: result.text };
      }
      case "peers":
        return { cmd: "peers", authenticated_peers: [...session.authenticatedPeers.keys()].sort() };
      case "routers":
        return {
          cmd: "routers",
          ok: true,
          routers: session.routers.map((r) => r.peerId),
          relay_addresses: session.relayAddresses.map((ma) => ma.toString()),
          go_away_received: Object.fromEntries(session.goAwayReceived),
        };
      case "sync": {
        const result = await session.sync();
        return {
          cmd: "sync",
          ok: result.errors.length === 0,
          error: result.errors.join("; "),
          keys_changed: result.keysChanged,
          refreshed: result.refreshed,
          trusted_keys: session.mesh.credential.controlPlaneKeys.map((k) => Buffer.from(k).toString("hex")),
          biscuit: Buffer.from(session.mesh.credential.biscuit).toString("base64"),
          banned: session.banned.peers(),
          router_addresses: session.mesh.credential.routerAddresses,
        };
      }
      case "banned":
        return { cmd: "banned", ok: true, banned: session.banned.peers(), authenticated_peers: [...session.authenticatedPeers.keys()].sort() };
      case "accept": {
        const spec: A2AEndpointSpec =
          command.target !== undefined
            ? { url: command.target }
            : {
                handler: (request, caller) =>
                  new Response(JSON.stringify({ sdk: "js", peer: caller.peerId, method: request.method, path: new URL(request.url).pathname }), {
                    headers: { "content-type": "application/json" },
                  }),
              };
        spec.name = command.name ?? DEFAULT_A2A_NAME;
        const service = await session.acceptA2A(spec);
        return { cmd: "accept", ok: true, service };
      }
      case "http": {
        const res = await session.request(command.addr ?? "", command.service ?? "", command.path ?? "/", {
          method: command.method ?? "GET",
          ...(command.headers !== undefined ? { headers: command.headers } : {}),
          ...(command.body !== undefined ? { body: command.body } : {}),
          signal: AbortSignal.timeout(15_000),
        });
        return { cmd: "http", ok: true, status: res.status, headers: res.headers, body: res.text() };
      }
      default:
        return failure(command.cmd, new Error(`unknown command ${JSON.stringify(command.cmd)}`));
    }
  } catch (err) {
    return failure(command.cmd, err);
  }
}

async function main(): Promise<void> {
  const controlPlaneUrl = requireEnv("AGENTMESH_CONTROL_PLANE_URL");
  // Enrollment is with a bootstrap token or a platform JWT, as the examples
  // offer; a JWT file is read again at every refresh.
  const bootstrapTokenPath = process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH;
  const jwtPath = process.env.AGENTMESH_JWT_PATH;
  if ((bootstrapTokenPath === undefined) === (jwtPath === undefined)) {
    throw new Error("exactly one of AGENTMESH_BOOTSTRAP_TOKEN_PATH or AGENTMESH_JWT_PATH is required");
  }
  const stateDir = requireEnv("AGENTMESH_SDK_STATE_DIR");
  const allowInsecure = process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "1";
  const listenAddrs = (process.env.AGENTMESH_SDK_LISTEN_ADDRS ?? "").split(",").filter((a) => a !== "");
  // Labels this member declares at enrollment; the policy's allowed_labels
  // decide whether the control plane attests them. AGENTMESH_SDK_EGRESS_REQUIRE_LABELS
  // is the floor every provider this member calls must attest.
  const labels = labelsFromEnv("AGENTMESH_SDK_LABELS");
  const egressRequireLabels = labelsFromEnv("AGENTMESH_SDK_EGRESS_REQUIRE_LABELS");
  const routerSelector = labelsFromEnv("AGENTMESH_SDK_ROUTER_SELECTOR");
  const routerPrefer = labelsFromEnv("AGENTMESH_SDK_ROUTER_PREFER");
  const routerCount = process.env.AGENTMESH_SDK_ROUTER_COUNT;
  const redialBackoffs = (process.env.AGENTMESH_SDK_REDIAL_BACKOFF_SECONDS ?? "")
    .split(",")
    .filter((s) => s.trim() !== "")
    .map((s) => Number(s.trim()) * 1000);
  // AGENTMESH_SDK_RELAY_CHECK_SECONDS shortens how often the relay reservation is
  // checked, so a test that moves a router sees the member follow it within
  // its budget.
  const relayCheck = process.env.AGENTMESH_SDK_RELAY_CHECK_SECONDS;
  const relayOptions = relayCheck !== undefined && relayCheck !== "" ? { relayCheckIntervalMs: Number(relayCheck) * 1000 } : {};

  const mesh = await AgentMesh.enroll({
    controlPlaneUrl,
    allowInsecure,
    stateDir,
    bootstrapTokenPath,
    jwtPath,
    pollIntervalMs: 200,
    ...(Object.keys(labels).length > 0 ? { labels } : {}),
  });
  // The test drives every pull itself; only gossip events bring one forward.
  // AGENTMESH_SDK_ROUTERS, peer IDs, joins through those routers only, so the test
  // can put two members on different routers.
  const only = new Set((process.env.AGENTMESH_SDK_ROUTERS ?? "").split(",").filter((id) => id !== ""));
  const routerAddresses = only.size === 0 ? undefined : mesh.credential.routerAddresses.filter((a) => [...only].some((id) => a.endsWith(`/p2p/${id}`)));
  const session = await mesh.join({
    listenAddrs,
    ...(routerAddresses !== undefined ? { routerAddresses } : {}),
    ...(routerCount !== undefined && routerCount !== "" ? { routers: Number(routerCount) } : {}),
    ...(Object.keys(routerSelector).length > 0 ? { routerSelector } : {}),
    ...(Object.keys(routerPrefer).length > 0 ? { routerPrefer } : {}),
    ...(redialBackoffs.length > 0 ? { routerRedialBackoffsMs: redialBackoffs } : {}),
    ...(Object.keys(egressRequireLabels).length > 0 ? { egressRequireLabels } : {}),
    ...relayOptions,
    signal: AbortSignal.timeout(20_000),
    controlPlaneSyncIntervalMs: 0,
    controlPlaneSyncJitterMs: 0,
  });

  emit({
    sdk: "js",
    peer_id: session.peerId,
    routers: session.routers.map((r) => ({ peer_id: r.peerId, addr: r.addr.toString(), roles: r.credential.roles })),
    relay_addresses: session.relayAddresses.map((ma) => ma.toString()),
    direct_addresses: session.addresses.filter((ma) => !ma.toString().includes("/p2p-circuit")).map((ma) => ma.toString()),
    biscuit: Buffer.from(mesh.credential.biscuit).toString("base64"),
    trusted_keys: mesh.credential.controlPlaneKeys.map((k) => Buffer.from(k).toString("hex")),
  });

  for await (const line of createInterface({ input: process.stdin })) {
    if (line.trim() === "") {
      continue;
    }
    let command: Command;
    try {
      command = JSON.parse(line) as Command;
    } catch (err) {
      emit({ ok: false, error: `not JSON: ${err instanceof Error ? err.message : String(err)}` });
      continue;
    }
    if (command.cmd === "quit") {
      emit({ cmd: "quit", ok: true });
      break;
    }
    emit(await handle(session, command));
  }
  // Leaving must not depend on every peer closing its side promptly.
  await Promise.race([session.close(), new Promise((resolve) => setTimeout(resolve, 5_000).unref())]);
  process.exit(0);
}

main().catch((err: unknown) => {
  process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
  process.exit(1);
});