agent-embassy 3.1.0 → 4.0.0

package/dist/src/gateway/broker-check.d.ts

@@ -0,0 +1,26 @@
+import { type Coordinator, type Destination, type WakeInput, type WakeResult } from "./coordinator.js";
+import { type LedgerLimits, type LedgerState } from "./ledger.js";
+import type { OwnedStateFile } from "./owned-state.js";
+export type BrokerCheckOptions = Readonly<{
+    host: string;
+    limits: LedgerLimits;
+    store: OwnedStateFile<LedgerState>;
+    coordinator: Coordinator;
+}>;
+export type BrokerCheckResult = Readonly<{
+    status: "ok";
+    scope: "broker-loopback";
+}>;
+/** Adds a broker-only destination around the real Codex adapter. It intercepts only
+ * identities minted for the duration of check(); every production write delegates. */
+export declare class LoopbackDestination implements Destination {
+    private readonly innerCodex;
+    private readonly expected;
+    private checking;
+    constructor(innerCodex: Destination);
+    deliver(input: WakeInput): Promise<WakeResult>;
+    cleanup({ host, limits, store }: Omit<BrokerCheckOptions, "coordinator">): Promise<void>;
+    check(options: BrokerCheckOptions): Promise<BrokerCheckResult>;
+    private runCheck;
+    close(): Promise<void>;
+}

package/dist/src/gateway/broker-check.js

@@ -0,0 +1,89 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { Ledger, bodyHash, sameEndpoint } from "./ledger.js";
+const LOOPBACK = /^loopback:([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i;
+const ref = ({ id, host, provider }) => ({ id, host, provider });
+const ids = () => ({ id: `msg_${randomUUID()}`, token: `dlv_${randomBytes(18).toString("base64url")}`,
+    reply: `conv_${randomBytes(24).toString("base64url")}` });
+function isLoopback(endpoint, host) {
+    const match = endpoint.host === host && endpoint.provider === "codex" ? LOOPBACK.exec(endpoint.handle) : null;
+    return match !== null && endpoint.id === `reg_loopback_${match[1]}`;
+}
+/** Adds a broker-only destination around the real Codex adapter. It intercepts only
+ * identities minted for the duration of check(); every production write delegates. */
+export class LoopbackDestination {
+    innerCodex;
+    expected = new Map();
+    checking;
+    constructor(innerCodex) {
+        this.innerCodex = innerCodex;
+    }
+    async deliver(input) {
+        const expected = this.expected.get(input.target.id);
+        if (!expected)
+            return this.innerCodex.deliver(input);
+        if (!sameEndpoint(input.target, expected.target) || input.messages.length !== 1 ||
+            !sameEndpoint(input.messages[0].source, expected.source))
+            throw new Error("INVALID_LOOPBACK_WAKE");
+        if (!await input.authorize({ bytes: Buffer.byteLength(input.text), sha256: bodyHash(input.text) })) {
+            return { outcome: "deferred", code: "WRITE_AUTHORIZATION_DENIED" };
+        }
+        await input.accepted("unconfirmed");
+        return { outcome: "delivered", code: "TRANSPORT_WRITTEN" };
+    }
+    async cleanup({ host, limits, store }) {
+        await store.transact((state, now) => {
+            const ledger = new Ledger(state, host, limits, now.getTime());
+            for (const endpoint of [...state.endpoints])
+                if (isLoopback(endpoint, host))
+                    ledger.retire(endpoint);
+        });
+    }
+    check(options) {
+        return this.checking ??= this.runCheck(options).finally(() => { this.checking = undefined; });
+    }
+    async runCheck({ host, limits, store, coordinator }) {
+        await this.cleanup({ host, limits, store });
+        const nonceA = randomUUID(), nonceB = randomUUID();
+        const source = { id: `reg_loopback_${nonceA}`, handle: `loopback:${nonceA}`,
+            host, provider: "codex", alias: `loopback-a-${nonceA.slice(0, 8)}@${host}` };
+        const target = { id: `reg_loopback_${nonceB}`, handle: `loopback:${nonceB}`,
+            host, provider: "codex", alias: `loopback-b-${nonceB.slice(0, 8)}@${host}` };
+        const change = (operation) => store.transact((state, now) => operation(new Ledger(state, host, limits, now.getTime())));
+        try {
+            await change((ledger) => { ledger.register(source); ledger.register(target); });
+            this.expected.set(target.id, { source: ref(source), target: ref(target) });
+            const challenge = await change((ledger) => ledger.admit({ ...ids(), source: ref(source), target: ref(target),
+                body: "Embassy broker loopback challenge.", deadline: ledger.now + limits.deadlineMs, steer: false }).delivery);
+            await coordinator.wake(target);
+            const delivered = (await store.snapshot()).deliveries.find((row) => row.id === challenge.id);
+            if (delivered?.state.phase !== "terminal" || delivered.state.outcome !== "delivered")
+                throw new Error("LOOPBACK_NOT_DELIVERED");
+            this.expected.delete(target.id);
+            this.expected.set(source.id, { source: ref(target), target: ref(source) });
+            const response = await change((ledger) => {
+                const replyTarget = ledger.replyTarget(challenge.reply, target);
+                if (!sameEndpoint(replyTarget, source))
+                    throw new Error("INVALID_LOOPBACK_REPLY_TARGET");
+                return ledger.admit({ ...ids(), source: ref(target), target: replyTarget,
+                    body: "Embassy broker loopback reply.", deadline: ledger.now + limits.deadlineMs, steer: false }).delivery;
+            });
+            await coordinator.wake(source);
+            const replied = (await store.snapshot()).deliveries.find((row) => row.id === response.id);
+            if (replied?.state.phase !== "terminal" || replied.state.outcome !== "delivered")
+                throw new Error("LOOPBACK_REPLY_NOT_DELIVERED");
+            return { status: "ok", scope: "broker-loopback" };
+        }
+        finally {
+            this.expected.delete(source.id);
+            this.expected.delete(target.id);
+            await change((ledger) => {
+                if (ledger.endpoint(source))
+                    ledger.retire(source);
+                if (ledger.endpoint(target))
+                    ledger.retire(target);
+            });
+        }
+    }
+    close() { return this.innerCodex.close(); }
+}
+//# sourceMappingURL=broker-check.js.map

package/dist/src/gateway/broker-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-check.js","sourceRoot":"","sources":["../../../src/gateway/broker-check.ts"],"names":[],"mappings":"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"}

package/dist/src/gateway/broker-control.d.ts

@@ -0,0 +1,72 @@
+import type { MessagingBroker } from "./broker.js";
+import type { EndpointCaller } from "./endpoint-directory.js";
+import type { EndpointRef } from "./ledger.js";
+import type { FederatedHandoff } from "./federation.js";
+export type BrokerCommand = {
+    method: "health" | "list_snapshot" | "refresh_discovery" | "check";
+    params: Record<string, never>;
+} | {
+    method: "register_codex";
+    params: {
+        caller: EndpointCaller;
+        alias: string;
+        succeeds?: string;
+    };
+} | {
+    method: "send";
+    params: {
+        caller: EndpointCaller;
+        body: string;
+        to?: string;
+        conversation?: string;
+    };
+} | {
+    method: "retire_route";
+    params: {
+        alias: string;
+    } | {
+        endpoint: string;
+    };
+} | {
+    method: "delivery_status";
+    params: {
+        token: string;
+    };
+} | {
+    method: "peer_catalog";
+    params: {
+        node: string;
+    };
+} | {
+    method: "peer_resolve";
+    params: {
+        node: string;
+        selector: string | EndpointRef;
+    };
+} | {
+    method: "peer_handoff";
+    params: {
+        node: string;
+        handoff: FederatedHandoff;
+    };
+};
+/** One public projection contract, used before emission and after transport. Native
+ * handles and arbitrary adapter fields can never hitchhike in a valid result. */
+export declare function isBrokerResult(method: BrokerCommand["method"], value: unknown): boolean;
+/** Closed application vocabulary; the Unix envelope/version belongs to local-control. */
+export declare function parseBrokerCommand(input: unknown, validateHandoff: (x: unknown) => boolean): BrokerCommand;
+export type BrokerControlOptions = Readonly<{
+    broker: MessagingBroker;
+    validateHandoff: (x: unknown) => boolean;
+    check: () => Promise<unknown>;
+}>;
+export declare function handleBrokerCommand(input: unknown, options: BrokerControlOptions): Promise<{
+    ok: true;
+    result: unknown;
+    code?: never;
+} | {
+    ok: false;
+    code: string;
+    result?: never;
+}>;
+export declare const commandMutates: (method: BrokerCommand["method"]) => boolean;

package/dist/src/gateway/broker-control.js

@@ -0,0 +1,164 @@
+import { BridgeError } from "../errors.js";
+const object = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+const exact = (x, keys, optional = []) => object(x) &&
+    keys.every((key) => Object.hasOwn(x, key)) && Object.keys(x).every((key) => keys.includes(key) || optional.includes(key));
+const alias = (x) => typeof x === "string" && /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/.test(x);
+const host = (x) => typeof x === "string" && /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/.test(x);
+const uuid = (x) => typeof x === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x);
+const token = (x, prefix, length) => typeof x === "string" && new RegExp(`^${prefix}[A-Za-z0-9_-]{${length}}$`).test(x);
+const ref = (x) => exact(x, ["id", "host", "provider"]) && token(x.id, "reg_", "1,252") && host(x.host) && (x.provider === "claude" || x.provider === "codex");
+const caller = (x) => exact(x, ["kind", "handle"]) && x.kind === "codex" && uuid(x.handle) ||
+    exact(x, ["kind", "address"]) && x.kind === "claude" && typeof x.address === "string" &&
+        x.address.startsWith("uds:/") && x.address.length <= 256 && !x.address.includes("\0");
+const invalid = () => { throw new BridgeError("INVALID_REQUEST", "The control request is invalid."); };
+const count = (x) => Number.isSafeInteger(x) && x >= 0;
+const code = (x) => typeof x === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(x);
+const date = (x) => typeof x === "string" && Number.isFinite(Date.parse(x)) && new Date(x).toISOString() === x;
+const outcomes = ["delivered", "failed", "cancelled", "expired", "ambiguous", "unconfirmed"];
+const endpoint = (x) => exact(x, ["id", "host", "provider", "alias"]) &&
+    ref({ id: x.id, host: x.host, provider: x.provider }) && alias(x.alias) && x.alias.endsWith(`@${x.host}`);
+const rows = (x, maximum, accepts) => Array.isArray(x) && x.length <= maximum && x.every(accepts);
+const endpoints = (x, accepts = endpoint) => rows(x, 128, accepts) &&
+    new Set(x.map((row) => JSON.stringify([row.host, row.id]))).size === x.length;
+/** One public projection contract, used before emission and after transport. Native
+ * handles and arbitrary adapter fields can never hitchhike in a valid result. */
+export function isBrokerResult(method, value) {
+    switch (method) {
+        case "health": return exact(value, ["status"]) && ["healthy", "degraded"].includes(String(value.status));
+        case "check": return exact(value, ["status", "scope"]) && value.status === "ok" && value.scope === "broker-loopback";
+        case "register_codex": return endpoint(value);
+        case "send": return exact(value, ["accepted", "conversationId", "deliveryToken"]) && value.accepted === true &&
+            token(value.conversationId, "conv_", "16,64") && token(value.deliveryToken, "dlv_", "24");
+        case "retire_route": return exact(value, ["cancelled", "ambiguous", "unconfirmed"]) && Object.values(value).every(count);
+        case "refresh_discovery": return exact(value, ["routes"]) && endpoints(value.routes);
+        case "peer_catalog": return endpoints(value);
+        case "peer_resolve": return value === null || endpoint(value);
+        case "peer_handoff": return exact(value, ["accepted"]) && value.accepted === true ||
+            exact(value, ["accepted", "code"]) && value.accepted === false && code(value.code);
+        case "delivery_status": return exact(value, ["found"]) && value.found === false ||
+            exact(value, ["found", "state", "terminal", "deadlineAt"], ["pendingForMs", "safeErrorCode"]) && value.found === true && date(value.deadlineAt) &&
+                (value.terminal === true ? outcomes.includes(String(value.state)) && code(value.safeErrorCode) && value.pendingForMs === undefined
+                    : value.terminal === false && ["queued", "reserved", "armed", "accepted"].includes(String(value.state)) && count(value.pendingForMs) && value.safeErrorCode === undefined);
+        case "list_snapshot": return exact(value, ["health", "revision", "routes", "messages", "retirements"], ["safeErrorCode", "federation"]) &&
+            ["healthy", "degraded"].includes(String(value.health)) && count(value.revision) &&
+            (value.safeErrorCode === undefined || code(value.safeErrorCode)) &&
+            (value.federation === undefined || exact(value.federation, ["nodes", "truncated"]) && typeof value.federation.truncated === "boolean" &&
+                rows(value.federation.nodes, 32, (node) => exact(node, ["host", "routes"], ["observedAt", "safeErrorCode"]) && host(node.host) &&
+                    endpoints(node.routes, (row) => endpoint(row) && row.host === node.host) &&
+                    (node.observedAt === undefined || date(node.observedAt)) &&
+                    (node.safeErrorCode === undefined || node.safeErrorCode === "PEER_TUNNEL_UNAVAILABLE")) &&
+                new Set(value.federation.nodes.map((node) => node.host)).size === value.federation.nodes.length &&
+                value.federation.nodes.reduce((sum, node) => sum + node.routes.length, 0) <= 128) &&
+            endpoints(value.routes, (row) => exact(row, ["id", "alias", "provider", "host", "queueDepth"], ["lastOperation"]) &&
+                endpoint({ id: row.id, alias: row.alias, provider: row.provider, host: row.host }) && count(row.queueDepth) &&
+                (row.lastOperation === undefined || exact(row.lastOperation, ["outcome", "code"]) &&
+                    [...outcomes, "deferred"].includes(String(row.lastOperation.outcome)) && code(row.lastOperation.code))) &&
+            rows(value.messages, 600, (row) => exact(row, ["state", "ageMs"], ["source", "target", "safeErrorCode"]) &&
+                [...outcomes, "queued", "reserved", "armed", "accepted"].includes(String(row.state)) && count(row.ageMs) &&
+                (row.source === undefined || alias(row.source)) && (row.target === undefined || alias(row.target)) &&
+                (row.safeErrorCode === undefined || code(row.safeErrorCode))) &&
+            rows(value.retirements, 500, (row) => exact(row, ["alias", "at"]) && alias(row.alias) && date(row.at));
+    }
+}
+/** Closed application vocabulary; the Unix envelope/version belongs to local-control. */
+export function parseBrokerCommand(input, validateHandoff) {
+    if (!exact(input, ["method", "params"]) || typeof input.method !== "string")
+        return invalid();
+    const p = input.params;
+    let valid = false;
+    switch (input.method) {
+        case "health":
+        case "list_snapshot":
+        case "refresh_discovery":
+        case "check":
+            valid = exact(p, []);
+            break;
+        case "register_codex":
+            valid = exact(p, ["caller", "alias"], ["succeeds"]) && caller(p.caller) && p.caller.kind === "codex" && alias(p.alias) &&
+                (p.succeeds === undefined || alias(p.succeeds));
+            break;
+        case "send":
+            valid = exact(p, ["caller", "body"], ["to", "conversation"]) && caller(p.caller) && typeof p.body === "string" &&
+                p.body.trim().length > 0 && !p.body.includes("\0") && Buffer.byteLength(p.body) <= 16_384 &&
+                (Object.hasOwn(p, "to") !== Object.hasOwn(p, "conversation")) &&
+                (p.to === undefined ? token(p.conversation, "conv_", "16,64") : alias(p.to) || uuid(p.to));
+            break;
+        case "retire_route":
+            valid = exact(p, ["alias"]) && alias(p.alias) ||
+                exact(p, ["endpoint"]) && token(p.endpoint, "reg_", "1,252");
+            break;
+        case "delivery_status":
+            valid = exact(p, ["token"]) && token(p.token, "dlv_", "24");
+            break;
+        case "peer_catalog":
+            valid = exact(p, ["node"]) && host(p.node);
+            break;
+        case "peer_resolve":
+            valid = exact(p, ["node", "selector"]) && host(p.node) && (alias(p.selector) || ref(p.selector));
+            break;
+        case "peer_handoff":
+            valid = exact(p, ["node", "handoff"]) && host(p.node) && validateHandoff(p.handoff);
+            break;
+    }
+    return valid ? input : invalid();
+}
+const publicEndpoint = ({ id, host, provider, alias }) => ({ id, host, provider, alias });
+export async function handleBrokerCommand(input, options) {
+    try {
+        const command = parseBrokerCommand(input, options.validateHandoff);
+        const broker = options.broker;
+        let result;
+        switch (command.method) {
+            case "health":
+                result = { status: (await broker.status()).health };
+                break;
+            case "list_snapshot":
+                result = await broker.status();
+                break;
+            case "refresh_discovery":
+                result = await broker.refresh();
+                break;
+            case "register_codex":
+                result = await broker.register(command.params.caller, command.params.alias, command.params.succeeds);
+                break;
+            case "send":
+                result = await broker.send(command.params.caller, command.params.to === undefined ? { conversation: command.params.conversation } : { to: command.params.to }, command.params.body);
+                break;
+            case "retire_route":
+                result = await broker.retire("alias" in command.params ? command.params.alias : command.params);
+                break;
+            case "delivery_status":
+                result = await broker.delivery(command.params.token);
+                break;
+            case "check":
+                result = await options.check();
+                break;
+            case "peer_catalog":
+            case "peer_resolve":
+            case "peer_handoff": {
+                if (!broker.options.nodes?.includes(command.params.node))
+                    throw new BridgeError("PEER_NOT_CONFIGURED", "The node is not configured.");
+                if (command.method === "peer_catalog")
+                    result = (await broker.options.directory.refresh()).map(publicEndpoint);
+                else if (command.method === "peer_handoff")
+                    result = await broker.handoff(command.params.node, command.params.handoff);
+                else {
+                    const selected = command.params.selector;
+                    if (typeof selected === "string" ? !selected.endsWith(`@${broker.options.host}`) : selected.host !== broker.options.host)
+                        return invalid();
+                    const endpoint = typeof selected === "string" ? await broker.options.directory.named(selected) : await broker.options.directory.exact(selected);
+                    result = endpoint ? publicEndpoint(endpoint) : null;
+                }
+                break;
+            }
+        }
+        if (!isBrokerResult(command.method, result))
+            throw new BridgeError("INVALID_HANDLER_RESPONSE", "The result is outside the public projection.");
+        return { ok: true, result };
+    }
+    catch (error) {
+        return { ok: false, code: error instanceof BridgeError && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : "HANDLER_FAILURE" };
+    }
+}
+export const commandMutates = (method) => !["health", "list_snapshot", "delivery_status", "peer_catalog", "peer_resolve"].includes(method);
+//# sourceMappingURL=broker-control.js.map

package/dist/src/gateway/broker-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-control.js","sourceRoot":"","sources":["../../../src/gateway/broker-control.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,117 @@
+import { Coordinator } from "./coordinator.js";
+import { EndpointDirectory, type EndpointCaller } from "./endpoint-directory.js";
+import { type LedgerLimits, type LedgerState } from "./ledger.js";
+import type { OwnedStateFile } from "./owned-state.js";
+import type { FederatedHandoff, Federation } from "./federation.js";
+export type BrokerOptions = Readonly<{
+    host: string;
+    store: OwnedStateFile<LedgerState>;
+    limits: LedgerLimits;
+    directory: EndpointDirectory;
+    coordinator: Coordinator;
+    now?: () => number;
+    nodes?: readonly string[];
+    steeringEnabled?: boolean;
+    federation?: Pick<Federation, "catalog" | "snapshot">;
+}>;
+/** Application commands over the directory and the single delivery ledger. */
+export declare class MessagingBroker {
+    readonly options: BrokerOptions;
+    private timer;
+    private stopped;
+    private started;
+    private pumping;
+    private requested;
+    private fault;
+    private readonly now;
+    constructor(options: BrokerOptions);
+    private change;
+    start(): Promise<void>;
+    register(caller: EndpointCaller, alias: string, succeeds?: string): Promise<{
+        id: string;
+        alias: string;
+        provider: "claude" | "codex";
+        host: string;
+    }>;
+    send(caller: EndpointCaller, address: {
+        to: string;
+    } | {
+        conversation: string;
+    }, body: string): Promise<{
+        accepted: true;
+        conversationId: string;
+        deliveryToken: string;
+    }>;
+    retire(selector: string | {
+        endpoint: string;
+    }): Promise<{
+        cancelled: number;
+        ambiguous: number;
+        unconfirmed: number;
+    }>;
+    handoff(peerHost: string, input: FederatedHandoff): Promise<{
+        accepted: false;
+        code: string;
+    } | {
+        accepted: true;
+        code?: never;
+    }>;
+    delivery(token: string): Promise<{
+        found: false;
+    } | {
+        safeErrorCode: string;
+        found: true;
+        state: import("./ledger.js").Outcome | "queued" | "reserved" | "armed" | "accepted";
+        terminal: boolean;
+        deadlineAt: string;
+    } | {
+        pendingForMs: number;
+        found: true;
+        state: import("./ledger.js").Outcome | "queued" | "reserved" | "armed" | "accepted";
+        terminal: boolean;
+        deadlineAt: string;
+    }>;
+    refresh(): Promise<{
+        routes: {
+            id: string;
+            alias: string;
+            provider: "claude" | "codex";
+            host: string;
+        }[];
+    }>;
+    status(): Promise<{
+        routes: {
+            queueDepth: number;
+            lastOperation?: Readonly<{
+                outcome: import("./ledger.js").Outcome | "deferred";
+                code: string;
+                unwritten?: true;
+            }> | undefined;
+            id: string;
+            alias: string;
+            provider: "claude" | "codex";
+            host: string;
+        }[];
+        messages: {
+            safeErrorCode?: string;
+            source: string | undefined;
+            target: string | undefined;
+            state: import("./ledger.js").Outcome | "queued" | "reserved" | "armed" | "accepted";
+            ageMs: number;
+        }[];
+        retirements: {
+            alias: string;
+            at: string;
+        }[];
+        federation?: Readonly<{
+            nodes: readonly import("./federation.js").FederationObservation[];
+            truncated: boolean;
+        }>;
+        revision: number;
+        safeErrorCode?: string;
+        health: string;
+    }>;
+    private kick;
+    private pump;
+    close(): Promise<void>;
+}