agent-embassy 1.0.0

package/dist/src/gateway/claude-helper.js

@@ -0,0 +1,269 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BridgeError } from "../errors.js";
+import { assertClaudeNativeHelperIpcSize, CLAUDE_NATIVE_HELPER_MAX_REQUESTS, CLAUDE_NATIVE_HELPER_PROTOCOL_VERSION, isClaudeNativeHelperParentMessage, } from "./claude-helper-protocol.js";
+import { createLocalClaudeGatewayProvider, } from "./providers.js";
+function sendChildMessage(value) {
+    assertClaudeNativeHelperIpcSize(value);
+    if (process.send === undefined || !process.connected) {
+        return Promise.reject(new Error("CLAUDE_NATIVE_HELPER_PARENT_GONE"));
+    }
+    return new Promise((resolve, reject) => {
+        process.send(value, undefined, {}, (error) => {
+            if (error === null)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+}
+function safeCode(error) {
+    if (error instanceof BridgeError &&
+        /^[A-Z][A-Z0-9_]{0,95}$/.test(error.code)) {
+        return { code: error.code, recoverable: error.recoverable };
+    }
+    return { code: "CLAUDE_NATIVE_HELPER_OPERATION_FAILED", recoverable: false };
+}
+function okResult() {
+    return { ok: true };
+}
+export async function runClaudeNativeHelperProcess() {
+    if (process.send === undefined)
+        return;
+    let provider;
+    let initialized = false;
+    let closing = false;
+    let admitted = 0;
+    let operation = Promise.resolve();
+    let sendOperation = Promise.resolve();
+    const queueSend = (message) => {
+        const queued = sendOperation.then(async () => await sendChildMessage(message));
+        sendOperation = queued.catch(() => undefined);
+        return queued;
+    };
+    const event = (value) => {
+        void queueSend({
+            protocolVersion: CLAUDE_NATIVE_HELPER_PROTOCOL_VERSION,
+            type: "event",
+            value,
+        }).catch(() => void shutdown());
+    };
+    const callbacks = {
+        onDelivery: (value) => event({ event: "delivery", value: { ...value } }),
+        onRouteState: () => undefined,
+        onClaudeReply: (value) => event({
+            event: "claude_reply",
+            value: {
+                routeHandle: value.endpoint.routeHandle,
+                text: value.text,
+            },
+        }),
+        onClaudeMessage: (value) => event({
+            event: "claude_message",
+            value: {
+                routeHandle: value.endpoint.routeHandle,
+                sourceAlias: value.sourceAlias,
+                targetAlias: value.targetAlias,
+                text: value.text,
+                ...(value.receiptHandle === undefined
+                    ? {}
+                    : { receiptHandle: value.receiptHandle }),
+            },
+        }),
+        onProtocolNotice: (value) => event({ event: "protocol_notice", value: { code: value.code } }),
+    };
+    const respond = async (requestId, result) => {
+        await queueSend({
+            protocolVersion: CLAUDE_NATIVE_HELPER_PROTOCOL_VERSION,
+            type: "response",
+            requestId,
+            ok: true,
+            result,
+        });
+    };
+    const reject = async (requestId, error) => {
+        await queueSend({
+            protocolVersion: CLAUDE_NATIVE_HELPER_PROTOCOL_VERSION,
+            type: "response",
+            requestId,
+            ok: false,
+            error: safeCode(error),
+        });
+    };
+    const initialize = async (message) => {
+        if (initialized || provider !== undefined) {
+            throw new BridgeError("CLAUDE_NATIVE_HELPER_ALREADY_INITIALIZED", "The native helper accepts exactly one immutable initialization.");
+        }
+        const created = createLocalClaudeGatewayProvider({
+            runtime: message.runtime,
+            hostId: message.hostId,
+            locale: message.locale,
+            deliveryNotices: message.deliveryNotices,
+            maxPendingMessages: message.maxPendingMessages,
+        });
+        provider = created;
+        try {
+            await created.initialize(callbacks);
+            const generation = created.currentUnadvertisedNativeCodexPeerGeneration();
+            await created.quiesceNativeCodexPeerGeneration(generation);
+            await created.advertiseNativeCodexPeer(message.registration);
+            initialized = true;
+            return { generation };
+        }
+        catch (error) {
+            await created.close().catch(() => undefined);
+            provider = undefined;
+            throw error;
+        }
+    };
+    const execute = async (command) => {
+        const active = provider;
+        if (!initialized || active === undefined) {
+            throw new BridgeError("CLAUDE_NATIVE_HELPER_NOT_INITIALIZED", "The native helper has not established its immutable registration.");
+        }
+        switch (command.method) {
+            case "resume_generation":
+                await active.resumeNativeCodexPeerGeneration(command.generation);
+                return okResult();
+            case "authorize_route": {
+                const snapshot = await active.discoverClaudePeers();
+                const peer = snapshot.peers.find((candidate) => candidate.routeHandle === command.routeHandle &&
+                    candidate.alias === command.alias);
+                if (peer === undefined) {
+                    throw new BridgeError("CLAUDE_ROUTE_MISMATCH", "The helper could not prove the exact selected Claude route.", true);
+                }
+                await active.assertWorkspaceDisjoint(command.routeHandle, command.stateRoot);
+                await active.selectRoute({
+                    alias: command.alias,
+                    routeHandle: command.routeHandle,
+                });
+                return okResult();
+            }
+            case "release_route":
+                await active.releaseRoute(command.routeHandle);
+                return okResult();
+            case "dispatch":
+                return await active.dispatch(command);
+            case "update_inbound_status":
+                await active.updateNativeInboundStatus(command.receiptHandle, command.status, command.diagnosticCode);
+                return okResult();
+            case "notify_inbound_progress":
+                await active.notifyNativeInboundProgress(command.receiptHandle, command.progress);
+                return okResult();
+            case "release_inbound_receipt":
+                return {
+                    released: await active.releaseNativeInboundReceipt(command.receiptHandle),
+                };
+            case "update_status":
+                await active.updateNativeCodexPeerStatus(command.alias, command.status);
+                return okResult();
+            case "unadvertise":
+                await active.unadvertiseNativeCodexPeer(command.alias);
+                return okResult();
+            case "quiesce_generation":
+                await active.quiesceNativeCodexPeerGeneration(command.generation);
+                return okResult();
+            case "observe_barrier":
+                return await active.observeNativeCodexSuccessionBarrier(command.generation);
+            case "prepare_generation":
+                await active.prepareNativeCodexPeerGeneration({
+                    alias: command.alias,
+                    cwd: command.cwd,
+                    generation: command.generation,
+                });
+                return okResult();
+            case "publish_prepared":
+                return {
+                    publication: await active.publishPreparedNativeCodexPeer({
+                        currentGeneration: command.currentGeneration,
+                        preparedGeneration: command.preparedGeneration,
+                    }),
+                };
+            case "activate_prepared":
+                await active.activatePreparedNativeCodexPeerGeneration(command.generation);
+                return okResult();
+            case "cleanup_prepared":
+                await active.cleanupPreparedNativeCodexPeerGeneration(command.generation);
+                return okResult();
+            case "rollback_prepared":
+                await active.rollbackPreparedNativeCodexPeerGeneration({
+                    preparedGeneration: command.preparedGeneration,
+                    resumeGeneration: command.resumeGeneration,
+                });
+                return okResult();
+            case "retire_generation":
+                await active.retireNativeCodexPeerGeneration({
+                    retiredGeneration: command.retiredGeneration,
+                    protectedActiveGeneration: command.protectedActiveGeneration,
+                });
+                return okResult();
+            case "purge_generation_replies":
+                return {
+                    purged: await active.purgeNativeCodexPeerGenerationReplyCapabilities(command.generation),
+                };
+            case "close":
+                await active.close();
+                return okResult();
+        }
+    };
+    const shutdown = async () => {
+        if (closing)
+            return;
+        closing = true;
+        const current = provider;
+        provider = undefined;
+        if (current !== undefined)
+            await current.close().catch(() => undefined);
+        if (process.connected)
+            process.disconnect();
+        setImmediate(() => process.exit(0));
+    };
+    process.on("disconnect", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+    process.on("SIGINT", () => void shutdown());
+    process.on("message", (value) => {
+        if (closing)
+            return;
+        try {
+            assertClaudeNativeHelperIpcSize(value);
+            if (!isClaudeNativeHelperParentMessage(value)) {
+                throw new Error("CLAUDE_NATIVE_HELPER_PROTOCOL_INVALID");
+            }
+        }
+        catch {
+            void shutdown();
+            return;
+        }
+        if (admitted >= CLAUDE_NATIVE_HELPER_MAX_REQUESTS) {
+            void shutdown();
+            return;
+        }
+        admitted += 1;
+        operation = operation
+            .then(async () => {
+            try {
+                const result = value.type === "initialize"
+                    ? await initialize(value)
+                    : await execute(value.command);
+                await respond(value.requestId, result);
+                if (value.type === "request" && value.command.method === "close") {
+                    await shutdown();
+                }
+            }
+            catch (error) {
+                await reject(value.requestId, error).catch(() => undefined);
+                if (value.type === "initialize")
+                    await shutdown();
+            }
+        })
+            .finally(() => {
+            admitted -= 1;
+        });
+    });
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined &&
+    path.resolve(invokedPath) === fileURLToPath(import.meta.url)) {
+    void runClaudeNativeHelperProcess();
+}
+//# sourceMappingURL=claude-helper.js.map

package/dist/src/gateway/claude-helper.js.map

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

package/dist/src/gateway/claude-peer.d.ts

@@ -0,0 +1,273 @@
+import { type Socket } from "node:net";
+import type { GatewayDeliveryNoticeMode } from "./config.js";
+import { type DashboardLocale } from "./locale.js";
+/**
+ * This adapter intentionally pins the inspected, implementation-specific
+ * local peer boundary. The feature is documented in Claude Code, but its
+ * registry and NDJSON formats are not a stable public integration contract.
+ */
+export declare const CLAUDE_PEER_COMPATIBILITY: Readonly<{
+    claudeCodeVersion: "2.1.226";
+    peerProtocol: 1;
+    messageVersion: 1;
+}>;
+/** Live peer records may outlive a same-protocol Claude Code upgrade. */
+export declare const CLAUDE_PEER_COMPATIBLE_SESSION_VERSIONS: readonly ["2.1.224", "2.1.225", "2.1.226"];
+export declare const claudePeerStatuses: readonly ["busy", "shell", "idle", "waiting"];
+export type ClaudePeerStatus = (typeof claudePeerStatuses)[number];
+export declare const claudePeerKinds: readonly ["interactive", "bg", "daemon", "daemon-worker"];
+export type ClaudePeerKind = (typeof claudePeerKinds)[number];
+export declare const claudePeerRejectionCodes: readonly ["ENTRY_LIMIT_EXCEEDED", "INVALID_FILE_NAME", "REGISTRY_NOT_REGULAR", "REGISTRY_OWNER_MISMATCH", "REGISTRY_MODE_UNSAFE", "REGISTRY_TOO_LARGE", "REGISTRY_RACED", "REGISTRY_INVALID_JSON", "REGISTRY_INVALID_SCHEMA", "PID_MISMATCH", "PID_NOT_LIVE", "PID_OWNER_MISMATCH", "SOCKET_OUTSIDE_ROOT", "SOCKET_NOT_SOCKET", "SOCKET_OWNER_MISMATCH", "SOCKET_MODE_UNSAFE", "SELF_TARGET", "SESSION_ID_COLLISION"];
+export type ClaudePeerRejectionCode = (typeof claudePeerRejectionCodes)[number];
+export type ClaudePeerDescriptor = {
+    /** Claude's stable logical session UUID. Names and sockets are not identity. */
+    targetId: string;
+    alias: string;
+    kind: ClaudePeerKind;
+    status: ClaudePeerStatus;
+    compatibility: "compatible";
+};
+export type ClaudePeerDiscovery = {
+    peers: ClaudePeerDescriptor[];
+    rejected: Partial<Record<ClaudePeerRejectionCode, number>>;
+    truncated: boolean;
+    /** Bounded registry entries examined, including safely skipped records. */
+    entriesScanned: number;
+    /** Records whose closed wire schema parsed before later liveness checks. */
+    parseableRecords: number;
+};
+export type ClaudePeerTransportStatus = "connecting" | "write_started" | "transport_written" | "ambiguous" | "not_written";
+export type ClaudePeerReceiptStatus = "held"
+/** Native `delivered`: approval released the frame to Claude's queue. */
+ | "released" | "denied" | "expired" | "unconfirmed" | "ambiguous";
+export type ClaudePeerDeliveryDiagnostic = {
+    /** Stable, non-sensitive gateway code rendered into Claude's context. */
+    code: string;
+};
+export declare const claudePeerInboundStallReasons: readonly ["ROUTE_BUSY", "ROUTE_UNAVAILABLE", "CODEX_ROUTE_STALE", "AWAITING_EXTERNAL_APPROVAL"];
+export type ClaudePeerInboundStallReason = (typeof claudePeerInboundStallReasons)[number];
+export type ClaudePeerInboundProgress = {
+    kind: "stall";
+    reason: ClaudePeerInboundStallReason;
+    queuedForMs: number;
+};
+export type ClaudePeerAcknowledgmentResult = {
+    transportStatus: "transport_written" | "suppressed";
+};
+export type ClaudePeerTransportEvent = {
+    messageId: string;
+    status: ClaudePeerTransportStatus;
+};
+export type ClaudePeerReceiptEvent = {
+    messageId: string;
+    status: ClaudePeerReceiptStatus;
+    trust: "untrusted_same_uid_peer";
+};
+export type ClaudePeerInboundMessage = {
+    inboundId: string;
+    content: string;
+    /** Validated connect-back capability, not proof of the connecting PID. */
+    sourceTargetId?: string;
+    /** Display label from that capability; never an authority. */
+    sourceAlias?: string;
+    /** Opaque listener-owned handle for native held/delivered status updates. */
+    receiptHandle?: string;
+    replySupported: boolean;
+    trust: "untrusted_same_uid_peer" | "untrusted_anonymous_local_peer";
+};
+export type ClaudePeerProtocolNotice = {
+    code: "FRAME_TOO_LARGE" | "INVALID_UTF8" | "INVALID_FRAME" | "UNSUPPORTED_FRAME" | "UNREGISTERED_REPLY_ADDRESS" | "UNKNOWN_RECEIPT" | "INVALID_RECEIPT_TRANSITION" | "RECEIPT_LIMIT" | "CONNECTION_LIMIT" | "CONNECTION_TIMEOUT" | "CALLBACK_ERROR";
+};
+export type ClaudeProcessIdentity = {
+    uid: number;
+    /** Stable only for the lifetime of this process, such as ps(1) lstart. */
+    generation: string;
+};
+export type ClaudeProcessInspector = (pid: number) => Promise<ClaudeProcessIdentity | undefined>;
+export type ClaudePeerConnect = (socketPath: string) => Socket;
+export type ClaudePeerAdapterOptions = {
+    sessionsDir: string;
+    socketDir: string;
+    /** Exact version attested by the trusted launcher, never user input. */
+    attestedClaudeCodeVersion: string;
+    /** Locale for bounded user-visible gateway notices written to Claude. */
+    locale?: DashboardLocale;
+    /** Gateway-authored user-frame policy; native status frames are unaffected. */
+    deliveryNotices?: GatewayDeliveryNoticeMode;
+    maxRegistryEntries?: number;
+    maxRegistryBytes?: number;
+    maxFrameBytes?: number;
+    targetLeaseMs?: number;
+    connectTimeoutMs?: number;
+    receiptDeadlineMs?: number;
+    maxPendingReceipts?: number;
+    maxConnections?: number;
+    connectionIdleMs?: number;
+    maxFramesPerConnection?: number;
+};
+/** Dependency seams for deterministic tests; never populate from config. */
+export type ClaudePeerAdapterTestOverrides = {
+    processInspector?: ClaudeProcessInspector;
+    connect?: ClaudePeerConnect;
+    now?: () => number;
+    createId?: () => string;
+    /** Separate from protocol/message UUID generation so lifecycle tests cannot alias it. */
+    createGeneration?: () => string;
+    registryRename?: (source: string, destination: string) => Promise<void>;
+    registryOperationHook?: (event: {
+        operation: "advertise" | "publish" | "status" | "unadvertise";
+        phase: "entered" | "exited";
+        generation: string;
+    }) => void | Promise<void>;
+    userHome?: string;
+    tempRoots?: readonly string[];
+    registryPublicationHook?: (stage: "before_rename" | "after_rename") => void | Promise<void>;
+};
+export type ClaudePeerRegistryPublicationOutcome = "published" | "not_published" | "unknown";
+export type ClaudePeerListenerOptions = {
+    onMessage: (message: ClaudePeerInboundMessage) => void | Promise<void>;
+    onReceipt?: (event: ClaudePeerReceiptEvent) => void | Promise<void>;
+    onProtocolNotice?: (notice: ClaudePeerProtocolNotice) => void | Promise<void>;
+};
+export type ClaudePeerSendOptions = {
+    listener?: ClaudePeerListener;
+    /** Exact gateway message deadline as an epoch-millisecond timestamp. */
+    receiptDeadlineAt?: number;
+    onTransportStatus?: (event: ClaudePeerTransportEvent) => void | Promise<void>;
+};
+export type ClaudePeerSendResult = {
+    messageId: string;
+    transportStatus: "transport_written";
+    receiptStatus: "pending" | "unavailable";
+};
+type FileGeneration = {
+    dev: number;
+    ino: number;
+    size: number;
+    mtimeMs: number;
+};
+type SocketGeneration = {
+    dev: number;
+    ino: number;
+};
+type ParsedRegistryRecord = {
+    pid: number;
+    sessionId: string;
+    cwd: string;
+    peerProtocol: 1;
+    kind: ClaudePeerKind;
+    messagingSocketPath: string;
+    name: string;
+    status: ClaudePeerStatus;
+};
+type TargetBinding = {
+    targetId: string;
+    alias: string;
+    registryPath: string;
+    registryGeneration: FileGeneration;
+    socketGeneration: SocketGeneration;
+    record: ParsedRegistryRecord;
+    processGeneration: string;
+    expiresAt: number;
+};
+type AdapterLimits = {
+    maxRegistryEntries: number;
+    maxRegistryBytes: number;
+    maxFrameBytes: number;
+    targetLeaseMs: number;
+    connectTimeoutMs: number;
+    receiptDeadlineMs: number;
+    maxPendingReceipts: number;
+    maxConnections: number;
+    connectionIdleMs: number;
+    maxFramesPerConnection: number;
+};
+export declare function encodeClaudePeerUserFrame(input: {
+    messageId: string;
+    content: string;
+    from?: string;
+    maxFrameBytes?: number;
+}): Buffer;
+export declare class ClaudePeerAdapter {
+    #private;
+    constructor(options: ClaudePeerAdapterOptions, testing?: ClaudePeerAdapterTestOverrides);
+    discover(): Promise<ClaudePeerDiscovery>;
+    /**
+     * Required selection gate. It reveals no workspace data and binds the
+     * opaque target to one canonical controller state root for later sends.
+     */
+    assertTargetWorkspaceDisjoint(targetId: string, controllerStateRoot: string): Promise<void>;
+    /**
+     * Converts a transient CLAUDE_CODE_MESSAGING_SOCKET-style address into the
+     * owning logical Claude session UUID. Callers discard the socket address;
+     * every later delivery resolves the UUID to fresh transport coordinates.
+     */
+    resolveReplyAddress(address: string): Promise<ClaudePeerDescriptor>;
+    listen(options: ClaudePeerListenerOptions): Promise<ClaudePeerListener>;
+    listenPrepared(generation: string, options: ClaudePeerListenerOptions): Promise<ClaudePeerListener>;
+    send(targetId: string, content: string, options?: ClaudePeerSendOptions): Promise<ClaudePeerSendResult>;
+    close(): Promise<void>;
+}
+type ListenerCreateOptions = {
+    sessionsDir: string;
+    socketDir: string;
+    expectedUid: number;
+    limits: AdapterLimits;
+    createId: () => string;
+    connect: ClaudePeerConnect;
+    now: () => number;
+    locale: DashboardLocale;
+    deliveryNotices: GatewayDeliveryNoticeMode;
+    attestedClaudeCodeVersion: string;
+    resolveReplyAddress: (address: string) => Promise<TargetBinding>;
+    resolveSessionBinding: (sessionId: string) => Promise<TargetBinding>;
+    revalidateBinding: (binding: TargetBinding) => Promise<TargetBinding>;
+    options: ClaudePeerListenerOptions;
+    owner: object;
+    generation: string;
+    registryRename: (source: string, destination: string) => Promise<void>;
+    registryOperationHook?: ClaudePeerAdapterTestOverrides["registryOperationHook"];
+    runRegistryMutation: <T>(operation: () => Promise<T>) => Promise<T>;
+    preparedGeneration?: string;
+    registryPublicationHook?: (stage: "before_rename" | "after_rename") => void | Promise<void>;
+    onClosed: () => void;
+};
+export declare class ClaudePeerListener {
+    #private;
+    readonly address: string;
+    readonly generation: string;
+    private constructor();
+    static create(options: ListenerCreateOptions): Promise<ClaudePeerListener>;
+    get closed(): boolean;
+    advertise(name: string, cwd: string): Promise<void>;
+    publishReplacing(current: ClaudePeerListener, name: string, cwd: string): Promise<ClaudePeerRegistryPublicationOutcome>;
+    updateAdvertisedStatus(status: ClaudePeerStatus): Promise<void>;
+    unadvertise(name?: string): Promise<void>;
+    grantSuccessionActivation(): void;
+    resumeInbound(): void;
+    acknowledge(receiptHandle: string, status: "held" | "delivered" | "denied" | "expired", diagnostic?: ClaudePeerDeliveryDiagnostic): Promise<ClaudePeerAcknowledgmentResult>;
+    /**
+     * Writes one nonterminal gateway progress frame without synthesizing a
+     * native peer_message_status transition. The receipt remains available for
+     * its later exact terminal acknowledgement or explicit release.
+     */
+    notifyInboundProgress(receiptHandle: string, progress: ClaudePeerInboundProgress): Promise<ClaudePeerAcknowledgmentResult>;
+    /**
+     * Releases a listener-owned native receipt capability without writing to the
+     * peer. The service uses this after a terminal notification becomes
+     * definitively undeliverable so bounded receipt capacity cannot leak.
+     */
+    releaseInboundReceipt(receiptHandle: string): boolean;
+    /**
+     * Stop admitting new user-message frames while keeping the listener alive
+     * for terminal receipt writes. The promise joins every frame already
+     * admitted, so controller shutdown can drain service receipt work before
+     * closing the provider socket.
+     */
+    quiesceInbound(): Promise<void>;
+    track(messageId: string, binding: TargetBinding, receiptDeadlineAt?: number): void;
+    recordTransportOutcome(messageId: string, outcome: "transport_written" | "transport_uncertain"): void;
+    untrack(messageId: string): void;
+    close(): Promise<void>;
+}
+export {};