agent-embassy 3.0.0 → 4.0.0

package/dist/src/gateway/control.js

@@ -1,903 +0,0 @@
-/** Private, bounded JSONL control transport over one same-user Unix socket. */
-import { randomBytes } from "node:crypto";
-import { chmod, lstat, mkdtemp, realpath, rename, rmdir, unlink } from "node:fs/promises";
-import net from "node:net";
-import path from "node:path";
-import { TextDecoder } from "node:util";
-import { CONNECTOR_OBSERVATION_STALE_AFTER_MS, GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayPublicSnapshotLimits, isGatewayProvider, isMessageDirection, isPublicRegistryObservationSnapshot, } from "./types.js";
-import { decodePeerParams, decodePeerResult } from "./peer-protocol.js";
-import { isPeerMailboxAwaitResult } from "./peer-mailbox.js";
-export const GATEWAY_CONTROL_PROTOCOL_VERSION = 3;
-export const GATEWAY_CONTROL_MAX_FRAME_BYTES = 32 * 1024;
-export const GATEWAY_CONTROL_MAX_RESPONSE_BYTES = 256 * 1024;
-export const GATEWAY_CONTROL_MAX_MESSAGE_BYTES = 16 * 1024;
-export const GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS = 3_000;
-export const GATEWAY_CONTROL_MAX_CONNECTIONS = 32;
-const MAX_SOCKET_PATH_BYTES = 100;
-const MAX_REPLY_ADDRESS_BYTES = 256;
-const MAX_REVISION = Number.MAX_SAFE_INTEGER;
-const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
-const UUID_PATTERN = /^[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 CONVERSATION_ID_PATTERN = /^conv_[A-Za-z0-9_-]{16,64}$/;
-const DELIVERY_TOKEN_PATTERN = /^dlv_[A-Za-z0-9_-]{24}$/;
-const PEER_TOKEN_PATTERN = /^peer_[A-Za-z0-9_-]{32}$/;
-const PEER_RECEIPT_PATTERN = /^prc_[A-Za-z0-9_-]{24}$/;
-const HOST_PATTERN = /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
-const SAFE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
-const PROTOCOL_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-const PROTOCOL_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:+-]{0,63}$/;
-const MESSAGE_SUFFIX_PATTERN = /^[0-9a-f]{8}$/;
-const CONVERSATION_SUFFIX_PATTERN = /^[A-Za-z0-9_-]{8}$/;
-const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
-export const gatewayControlMethods = [
-    "health", "register_codex", "unregister_codex", "list_snapshot",
-    "observe_snapshot", "delivery_status", "send",
-    "refresh_discovery", "peer_catalog", "peer_handoff",
-    "register_peer", "unregister_peer", "await_peer", "peer_receipt",
-];
-/** Bounds on an ephemeral peer registration's lifetime, in milliseconds. */
-export const GATEWAY_EPHEMERAL_PEER_TTL_DEFAULT_MS = 300_000;
-export const GATEWAY_EPHEMERAL_PEER_TTL_MIN_MS = 1_000;
-export const GATEWAY_EPHEMERAL_PEER_TTL_MAX_MS = 3_600_000;
-const WIRE_ERROR_MESSAGES = {
-    INVALID_JSON: "The control frame is not valid JSON.", FRAME_TOO_LARGE: "The control frame exceeds the size limit.",
-    INVALID_REQUEST: "The control request is invalid.", UNSUPPORTED_VERSION: "The control protocol version is unsupported.",
-    UNKNOWN_METHOD: "The control method is unsupported.", MULTIPLE_FRAMES: "Only one control request is allowed per connection.",
-    SERVER_BUSY: "The gateway control server is at its connection limit.", REQUEST_TIMEOUT: "The control request timed out.",
-    HANDLER_FAILURE: "The gateway could not complete the control request.", INVALID_HANDLER_RESPONSE: "The gateway produced an invalid control response.",
-    RESPONSE_TOO_LARGE: "The control response exceeds the size limit.",
-};
-const TRANSPORT_MESSAGES = {
-    UNSUPPORTED_PLATFORM: "Unix-domain gateway control sockets are unavailable.",
-    INVALID_STATE_DIR: "The gateway state directory is invalid.",
-    INSECURE_STATE_DIR: "The gateway state directory is not private to this user.",
-    INVALID_SOCKET_PATH: "The gateway control socket path is invalid.",
-    UNSAFE_SOCKET_TARGET: "The gateway control socket target is unsafe.",
-    SOCKET_IN_USE: "The gateway control socket is already served by a live process.",
-    SOCKET_PROBE_FAILED: "The gateway control socket could not be checked safely.",
-    SOCKET_BIND_FAILED: "The gateway control socket could not be bound.",
-    SOCKET_PERMISSION_FAILED: "The gateway control socket permissions could not be secured.",
-    SOCKET_CLEANUP_CONFLICT: "The gateway control socket path changed during cleanup.",
-    CONTROL_CONNECT_FAILED: "The gateway control socket could not be reached.",
-    CONTROL_CONNECT_DENIED: "The gateway control socket connection was denied by local policy.",
-    CONTROL_SOCKET_MISSING: "The gateway control socket does not exist at the configured path.",
-    CONTROL_LISTENER_UNAVAILABLE: "Nothing is listening on the gateway control socket.",
-    CONTROL_TIMEOUT: "The gateway control request timed out.",
-    CONTROL_RESPONSE_TOO_LARGE: "The gateway control response exceeds the client limit.",
-    CONTROL_INVALID_RESPONSE: "The gateway returned an invalid control response. Restart the broker, then retry.",
-    CONTROL_VERSION_MISMATCH: "The gateway control protocol version does not match this client.",
-    CONTROL_CONNECTION_CLOSED: "The gateway closed before returning a control response.",
-    CONTROL_OUTCOME_AMBIGUOUS: "The gateway may have applied the control mutation before the response was lost; do not retry automatically.",
-};
-export class GatewayControlTransportError extends Error {
-    code;
-    ambiguous;
-    recoverable;
-    constructor(code, message, ambiguous = false) {
-        super(message);
-        this.name = "GatewayControlTransportError";
-        this.code = code;
-        this.ambiguous = ambiguous;
-        this.recoverable = !ambiguous;
-    }
-}
-class ProtocolFault extends Error {
-    code;
-    constructor(code) {
-        super(WIRE_ERROR_MESSAGES[code]);
-        this.name = "ProtocolFault";
-        this.code = code;
-    }
-}
-function controlTransportError(code, ambiguous = false) {
-    return new GatewayControlTransportError(code, TRANSPORT_MESSAGES[code] ?? "The gateway control transport failed.", ambiguous);
-}
-function invalid() { throw new ProtocolFault("INVALID_REQUEST"); }
-export function createGatewayConversationId() {
-    return `conv_${randomBytes(18).toString("base64url")}`;
-}
-export function isGatewayAlias(value) { return ALIAS_PATTERN.test(value); }
-export function isClaudeSessionSelector(value) {
-    return isGatewayAlias(value) || UUID_PATTERN.test(value);
-}
-export function isGatewayHostId(value) { return HOST_PATTERN.test(value); }
-export function isGatewayConversationId(value) { return CONVERSATION_ID_PATTERN.test(value); }
-export function isGatewayDeliveryToken(value) { return DELIVERY_TOKEN_PATTERN.test(value); }
-export function isGatewayReplyAddress(value) {
-    if (value.includes("\0") || !value.startsWith("uds:") ||
-        Buffer.byteLength(value, "utf8") > MAX_REPLY_ADDRESS_BYTES)
-        return false;
-    const socketPath = value.slice(4);
-    return path.isAbsolute(socketPath) && path.resolve(socketPath) === socketPath &&
-        Buffer.byteLength(socketPath, "utf8") <= MAX_SOCKET_PATH_BYTES;
-}
-function isRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
-function hasExactKeys(value, required, optional = []) {
-    const ownKeys = Reflect.ownKeys(value);
-    if (ownKeys.some((key) => typeof key !== "string"))
-        return false;
-    const allowed = new Set([...required, ...optional]);
-    return (required.every((key) => Object.hasOwn(value, key)) &&
-        ownKeys.every((key) => typeof key === "string" && allowed.has(key)));
-}
-function isNonNegativeInteger(value) {
-    return (typeof value === "number" &&
-        Number.isSafeInteger(value) &&
-        value >= 0 &&
-        value <= MAX_REVISION);
-}
-function isIsoTimestamp(value) {
-    if (typeof value !== "string" || !ISO_TIMESTAMP_PATTERN.test(value)) {
-        return false;
-    }
-    const parsed = Date.parse(value);
-    return Number.isFinite(parsed);
-}
-function isUuid(value) {
-    return typeof value === "string" && UUID_PATTERN.test(value);
-}
-function isAlias(value) {
-    return typeof value === "string" && isGatewayAlias(value);
-}
-function isHostId(value) {
-    return typeof value === "string" && isGatewayHostId(value);
-}
-function isMessageText(value) {
-    return (typeof value === "string" &&
-        value.trim().length > 0 &&
-        !value.includes("\0") &&
-        Buffer.byteLength(value, "utf8") <= GATEWAY_CONTROL_MAX_MESSAGE_BYTES);
-}
-const exact = hasExactKeys;
-const nonNegative = isNonNegativeInteger;
-const iso = isIsoTimestamp;
-const uuid = isUuid;
-const alias = isAlias;
-const host = isHostId;
-function shape(value, required, optional = {}) {
-    if (!isRecord(value) || !exact(value, Object.keys(required), Object.keys(optional)))
-        return false;
-    return Object.entries(required).every(([key, check]) => check(value[key])) &&
-        Object.entries(optional).every(([key, check]) => value[key] === undefined || check(value[key]));
-}
-function oneOf(...values) { return (value) => values.includes(value); }
-function arrayOf(value, maximum, check) {
-    return Array.isArray(value) && value.length <= maximum && value.every(check);
-}
-function positive(value) { return nonNegative(value) && value > 0; }
-function safeCode(value) { return typeof value === "string" && SAFE_CODE_PATTERN.test(value); }
-const messageText = isMessageText;
-const peerToken = (value) => typeof value === "string" && PEER_TOKEN_PATTERN.test(value);
-const peerAlias = (value) => alias(value) && value.startsWith("peer-");
-function emptyParams(value) {
-    if (!isRecord(value) || !exact(value, []))
-        invalid();
-    return {};
-}
-function decodePeerCatalog(value) {
-    if (!shape(value, { peerHost: host }))
-        invalid();
-    return { peerHost: value.peerHost };
-}
-function decodePeerHandoff(value) {
-    if (!isRecord(value) || !exact(value, ["peerHost", "handoff"]) || !host(value.peerHost))
-        invalid();
-    try {
-        return { peerHost: value.peerHost, handoff: decodePeerParams("handoff", value.handoff) };
-    }
-    catch {
-        return invalid();
-    }
-}
-function decodeRegisterPeer(value) {
-    // `ephemeral` belongs only to a first registration: re-presenting a token
-    // proves an existing route, and an existing route's lifetime is already
-    // fixed. `ttlMs` without `ephemeral` would name a lifetime nothing honours.
-    if (!shape(value, { alias: peerAlias }, { token: peerToken, ephemeral: oneOf(true),
-        ttlMs: (item) => Number.isSafeInteger(item) &&
-            Number(item) >= GATEWAY_EPHEMERAL_PEER_TTL_MIN_MS &&
-            Number(item) <= GATEWAY_EPHEMERAL_PEER_TTL_MAX_MS }) ||
-        (value.ephemeral !== undefined && value.token !== undefined) ||
-        (value.ttlMs !== undefined && value.ephemeral === undefined))
-        invalid();
-    return { alias: value.alias,
-        ...(value.token === undefined ? {} : { token: value.token }),
-        ...(value.ephemeral === undefined ? {} : { ephemeral: true }),
-        ...(value.ttlMs === undefined ? {} : { ttlMs: value.ttlMs }) };
-}
-function decodePeerPrincipal(value) {
-    if (!shape(value, { alias: peerAlias, token: peerToken }))
-        invalid();
-    return { alias: value.alias, token: value.token };
-}
-function decodePeerReceipt(value) {
-    if (!shape(value, { alias: peerAlias, token: peerToken,
-        receipt: (item) => typeof item === "string" && PEER_RECEIPT_PATTERN.test(item) }))
-        invalid();
-    return { alias: value.alias, token: value.token, receipt: value.receipt };
-}
-const isPeerCatalog = (value) => {
-    try {
-        decodePeerResult("catalog/get", value);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-const isPeerHandoffResult = (value) => {
-    try {
-        decodePeerResult("handoff", value);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
-function decodeRegister(value) {
-    if (!isRecord(value) || !exact(value, ["alias", "threadId", "hostId", "busyPolicy"], ["succeedsAlias"]) ||
-        !alias(value.alias) || !value.alias.startsWith("codex-") || !uuid(value.threadId) ||
-        !host(value.hostId) || value.busyPolicy !== "queue" ||
-        (value.succeedsAlias !== undefined && (!alias(value.succeedsAlias) || !value.succeedsAlias.startsWith("codex-"))))
-        invalid();
-    if (!value.alias.endsWith(`@${value.hostId}`) ||
-        (value.succeedsAlias !== undefined &&
-            (value.succeedsAlias === value.alias || !value.succeedsAlias.endsWith(`@${value.hostId}`))))
-        invalid();
-    return { alias: value.alias, threadId: value.threadId.toLowerCase(), hostId: value.hostId,
-        busyPolicy: value.busyPolicy, ...(value.succeedsAlias === undefined ? {} : { succeedsAlias: value.succeedsAlias }) };
-}
-function decodeUnregister(value) {
-    if (!shape(value, { alias, threadId: uuid }) || !value.alias.startsWith("codex-"))
-        invalid();
-    return { alias: value.alias, threadId: value.threadId.toLowerCase() };
-}
-function decodeSend(value) {
-    if (!isRecord(value) || !exact(value, ["fromAlias", "text"], ["toAlias", "conversationId", "threadId", "replyAddress", "peerToken", "expectsReply"]) ||
-        !alias(value.fromAlias) || !messageText(value.text) ||
-        [value.toAlias, value.conversationId].filter((item) => item !== undefined).length !== 1 ||
-        (value.toAlias !== undefined && (typeof value.toAlias !== "string" || !isClaudeSessionSelector(value.toAlias))) ||
-        (value.conversationId !== undefined && (typeof value.conversationId !== "string" || !isGatewayConversationId(value.conversationId))) ||
-        [value.threadId, value.replyAddress, value.peerToken].filter((item) => item !== undefined).length !== 1 ||
-        (value.threadId !== undefined && !uuid(value.threadId)) ||
-        (value.replyAddress !== undefined && (typeof value.replyAddress !== "string" || !isGatewayReplyAddress(value.replyAddress))) ||
-        (value.peerToken !== undefined && !peerToken(value.peerToken)) ||
-        (value.expectsReply !== undefined &&
-            (typeof value.expectsReply !== "boolean" || value.conversationId !== undefined)))
-        invalid();
-    const authority = value.threadId !== undefined ? { threadId: value.threadId.toLowerCase() }
-        : value.replyAddress !== undefined ? { replyAddress: value.replyAddress }
-            : { peerToken: value.peerToken };
-    const target = value.conversationId !== undefined
-        ? { conversationId: value.conversationId }
-        : { toAlias: UUID_PATTERN.test(value.toAlias) ? value.toAlias.toLowerCase() : value.toAlias,
-            expectsReply: value.expectsReply === true };
-    return { fromAlias: value.fromAlias, text: value.text, ...target, ...authority };
-}
-function decodeDeliveryStatus(value) {
-    if (!shape(value, { token: (item) => typeof item === "string" && DELIVERY_TOKEN_PATTERN.test(item) }))
-        invalid();
-    return { token: value.token };
-}
-function isDecision(value) {
-    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected") }) && (value.accepted === true ? value.code === "ok" : value.code !== "ok");
-}
-function isRegisterPeerResult(value) {
-    return isDecision(value) || shape(value, { accepted: oneOf(true), code: oneOf("ok"), token: peerToken });
-}
-function isHealthResult(value) {
-    return shape(value, { status: oneOf("ok", "degraded"), revision: nonNegative });
-}
-function isSendResult(value) {
-    if (!isRecord(value) || value.accepted !== true) {
-        return shape(value, { accepted: oneOf(false), code: oneOf("not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected") }, { reason: safeCode });
-    }
-    return shape(value, { accepted: oneOf(true), code: oneOf("ok"),
-        conversationId: (item) => typeof item === "string" && CONVERSATION_ID_PATTERN.test(item),
-        deliveryToken: (item) => typeof item === "string" && DELIVERY_TOKEN_PATTERN.test(item) });
-}
-function isRefreshResult(value) {
-    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "route_mismatch", "busy", "unavailable", "rejected"), revision: nonNegative }) && isDecision({ accepted: value.accepted, code: value.code });
-}
-const TERMINAL = new Set(["delivered", "unconfirmed", "expired", "failed", "ambiguous", "cancelled"]);
-function isDeliveryStatusResult(value) {
-    if (!isRecord(value) || typeof value.found !== "boolean")
-        return false;
-    if (!value.found)
-        return exact(value, ["found"]);
-    return shape(value, { found: oneOf(true), state: oneOf("queued", "stalled", "delivered", "unconfirmed", "expired", "failed", "ambiguous", "cancelled"), terminal: (item) => typeof item === "boolean", updatedAt: iso, deadlineAt: iso }, { pendingForMs: nonNegative, safeErrorCode: safeCode }) && value.terminal === TERMINAL.has(value.state);
-}
-function isRouteCounters(value) {
-    const keys = ["accepted", "delivered", "unconfirmed", "failed", "ambiguous", "expired",
-        "cancelled", "abandoned", "rejected", "bytesAccepted"];
-    return isRecord(value) && exact(value, keys) && keys.every((key) => nonNegative(value[key]));
-}
-const isConnectorHealth = oneOf("offline", "connecting", "healthy", "degraded");
-function isConnectorSnapshot(value) {
-    if (!shape(value, { provider: isGatewayProvider, host, health: isConnectorHealth,
-        protocol: (item) => typeof item === "string" && PROTOCOL_PATTERN.test(item),
-        protocolVersion: (item) => typeof item === "string" && PROTOCOL_VERSION_PATTERN.test(item) }, { lastSeenAt: iso, observationAgeMs: nonNegative, safeErrorCode: safeCode,
-        registry: isPublicRegistryObservationSnapshot }))
-        return false;
-    return value.registry === undefined || value.provider === "claude";
-}
-function isRouteSnapshot(value) {
-    if (!shape(value, { alias, provider: isGatewayProvider, host, enabled: (item) => typeof item === "boolean",
-        state: oneOf("stale", "idle", "busy", "awaiting_approval", "offline", "disabled"),
-        busyPolicy: oneOf("queue"), queueDepth: nonNegative, counters: isRouteCounters }, { lastSeenAt: iso, oldestQueuedAt: iso, safeErrorCode: safeCode, mutable: (item) => typeof item === "boolean" }))
-        return false;
-    const row = value;
-    return row.alias.endsWith(`@${row.host}`) &&
-        (row.oldestQueuedAt === undefined ? row.queueDepth === 0 : row.queueDepth > 0);
-}
-function isAvailablePeerSnapshot(value) {
-    return shape(value, { alias, provider: oneOf("claude"), host,
-        state: oneOf("idle", "busy", "awaiting_approval", "offline"),
-        validated: (item) => typeof item === "boolean", routed: (item) => typeof item === "boolean" }, { lastSeenAt: iso, safeErrorCode: safeCode }) &&
-        value.alias.endsWith(`@${String(value.host)}`);
-}
-function isNormalizedMessageEvent(value) {
-    if (!shape(value, { sequence: nonNegative, timestamp: iso,
-        messageIdSuffix: (item) => typeof item === "string" && MESSAGE_SUFFIX_PATTERN.test(item),
-        direction: isMessageDirection, sourceAlias: alias, targetAlias: alias,
-        state: oneOf("queued", "duplicate", "dispatching", "transport_written", "held", "delivered", "unconfirmed", "failed", "ambiguous", "expired", "cancelled", "abandoned", "rejected"),
-        bytes: nonNegative }, { conversationIdSuffix: (item) => typeof item === "string" && CONVERSATION_SUFFIX_PATTERN.test(item),
-        body: (item) => typeof item === "string" && item.length > 0 && !item.includes("\0"),
-        latencyMs: nonNegative, safeErrorCode: safeCode, steer: oneOf(true) }))
-        return false;
-    return value.body === undefined || Buffer.byteLength(value.body, "utf8") === value.bytes;
-}
-function isAccounting(value) {
-    const keys = ["accepted", "duplicates", "delivered", "unconfirmed", "failed", "ambiguous",
-        "expired", "cancelled", "abandoned", "rejected", "bytesAccepted", "queuedBytes"];
-    return isRecord(value) && exact(value, keys) && keys.every((key) => nonNegative(value[key]));
-}
-function isSafeAlert(value) {
-    return shape(value, { code: safeCode, severity: oneOf("info", "warning", "error"), timestamp: iso }, { provider: isGatewayProvider, host, alias });
-}
-function isGatewayActivityEvent(value) {
-    if (!shape(value, { sequence: positive, timestamp: iso,
-        kind: oneOf("discovery", "registration"),
-        action: oneOf("discovery_refreshed", "codex_registered", "codex_succeeded", "codex_unregistered", "claude_route_installed", "claude_route_retired"),
-        outcome: oneOf("accepted", "rejected"), aliases: (rows) => arrayOf(rows, 2, alias),
-        operatorAction: oneOf(true) }, { safeErrorCode: safeCode }))
-        return false;
-    const allowed = {
-        discovery: ["discovery_refreshed"],
-        registration: ["codex_registered", "codex_succeeded", "codex_unregistered",
-            "claude_route_installed", "claude_route_retired"],
-    };
-    return new Set(value.aliases).size === value.aliases.length &&
-        (allowed[value.kind]?.includes(value.action) ?? false);
-}
-function isDeadlinePressure(value) {
-    const names = ["under_1m", "1m_to_5m", "5m_to_15m", "15m_to_60m", "over_60m"];
-    if (!shape(value, { configuredDeadlineMs: positive, terminalEvents: nonNegative,
-        expiredEvents: nonNegative, buckets: (rows) => Array.isArray(rows) && rows.length === names.length }, { retainedSince: iso }) || Number(value.expiredEvents) > Number(value.terminalEvents))
-        return false;
-    const rows = value.buckets;
-    if (!rows.every((row, index) => shape(row, { bucket: oneOf(names[index]), settled: nonNegative, expired: nonNegative }) &&
-        row.expired <= row.settled))
-        return false;
-    return rows.reduce((sum, row) => sum + Number(row.settled), 0) === value.terminalEvents &&
-        rows.reduce((sum, row) => sum + Number(row.expired), 0) === value.expiredEvents;
-}
-function isSnapshotTruncation(value) {
-    const required = ["connectors", "availablePeers", "routes", "messages", "alerts"];
-    const optional = ["activityEvents"];
-    return isRecord(value) && exact(value, required, optional) &&
-        [...required, ...optional].every((key) => value[key] === undefined || nonNegative(value[key]));
-}
-export function isGatewaySnapshot(value) {
-    if (!shape(value, { schemaVersion: oneOf(2), generatedAt: iso,
-        health: isConnectorHealth,
-        connectors: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.connectors, isConnectorSnapshot),
-        availablePeers: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.availablePeers, isAvailablePeerSnapshot),
-        routes: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.routes, isRouteSnapshot),
-        messages: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.messages, isNormalizedMessageEvent),
-        accounting: isAccounting, alerts: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.alerts, isSafeAlert),
-        truncation: isSnapshotTruncation }, { activityEvents: (rows) => arrayOf(rows, gatewayPublicSnapshotLimits.activityEvents, isGatewayActivityEvent),
-        deadlinePressure: isDeadlinePressure }))
-        return false;
-    const snapshot = value;
-    const unique = (rows) => new Set(rows).size === rows.length;
-    const generated = Date.parse(snapshot.generatedAt);
-    const connectorKeys = snapshot.connectors.map((row) => `${row.provider}@${row.host}`);
-    const aliases = snapshot.routes.map((row) => row.alias);
-    const peers = snapshot.availablePeers.map((row) => row.alias);
-    const honest = snapshot.connectors.every((row) => {
-        const seen = row.lastSeenAt === undefined ? undefined : Date.parse(row.lastSeenAt);
-        const age = seen === undefined ? undefined : Math.min(MAX_REVISION, Math.max(0, generated - seen));
-        return (row.observationAgeMs === undefined || row.observationAgeMs === age) &&
-            (row.health !== "healthy" || (age !== undefined && age <= CONNECTOR_OBSERVATION_STALE_AFTER_MS));
-    });
-    return honest && unique(connectorKeys) && unique(aliases) && unique(peers) &&
-        Buffer.byteLength(JSON.stringify(snapshot), "utf8") <= GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET;
-}
-function isSnapshotObservation(value) {
-    return shape(value, { snapshotRevision: nonNegative, snapshot: isGatewaySnapshot });
-}
-const descriptors = {
-    health: { handler: "health", decode: emptyParams, result: isHealthResult, mutation: false }, register_codex: { handler: "registerCodex", decode: decodeRegister, result: isDecision, mutation: true },
-    unregister_codex: { handler: "unregisterCodex", decode: decodeUnregister, result: isDecision, mutation: true },
-    list_snapshot: { handler: "listSnapshot", decode: emptyParams, result: isGatewaySnapshot, mutation: false }, observe_snapshot: { handler: "observeSnapshot", decode: emptyParams, result: isSnapshotObservation, mutation: false },
-    delivery_status: { handler: "deliveryStatus", decode: decodeDeliveryStatus, result: isDeliveryStatusResult, mutation: false },
-    send: { handler: "send", decode: decodeSend, result: isSendResult, mutation: true },
-    refresh_discovery: { handler: "refreshDiscovery", decode: emptyParams, result: isRefreshResult, mutation: false },
-    peer_catalog: { handler: "peerCatalog", decode: decodePeerCatalog, result: isPeerCatalog, mutation: false },
-    peer_handoff: { handler: "peerHandoff", decode: decodePeerHandoff, result: isPeerHandoffResult, mutation: true },
-    register_peer: { handler: "registerPeer", decode: decodeRegisterPeer, result: isRegisterPeerResult, mutation: true },
-    unregister_peer: { handler: "unregisterPeer", decode: decodePeerPrincipal, result: isDecision, mutation: true },
-    await_peer: { handler: "awaitPeer", decode: decodePeerPrincipal, result: isPeerMailboxAwaitResult, mutation: false },
-    peer_receipt: { handler: "peerReceipt", decode: decodePeerReceipt, result: isDecision, mutation: true },
-};
-function parseRequestObject(value) {
-    if (!isRecord(value) || !exact(value, ["protocolVersion", "method", "params"]))
-        invalid();
-    if (value.protocolVersion !== GATEWAY_CONTROL_PROTOCOL_VERSION)
-        throw new ProtocolFault("UNSUPPORTED_VERSION");
-    if (typeof value.method !== "string" || !Object.hasOwn(descriptors, value.method))
-        throw new ProtocolFault("UNKNOWN_METHOD");
-    const method = value.method;
-    return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, method, params: descriptors[method].decode(value.params) };
-}
-function decodeJson(frame, invalidCode) {
-    try {
-        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(frame));
-    }
-    catch {
-        throw new ProtocolFault(invalidCode);
-    }
-}
-function errorResponse(code) {
-    return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, ok: false, error: { code, message: WIRE_ERROR_MESSAGES[code] } };
-}
-async function dispatch(request, handlers) {
-    const descriptor = descriptors[request.method];
-    const handler = handlers[descriptor.handler];
-    try {
-        const result = await (Object.keys(request.params).length === 0 ? handler() : handler(request.params));
-        return { protocolVersion: GATEWAY_CONTROL_PROTOCOL_VERSION, ok: true, result };
-    }
-    catch {
-        return errorResponse("HANDLER_FAILURE");
-    }
-}
-function serializeResponse(response) {
-    try {
-        const encoded = Buffer.from(`${JSON.stringify(response)}\n`, "utf8");
-        return encoded.length <= GATEWAY_CONTROL_MAX_RESPONSE_BYTES ? encoded : Buffer.from(`${JSON.stringify(errorResponse("RESPONSE_TOO_LARGE"))}\n`);
-    }
-    catch {
-        return Buffer.from(`${JSON.stringify(errorResponse("INVALID_HANDLER_RESPONSE"))}\n`);
-    }
-}
-class FrameFault extends Error {
-    kind;
-    systemCode;
-    constructor(kind, systemCode) {
-        super(kind);
-        this.kind = kind;
-        this.systemCode = systemCode;
-    }
-}
-function readOneFrame(socket, maximum) {
-    return new Promise((resolve, reject) => {
-        let buffered = Buffer.alloc(0);
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.pause();
-            socket.off("data", onData);
-            socket.off("end", onEnd);
-            socket.off("timeout", onTimeout);
-            value instanceof FrameFault ? reject(value) : resolve(value);
-        };
-        const onData = (chunk) => {
-            if (buffered.length + chunk.length > maximum)
-                return finish(new FrameFault("too_large"));
-            buffered = Buffer.concat([buffered, chunk]);
-            const newline = buffered.indexOf(0x0a);
-            if (newline < 0)
-                return;
-            if (buffered.subarray(newline + 1).toString("utf8").trim().length > 0)
-                return finish(new FrameFault("multiple"));
-            finish(buffered.subarray(0, newline));
-        };
-        const onEnd = () => finish(new FrameFault("closed"));
-        const onTimeout = () => finish(new FrameFault("timeout"));
-        socket.on("data", onData);
-        socket.once("end", onEnd);
-        socket.once("timeout", onTimeout);
-        socket.once("error", (error) => finish(new FrameFault("error", error.code)));
-    });
-}
-function respond(socket, response) {
-    if (!socket.destroyed)
-        socket.end(serializeResponse(response));
-}
-function handleConnection(socket, handlers, timeoutMs) {
-    socket.setTimeout(timeoutMs);
-    void readOneFrame(socket, GATEWAY_CONTROL_MAX_FRAME_BYTES).then(async (frame) => {
-        socket.setTimeout(0);
-        let request;
-        try {
-            request = parseRequestObject(decodeJson(frame, "INVALID_JSON"));
-        }
-        catch (error) {
-            respond(socket, errorResponse(error instanceof ProtocolFault ? error.code : "INVALID_REQUEST"));
-            return;
-        }
-        respond(socket, await dispatch(request, handlers));
-    }, (error) => {
-        const kind = error instanceof FrameFault ? error.kind : "error";
-        if (kind === "too_large")
-            respond(socket, errorResponse("FRAME_TOO_LARGE"));
-        else if (kind === "multiple")
-            respond(socket, errorResponse("MULTIPLE_FRAMES"));
-        else if (kind === "timeout")
-            respond(socket, errorResponse("REQUEST_TIMEOUT"));
-        else
-            socket.destroy();
-    });
-}
-async function optionalLstat(target) {
-    try {
-        return await lstat(target);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
-        throw error;
-    }
-}
-function assertSocketPath(socketPath) {
-    if (!path.isAbsolute(socketPath) ||
-        path.resolve(socketPath) !== socketPath ||
-        Buffer.byteLength(socketPath, "utf8") > MAX_SOCKET_PATH_BYTES) {
-        throw controlTransportError("INVALID_SOCKET_PATH");
-    }
-}
-async function validateSocketLocation(stateDir, socketPath) {
-    if (process.platform === "win32") {
-        throw controlTransportError("UNSUPPORTED_PLATFORM");
-    }
-    assertSocketPath(socketPath);
-    if (!path.isAbsolute(stateDir) || path.resolve(stateDir) !== stateDir) {
-        throw controlTransportError("INVALID_SOCKET_PATH");
-    }
-    let stateInfo;
-    try {
-        stateInfo = await lstat(stateDir);
-    }
-    catch {
-        throw controlTransportError("INVALID_STATE_DIR");
-    }
-    if (stateInfo.isSymbolicLink() || !stateInfo.isDirectory()) {
-        throw controlTransportError("INVALID_STATE_DIR");
-    }
-    const getuid = process.getuid;
-    if ((getuid !== undefined && stateInfo.uid !== getuid.call(process)) ||
-        (stateInfo.mode & 0o077) !== 0) {
-        throw controlTransportError("INSECURE_STATE_DIR");
-    }
-    let stateReal;
-    let parentReal;
-    try {
-        [stateReal, parentReal] = await Promise.all([
-            realpath(stateDir),
-            realpath(path.dirname(socketPath)),
-        ]);
-    }
-    catch {
-        throw controlTransportError("INVALID_SOCKET_PATH");
-    }
-    if (socketPath === stateDir ||
-        (parentReal !== stateReal &&
-            !parentReal.startsWith(`${stateReal}${path.sep}`))) {
-        throw controlTransportError("INVALID_SOCKET_PATH");
-    }
-}
-async function socketIsLive(socketPath) {
-    return await new Promise((resolve, reject) => {
-        const socket = net.createConnection(socketPath);
-        let settled = false;
-        const finish = (action) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            action();
-        };
-        socket.setTimeout(250);
-        socket.once("connect", () => finish(() => resolve(true)));
-        socket.once("timeout", () => finish(() => reject(controlTransportError("SOCKET_PROBE_FAILED"))));
-        socket.once("error", (error) => {
-            if (error.code === "ECONNREFUSED" || error.code === "ENOENT") {
-                finish(() => resolve(false));
-            }
-            else {
-                finish(() => reject(controlTransportError("SOCKET_PROBE_FAILED")));
-            }
-        });
-    });
-}
-function sameIdentity(info, identity) {
-    return info.dev === identity.dev && info.ino === identity.ino;
-}
-async function prepareSocketTarget(socketPath) {
-    let existing;
-    try {
-        existing = await optionalLstat(socketPath);
-    }
-    catch {
-        throw controlTransportError("UNSAFE_SOCKET_TARGET");
-    }
-    if (!existing)
-        return;
-    if (existing.isSymbolicLink() || !existing.isSocket()) {
-        throw controlTransportError("UNSAFE_SOCKET_TARGET");
-    }
-    const identity = { dev: existing.dev, ino: existing.ino };
-    if (await socketIsLive(socketPath)) {
-        throw controlTransportError("SOCKET_IN_USE");
-    }
-    let current;
-    try {
-        current = await lstat(socketPath);
-    }
-    catch {
-        throw controlTransportError("UNSAFE_SOCKET_TARGET");
-    }
-    if (!current.isSocket() || !sameIdentity(current, identity)) {
-        throw controlTransportError("UNSAFE_SOCKET_TARGET");
-    }
-    try {
-        await unlink(socketPath);
-    }
-    catch {
-        throw controlTransportError("UNSAFE_SOCKET_TARGET");
-    }
-}
-async function closeNativeServer(server) {
-    await new Promise((resolve) => {
-        try {
-            server.close(() => resolve());
-        }
-        catch {
-            resolve();
-        }
-    });
-}
-async function removeOwnedSocket(socketPath, identity) {
-    let current;
-    try {
-        current = await optionalLstat(socketPath);
-    }
-    catch {
-        return;
-    }
-    if (!current)
-        return;
-    if (!current.isSocket() || !sameIdentity(current, identity))
-        return;
-    try {
-        await unlink(socketPath);
-    }
-    catch {
-        // Never broaden cleanup to a replacement path.
-    }
-}
-async function protectSocketReplacement(socketPath, identity) {
-    let current;
-    try {
-        current = await optionalLstat(socketPath);
-    }
-    catch {
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-    if (!current || sameIdentity(current, identity))
-        return undefined;
-    let directory;
-    try {
-        directory = await mkdtemp(path.join(path.dirname(socketPath), ".gateway-control-close-"));
-    }
-    catch {
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-    const backupPath = path.join(directory, "replacement");
-    try {
-        await rename(socketPath, backupPath);
-    }
-    catch (error) {
-        await rmdir(directory).catch(() => undefined);
-        if (error.code === "ENOENT")
-            return undefined;
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-    return { directory, backupPath };
-}
-async function restoreSocketReplacement(socketPath, replacement) {
-    if (!replacement)
-        return;
-    let current;
-    try {
-        current = await optionalLstat(socketPath);
-    }
-    catch {
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-    if (current) {
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-    try {
-        await rename(replacement.backupPath, socketPath);
-        await rmdir(replacement.directory);
-    }
-    catch {
-        throw controlTransportError("SOCKET_CLEANUP_CONFLICT");
-    }
-}
-export async function startGatewayControlServer(options) {
-    await validateSocketLocation(options.stateDir, options.socketPath);
-    await prepareSocketTarget(options.socketPath);
-    const requestTimeoutMs = options.requestTimeoutMs ?? GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS;
-    if (!Number.isInteger(requestTimeoutMs) ||
-        requestTimeoutMs < 50 ||
-        requestTimeoutMs > 30_000) {
-        throw controlTransportError("INVALID_SOCKET_PATH");
-    }
-    const connections = new Set();
-    const server = net.createServer({ allowHalfOpen: true }, (socket) => {
-        if (connections.size >= GATEWAY_CONTROL_MAX_CONNECTIONS) {
-            socket.once("error", () => socket.destroy());
-            socket.end(serializeResponse(errorResponse("SERVER_BUSY")), () => socket.destroy());
-            return;
-        }
-        connections.add(socket);
-        socket.once("close", () => connections.delete(socket));
-        handleConnection(socket, options.handlers, requestTimeoutMs);
-    });
-    try {
-        await new Promise((resolve, reject) => {
-            const onError = () => reject(controlTransportError("SOCKET_BIND_FAILED"));
-            server.once("error", onError);
-            server.listen(options.socketPath, () => {
-                server.off("error", onError);
-                resolve();
-            });
-        });
-    }
-    catch (error) {
-        await closeNativeServer(server);
-        throw error;
-    }
-    let identity;
-    try {
-        const info = await lstat(options.socketPath);
-        if (!info.isSocket())
-            throw new Error("not a socket");
-        identity = { dev: info.dev, ino: info.ino };
-        await chmod(options.socketPath, 0o600);
-        const secured = await lstat(options.socketPath);
-        if (!secured.isSocket() ||
-            !sameIdentity(secured, identity) ||
-            (secured.mode & 0o777) !== 0o600) {
-            throw new Error("socket identity changed");
-        }
-    }
-    catch {
-        for (const socket of connections)
-            socket.destroy();
-        await closeNativeServer(server);
-        if (identity)
-            await removeOwnedSocket(options.socketPath, identity);
-        throw controlTransportError("SOCKET_PERMISSION_FAILED");
-    }
-    const ownedIdentity = identity;
-    let closed = false;
-    let closePromise;
-    const close = () => {
-        closePromise ??= (async () => {
-            const replacement = await protectSocketReplacement(options.socketPath, ownedIdentity);
-            for (const socket of connections)
-                socket.destroy();
-            await closeNativeServer(server);
-            await removeOwnedSocket(options.socketPath, ownedIdentity);
-            await restoreSocketReplacement(options.socketPath, replacement);
-            closed = true;
-        })();
-        return closePromise;
-    };
-    return {
-        socketPath: options.socketPath,
-        get closed() {
-            return closed;
-        },
-        close,
-    };
-}
-function decodeResponse(method, params, value) {
-    if (!isRecord(value) || !Number.isSafeInteger(value.protocolVersion))
-        throw controlTransportError("CONTROL_INVALID_RESPONSE");
-    if (value.protocolVersion !== GATEWAY_CONTROL_PROTOCOL_VERSION)
-        throw controlTransportError("CONTROL_VERSION_MISMATCH");
-    if (value.ok === false) {
-        if (!shape(value, { protocolVersion: oneOf(GATEWAY_CONTROL_PROTOCOL_VERSION), ok: oneOf(false), error: (item) => shape(item, { code: (code) => typeof code === "string" && Object.hasOwn(WIRE_ERROR_MESSAGES, code),
-                message: (message) => typeof message === "string" }) }) ||
-            !isRecord(value.error) || value.error.message !== WIRE_ERROR_MESSAGES[value.error.code])
-            throw controlTransportError("CONTROL_INVALID_RESPONSE");
-        return value;
-    }
-    if (!shape(value, { protocolVersion: oneOf(GATEWAY_CONTROL_PROTOCOL_VERSION), ok: oneOf(true), result: descriptors[method].result }))
-        throw controlTransportError("CONTROL_INVALID_RESPONSE");
-    if (method === "register_peer" && isRecord(value.result) && value.result.accepted === true &&
-        Object.hasOwn(params, "token") === Object.hasOwn(value.result, "token"))
-        throw controlTransportError("CONTROL_INVALID_RESPONSE");
-    if (method === "await_peer" && isRecord(value.result) && value.result.state === "message" &&
-        JSON.parse(value.result.frame).result.toAlias !==
-            params.alias)
-        throw controlTransportError("CONTROL_INVALID_RESPONSE");
-    return value;
-}
-export async function sendGatewayControlRequest(options) {
-    assertSocketPath(options.socketPath);
-    const timeout = options.timeoutMs ?? GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS;
-    const maximum = options.maxResponseBytes ?? GATEWAY_CONTROL_MAX_RESPONSE_BYTES;
-    if (!Number.isInteger(timeout) || timeout < 50 || timeout > 90_000 ||
-        !Number.isInteger(maximum) || maximum < 256 || maximum > GATEWAY_CONTROL_MAX_RESPONSE_BYTES)
-        throw controlTransportError("CONTROL_INVALID_RESPONSE");
-    const request = parseRequestObject(options.request);
-    const frame = Buffer.from(`${JSON.stringify(request)}\n`, "utf8");
-    if (frame.length > GATEWAY_CONTROL_MAX_FRAME_BYTES)
-        throw new ProtocolFault("FRAME_TOO_LARGE");
-    return await new Promise((resolve, reject) => {
-        const socket = net.createConnection(options.socketPath);
-        let settled = false;
-        let writeStarted = false;
-        const mutation = descriptors[request.method].mutation;
-        const fail = (error) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            reject(mutation && writeStarted ? controlTransportError("CONTROL_OUTCOME_AMBIGUOUS", true) : error);
-        };
-        socket.setTimeout(timeout);
-        socket.once("connect", () => { writeStarted = true; socket.write(frame); });
-        void readOneFrame(socket, maximum).then((responseFrame) => {
-            try {
-                const response = decodeResponse(options.request.method, request.params, decodeJson(responseFrame, "INVALID_JSON"));
-                if (!settled) {
-                    settled = true;
-                    socket.destroy();
-                    resolve(response);
-                }
-            }
-            catch (error) {
-                fail(error instanceof GatewayControlTransportError
-                    ? error : controlTransportError("CONTROL_INVALID_RESPONSE"));
-            }
-        }, (error) => {
-            const kind = error instanceof FrameFault ? error.kind : "error";
-            const systemCode = !writeStarted && error instanceof FrameFault ? error.systemCode : undefined;
-            const code = kind === "timeout" ? "CONTROL_TIMEOUT" :
-                kind === "too_large" ? "CONTROL_RESPONSE_TOO_LARGE" :
-                    kind === "closed" ? "CONTROL_CONNECTION_CLOSED" :
-                        systemCode === "EPERM" || systemCode === "EACCES"
-                            ? "CONTROL_CONNECT_DENIED" : systemCode === "ENOENT"
-                            ? "CONTROL_SOCKET_MISSING" : systemCode === "ECONNREFUSED"
-                            ? "CONTROL_LISTENER_UNAVAILABLE" : "CONTROL_CONNECT_FAILED";
-            fail(controlTransportError(code));
-        });
-    });
-}
-//# sourceMappingURL=control.js.map