agent-embassy 1.0.0

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

@@ -0,0 +1,287 @@
+import { ClaudePeerAdapter, type ClaudePeerInboundProgress, type ClaudePeerRegistryPublicationOutcome } from "./claude-peer.js";
+import type { AttestedClaudePeerRuntime } from "./claude-runtime.js";
+import { type ClaudeCompatibilityScratchFactory } from "./claude-compatibility-scratch.js";
+import { type CompatibilityAttestation, type CompatibilityCertification, type CompatibilityProbeResult, type CompatibilitySurfaceObservation } from "./compatibility.js";
+import { type CodexConnectorObservation } from "./codex-app-server.js";
+import type { LocalCodexTransportFactory } from "./codex-local-transport.js";
+import type { GatewayDeliveryNoticeMode } from "./config.js";
+import type { ClaudeNativeHelperFactory } from "./claude-helper-client.js";
+import { type DashboardLocale } from "./locale.js";
+import type { GatewayAdapterCallbacks, GatewayAdapterDiscoverySnapshot, GatewayAdapterDispatchResult, GatewayAdapterRouteState, GatewayAdapterStart, GatewayProviderAdapter } from "./service.js";
+import type { PrivateEndpointIdentity, PrivateRouteBinding } from "./types.js";
+type ClaudePeerFactory = (runtime: AttestedClaudePeerRuntime, locale: DashboardLocale, deliveryNotices: GatewayDeliveryNoticeMode) => ClaudePeerAdapter;
+export type LocalClaudeGatewayProviderOptions = {
+    /** Exact result of attestClaudePeerRuntime; paths are never rediscovered. */
+    runtime: AttestedClaudePeerRuntime;
+    hostId?: "this-mac";
+    /** Locale for bounded notices written into native Claude sessions. */
+    locale?: DashboardLocale;
+    /** Gateway-authored user-frame policy; native receipt status is unchanged. */
+    deliveryNotices?: GatewayDeliveryNoticeMode;
+    discoveryPollMs?: number;
+    maxPendingMessages?: number;
+    now?: () => number;
+    /** Production-only real-PID advertisement helpers. Omit in child/test hosts. */
+    nativeHelpers?: Readonly<{
+        maxHelpers: number;
+        factory?: ClaudeNativeHelperFactory;
+    }>;
+    /** Deterministic test seam. Production callers must omit this. */
+    peerFactory?: ClaudePeerFactory;
+    /** Deterministic test seam. Production starts one bounded local scratch. */
+    compatibilityScratchFactory?: ClaudeCompatibilityScratchFactory;
+};
+export type ClaudeNativeCodexSuccessionBarrier = Readonly<{
+    generation: string;
+    activeGenerationMatched: boolean;
+    ingressQuiesced: boolean;
+    monitorFrozen: boolean;
+    discoveryInFlight: boolean;
+    pendingOutboundReceipts: number;
+    pendingInboundReceipts: number;
+    rejectedInboundSettlements: number;
+    clean: boolean;
+}>;
+export type CodexRouteSuccessionBarrier = Readonly<{
+    routePresent: boolean;
+    connection: CodexConnectorObservation["connection"] | "absent";
+    routeStatus: CodexConnectorObservation["routeStatus"] | "absent";
+    queueDepth: number;
+    hasActiveTurn: boolean;
+    requestInFlight: boolean;
+    routeCreationInFlight: boolean;
+    routeReleaseInFlight: boolean;
+    pendingReplyCorrelations: number;
+    pendingCallbacks: number;
+    clean: boolean;
+}>;
+export declare class LocalClaudeGatewayProvider implements GatewayProviderAdapter {
+    readonly identity: PrivateEndpointIdentity;
+    readonly protocol = "claude-peer";
+    readonly protocolVersion: string;
+    private readonly peer;
+    private readonly runtimeVersion;
+    private readonly maxPending;
+    private readonly discoveryPollMs;
+    private readonly now;
+    private readonly selectedStateRoots;
+    private readonly nativeHelpers;
+    private readonly compatibilityScratchFactory;
+    private readonly discovered;
+    private readonly selected;
+    /** Exact live same-UID sessions observed through native inbound frames. */
+    private readonly nativeInbound;
+    /** Exact listener owner for every receipt capability handed to the service. */
+    private readonly nativeInboundReceiptOwners;
+    private readonly selectedObservations;
+    /** Invalidates any discovery that overlaps a dispatch on this route. */
+    private readonly selectedDispatchEpoch;
+    /**
+     * A dispatch invalidates the pre-dispatch registry observation. The first
+     * subsequent successful discovery must therefore be published even when
+     * the native peer completed between polls and is idle again.
+     */
+    private readonly selectedObservationDirty;
+    private readonly pendingByProviderId;
+    private readonly providerIdByGatewayId;
+    /** Includes the pre-write reservation through exact terminal settlement. */
+    private readonly pendingTargetByGatewayId;
+    /** Provider-owned terminal rejections that never enter the service queue. */
+    private readonly rejectedNativeInbound;
+    private discoveryInFlight;
+    private monitorTimer;
+    /** Invocation-ordered registry mutations; the tail itself never rejects. */
+    private nativeCodexRegistrationTail;
+    private callbacks;
+    private activeNativeCodexListener;
+    private preparedNativeCodexListener;
+    private nativeCodexPreparationInFlight;
+    private retiredNativeCodexListener;
+    /** Fences discovery callbacks and monitor restarts across listener rotation. */
+    private nativeCodexSuccessionFreeze;
+    private compatibilityCertificationInFlight;
+    private initialized;
+    private closed;
+    constructor(options: LocalClaudeGatewayProviderOptions);
+    compatibilitySurface(): CompatibilitySurfaceObservation;
+    runCompatibilityProbes(): Promise<readonly CompatibilityProbeResult[]>;
+    runCompatibilityCertification(input: Readonly<{
+        controllerStateRoot: string;
+        routeHandle?: string;
+        withTurn: boolean;
+    }>): Promise<CompatibilityCertification>;
+    initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
+    discoverClaudePeers(): Promise<GatewayAdapterDiscoverySnapshot>;
+    assertWorkspaceDisjoint(routeHandle: string, stateRoot: string): Promise<void>;
+    selectRoute(input: {
+        alias: string;
+        routeHandle: string;
+    }): Promise<{
+        routeHandle: string;
+        state: GatewayAdapterRouteState;
+    }>;
+    resolveReplyAddress(address: string): Promise<{
+        routeHandle: string;
+    }>;
+    advertiseNativeCodexPeer(input: {
+        alias: string;
+        cwd: string;
+    }): Promise<void>;
+    currentNativeCodexPeerGeneration(alias: string): string;
+    /** Child-host initialization seam before its immutable advertisement exists. */
+    currentUnadvertisedNativeCodexPeerGeneration(): string;
+    prepareNativeCodexPeerGeneration(input: {
+        alias: string;
+        cwd: string;
+        generation: string;
+        currentGeneration?: string;
+    }): Promise<void>;
+    quiesceNativeCodexPeerGeneration(generation: string): Promise<void>;
+    observeNativeCodexSuccessionBarrier(generation: string): Promise<ClaudeNativeCodexSuccessionBarrier>;
+    publishPreparedNativeCodexPeer(input: {
+        currentGeneration: string;
+        preparedGeneration: string;
+    }): Promise<ClaudePeerRegistryPublicationOutcome>;
+    activatePreparedNativeCodexPeerGeneration(generation: string): Promise<void>;
+    cleanupPreparedNativeCodexPeerGeneration(generation: string): Promise<void>;
+    resumeNativeCodexPeerGeneration(generation: string): Promise<void>;
+    rollbackPreparedNativeCodexPeerGeneration(input: {
+        preparedGeneration: string;
+        resumeGeneration: string;
+    }): Promise<void>;
+    retireNativeCodexPeerGeneration(input: {
+        retiredGeneration: string;
+        protectedActiveGeneration: string;
+    }): Promise<void>;
+    purgeNativeCodexPeerGenerationReplyCapabilities(generation: string): Promise<number>;
+    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: ClaudePeerInboundProgress): Promise<void>;
+    releaseNativeInboundReceipt(receiptHandle: string): Promise<boolean>;
+    quiesceNativeInbound(): Promise<void>;
+    dispatch(input: {
+        sourceAlias?: string;
+        binding: PrivateRouteBinding;
+        authorization: "selected_route" | "native_reply";
+        messageId: string;
+        text: string;
+        expectsReply: boolean;
+        deadlineAt: string;
+    }): Promise<GatewayAdapterDispatchResult>;
+    releaseRoute(routeHandle: string): Promise<void>;
+    close(): Promise<void>;
+    private assertReady;
+    private serializeNativeCodexRegistration;
+    private nativeCodexRegistration;
+    private requireActiveNativeCodexListener;
+    private requireNativeCodexListenerGeneration;
+    private requireNativeInboundReceiptOwner;
+    private ownsNativeCodexListener;
+    private onListenerMessage;
+    private rejectNativeInboundReceipt;
+    private settleRejectedNativeInbound;
+    private ownsNativeCodexListenerGeneration;
+    private waitForRejectedNativeInboundRetry;
+    private releaseRejectedNativeInbound;
+    private trackClaudeMessage;
+    private abandonClaudeTracking;
+    private onReceipt;
+    private recordClaudeWriteEvidence;
+    private finishClaudeMessage;
+    private emitDelivery;
+    private refreshClaudeDiscovery;
+    private refreshClaudeDiscoveryOnce;
+    private emitClaudeRouteObservation;
+    private hasPendingClaudeReceipt;
+    private scheduleClaudeMonitor;
+}
+export declare function createLocalClaudeGatewayProvider(options: LocalClaudeGatewayProviderOptions): LocalClaudeGatewayProvider;
+export type LocalCodexGatewayProviderOptions = {
+    factory: LocalCodexTransportFactory;
+    cleanupPollMs?: number;
+    cleanupTimeoutMs?: number;
+    recoveryInitialMs?: number;
+    recoveryMaxMs?: number;
+    maxCallbackEvents?: number;
+    maxRoutes?: number;
+    maxReplyBytes?: number;
+    now?: () => Date;
+};
+export declare class LocalCodexGatewayProvider implements GatewayProviderAdapter {
+    readonly identity: PrivateEndpointIdentity;
+    readonly protocol: string;
+    readonly protocolVersion: string;
+    private readonly factory;
+    private readonly maxCallbacks;
+    private readonly maxRoutes;
+    private readonly maxReplyBytes;
+    private readonly cleanupPollMs;
+    private readonly cleanupTimeoutMs;
+    private readonly recoveryInitialMs;
+    private readonly recoveryMaxMs;
+    private readonly now;
+    private readonly routes;
+    private readonly routeCreations;
+    private readonly routeReleases;
+    private readonly routeRecoveryAttempts;
+    private readonly routeRecoveryTimers;
+    private readonly routeRecoveries;
+    private readonly routesRequiringRecovery;
+    private readonly expectsReply;
+    private readonly compatibilityCertifyingRoutes;
+    private readonly compatibilityTurns;
+    private readonly callbackQueue;
+    private callbackScheduled;
+    private callbacks;
+    private compatibilityAttested;
+    private initialized;
+    private closing;
+    private closed;
+    constructor(options: LocalCodexGatewayProviderOptions);
+    compatibilitySurface(): CompatibilitySurfaceObservation;
+    acceptCompatibilityAttestation(attestation: CompatibilityAttestation): void;
+    runCompatibilityProbes(): Promise<readonly CompatibilityProbeResult[]>;
+    runCompatibilityCertification(input: Readonly<{
+        controllerStateRoot: string;
+        routeHandle?: string;
+        withTurn: boolean;
+    }>): Promise<CompatibilityCertification>;
+    initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
+    selectRoute(input: {
+        alias: string;
+        routeHandle: string;
+    }): Promise<{
+        routeHandle: string;
+        state: GatewayAdapterRouteState;
+    }>;
+    observeRouteSuccessionBarrier(routeHandle: string): CodexRouteSuccessionBarrier;
+    dispatch(input: {
+        binding: PrivateRouteBinding;
+        authorization: "selected_route" | "native_reply";
+        messageId: string;
+        text: string;
+        expectsReply: boolean;
+        deadlineAt: string;
+        steer?: true;
+    }): Promise<GatewayAdapterDispatchResult>;
+    releaseRoute(routeHandle: string): Promise<void>;
+    private releaseRouteInternal;
+    close(): Promise<void>;
+    private assertReady;
+    private ensureRoute;
+    private createRoute;
+    private onConnectorEvent;
+    private scheduleRouteRecovery;
+    private recoverRoute;
+    private cancelRouteRecovery;
+    private onTurnResult;
+    private queueRouteObservation;
+    private enqueueCodexCallback;
+    private drainOneCallback;
+    private drainCallbackQueue;
+    private closeRoute;
+    private waitForOwnedTurnToSettle;
+}
+export declare function createLocalCodexGatewayProvider(options: LocalCodexGatewayProviderOptions): LocalCodexGatewayProvider;
+export {};