agent-embassy 1.8.2 → 1.9.2

package/dist/src/gateway/service.js

@@ -1,15 +1,19 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { BridgeError } from "../errors.js";
 import { createGatewayConversationId, startGatewayControlServer, pairParamAliases, pairParamThreadAttestation, } from "./control.js";
 import { publishGatewayDashboard } from "./dashboard.js";
+import { spawnPeerClient } from "./peer-client.js";
+import { peerEdgeRef } from "./peer-protocol.js";
 import { PROGRESS_WATCH_DEFAULT_CAPACITY, PROGRESS_WATCH_DEFAULT_IDLE_MS, PROGRESS_WATCH_HARD_CAPACITY, commitProgressWatchNudge, createProgressWatch, deferProgressWatchNudge, inspectProgressWatchDue, recordProgressWatchActivity, } from "./progress-watch-machine.js";
 import { GatewayStore } from "./store.js";
 import { CONNECTOR_OBSERVATION_STALE_AFTER_MS, GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, gatewayRegistrationIngressPrefixes, parseDirection, projectGatewayPublicSnapshot, } from "./types.js";
 const SAFE_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const PRIVATE_HANDLE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
 const PUBLIC_ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const PEER_TOKEN = /^peer_[A-Za-z0-9_-]{32}$/;
 const DISCOVERY_INTERVAL_MS = 30_000;
 const CODEX_DOCTOR_INTERVAL_MS = 30_000;
+const PEER_REFRESH_INTERVAL_MS = 30_000;
 const CLEAN_RETRY_DELAY_MS = 500;
 const MAX_CONVERSATIONS = 1_024;
 const MAX_PENDING_CLAUDE_REPLIES = MAX_CONVERSATIONS;
@@ -24,6 +28,7 @@ const CLEAN_RETRY_CODES = new Set([
     "SPAWN_TIMEOUT",
     "TRANSPORT_CONNECT_FAILED",
     "REQUEST_TIMEOUT",
+    "PEER_NOT_AWAITING",
 ]);
 function registrationId() {
     return `reg_${randomBytes(18).toString("base64url")}`;
@@ -34,7 +39,16 @@ function aliasHost(alias) {
 function safeCode(value, fallback) {
     return value !== undefined && SAFE_CODE.test(value) ? value : fallback;
 }
-function decisionFor(error) {
+class ConsentOwnerError extends BridgeError {
+    ownerHost;
+    constructor(ownerHost) {
+        super("CONSENT_OWNER_HOST_REQUIRED", `Run pair or unpair on the edge owner host ${ownerHost}.`);
+        this.ownerHost = ownerHost;
+    }
+}
+function decisionFor(error, peerPrincipal = false) {
+    if (error instanceof ConsentOwnerError)
+        return { accepted: false, code: "conflict", ownerHost: error.ownerHost };
     if (!(error instanceof BridgeError))
         return { accepted: false, code: "rejected" };
     if (error.code.includes("NOT_FOUND") || error.code.includes("NOT_AVAILABLE")) {
@@ -49,7 +63,7 @@ function decisionFor(error) {
     if (error.code.includes("UNAVAILABLE") || error.code.includes("OFFLINE") || error.code.includes("UNOBSERVED")) {
         return { accepted: false, code: "unavailable" };
     }
-    if (error.code.includes("MISMATCH") || error.code.includes("ADDRESS")) {
+    if ((peerPrincipal && error.code === "ROUTE_UNREGISTERED") || error.code.includes("MISMATCH") || error.code.includes("ADDRESS")) {
         return { accepted: false, code: "route_mismatch" };
     }
     return { accepted: false, code: "rejected" };
@@ -81,6 +95,26 @@ function conversationIdForSuffix(suffix) {
 function bodyHash(body) {
     return createHash("sha256").update(body, "utf8").digest("hex");
 }
+function peerCatalogAuthorityChanged(prior, current) {
+    const authority = (catalog) => JSON.stringify([
+        catalog.routes.map(({ state: _state, queueDepth: _depth, lastSeenAt: _seen, safeErrorCode: _code, ...route }) => route).sort((a, b) => a.ref.localeCompare(b.ref)),
+        [...catalog.consentEdges].sort((a, b) => a.ref.localeCompare(b.ref)),
+    ]);
+    return prior === undefined || authority(prior) !== authority(current);
+}
+function peerCatalogViewChanged(prior, current) {
+    const view = (catalog) => JSON.stringify([
+        catalog.health,
+        catalog.connectors.map(({ lastSeenAt: _seen, observationAgeMs: _age, ...row }) => row),
+        catalog.routes.map(({ lastSeenAt: _seen, ...row }) => row).sort((a, b) => a.ref.localeCompare(b.ref)),
+        [...catalog.consentEdges].sort((a, b) => a.ref.localeCompare(b.ref)),
+        catalog.alerts.map(({ timestamp: _timestamp, ...row }) => row),
+    ]);
+    return prior === undefined || view(prior) !== view(current);
+}
+function peerHandle(uid, alias, token) {
+    return `peer:${createHash("sha256").update(`${uid}\0${alias}\0${token}`).digest("hex")}`;
+}
 export class GatewayService {
     config;
     store;
@@ -90,6 +124,12 @@ export class GatewayService {
     timers;
     nativePeerCwd;
     codexDoctor;
+    spawnPeer;
+    peerClients = new Map();
+    peerCatalogs = new Map();
+    peerCleanupAliases = new Set();
+    /** View-only freshness; never consulted by routing or write authorization. */
+    peerRouteViews = new Map();
     connectors = new Map();
     routeObservations = new Map();
     candidates = new Map();
@@ -98,6 +138,7 @@ export class GatewayService {
     activeAttempts = new Map();
     reserveOperations = new Set();
     inboundOperations = new Set();
+    peerRefreshOperations = new Set();
     pendingClaudeReplies = new Map();
     nativeReceipts = new Map();
     progressWatches = new Map();
@@ -110,6 +151,7 @@ export class GatewayService {
     wakeTimer;
     nextDiscoveryAt = 0;
     nextDoctorAt = 0;
+    nextPeerRefreshAt = 0;
     codexDoctorResult;
     revision = 0;
     snapshotRevision = 0;
@@ -125,6 +167,7 @@ export class GatewayService {
         this.now = options.now ?? (() => new Date());
         this.nativePeerCwd = options.nativePeerCwd ?? process.cwd();
         this.codexDoctor = options.codexDoctor;
+        this.spawnPeer = options.spawnPeer ?? spawnPeerClient;
         this.timers = options.timers ?? {
             setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
             clearTimeout: (timer) => clearTimeout(timer),
@@ -188,6 +231,7 @@ export class GatewayService {
             const now = this.now().getTime();
             this.nextDiscoveryAt = now + DISCOVERY_INTERVAL_MS;
             this.nextDoctorAt = now + CODEX_DOCTOR_INTERVAL_MS;
+            this.nextPeerRefreshAt = (this.config.peerNodes?.length ?? 0) > 0 ? now : 0;
             for (const target of await this.store.inspectDispatchableTargets())
                 this.kick(target);
             await this.publish();
@@ -239,6 +283,12 @@ export class GatewayService {
         const failures = [];
         if (control !== undefined)
             await control.close().catch((error) => failures.push(error));
+        for (const peer of this.peerClients.values())
+            peer.close();
+        this.peerClients.clear();
+        await Promise.all([...this.peerRefreshOperations]).catch((error) => failures.push(error));
+        this.peerCatalogs.clear();
+        this.peerRouteViews.clear();
         // Provider close aborts exact owned operations. It must never join a turn.
         await Promise.all(this.adapters.map(async (adapter) => {
             await adapter.close().catch((error) => failures.push(error));
@@ -252,7 +302,7 @@ export class GatewayService {
         }
     }
     handlers() {
-        const decide = async (operation) => {
+        const decide = async (operation, peerPrincipal = false) => {
             try {
                 this.assertWritable();
                 await operation();
@@ -261,12 +311,27 @@ export class GatewayService {
                 return { accepted: true, code: "ok" };
             }
             catch (error) {
-                return decisionFor(error);
+                return decisionFor(error, peerPrincipal);
             }
         };
         return {
             health: () => ({ status: this.health(), revision: this.revision }),
             registerCodex: (params) => decide(async () => this.registerCodex(params)),
+            registerPeer: async (params) => {
+                try {
+                    this.assertWritable();
+                    const token = await this.registerPeer(params);
+                    this.revision += 1;
+                    await this.publish();
+                    return token === undefined ? { accepted: true, code: "ok" } : { accepted: true, code: "ok", token };
+                }
+                catch (error) {
+                    return decisionFor(error, true);
+                }
+            },
+            unregisterPeer: (params) => decide(async () => this.unregisterPeer(params), true),
+            awaitPeer: (params) => this.awaitPeer(params),
+            peerReceipt: (params) => decide(async () => this.peerReceipt(params), true),
             unregisterCodex: (params) => decide(async () => this.unregisterCodex(params)),
             removeCodexRegistration: (params) => decide(async () => this.removeCodexRegistration(params.alias)),
             selectClaude: (params) => decide(async () => this.selectClaude(params)),
@@ -289,12 +354,81 @@ export class GatewayService {
                 await this.publish();
                 return { accepted: true, code: "ok", revision: this.revision };
             },
+            peerCatalog: ({ peerHost }) => this.buildPeerCatalog(peerHost),
+            peerHandoff: ({ peerHost, handoff }) => this.receivePeerHandoff(peerHost, handoff),
         };
     }
+    async buildPeerCatalog(peerHost) {
+        const localHost = this.config.hostId ?? this.config.allowedHosts[0];
+        if (!(this.config.peerNodes ?? []).includes(peerHost))
+            throw new BridgeError("PEER_NOT_CONFIGURED", "The requested peer host is not configured.");
+        const [snapshot, privateRoutes, privateEdges] = await Promise.all([
+            this.snapshot(), this.store.inspectPrivateRoutes(), this.store.inspectPrivateConsentEdges(),
+        ]);
+        const localRoutes = privateRoutes.filter((route) => route.registrationMode !== "federated_peer" && route.binding.hostId === localHost);
+        const publicRoutes = new Map(snapshot.routes.map((route) => [route.alias, route]));
+        const routeByAlias = new Map(privateRoutes.map((route) => [route.alias, route]));
+        const routes = localRoutes.map((route) => {
+            const row = publicRoutes.get(route.alias);
+            return {
+                ref: route.binding.registrationId, alias: route.alias, provider: route.binding.provider, host: localHost,
+                enabled: route.enabled, state: row?.state ?? (route.enabled ? "stale" : "disabled"),
+                queueDepth: row?.queueDepth ?? 0, ...(row?.lastSeenAt === undefined ? {} : { lastSeenAt: row.lastSeenAt }),
+                ...(row?.safeErrorCode === undefined ? {} : { safeErrorCode: row.safeErrorCode }),
+            };
+        });
+        const consentEdges = privateEdges.flatMap((edge) => {
+            if (edge.endpoints.map((endpoint) => aliasHost(endpoint.alias)).sort()[0] !== localHost)
+                return [];
+            const rows = edge.endpoints.map((endpoint) => routeByAlias.get(endpoint.alias));
+            if (rows[0] === undefined || rows[1] === undefined ||
+                !rows.some((route) => route?.binding.hostId === peerHost) ||
+                !rows.some((route) => route?.binding.hostId === localHost))
+                return [];
+            const endpoint = (route) => ({ alias: route.alias, provider: route.binding.provider,
+                host: route.binding.hostId, routeRef: route.registrationMode === "federated_peer"
+                    ? route.binding.routeHandle : route.binding.registrationId });
+            const endpoints = [endpoint(rows[0]), endpoint(rows[1])];
+            return [{ ref: peerEdgeRef(endpoints), ownerHost: localHost, endpoints }];
+        });
+        return { revision: this.revision, complete: true, truncated: false, generatedAt: snapshot.generatedAt,
+            health: snapshot.health, connectors: snapshot.connectors.filter((row) => row.host === localHost).map((row) => ({
+                provider: row.provider, host: row.host, health: row.health, protocol: row.protocol, protocolVersion: row.protocolVersion,
+                ...(row.lastSeenAt === undefined ? {} : { lastSeenAt: row.lastSeenAt }),
+                ...(row.observationAgeMs === undefined ? {} : { observationAgeMs: row.observationAgeMs }),
+                ...(row.safeErrorCode === undefined ? {} : { safeErrorCode: row.safeErrorCode }),
+            })), routes, consentEdges, alerts: snapshot.alerts.filter((alert) => (alert.host === undefined || alert.host === localHost) && (alert.alias === undefined || aliasHost(alert.alias) === localHost)), };
+    }
+    async receivePeerHandoff(peerHost, handoff) {
+        if (!(this.config.peerNodes ?? []).includes(peerHost))
+            throw new BridgeError("PEER_NOT_CONFIGURED", "The sending peer host is not configured.");
+        const enqueued = await this.store.enqueuePeerHandoff(peerHost, handoff);
+        if (enqueued.messageId !== undefined) {
+            const source = await this.store.inspectPrivateRoute(handoff.source.alias);
+            const target = await this.store.inspectPrivateRoute(handoff.target.alias);
+            if (source === undefined || target === undefined)
+                throw new BridgeError("ROUTE_UNREGISTERED", "The committed peer handoff endpoint is no longer current.");
+            const conversationId = conversationIdForSuffix(handoff.conversationCorrelation);
+            this.rememberConversation({ id: conversationId, sourceAlias: source.alias, targetAlias: target.alias,
+                sourceBinding: source.binding, targetBinding: target.binding, expectsReply: handoff.expectsReply,
+                pair: true, nextSequence: 1 });
+            this.messageContexts.set(enqueued.messageId, { conversationId, expectsReply: handoff.expectsReply });
+            this.kick(target.alias, target.binding.registrationId);
+        }
+        this.revision += 1;
+        await this.publish();
+        return { accepted: true };
+    }
     async snapshot() {
         const base = await this.store.publicSnapshot();
         const now = this.now();
         const routes = base.routes.map((route) => {
+            const peer = this.peerRouteViews.get(route.alias);
+            if (peer !== undefined) {
+                const age = now.getTime() - Date.parse(peer.observedAt);
+                return { ...route, state: peer.state === "unobserved" || age > CONNECTOR_OBSERVATION_STALE_AFTER_MS ? "stale" : peer.state,
+                    lastSeenAt: peer.observedAt, ...(peer.safeErrorCode === undefined ? {} : { safeErrorCode: peer.safeErrorCode }) };
+            }
             const persisted = this.routeObservations.get(route.alias);
             if (persisted === undefined)
                 return route;
@@ -420,6 +554,9 @@ export class GatewayService {
     }
     async observeLoadedRoutes() {
         for (const route of await this.store.listLogicalRoutes()) {
+            if (route.registrationMode === "federated_peer")
+                this.peerRouteViews.set(route.alias, { route: route.binding,
+                    state: "unobserved", observedAt: this.now().toISOString(), safeErrorCode: "PEER_TUNNEL_UNAVAILABLE" });
             this.observeRoute(route);
             if (route.binding.provider !== "claude") {
                 this.reconcileAdvertisement(route);
@@ -456,20 +593,24 @@ export class GatewayService {
         return this.adapterFor({ provider: "claude", hostId });
     }
     async advertise(route) {
-        await this.claudeAdapter(route.binding.hostId)?.advertiseNativeSourcePeer?.({
+        const hostId = route.registrationMode === "federated_peer"
+            ? (this.config.hostId ?? this.config.allowedHosts[0]) : route.binding.hostId;
+        await this.claudeAdapter(hostId)?.advertiseNativeSourcePeer?.({
             alias: route.alias,
             sourceProvider: route.binding.provider,
             cwd: this.nativePeerCwd,
         });
     }
     async unadvertise(route) {
-        await this.claudeAdapter(route.binding.hostId)?.unadvertiseNativeSourcePeer?.(route.alias);
+        const hostId = route.registrationMode === "federated_peer"
+            ? (this.config.hostId ?? this.config.allowedHosts[0]) : route.binding.hostId;
+        await this.claudeAdapter(hostId)?.unadvertiseNativeSourcePeer?.(route.alias);
     }
     reconcileAdvertisement(route) {
         void this.advertise(route).catch((error) => this.alert("NATIVE_ADVERTISEMENT_FAILED", route, error));
     }
-    reconcileUnadvertisement(route) {
-        void this.unadvertise(route).catch((error) => this.alert("NATIVE_UNADVERTISEMENT_FAILED", route, error));
+    async reconcileUnadvertisement(route) {
+        await this.unadvertise(route).catch((error) => this.alert("NATIVE_UNADVERTISEMENT_FAILED", route, error));
     }
     async removeOwnedRoute(route, notFoundCode, releaseProviderRoute) {
         this.assertWritable();
@@ -487,7 +628,7 @@ export class GatewayService {
             await this.adapterFor(route.binding)?.releaseRoute?.(route.binding.routeHandle);
         }
         else {
-            this.reconcileUnadvertisement(route);
+            await this.reconcileUnadvertisement(route);
         }
     }
     async recordActivity(kind, action, aliases, operatorAction) {
@@ -559,6 +700,79 @@ export class GatewayService {
         this.reconcileAdvertisement(installed);
         this.kick(params.alias);
     }
+    async registerPeer(params) {
+        if (this.peerCleanupAliases.has(params.alias)) {
+            throw new BridgeError("ROUTE_BUSY", "The route is still completing cleanup.", true);
+        }
+        const existing = await this.store.inspectPrivateRoute(params.alias);
+        if (existing !== undefined) {
+            if (params.token === undefined)
+                throw new BridgeError("ROUTE_UNREGISTERED", "The route binding does not match.");
+            await this.assertPeer({ alias: params.alias, token: params.token });
+            this.observeRoute(existing);
+            this.reconcileAdvertisement(existing);
+            this.kick(existing.alias, existing.binding.registrationId);
+            return undefined;
+        }
+        if (params.token !== undefined || !params.alias.endsWith(`@${this.config.hostId ?? this.config.allowedHosts[0]}`)) {
+            throw new BridgeError("ROUTE_UNREGISTERED", "The route binding does not match.");
+        }
+        const token = `peer_${randomBytes(24).toString("base64url")}`;
+        await this.store.registerRoute({ alias: params.alias, binding: {
+                provider: "peer", hostId: this.config.hostId ?? this.config.allowedHosts[0],
+                routeHandle: peerHandle(process.getuid(), params.alias, token), registrationId: registrationId(),
+            }, registrationMode: "explicit_opt_in" });
+        const installed = (await this.store.inspectPrivateRoute(params.alias));
+        this.observeRoute(installed);
+        this.reconcileAdvertisement(installed);
+        return token;
+    }
+    async assertPeer(params) {
+        const route = await this.store.inspectPrivateRoute(params.alias);
+        const expected = Buffer.from(peerHandle(process.getuid(), params.alias, params.token));
+        const actualHandle = route?.binding.provider === "peer" && /^peer:[0-9a-f]{64}$/.test(route.binding.routeHandle)
+            ? route.binding.routeHandle : `peer:${"0".repeat(64)}`;
+        const matches = timingSafeEqual(Buffer.from(actualHandle), expected);
+        if (!PEER_TOKEN.test(params.token) || route?.binding.provider !== "peer" || !matches) {
+            throw new BridgeError("ROUTE_UNREGISTERED", "The route binding does not match.");
+        }
+        return route;
+    }
+    async unregisterPeer(params) {
+        const route = await this.assertPeer(params);
+        if (this.peerCleanupAliases.has(route.alias))
+            throw new BridgeError("ROUTE_BUSY", "The route is still completing cleanup.", true);
+        this.peerCleanupAliases.add(route.alias);
+        try {
+            const result = await this.store.removeOwnedRouteAtomic({ alias: route.alias, binding: route.binding });
+            if (!result.removed)
+                throw new BridgeError("ROUTE_UNREGISTERED", "The route binding does not match.");
+            await this.finishSettlements(result.settlements);
+            this.settleWatchesForAlias(route.alias, "endpoint_retired", "operator");
+            this.forgetRoute(route);
+            await this.reconcileUnadvertisement(route);
+        }
+        finally {
+            this.peerCleanupAliases.delete(route.alias);
+        }
+    }
+    async awaitPeer(params) {
+        this.assertWritable();
+        const route = await this.assertPeer(params);
+        const adapter = this.adapterFor(route.binding);
+        if (adapter?.awaitMessage === undefined)
+            throw new BridgeError("PROVIDER_UNAVAILABLE", "The provider is unavailable.", true);
+        const pending = adapter.awaitMessage({ alias: route.alias, ...route.binding });
+        this.kick(route.alias, route.binding.registrationId);
+        return await pending;
+    }
+    async peerReceipt(params) {
+        const route = await this.assertPeer(params);
+        const adapter = this.adapterFor(route.binding);
+        if (adapter?.acknowledgeReceipt({ alias: route.alias, ...route.binding, receipt: params.receipt }) === "rejected") {
+            throw new BridgeError("ROUTE_UNREGISTERED", "The route binding does not match.");
+        }
+    }
     async unregisterCodex(params) {
         const route = await this.store.inspectPrivateRoute(params.alias);
         if (route === undefined ||
@@ -570,7 +784,7 @@ export class GatewayService {
     }
     async removeCodexRegistration(alias) {
         const route = await this.store.inspectPrivateRoute(alias);
-        if (route === undefined || route.binding.provider !== "codex") {
+        if (route === undefined || route.binding.provider !== "codex" || route.registrationMode === "federated_peer") {
             throw new BridgeError("CODEX_REGISTRATION_NOT_FOUND", "The Codex registration is absent.");
         }
         await this.removeOwnedRoute(route, "CODEX_REGISTRATION_NOT_FOUND", false);
@@ -624,13 +838,16 @@ export class GatewayService {
     }
     async unselectClaude(params) {
         const route = await this.resolveSelectedClaudeRoute(params.alias);
-        if (route === undefined)
+        if (route === undefined || route.registrationMode === "federated_peer")
             throw new BridgeError("CLAUDE_ROUTE_NOT_FOUND", "The selected Claude route is absent.");
         await this.removeOwnedRoute(route, "CLAUDE_ROUTE_NOT_FOUND", true);
     }
     async pair(params) {
         const endpoints = await this.resolvePairEndpoints(params, true);
         const aliases = endpoints.aliases;
+        const ownerHost = aliases.map(aliasHost).sort()[0];
+        if ((this.config.hostId ?? this.config.allowedHosts[0]) !== ownerHost)
+            throw new ConsentOwnerError(ownerHost);
         const attestation = pairParamThreadAttestation(params);
         if (attestation !== undefined)
             await this.assertThread(attestation.alias, attestation.threadId);
@@ -643,6 +860,9 @@ export class GatewayService {
     async unpair(params) {
         const endpoints = await this.resolvePairEndpoints(params, false);
         const aliases = endpoints.aliases;
+        const ownerHost = aliases.map(aliasHost).sort()[0];
+        if ((this.config.hostId ?? this.config.allowedHosts[0]) !== ownerHost)
+            throw new ConsentOwnerError(ownerHost);
         const attestation = pairParamThreadAttestation(params);
         if (attestation !== undefined)
             await this.assertThread(attestation.alias, attestation.threadId);
@@ -693,8 +913,11 @@ export class GatewayService {
     async sendToClaude(params) {
         try {
             this.assertWritable();
-            const source = await this.assertThread(params.fromAlias, params.threadId);
-            const target = await this.resolveSelectedClaudeRoute(params.toAlias);
+            const source = "peerToken" in params && params.peerToken !== undefined
+                ? await this.assertPeer({ alias: params.fromAlias, token: params.peerToken })
+                : await this.assertThread(params.fromAlias, params.threadId);
+            const direct = await this.store.inspectPrivateRoute(params.toAlias);
+            const target = direct?.binding.provider === "peer" ? direct : await this.resolveSelectedClaudeRoute(params.toAlias);
             if (target === undefined)
                 throw new BridgeError("CLAUDE_ROUTE_NOT_FOUND", "The selected Claude route is absent.");
             return await this.enqueueConversation({
@@ -710,29 +933,35 @@ export class GatewayService {
             });
         }
         catch (error) {
-            return decisionFor(error);
+            return decisionFor(error, "peerToken" in params);
         }
     }
     async sendToCodex(params) {
         try {
             this.assertWritable();
             let source;
-            if (params.replyAddress === undefined) {
+            if ("peerToken" in params && params.peerToken !== undefined) {
+                source = await this.assertPeer({ alias: params.fromAlias, token: params.peerToken });
+            }
+            else if (params.replyAddress === undefined) {
                 throw new BridgeError("CLAUDE_REPLY_ADDRESS_INVALID", "The inherited reply capability is required.");
             }
-            const adapter = this.claudeAdapter(aliasHost(params.toAlias));
-            const resolved = await adapter?.resolveReplyAddress?.(params.replyAddress);
-            if (resolved === undefined)
-                throw new BridgeError("CLAUDE_REPLY_ADDRESS_INVALID", "The reply capability is stale.");
-            source = (await this.store.listLogicalRoutes()).find((route) => route.binding.provider === "claude" &&
-                route.alias === params.fromAlias &&
-                route.binding.routeHandle === resolved.routeHandle);
-            if (source === undefined)
-                throw new BridgeError("CLAUDE_ROUTE_NOT_FOUND", "The reply route is not selected.");
+            else {
+                const resolved = await this.claudeAdapter(aliasHost(params.fromAlias))?.resolveReplyAddress?.(params.replyAddress);
+                if (resolved === undefined)
+                    throw new BridgeError("CLAUDE_REPLY_ADDRESS_INVALID", "The reply capability is stale.");
+                source = (await this.store.listLogicalRoutes()).find((route) => route.binding.provider === "claude" &&
+                    route.alias === params.fromAlias && route.binding.routeHandle === resolved.routeHandle);
+                if (source === undefined)
+                    throw new BridgeError("CLAUDE_ROUTE_NOT_FOUND", "The reply route is not selected.");
+            }
             const target = await this.store.inspectPrivateRoute(params.toAlias);
             if (source === undefined || target === undefined) {
                 throw new BridgeError("ROUTE_NOT_AVAILABLE", "The selected route is absent.");
             }
+            if (target.binding.provider !== "codex" && target.binding.provider !== "peer") {
+                throw new BridgeError("ROUTE_NOT_AVAILABLE", "The selected route is absent.");
+            }
             return await this.enqueueConversation({
                 sourceAlias: params.fromAlias,
                 targetAlias: params.toAlias,
@@ -746,7 +975,7 @@ export class GatewayService {
             });
         }
         catch (error) {
-            return decisionFor(error);
+            return decisionFor(error, "peerToken" in params);
         }
     }
     async reply(params) {
@@ -801,7 +1030,7 @@ export class GatewayService {
             });
         }
         catch (error) {
-            return decisionFor(error);
+            return decisionFor(error, params.caller.kind === "peer");
         }
     }
     async assertReplyCaller(conversation, caller) {
@@ -829,6 +1058,8 @@ export class GatewayService {
                 throw new BridgeError("CLAUDE_REPLY_ADDRESS_INVALID", "The reply capability is stale.");
             }
         }
+        if (caller.kind === "peer")
+            await this.assertPeer({ alias: caller.alias, token: caller.token });
         return route.binding;
     }
     async enqueueConversation(input) {
@@ -850,6 +1081,8 @@ export class GatewayService {
                     : undefined;
         const sourceBinding = input.expectedSourceBinding ?? conversationSourceBinding ?? source?.binding;
         const targetBinding = input.expectedTargetBinding ?? conversationTargetBinding ?? target?.binding;
+        const steer = input.text.startsWith("STEER:") && this.config.steeringEnabled &&
+            sourceBinding?.provider === "claude" && targetBinding?.provider === "codex";
         if (input.existingConversation === undefined &&
             this.conversations.size >= MAX_CONVERSATIONS &&
             [...this.conversations.keys()].every((id) => this.conversationIsActive(id))) {
@@ -886,9 +1119,7 @@ export class GatewayService {
                         expectedSourceRegistrationId: sourceBinding.registrationId,
                         expectedTargetRegistrationId: targetBinding.registrationId,
                     }),
-                ...(input.text.startsWith("STEER:") && this.config.steeringEnabled
-                    ? { steer: true }
-                    : {}),
+                ...(steer ? { steer: true } : {}),
             });
         }
         catch (error) {
@@ -909,9 +1140,8 @@ export class GatewayService {
         if (enqueued.supersededSettlement !== undefined) {
             await this.finishSettlement(enqueued.supersededSettlement);
         }
-        if (input.text.startsWith("STEER:") && this.config.steeringEnabled) {
+        if (steer)
             this.kickSteer(input.targetAlias);
-        }
         this.kick(input.targetAlias);
         this.scheduleWake();
         return {
@@ -1020,8 +1250,9 @@ export class GatewayService {
             else if (steer && this.running && !this.closing)
                 this.kickSteer(targetAlias);
             else if (this.running)
-                void this.store.inspectDispatchableTargets().then((targets) => {
-                    if (targets.includes(targetAlias))
+                void Promise.all([this.store.inspectDispatchableTargets(), this.store.inspectPrivateRoute(targetAlias)]).then(([targets, route]) => {
+                    if (targets.includes(targetAlias) &&
+                        (route?.registrationMode !== "federated_peer" || this.peerClients.has(route.binding.hostId)))
                         this.kick(targetAlias);
                 }).catch(() => undefined);
         });
@@ -1093,6 +1324,72 @@ export class GatewayService {
                 await this.resolvePrewrite(attempt.messageId, attempt.attemptId, "failed", "ROUTE_UNREGISTERED");
                 return false;
             }
+            if (target.registrationMode === "federated_peer") {
+                const peer = this.peerClients.get(target.binding.hostId);
+                if (peer === undefined || source === undefined || source.registrationMode === "federated_peer") {
+                    await this.resolvePrewrite(attempt.messageId, attempt.attemptId, "requeue", "PEER_TUNNEL_UNAVAILABLE");
+                    return false;
+                }
+                const sourceEndpoint = { alias: source.alias, provider: source.binding.provider,
+                    host: source.binding.hostId, routeRef: source.binding.registrationId };
+                const targetEndpoint = { alias: target.alias, provider: target.binding.provider,
+                    host: target.binding.hostId, routeRef: target.binding.routeHandle };
+                const params = {
+                    originAttemptId: attempt.attemptId, originMessageId: attempt.messageId,
+                    source: sourceEndpoint, target: targetEndpoint,
+                    edgeRef: peerEdgeRef([sourceEndpoint, targetEndpoint]),
+                    edgeOwnerHost: [sourceEndpoint.host, targetEndpoint.host].sort()[0],
+                    deadlineAt: attempt.deadlineAt, expectsReply: conversation?.expectsReply ?? true,
+                    body: attempt.body,
+                    ...(attempt.steer === true ? { steer: true } : {}),
+                    ...(attempt.conversationIdSuffix === undefined ? {} : { conversationCorrelation: attempt.conversationIdSuffix }),
+                };
+                let armed = false, authorizationUncertain = false, acceptanceObserved = false, result;
+                try {
+                    const prepared = peer.prepareHandoff(params);
+                    let authorized;
+                    try {
+                        authorized = await this.store.authorizeMessage({ messageId: attempt.messageId,
+                            attemptId: attempt.attemptId, sourceRegistrationId: attempt.sourceRegistrationId,
+                            targetRegistrationId: attempt.targetRegistrationId,
+                            prepared: { kind: "peer_handoff", bodyBytes: prepared.bodyBytes,
+                                bodySha256: prepared.bodySha256, frameBytes: prepared.frameBytes, sha256: prepared.sha256 } });
+                    }
+                    catch (error) {
+                        authorizationUncertain = true;
+                        throw error;
+                    }
+                    if (authorized.status !== "authorized") {
+                        prepared.cancel();
+                        if (authorized.status === "terminal")
+                            await this.finishSettlement(authorized.settlement);
+                        this.activeAttempts.delete(attempt.messageId);
+                        return false;
+                    }
+                    armed = true;
+                    await prepared.perform();
+                    acceptanceObserved = true;
+                    const accepted = await this.store.acceptMessage({ messageId: attempt.messageId,
+                        attemptId: attempt.attemptId, lossOutcome: "unconfirmed" });
+                    if (accepted.status !== "accepted")
+                        throw new BridgeError("ACCEPTANCE_UNCONFIRMED", "The peer acceptance fence is stale.");
+                    result = { state: "delivered", safeErrorCode: "PEER_HANDOFF_CONFIRMED" };
+                }
+                catch {
+                    if (!armed && !authorizationUncertain) {
+                        peer.close();
+                        this.peerClients.delete(target.binding.hostId);
+                        await this.resolvePrewrite(attempt.messageId, attempt.attemptId, "requeue", "PEER_TUNNEL_UNAVAILABLE");
+                        return false;
+                    }
+                    result = acceptanceObserved
+                        ? { state: "unconfirmed", safeErrorCode: "PEER_HANDOFF_ACCEPTANCE_UNCONFIRMED" }
+                        : { state: "ambiguous", safeErrorCode: authorizationUncertain ? "WRITE_AUTHORIZATION_UNCERTAIN" : "PEER_HANDOFF_OUTCOME_UNKNOWN" };
+                }
+                const requeued = await this.applyDispatchResult(attempt.messageId, attempt.attemptId, result, armed, conversation, attempt.sourceAlias, attempt.targetAlias);
+                this.activeAttempts.delete(attempt.messageId);
+                return requeued;
+            }
             const adapter = this.adapterFor(target.binding);
             if (adapter === undefined) {
                 await this.resolvePrewrite(attempt.messageId, attempt.attemptId, "failed", "PROVIDER_UNAVAILABLE");
@@ -1177,7 +1474,7 @@ export class GatewayService {
                         }
                     },
                     onAccepted: async (evidence) => {
-                        if (target.binding.provider !== "codex" ||
+                        if ((target.binding.provider !== "codex" && target.binding.provider !== "peer") ||
                             evidence.attemptId !== attempt.attemptId) {
                             throw new BridgeError("ACCEPTANCE_UNCONFIRMED", "The provider accepted another attempt.");
                         }
@@ -1344,7 +1641,9 @@ export class GatewayService {
     }
     async onClaudeMessage(event) {
         const target = await this.store.inspectPrivateRoute(event.targetAlias);
-        if (target === undefined || target.binding.hostId !== event.endpoint.hostId) {
+        const localHost = this.config.hostId ?? this.config.allowedHosts[0];
+        if (target === undefined || (target.binding.hostId !== event.endpoint.hostId &&
+            !(target.registrationMode === "federated_peer" && event.endpoint.hostId === localHost))) {
             throw new BridgeError("ROUTE_NOT_AVAILABLE", "The native target is absent.");
         }
         const selected = (await this.store.listLogicalRoutes()).find((route) => route.binding.provider === "claude" &&
@@ -1358,7 +1657,7 @@ export class GatewayService {
             registrationId: `native_${bodyHash(`${event.endpoint.routeHandle}\0${event.sourceAlias}`).slice(0, 32)}`,
         };
         const conversationId = createGatewayConversationId();
-        const steer = event.text.startsWith("STEER:") && this.config.steeringEnabled;
+        const steer = target.binding.provider === "codex" && event.text.startsWith("STEER:") && this.config.steeringEnabled;
         this.assertWritable();
         const enqueued = await this.store.enqueueNativeIngress({
             source: { alias: event.sourceAlias, binding: sourceBinding },
@@ -1820,6 +2119,9 @@ export class GatewayService {
             const due = [
                 this.nextDiscoveryAt || now + DISCOVERY_INTERVAL_MS,
                 this.nextDoctorAt || now + CODEX_DOCTOR_INTERVAL_MS,
+                ...((this.config.peerNodes?.length ?? 0) > 0
+                    ? [this.nextPeerRefreshAt || now + PEER_REFRESH_INTERVAL_MS]
+                    : []),
                 ...(deadlineAt === undefined ? [] : [Date.parse(deadlineAt)]),
                 ...[...this.pendingClaudeReplies.values()].flatMap((rows) => rows.map((row) => Date.parse(row.deadlineAt))),
                 ...[...this.progressWatches.values()].map((watch) => Date.parse(watch.nextActionAt)),
@@ -1846,11 +2148,100 @@ export class GatewayService {
             await this.refreshCodexDoctor().catch(() => undefined);
             this.nextDoctorAt = now.getTime() + CODEX_DOCTOR_INTERVAL_MS;
         }
+        if (this.nextPeerRefreshAt > 0 && now.getTime() >= this.nextPeerRefreshAt) {
+            const operation = this.refreshPeers();
+            this.peerRefreshOperations.add(operation);
+            try {
+                await operation;
+            }
+            finally {
+                this.peerRefreshOperations.delete(operation);
+            }
+            this.nextPeerRefreshAt = now.getTime() + PEER_REFRESH_INTERVAL_MS;
+        }
+        if (!this.running || this.closing)
+            return;
         for (const target of await this.store.inspectDispatchableTargets())
             this.kick(target);
         await this.publish();
         this.scheduleWake();
     }
+    async refreshPeers() {
+        const localHost = this.config.hostId ?? this.config.allowedHosts[0];
+        await Promise.all((this.config.peerNodes ?? []).map(async (peerHost) => {
+            let failureCode = "PEER_TUNNEL_UNAVAILABLE";
+            try {
+                let client = this.peerClients.get(peerHost);
+                if (client === undefined) {
+                    failureCode = "PEER_DIAL_FAILED";
+                    client = await this.spawnPeer({ node: peerHost, localHost });
+                    if (!this.running || this.closing) {
+                        client.close();
+                        return;
+                    }
+                    this.peerClients.set(peerHost, client);
+                }
+                failureCode = "PEER_TUNNEL_UNAVAILABLE";
+                const catalog = await client.catalog();
+                if (!this.running || this.closing)
+                    return;
+                this.recordPeerFailure(peerHost);
+                const prior = this.peerCatalogs.get(peerHost);
+                let routes = await this.store.inspectPrivateRoutes().then((rows) => rows.filter((route) => route.registrationMode === "federated_peer" && route.binding.hostId === peerHost));
+                if (!catalog.complete || catalog.truncated) {
+                    const observedAt = this.now().toISOString();
+                    for (const route of routes)
+                        this.peerRouteViews.set(route.alias, { route: route.binding,
+                            state: "unobserved", observedAt, safeErrorCode: "PEER_CATALOG_INCOMPLETE" });
+                    return;
+                }
+                const authorityChanged = peerCatalogAuthorityChanged(prior, catalog);
+                const viewChanged = peerCatalogViewChanged(prior, catalog);
+                if (authorityChanged) {
+                    const before = routes;
+                    const reconciled = await this.store.reconcilePeerCatalog(peerHost, catalog);
+                    routes = [...reconciled.routes];
+                    await this.finishSettlements(reconciled.settlements);
+                    for (const old of before)
+                        if (!routes.some((route) => route.alias === old.alias &&
+                            route.binding.registrationId === old.binding.registrationId)) {
+                            this.peerRouteViews.delete(old.alias);
+                            await this.reconcileUnadvertisement(old);
+                        }
+                    for (const route of routes)
+                        if (!before.some((old) => old.alias === route.alias &&
+                            old.binding.registrationId === route.binding.registrationId))
+                            this.reconcileAdvertisement(route);
+                }
+                this.peerCatalogs.set(peerHost, catalog);
+                const observedAt = this.now().toISOString();
+                for (const route of routes) {
+                    const row = catalog.routes.find((candidate) => candidate.ref === route.binding.routeHandle);
+                    const state = row?.state === "idle" || row?.state === "busy" || row?.state === "awaiting_approval"
+                        ? row.state : "unobserved";
+                    this.peerRouteViews.set(route.alias, { route: route.binding, state, observedAt,
+                        ...(state === "unobserved" ? { safeErrorCode: row?.safeErrorCode ?? "PEER_ROUTE_STALE" } : {}) });
+                    if (row?.enabled === true)
+                        this.kick(route.alias, route.binding.registrationId);
+                }
+                if (viewChanged)
+                    this.revision += 1;
+            }
+            catch {
+                this.peerClients.get(peerHost)?.close();
+                this.peerClients.delete(peerHost);
+                if (!this.running || this.closing)
+                    return;
+                this.recordPeerFailure(peerHost, failureCode);
+                const observedAt = this.now().toISOString();
+                for (const route of await this.store.inspectPrivateRoutes())
+                    if (route.registrationMode === "federated_peer" &&
+                        route.binding.hostId === peerHost)
+                        this.peerRouteViews.set(route.alias, { route: route.binding,
+                            state: "unobserved", observedAt, safeErrorCode: "PEER_TUNNEL_UNAVAILABLE" });
+            }
+        }));
+    }
     async refreshClaudeDiscovery() {
         const seen = new Set();
         for (const adapter of this.adapters) {
@@ -1921,5 +2312,14 @@ export class GatewayService {
         while (this.runtimeAlerts.length > gatewayPublicSnapshotLimits.alerts)
             this.runtimeAlerts.shift();
     }
+    recordPeerFailure(host, code) {
+        for (let index = this.runtimeAlerts.length - 1; index >= 0; index -= 1) {
+            const alert = this.runtimeAlerts[index];
+            if (alert?.host === host && (alert.code === "PEER_DIAL_FAILED" || alert.code === "PEER_TUNNEL_UNAVAILABLE"))
+                this.runtimeAlerts.splice(index, 1);
+        }
+        if (code !== undefined)
+            this.runtimeAlerts.push({ code, severity: "warning", timestamp: this.now().toISOString(), host });
+    }
 }
 //# sourceMappingURL=service.js.map