agent-embassy 1.0.0

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

@@ -0,0 +1,449 @@
+import type { GatewayConfig } from "./config.js";
+import { type CompatibilityAttestation, type CompatibilityCertification, type CompatibilityCertificationReport, type CompatibilityCheckReport, type CompatibilityProbeResult, type CompatibilitySurfaceObservation } from "./compatibility.js";
+import { type GatewayControlHandlers, type GatewaySnapshotObservation } from "./control.js";
+import { publishGatewayDashboard } from "./dashboard.js";
+import { GatewayStore } from "./store.js";
+import { type CompatibilityState, type GatewayPublicSnapshot, type PrivateEndpointIdentity, type PrivateRouteBinding, type RouteState } from "./types.js";
+export type GatewayAdapterRouteState = Extract<RouteState, "idle" | "busy" | "awaiting_approval">;
+export type GatewayAdapterRouteObservationState = GatewayAdapterRouteState | "stale";
+export type GatewayAdapterDiscovery = {
+    /** Canonical public alias. The service never lowercases or truncates it. */
+    alias: string;
+    /** Stable provider identity; for Claude this is its native session UUID. */
+    routeHandle: string;
+    kind: "interactive";
+    state: GatewayAdapterRouteState;
+    compatibility: "compatible";
+};
+/**
+ * One bounded discovery pass. `complete` is false when the provider stopped
+ * before it could inspect the full registry; such a pass may be displayed but
+ * cannot authorize selection restoration.
+ */
+export type GatewayAdapterDiscoverySnapshot = {
+    peers: readonly GatewayAdapterDiscovery[];
+    complete: boolean;
+};
+export type GatewayAdapterDeliveryState = "transport_uncertain" | "transport_written" | "held" | "released" | "unconfirmed" | "denied" | "expired" | "ambiguous" | "completed" | "failed" | "cancelled";
+export type GatewayAdapterDelivery = {
+    messageId: string;
+    state: GatewayAdapterDeliveryState;
+    safeErrorCode?: string;
+    /** Transient, bounded by the adapter. Never copied into normalized state. */
+    replyText?: string;
+};
+export type GatewayAdapterCallbacks = {
+    onDelivery: (event: GatewayAdapterDelivery) => void;
+    onRouteState: (event: {
+        endpoint: PrivateEndpointIdentity & {
+            routeHandle: string;
+        };
+        state: GatewayAdapterRouteObservationState;
+        safeErrorCode?: string;
+    }) => void;
+    /** A callback user frame has no conversation ID; correlation is service-owned. */
+    onClaudeReply: (event: {
+        endpoint: PrivateEndpointIdentity & {
+            routeHandle: string;
+        };
+        text: string;
+    }) => void;
+    onClaudeMessage?: (event: {
+        endpoint: PrivateEndpointIdentity & {
+            routeHandle: string;
+        };
+        sourceAlias: string;
+        targetAlias: string;
+        text: string;
+        receiptHandle?: string;
+    }) => void;
+    /** Bounded provider protocol diagnostics; never includes raw frame data. */
+    onProtocolNotice?: (event: {
+        code: string;
+    }) => void;
+};
+export type GatewayAdapterStart = {
+    health: "healthy" | "degraded";
+    compatibility: CompatibilityState;
+    safeErrorCode?: string;
+};
+export type GatewayAdapterDispatchResult = {
+    state: "pending";
+}
+/** Provider accepted the turn, but its final result/reply remains pending. */
+ | {
+    state: "accepted";
+} | {
+    state: "deferred";
+    safeErrorCode?: string;
+} | {
+    state: "delivered" | "failed" | "ambiguous" | "cancelled";
+    safeErrorCode?: string;
+    replyText?: string;
+};
+/**
+ * Narrow provider boundary. Production adapters wrap ClaudePeerAdapter or one
+ * exact CodexAppServerConnector; tests use in-memory fakes. Implementations
+ * must never retry a dispatch after a write may have occurred.
+ */
+export interface GatewayProviderAdapter {
+    readonly identity: PrivateEndpointIdentity;
+    readonly protocol: string;
+    readonly protocolVersion: string;
+    /** Version identity is cheap; probes are invoked only on a cache miss. */
+    compatibilitySurface?(): CompatibilitySurfaceObservation;
+    runCompatibilityProbes?(): Promise<readonly CompatibilityProbeResult[]>;
+    acceptCompatibilityAttestation?(attestation: CompatibilityAttestation): void;
+    runCompatibilityCertification?(input: Readonly<{
+        controllerStateRoot: string;
+        routeHandle?: string;
+        withTurn: boolean;
+    }>): Promise<CompatibilityCertification>;
+    initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
+    discoverClaudePeers?(): Promise<GatewayAdapterDiscoverySnapshot>;
+    selectRoute(input: {
+        alias: string;
+        routeHandle: string;
+    }): Promise<{
+        routeHandle: string;
+        state: GatewayAdapterRouteState;
+    }>;
+    /** Claude-only workspace guard. Codex registration has no workspace gate. */
+    assertWorkspaceDisjoint?(routeHandle: string, stateRoot: string): Promise<void>;
+    /** Converts a UDS connect-back capability to an exact already-observed handle. */
+    resolveReplyAddress?(address: string): Promise<{
+        routeHandle: string;
+    }>;
+    advertiseNativeCodexPeer?(input: {
+        alias: string;
+        cwd: string;
+    }): Promise<void>;
+    unadvertiseNativeCodexPeer?(alias: string): Promise<void>;
+    updateNativeCodexPeerStatus?(alias: string, status: "idle" | "busy" | "waiting"): Promise<void>;
+    updateNativeInboundStatus?(receiptHandle: string, status: "held" | "delivered" | "denied" | "expired", diagnosticCode?: string): Promise<void>;
+    notifyNativeInboundProgress?(receiptHandle: string, progress: {
+        kind: "stall";
+        reason: "ROUTE_BUSY" | "ROUTE_UNAVAILABLE" | "CODEX_ROUTE_STALE" | "AWAITING_EXTERNAL_APPROVAL";
+        queuedForMs: number;
+    }): Promise<void>;
+    releaseNativeInboundReceipt?(receiptHandle: string): boolean | Promise<boolean>;
+    /** Fence new native ingress while keeping receipt writes available. */
+    quiesceNativeInbound?(): Promise<void>;
+    /** Claude-only exact listener-generation succession controls. */
+    currentNativeCodexPeerGeneration?(alias: string): string;
+    prepareNativeCodexPeerGeneration?(input: {
+        alias: string;
+        cwd: string;
+        generation: string;
+        currentGeneration?: string;
+    }): Promise<void>;
+    quiesceNativeCodexPeerGeneration?(generation: string): Promise<void>;
+    observeNativeCodexSuccessionBarrier?(generation: string): Readonly<{
+        generation: string;
+        activeGenerationMatched: boolean;
+        ingressQuiesced: boolean;
+        monitorFrozen: boolean;
+        discoveryInFlight: boolean;
+        pendingOutboundReceipts: number;
+        pendingInboundReceipts: number;
+        rejectedInboundSettlements: number;
+        clean: boolean;
+    }> | Promise<Readonly<{
+        generation: string;
+        activeGenerationMatched: boolean;
+        ingressQuiesced: boolean;
+        monitorFrozen: boolean;
+        discoveryInFlight: boolean;
+        pendingOutboundReceipts: number;
+        pendingInboundReceipts: number;
+        rejectedInboundSettlements: number;
+        clean: boolean;
+    }>>;
+    publishPreparedNativeCodexPeer?(input: {
+        currentGeneration: string;
+        preparedGeneration: string;
+    }): Promise<"published" | "not_published" | "unknown">;
+    activatePreparedNativeCodexPeerGeneration?(generation: string): void | Promise<void>;
+    cleanupPreparedNativeCodexPeerGeneration?(generation: string): Promise<void>;
+    resumeNativeCodexPeerGeneration?(generation: string): void | Promise<void>;
+    rollbackPreparedNativeCodexPeerGeneration?(input: {
+        preparedGeneration: string;
+        resumeGeneration: string;
+    }): Promise<void>;
+    retireNativeCodexPeerGeneration?(input: {
+        retiredGeneration: string;
+        protectedActiveGeneration: string;
+    }): Promise<void>;
+    purgeNativeCodexPeerGenerationReplyCapabilities?(generation: string): number | Promise<number>;
+    /** Codex-only private provider-work barrier for one exact task route. */
+    observeRouteSuccessionBarrier?(routeHandle: string): Readonly<{
+        routePresent: boolean;
+        connection: string;
+        routeStatus: string;
+        queueDepth: number;
+        hasActiveTurn: boolean;
+        requestInFlight: boolean;
+        routeCreationInFlight: boolean;
+        routeReleaseInFlight: boolean;
+        pendingReplyCorrelations: number;
+        pendingCallbacks: number;
+        clean: boolean;
+    }>;
+    dispatch(input: {
+        sourceAlias: string;
+        binding: PrivateRouteBinding;
+        authorization: "selected_route" | "native_reply";
+        messageId: string;
+        text: string;
+        expectsReply: boolean;
+        deadlineAt: string;
+        steer?: true;
+    }): Promise<GatewayAdapterDispatchResult>;
+    releaseRoute?(routeHandle: string): Promise<void>;
+    close(): Promise<void>;
+}
+type GatewayServiceTimer = ReturnType<typeof setTimeout>;
+type GatewayServiceTimers = {
+    setTimeout: (callback: () => void, delayMs: number) => GatewayServiceTimer;
+    clearTimeout: (timer: GatewayServiceTimer) => void;
+};
+export type GatewayServiceOptions = {
+    config: GatewayConfig;
+    adapters?: readonly GatewayProviderAdapter[];
+    store?: GatewayStore;
+    publishDashboard?: typeof publishGatewayDashboard;
+    now?: () => Date;
+    nativePeerCwd?: string;
+    timers?: GatewayServiceTimers;
+    /** Test seam for opaque listener generations; production remains random. */
+    successionGeneration?: () => string;
+};
+export declare class GatewayService {
+    readonly config: GatewayConfig;
+    readonly store: GatewayStore;
+    private readonly adapters;
+    private readonly publishDashboard;
+    private readonly now;
+    private readonly timers;
+    private readonly nativePeerCwd;
+    private readonly successionGeneration;
+    private readonly mutex;
+    private readonly routeBindings;
+    private readonly routeStates;
+    private readonly bindingAliases;
+    private readonly candidates;
+    private availablePeers;
+    private readonly conversations;
+    private readonly messageContexts;
+    private readonly providerTurnContinuations;
+    private readonly activeDispatchByTarget;
+    private readonly scheduledDispatchTargets;
+    private readonly dispatchRunnerTargets;
+    private readonly heldRedispatchTimers;
+    private readonly pendingClaudeReplies;
+    private readonly deliveryTrackers;
+    private readonly deliveryTokens;
+    private readonly runtimeAlerts;
+    private readonly activityEvents;
+    private activitySequence;
+    private readonly detachedReceiptWrites;
+    private readonly nativeIngressByConversation;
+    private readonly callbackQueue;
+    private callbackWorker;
+    private callbackScheduled;
+    private readonly callbackCapacity;
+    private readonly deliveryCallbackReserve;
+    private readonly deliveryTokenCapacity;
+    private lifecycleTimer;
+    private nextDashboardRefreshAt;
+    private nextProgressWatchAt;
+    private control;
+    /** Coarse controller mutation revision exposed by `health`. */
+    private revision;
+    /**
+     * Process-local semantic public-snapshot clock. The first observation
+     * establishes revision zero; a new GatewayService process resets it.
+     */
+    private snapshotRevision;
+    private snapshotFingerprint;
+    private running;
+    private closing;
+    private closeInFlight;
+    private acceptingCallbacks;
+    private dashboardHealthy;
+    /** Route-scoped fences; unrelated Codex registrations remain dispatchable. */
+    private readonly codexSuccessionDispatchFrozen;
+    private readonly codexSuccessionPoisoned;
+    private codexSuccessionState;
+    private pendingCodexSuccessionRecovery;
+    /**
+     * Exact active identity. It changes only through the journaled succession
+     * machine; ordinary unregister/register cannot repurpose one listener.
+     */
+    private readonly codexRegistrationLocks;
+    constructor(options: GatewayServiceOptions);
+    start(signal?: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+    private closeOnce;
+    handlers(): GatewayControlHandlers;
+    snapshot(): Promise<GatewayPublicSnapshot>;
+    compatibilityCheck(): Promise<CompatibilityCheckReport>;
+    compatibilityCertify(params: Readonly<{
+        codexAlias?: string;
+        withTurn: boolean;
+    }>): Promise<CompatibilityCertificationReport>;
+    private compatibilityCheckLocked;
+    observeSnapshot(): Promise<GatewaySnapshotObservation>;
+    private fingerprintSnapshot;
+    private callbacksFor;
+    private enqueueCallback;
+    private enqueueCallbackWorkerOnly;
+    private drainCallbackQueueLocked;
+    private isTerminalAdapterDelivery;
+    /**
+     * Delivery evidence observed strictly before the deadline must reach the
+     * reducer before its deadline event, even when callback scheduling is late.
+     * Evidence observed at/after the cutoff cannot reopen the terminal machine.
+     */
+    private drainPreDeadlineDeliveryCallbacksLocked;
+    /**
+     * A provider may synchronously emit a terminal callback before its dispatch
+     * promise resolves to `pending`. Consume those already-retained callbacks
+     * before interpreting `pending` as successful provider acceptance, otherwise
+     * the sender can observe a false delivered result that wins the terminal
+     * race against the queued failure.
+     */
+    private drainDeliveryCallbacksForMessageLocked;
+    private adapter;
+    private assertClaudeWorkspaceDisjoint;
+    private contextTargetBinding;
+    private recoverCodexSuccessionAfterRestartLocked;
+    private completePendingCodexSuccessionRecoveryLocked;
+    private assertPendingCodexSuccessionRecoveryMatch;
+    private requireCurrentNativeCodexGeneration;
+    private nextCodexSuccessionGeneration;
+    private successionStoreIdentity;
+    private sameSuccessionStoreIdentity;
+    private reconcilePreparedCodexSuccessionAfterUnknownCommit;
+    private requireSuccessionMethod;
+    private succeedCodexRegistration;
+    private driveCodexSuccessionLocked;
+    private recoverCodexSuccessionLocked;
+    private successionNewRegistration;
+    private codexSuccessionFailurePhase;
+    private executeCodexSuccessionEffectLocked;
+    private successionOldRegistration;
+    private quiesceAndDrainPoisonedSuccessionLocked;
+    private codexRouteSuccessionQuiet;
+    private conversationTouchesAliases;
+    private successionServiceStateClean;
+    private purgeSuccessionTransientState;
+    private codexSuccessionPoisonBarrierCleanLocked;
+    private codexSuccessionBarrierCleanLocked;
+    private rescheduleIdleRoutesLocked;
+    private registerCodex;
+    private lockCodexRegistration;
+    private rollbackCodexRegistration;
+    private unregisterCodex;
+    private discoveryPublicFingerprint;
+    private refreshClaudeDiscovery;
+    private renameClaudeRoute;
+    private claudeCandidate;
+    private activatePersistedClaudeCandidate;
+    private selectClaudeCandidate;
+    private replaceClaudeSelectionCandidate;
+    private resolveSelectedClaudeDestination;
+    private inferCodexAlias;
+    private assertCodexPairCaller;
+    private pairRoutes;
+    private unpairRoutes;
+    private unpairClaudeRoute;
+    private selectClaude;
+    private selectAndPairClaude;
+    private rollbackFreshClaudeSelection;
+    private unselectClaude;
+    private selectedClaudeRoute;
+    private registerOrRebind;
+    private rememberBinding;
+    private forgetBinding;
+    private verifyCodex;
+    private verifyClaude;
+    private acceptedControlResult;
+    private reserveDeliveryToken;
+    private armDeliveryTracker;
+    private isTerminalDeliveryState;
+    private settlementDeliveryState;
+    private pruneDeliveryTrackers;
+    private addRuntimeAlert;
+    private releaseNativeReceiptLocked;
+    /**
+     * Native `held` is progress, not terminal delivery or approval. Emit it
+     * only after this exact message is known to be waiting, or after its prompt
+     * dispatch threshold elapses. A clean pre-write may retry; an ambiguous
+     * write is never replayed, and neither path consumes the terminal receipt.
+     */
+    private publishNativeHeldLocked;
+    private nativeReceiptNotificationFor;
+    private sendNativeReceiptLocked;
+    private deliveryCorrelation;
+    private eventTime;
+    private normalizeDeliverySafeCode;
+    private planRouteInFlightSettlementsLocked;
+    private planRoutesInFlightSettlementsLocked;
+    private planPairInFlightSettlementsLocked;
+    private purgePairCapabilitiesLocked;
+    private settleDeliveryStoreLocked;
+    private publishStallNoticeLocked;
+    private applyDeliveryEffectsLocked;
+    private advanceDeliveryLocked;
+    private applyTerminalSettlementLocked;
+    private takeMessageContextLocked;
+    /**
+     * Codex App Server acceptance is a terminal delivery boundary for the
+     * original message body, but not for its later model reply. Settle the
+     * durable ledger/body now and retain only bounded in-memory reply
+     * correlation until completion or the original deadline.
+     */
+    private acceptProviderDeliveryLocked;
+    private stallReasonFor;
+    private refreshNextProgressWatchWakeLocked;
+    private processProgressWatchesLocked;
+    private processLifecycleLocked;
+    private scheduleLifecycleWakeLocked;
+    private deliveryStatus;
+    private acceptToClaude;
+    private acceptToCodex;
+    private acceptReply;
+    private enqueue;
+    private enqueueNativeReply;
+    /**
+     * A provider reply observed before route teardown remains valid evidence
+     * even when the same atomic mutation removes its selected Claude route.
+     * Re-enter that already-observed reply through the existing transient
+     * native-ingress boundary; this preserves the exact connector generation
+     * without recreating route authority or accepting a new unsolicited send.
+     */
+    private enqueueObservedClaudeReplyAfterRouteTeardownLocked;
+    private pruneTransient;
+    private awaitDispatchWithNativeHeldLocked;
+    private dispatchOne;
+    private scheduleDispatch;
+    private scheduleHeldRedispatch;
+    private onDelivery;
+    private finishDelivery;
+    private finishDeliveredReplyLocked;
+    private finishProviderTurnContinuationLocked;
+    private onClaudeReply;
+    private onClaudeMessage;
+    private releasePendingClaude;
+    private onRouteState;
+    private setNativeCodexStatus;
+    private rejectDetachedNativeReceipt;
+    private drainDetachedReceiptWritesLocked;
+    private settleDetachedNativeReceipt;
+    private exclusiveDecision;
+    private changed;
+    private publicSnapshotLocked;
+    private publish;
+}
+export {};