agent-embassy 3.0.0 → 4.0.0

package/dist/src/gateway/endpoint-directory.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { BridgeError } from "../errors.js";
+import { Ledger, nativeKey, sameEndpoint } from "./ledger.js";
+const ALIAS = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const HOST = /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const REGISTRATION = /^reg_[A-Za-z0-9_-]{1,252}$/;
+const allowedClaude = (peer) => peer.kind === "interactive" || peer.kind === "bg";
+const reference = ({ id, host, provider }) => ({ id, host, provider });
+export class EndpointDirectory {
+    options;
+    #createRegistrationId;
+    #collidingAliases = new Set();
+    #observedClaudeAliases = new Set();
+    #completeRefreshObserved = false;
+    #proofOverflow = false;
+    constructor(options) {
+        this.options = options;
+        if (!HOST.test(options.host))
+            throw new BridgeError("INVALID_GATEWAY_CONFIGURATION", "The endpoint host is invalid.");
+        this.#createRegistrationId = options.createRegistrationId ?? (() => `reg_${randomUUID()}`);
+    }
+    async registerCodex(handle, alias, succeeds) {
+        this.#assertAlias(alias, true);
+        if (succeeds !== undefined)
+            this.#assertAlias(succeeds, true);
+        if (!UUID.test(handle)) {
+            throw new BridgeError("INVALID_GATEWAY_CONFIGURATION", "The Codex registration is invalid.");
+        }
+        return await this.options.store.transact((state, now) => {
+            const ledger = new Ledger(state, this.options.host, this.options.limits, now.getTime());
+            const normalizedHandle = handle.toLowerCase();
+            const existing = state.endpoints.find((row) => row.provider === "codex" && row.handle === normalizedHandle);
+            if (succeeds !== undefined) {
+                const predecessor = ledger.resolve(succeeds);
+                if (predecessor === undefined || predecessor.provider !== "codex") {
+                    throw new BridgeError("ROUTE_UNREGISTERED", "The predecessor route is absent.");
+                }
+                if (predecessor.handle !== normalizedHandle)
+                    ledger.retire(reference(predecessor));
+            }
+            const endpoint = {
+                id: existing?.id ?? this.#id("codex", normalizedHandle), host: this.options.host, provider: "codex",
+                alias, handle: normalizedHandle,
+            };
+            if (state.endpoints.some((row) => row.alias === alias && !sameEndpoint(row, endpoint))) {
+                throw new BridgeError("PEER_ALIAS_COLLISION", "The requested Codex alias is already in use.");
+            }
+            ledger.register(endpoint);
+            return endpoint;
+        });
+    }
+    async caller(input) {
+        if (input.kind === "codex") {
+            if (!UUID.test(input.handle))
+                throw new BridgeError("ROUTE_UNREGISTERED", "The Codex caller is invalid.");
+            const matches = (await this.options.store.snapshot()).endpoints.filter((row) => row.provider === "codex" && row.handle === input.handle.toLowerCase());
+            if (matches.length !== 1)
+                throw new BridgeError("ROUTE_UNREGISTERED", "The Codex caller is not registered.");
+            return matches[0];
+        }
+        const peer = await this.options.claude.resolveReplyAddress(input.address);
+        if (!allowedClaude(peer))
+            throw new BridgeError("CLAUDE_REPLY_ROUTE_MISMATCH", "The caller is not an interactive Claude session.");
+        return await this.#recordClaude(peer);
+    }
+    async named(selector) {
+        if (UUID.test(selector)) {
+            const peer = (await this.options.claude.discover()).peers.find((row) => row.targetId.toLowerCase() === selector.toLowerCase() && allowedClaude(row));
+            if (peer === undefined)
+                return undefined;
+            const endpoint = await this.#recordClaude(peer);
+            await this.options.claude.assertTargetWorkspaceDisjoint(peer.targetId, this.options.store.rootDir);
+            return endpoint;
+        }
+        if (!ALIAS.test(selector))
+            return undefined;
+        const at = selector.lastIndexOf("@");
+        if (selector.slice(at + 1) !== this.options.host)
+            return await this.#remoteNamed(selector);
+        const before = await this.options.store.snapshot();
+        const known = before.endpoints.filter((row) => row.alias === selector);
+        const codex = known.filter((row) => row.provider === "codex");
+        let live;
+        try {
+            live = await this.refresh();
+        }
+        catch (error) {
+            if (this.#proofOverflow || this.#collidingAliases.has(selector) || !this.#completeRefreshObserved && known.length > 1) {
+                throw new BridgeError("PEER_ALIAS_COLLISION", "The endpoint name is ambiguous.");
+            }
+            if (codex.length === 1 && (known.length === 1 ||
+                this.#completeRefreshObserved && !this.#observedClaudeAliases.has(selector)))
+                return codex[0];
+            throw error;
+        }
+        if (this.#proofOverflow || this.#collidingAliases.has(selector)) {
+            throw new BridgeError("PEER_ALIAS_COLLISION", "A complete discovery is required to clear this name's collision.");
+        }
+        const matches = live.filter((row) => row.alias === selector);
+        if (matches.length > 1)
+            throw new BridgeError("PEER_ALIAS_COLLISION", "The endpoint name is ambiguous.");
+        const endpoint = matches[0];
+        if (endpoint === undefined && before.retirements.some((row) => row.alias === selector)) {
+            throw new BridgeError("ROUTE_UNREGISTERED", "The endpoint name belongs to a retired identity.");
+        }
+        if (endpoint?.provider === "claude") {
+            await this.options.claude.assertTargetWorkspaceDisjoint(endpoint.handle, this.options.store.rootDir);
+        }
+        return endpoint;
+    }
+    async exact(identity) {
+        if (identity.host !== this.options.host) {
+            const endpoint = await this.options.remote?.exact(identity);
+            if (endpoint === undefined)
+                return undefined;
+            if (!this.#validRemote(endpoint) || !sameEndpoint(endpoint, identity)) {
+                throw new BridgeError("INVALID_PEER_CATALOG", "The remote endpoint identity is invalid.");
+            }
+            return endpoint;
+        }
+        const endpoint = (await this.options.store.snapshot()).endpoints.find((row) => sameEndpoint(row, identity));
+        if (endpoint === undefined || endpoint.provider === "codex")
+            return endpoint;
+        const peer = (await this.options.claude.discover()).peers.find((row) => row.targetId.toLowerCase() === endpoint.handle && allowedClaude(row));
+        if (peer === undefined)
+            return undefined;
+        const current = await this.#recordClaude(peer);
+        if (!sameEndpoint(current, identity))
+            return undefined;
+        await this.options.claude.assertTargetWorkspaceDisjoint(peer.targetId, this.options.store.rootDir);
+        return current;
+    }
+    async refresh() {
+        const discovery = await this.options.claude.discover();
+        const peers = discovery.peers.filter(allowedClaude);
+        const refreshed = await this.options.store.transact((state, now) => {
+            const ledger = new Ledger(state, this.options.host, this.options.limits, now.getTime());
+            const current = peers.flatMap((peer) => {
+                const endpoint = this.#upsertClaude(ledger, state, peer, true);
+                return endpoint === undefined ? [] : [endpoint];
+            });
+            if (!discovery.truncated)
+                return { listed: current, observed: current };
+            const seen = new Set(current.map((row) => row.id));
+            return { observed: current, listed: [...current,
+                    ...state.endpoints.filter((row) => row.provider === "claude" && !seen.has(row.id))] };
+        });
+        const observed = refreshed.observed.map((row) => row.alias);
+        const codex = (await this.options.store.snapshot()).endpoints.filter((row) => row.provider === "codex");
+        const collisions = new Set(observed.filter((alias, index) => observed.indexOf(alias) !== index || codex.some((row) => row.alias === alias)));
+        if (!discovery.truncated) {
+            this.#completeRefreshObserved = true;
+            this.#observedClaudeAliases.clear();
+            this.#collidingAliases.clear();
+            this.#proofOverflow = false;
+        }
+        for (const [set, aliases] of [[this.#observedClaudeAliases, observed], [this.#collidingAliases, collisions]]) {
+            for (const alias of aliases) {
+                if (set.has(alias))
+                    continue;
+                if (set.size < this.options.limits.endpoints)
+                    set.add(alias);
+                else
+                    this.#proofOverflow = true;
+            }
+        }
+        return [...codex, ...refreshed.listed];
+    }
+    #upsertClaude(ledger, state, peer, skipRetired = false) {
+        if (!UUID.test(peer.targetId) || !allowedClaude(peer)) {
+            throw new BridgeError("CLAUDE_ROUTE_MISMATCH", "The discovered Claude identity is invalid.");
+        }
+        const alias = `${peer.alias}@${this.options.host}`;
+        this.#assertAlias(alias, false);
+        const handle = peer.targetId.toLowerCase();
+        const existing = state.endpoints.find((row) => row.provider === "claude" && row.handle === handle);
+        const endpoint = { id: existing?.id ?? this.#id("claude", handle), host: this.options.host,
+            provider: "claude", alias, handle };
+        if (state.retirements.some((row) => sameEndpoint(row.endpoint, endpoint) || row.nativeKey === nativeKey(endpoint))) {
+            if (skipRetired)
+                return undefined;
+            throw new BridgeError("ROUTE_UNREGISTERED", "The Claude endpoint was retired.");
+        }
+        ledger.register(endpoint);
+        return endpoint;
+    }
+    async #recordClaude(peer) {
+        return await this.options.store.transact((state, now) => {
+            const endpoint = this.#upsertClaude(new Ledger(state, this.options.host, this.options.limits, now.getTime()), state, peer);
+            if (endpoint === undefined)
+                throw new RangeError("CLAUDE_ENDPOINT_MISSING");
+            return endpoint;
+        });
+    }
+    async #remoteNamed(alias) {
+        const matches = await this.options.remote?.named(alias) ?? [];
+        if (matches.some((row) => !this.#validRemote(row) || row.alias !== alias)) {
+            throw new BridgeError("INVALID_PEER_CATALOG", "The remote endpoint projection is invalid.");
+        }
+        if (matches.length > 1)
+            throw new BridgeError("PEER_ALIAS_COLLISION", "The endpoint name is ambiguous.");
+        return matches[0];
+    }
+    #validRemote(endpoint) {
+        return endpoint.host !== this.options.host && HOST.test(endpoint.host) && REGISTRATION.test(endpoint.id) &&
+            (endpoint.provider === "claude" || endpoint.provider === "codex") && ALIAS.test(endpoint.alias) &&
+            endpoint.alias.endsWith(`@${endpoint.host}`) && endpoint.handle.length > 0 && endpoint.handle.length <= 256 &&
+            !endpoint.handle.includes("\0");
+    }
+    #assertAlias(alias, codex) {
+        if (!ALIAS.test(alias) || !alias.endsWith(`@${this.options.host}`) || codex && !alias.startsWith("codex-")) {
+            throw new BridgeError("INVALID_GATEWAY_CONFIGURATION", "The endpoint alias is invalid.");
+        }
+    }
+    #id(provider, handle) {
+        const id = this.#createRegistrationId(provider, handle);
+        if (!REGISTRATION.test(id))
+            throw new RangeError("INVALID_REGISTRATION_ID");
+        return id;
+    }
+}
+//# sourceMappingURL=endpoint-directory.js.map

package/dist/src/gateway/endpoint-directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-directory.js","sourceRoot":"","sources":["../../../src/gateway/endpoint-directory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAwE,MAAM,aAAa,CAAC;AAGpI,MAAM,KAAK,GAAG,+DAA+D,CAAC;AAC9E,MAAM,IAAI,GAAG,yCAAyC,CAAC;AACvD,MAAM,IAAI,GAAG,4EAA4E,CAAC;AAC1F,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAgBlD,MAAM,aAAa,GAAG,CAAC,IAA0B,EAAW,EAAE,CAC5D,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;AACpD,MAAM,SAAS,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAY,EAAe,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE9F,MAAM,OAAO,iBAAiB;IAOP;IANZ,qBAAqB,CAA2D;IAChF,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,sBAAsB,GAAG,IAAI,GAAG,EAAU,CAAC;IACpD,wBAAwB,GAAG,KAAK,CAAC;IACjC,cAAc,GAAG,KAAK,CAAC;IAEvB,YAAqB,OAAiC;QAAjC,YAAO,GAAP,OAAO,CAA0B;QACpD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,+BAA+B,EAAE,+BAA+B,CAAC,CAAC;QACtH,IAAI,CAAC,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAAc,EAAE,KAAa,EAAE,QAAiB;QAClE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC/B,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CAAC,+BAA+B,EAAE,oCAAoC,CAAC,CAAC;QAC/F,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACtD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACxF,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;YAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,MAAM,KAAK,gBAAgB,CAAC,CAAC;YAC5G,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC7C,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;oBAClE,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,kCAAkC,CAAC,CAAC;gBAClF,CAAC;gBACD,IAAI,WAAW,CAAC,MAAM,KAAK,gBAAgB;oBAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;YACrF,CAAC;YACD,MAAM,QAAQ,GAAa;gBACzB,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO;gBACnG,KAAK,EAAE,MAAM,EAAE,gBAAgB;aAChC,CAAC;YACF,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC;gBACvF,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,8CAA8C,CAAC,CAAC;YAChG,CAAC;YACD,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAqB;QAChC,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,8BAA8B,CAAC,CAAC;YAC1G,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAC7E,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;YACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,qCAAqC,CAAC,CAAC;YAC7G,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;QACrB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,6BAA6B,EAAE,kDAAkD,CAAC,CAAC;QACnI,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAAgB;QAC1B,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CACrE,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;YAC/E,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnG,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,EAAE,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC;QACvE,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QAC9D,IAAI,IAAgB,CAAC;QACrB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,wBAAwB,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtH,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,iCAAiC,CAAC,CAAC;YACnF,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;gBAC3C,IAAI,CAAC,wBAAwB,IAAI,CAAC,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;YAChG,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,kEAAkE,CAAC,CAAC;QACpH,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC;QAC7D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,iCAAiC,CAAC,CAAC;QACzG,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,EAAE,CAAC;YACvF,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,kDAAkD,CAAC,CAAC;QAClG,CAAC;QACD,IAAI,QAAQ,EAAE,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvG,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAAqB;QAC/B,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC5D,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACtE,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,0CAA0C,CAAC,CAAC;YAC5F,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC5G,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,QAAQ,CAAC;QAC7E,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CACrE,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,MAAM,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QACxE,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QACvD,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,6BAA6B,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnG,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACvD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACjE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACxF,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC/D,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,SAAS,CAAC,SAAS;gBAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;YACxE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YACnD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO;oBAC7C,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;QACxG,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAC1D,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC;QAClF,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC;YACrC,IAAI,CAAC,sBAAsB,CAAC,KAAK,EAAE,CAAC;YACpC,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;YAC/B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC9B,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CAAU,EAAE,CAAC;YACtH,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC;oBAAE,SAAS;gBAC7B,IAAI,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS;oBAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;;oBACxD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAClC,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,aAAa,CAAC,MAAc,EAAE,KAAkB,EAAE,IAA0B,EAAE,WAAW,GAAG,KAAK;QAC/F,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,4CAA4C,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACnG,MAAM,QAAQ,GAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YAClG,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACnH,IAAI,WAAW;gBAAE,OAAO,SAAS,CAAC;YAClC,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,kCAAkC,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAA0B;QAC5C,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CACjC,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CACtF,CAAC;YACF,IAAI,QAAQ,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAC;YAC5E,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,KAAa;QAC9B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9D,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,4CAA4C,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,sBAAsB,EAAE,iCAAiC,CAAC,CAAC;QACzG,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,YAAY,CAAC,QAAkB;QAC7B,OAAO,QAAQ,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtG,CAAC,QAAQ,CAAC,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAC/F,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,IAAI,GAAG;YAC3G,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,YAAY,CAAC,KAAa,EAAE,KAAc;QACxC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3G,MAAM,IAAI,WAAW,CAAC,+BAA+B,EAAE,gCAAgC,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,GAAG,CAAC,QAA4B,EAAE,MAAc;QAC9C,MAAM,EAAE,GAAG,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAC;QAC5E,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

package/dist/src/gateway/federation.d.ts

@@ -0,0 +1,89 @@
+import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import type { Destination, WakeInput, WakeResult } from "./coordinator.js";
+import type { RemoteEndpointResolver } from "./endpoint-directory.js";
+import type { Endpoint, EndpointRef } from "./ledger.js";
+export declare const FEDERATION_PROTOCOL_VERSION = 3;
+export type PublicEndpoint = Readonly<{
+    id: string;
+    host: string;
+    provider: "claude" | "codex";
+    alias: string;
+}>;
+export type FederationObservation = Readonly<{
+    host: string;
+    observedAt?: string;
+    safeErrorCode?: "PEER_TUNNEL_UNAVAILABLE";
+    routes: readonly PublicEndpoint[];
+}>;
+export type FederationSnapshot = Readonly<{
+    nodes: readonly FederationObservation[];
+    truncated: boolean;
+}>;
+export type FederatedHandoff = Readonly<{
+    target: PublicEndpoint;
+    messages: readonly Readonly<{
+        id: string;
+        reply: string;
+        source: PublicEndpoint;
+        body: string;
+        deadline: number;
+        steer: boolean;
+    }>[];
+}>;
+type FederationResult = Readonly<{
+    accepted: true;
+} | {
+    accepted: false;
+    code: string;
+}>;
+type Child = Pick<ChildProcessWithoutNullStreams, "kill" | "once" | "stderr" | "stdin" | "stdout">;
+export type FederationSpawn = (command: string, args: readonly string[], options: SpawnOptionsWithoutStdio) => Child;
+export declare function isFederatedHandoff(value: unknown): value is FederatedHandoff;
+export declare class Federation implements Destination, RemoteEndpointResolver {
+    private readonly options;
+    private readonly nodes;
+    private readonly connections;
+    private readonly catalogs;
+    private readonly catalogCounts;
+    private readonly observedAt;
+    private readonly failed;
+    private readonly now;
+    private catalogTruncated;
+    private closing;
+    constructor(options: Readonly<{
+        host: string;
+        nodes: readonly string[];
+        spawn?: FederationSpawn;
+        now?: () => number;
+    }>);
+    named(name: string): Promise<readonly Endpoint[]>;
+    exact(identity: EndpointRef): Promise<Endpoint | undefined>;
+    catalog(): Promise<PublicEndpoint[]>;
+    /** Last bounded display observation only. Reading it performs no network I/O;
+     * exact and named routing continue to use the authenticated owner RPC. */
+    snapshot(): FederationSnapshot;
+    deliver(input: WakeInput): Promise<WakeResult>;
+    close(): Promise<void>;
+    private resolveAt;
+    private connection;
+    private drop;
+    private compactCatalogs;
+}
+export type FederationHandlers = Readonly<{
+    resolve: (peerHost: string, selector: string | EndpointRef) => PublicEndpoint | null | Promise<PublicEndpoint | null>;
+    catalog: (peerHost: string) => readonly PublicEndpoint[] | Promise<readonly PublicEndpoint[]>;
+    handoff: (peerHost: string, input: FederatedHandoff) => FederationResult | Promise<FederationResult>;
+}>;
+export type FederationStdioSession = Readonly<{
+    done: Promise<void>;
+    close: () => void;
+}>;
+export declare function runFederationStdio(options: Readonly<{
+    host: string;
+    nodes: readonly string[];
+    handlers: FederationHandlers;
+    input?: Readable;
+    output?: Writable;
+}>): FederationStdioSession;
+export {};