agent-embassy 1.0.0

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

@@ -0,0 +1,340 @@
+import { type CompatibilityAttestation, type CompatibilitySurface } from "./compatibility.js";
+import type { GatewayConfig } from "./config.js";
+import { type ProgressWatchMachine, type ProgressWatchOutcome } from "./progress-watch-machine.js";
+import { type DeliveryState, type EnqueueMessageInput, type EnqueueMessageResult, type EnqueueNativeIngressInput, type EnqueueNativeReplyInput, type GatewayPrivateRouteInspection, type GatewayPublicSnapshot, type GatewayStoreDependencies, type InFlightMessageProgressState, type ObserveConnectorInput, type ObserveRouteInput, type PrivateEndpointIdentity, type PrivateRouteBinding, type RebindStaleRouteInput, type RegisterRouteInput, type RequeueInFlightMessageResult, type SettleMessageInput, type SettleMessageResult, type TerminalMessageSettlement, type TransientQueuedMessage } from "./types.js";
+export declare const GATEWAY_MAX_STATE_FILE_BYTES: number;
+export type OpenProgressWatchInput = Readonly<{
+    conversationId: string;
+    ownerAlias: string;
+    workerAlias: string;
+    idleMs: number;
+}>;
+export type ProgressWatchAction = Readonly<{
+    type: "send_nudge";
+    conversationId: string;
+    ownerAlias: string;
+    workerAlias: string;
+    nudgeNumber: 1 | 2;
+}> | Readonly<{
+    type: "notify_capability_degraded";
+    conversationId: string;
+    ownerAlias: string;
+    workerAlias: string;
+}> | Readonly<{
+    type: "settled";
+    conversationId: string;
+    ownerAlias: string;
+    workerAlias: string;
+    outcome: ProgressWatchOutcome;
+}>;
+export type SettleQueuedMessageInput = {
+    messageId: string;
+    state: Extract<DeliveryState, "failed" | "expired" | "cancelled" | "abandoned">;
+    safeErrorCode?: string;
+};
+export type SettleQueuedMessageResult = {
+    status: "settled";
+    settlement: TerminalMessageSettlement;
+} | {
+    status: "not_queued";
+};
+export type AffectedInFlightMessageInspection = Readonly<{
+    messageId: string;
+    deadlineAt: string;
+}>;
+export type RouteInFlightSettlementInput = Readonly<{
+    messageId: string;
+    state: SettleMessageInput["state"];
+    safeErrorCode?: string;
+}>;
+export type ReplaceClaudeSelectionInput = Readonly<{
+    replacement: RegisterRouteInput;
+    inFlightSettlements?: readonly RouteInFlightSettlementInput[];
+}>;
+export type GatewayPairInput = Readonly<{
+    claudeAlias: string;
+    codexAlias: string;
+}>;
+export type UnpairRoutesInput = GatewayPairInput & Readonly<{
+    inFlightSettlements?: readonly RouteInFlightSettlementInput[];
+}>;
+export type UnpairRoutesResult = Readonly<{
+    settlements: readonly TerminalMessageSettlement[];
+    claudeRouteUnreferenced: boolean;
+}>;
+export declare const codexSuccessionJournalStages: readonly ["prepared", "publication_armed", "published", "activated", "recovery_forbidden"];
+export type CodexSuccessionJournalStage = (typeof codexSuccessionJournalStages)[number];
+export type CodexSuccessionStoreIdentity = Readonly<{
+    alias: string;
+    threadId: string;
+    hostId: string;
+    /** Opaque exact ownership/listener generation; never interpreted as a path. */
+    generation: string;
+    /** Existing private route metadata only; never publicly projected. */
+    binding: PrivateRouteBinding;
+}>;
+type CodexSuccessionJournal = Readonly<{
+    schemaVersion: 1;
+    stage: CodexSuccessionJournalStage;
+    old: CodexSuccessionStoreIdentity;
+    new: CodexSuccessionStoreIdentity;
+    safeErrorCode?: string;
+}>;
+export type PrepareCodexSuccessionInput = Readonly<{
+    old: CodexSuccessionStoreIdentity;
+    new: CodexSuccessionStoreIdentity;
+}>;
+export type ExactCodexSuccessionInput = Readonly<{
+    oldGeneration: string;
+    newGeneration: string;
+}>;
+export type ClearCodexSuccessionInput = ExactCodexSuccessionInput & Readonly<{
+    /** Required once the durable arm exists; ignored only before arming. */
+    publicationAbsenceConfirmed?: true;
+}>;
+export type ActivateCodexSuccessionInput = ExactCodexSuccessionInput & Readonly<{
+    state: "idle" | "busy" | "awaiting_approval";
+}>;
+export type ForbidCodexSuccessionRecoveryInput = ExactCodexSuccessionInput & Readonly<{
+    safeErrorCode: string;
+}>;
+export type CodexSuccessionRecoveryAuthority = Readonly<{
+    authority: "none";
+}> | Readonly<{
+    authority: "old" | "new";
+    journal: CodexSuccessionJournal;
+}>;
+export type CodexSuccessionBarrierInspection = Readonly<{
+    codexRouteCount: number;
+    queueCount: number;
+    inFlightCount: number;
+    transientBodyCount: number;
+    codexQueueDepth: number;
+    clean: boolean;
+}>;
+export declare class GatewayStore {
+    readonly config: GatewayConfig;
+    rootDir: string;
+    private readonly now;
+    private readonly randomId;
+    private readonly afterStateFileRename;
+    private readonly mutex;
+    private readonly transientBodies;
+    private state;
+    private lockHandle;
+    private lockToken;
+    /**
+     * Startup admission may exercise migrated state in memory, but it must not
+     * strand an older binary by rewriting the durable schema before every
+     * provider and control-socket readiness check has passed.
+     */
+    private persistenceDeferred;
+    constructor(config: GatewayConfig, dependencies?: GatewayStoreDependencies);
+    get stateFilePath(): string;
+    initialize(options?: Readonly<{
+        deferPersistence?: boolean;
+    }>): Promise<void>;
+    /** Commit a successfully admitted startup exactly once. */
+    commitInitialization(): Promise<void>;
+    close(): Promise<void>;
+    observeConnector(input: ObserveConnectorInput): Promise<void>;
+    markConnectorOffline(identity: PrivateEndpointIdentity, safeErrorCode?: string, inFlightSettlements?: readonly RouteInFlightSettlementInput[]): Promise<TerminalMessageSettlement[]>;
+    registerRoute(input: RegisterRouteInput): Promise<void>;
+    /**
+     * Replace the complete selected-Claude set with one exact live session in a
+     * single durable mutation. Work owned by every retired selection settles by
+     * the same evidence-aware rules as explicit unselection; no public snapshot
+     * can observe a two-selection intermediate state.
+     */
+    replaceClaudeSelection(input: ReplaceClaudeSelectionInput): Promise<TerminalMessageSettlement[]>;
+    observeRoute(input: ObserveRouteInput): Promise<void>;
+    invalidateRoute(binding: PrivateRouteBinding, safeErrorCode?: string, inFlightSettlements?: readonly RouteInFlightSettlementInput[]): Promise<TerminalMessageSettlement[]>;
+    /**
+     * Replaces only an already-invalidated binding. Codex must retain the exact
+     * task handle. Claude must retain its exact session UUID and ownership lease;
+     * an authorized discovery may also atomically adopt that UUID's latest live
+     * display name. Names alone are never rebind authority.
+     */
+    rebindStaleRoute(input: RebindStaleRouteInput): Promise<void>;
+    disableRoute(alias: string, ownerLease: string, inFlightSettlements?: readonly RouteInFlightSettlementInput[]): Promise<TerminalMessageSettlement[]>;
+    unregisterRoute(alias: string, ownerLease: string, inFlightSettlements?: readonly RouteInFlightSettlementInput[]): Promise<TerminalMessageSettlement[]>;
+    /**
+     * Move one owned route to its provider's latest live display name without
+     * changing the logical provider route binding. Historical normalized events
+     * retain the name that was true when they were emitted; active metadata is
+     * rewritten so subsequent settlement and dispatch use only the latest name.
+     */
+    renameRoute(alias: string, newAlias: string, ownerLease: string): Promise<void>;
+    resolveRoute(alias: string): Promise<PrivateRouteBinding>;
+    /**
+     * Controller-internal ownership lookup used for explicit reactivation and
+     * unregister after restart. Callers must never return this value through a
+     * control response, dashboard projection, log, or normalized event.
+     */
+    inspectPrivateRoute(alias: string): Promise<GatewayPrivateRouteInspection | undefined>;
+    /**
+     * Controller-internal inventory used to preserve exact Codex registration
+     * identities across restart. Native task handles never cross the control
+     * protocol or enter a public projection.
+     */
+    inspectPrivateCodexRoutes(): Promise<GatewayPrivateRouteInspection[]>;
+    /**
+     * Bounded, metadata-only barrier observation for the succession controller.
+     * No route, message, conversation, or listener identifier is returned.
+     */
+    inspectCodexSuccessionBarrier(alias: string): Promise<CodexSuccessionBarrierInspection>;
+    /** Begin one exact, same-host Codex registration succession. */
+    prepareCodexSuccession(input: PrepareCodexSuccessionInput): Promise<void>;
+    /** Durably closes the rollback-to-old boundary before registry publication. */
+    armCodexSuccessionPublication(input: ExactCodexSuccessionInput): Promise<void>;
+    /** Record that the exact new registry generation is externally visible. */
+    markCodexSuccessionPublished(input: ExactCodexSuccessionInput): Promise<void>;
+    /**
+     * Atomically replace the sole old Codex route with the exact journaled new
+     * private binding. No route gap is ever persisted.
+     */
+    activateCodexSuccession(input: ActivateCodexSuccessionInput): Promise<void>;
+    /** Record an armed-or-later failure for fail-closed restart authority. */
+    forbidCodexSuccessionRecovery(input: ForbidCodexSuccessionRecoveryInput): Promise<void>;
+    /** Clear before arming, or after positive proof that an arm was unpublished. */
+    clearCodexSuccession(input: ClearCodexSuccessionInput): Promise<void>;
+    /** Complete an activated or restart-canonicalized new generation. */
+    completeCodexSuccession(input: ExactCodexSuccessionInput): Promise<void>;
+    /** Controller-private restart authority; omitted from every public view. */
+    inspectCodexSuccessionRecoveryAuthority(): Promise<CodexSuccessionRecoveryAuthority>;
+    /**
+     * Controller-internal inventory used only for exact-UUID Claude restoration
+     * and explicit offline unselection. The result is bounded by maxRoutes and
+     * must never cross the control protocol or enter a public projection.
+     */
+    inspectPrivateClaudeRoutes(): Promise<GatewayPrivateRouteInspection[]>;
+    /** Create one explicit, durable Claude↔Codex consent edge. */
+    pairRoutes(input: GatewayPairInput): Promise<{
+        created: boolean;
+    }>;
+    /** Bounded metadata-only graph inventory for controller inference. */
+    inspectPairs(): Promise<GatewayPairInput[]>;
+    /** Open one durable owner-ended watch on an exact consent edge. */
+    openProgressWatch(input: OpenProgressWatchInput): Promise<{
+        created: boolean;
+        watch: ProgressWatchMachine;
+    }>;
+    inspectProgressWatches(): Promise<ProgressWatchMachine[]>;
+    inspectCompatibilityAttestation(surface: CompatibilitySurface, version: string): Promise<CompatibilityAttestation | undefined>;
+    inspectCompatibilityAttestations(): Promise<CompatibilityAttestation[]>;
+    recordCompatibilityAttestation(attestation: CompatibilityAttestation): Promise<void>;
+    touchProgressWatch(input: Readonly<{
+        conversationId: string;
+        actorAlias: string;
+        workerReportedComplete?: true;
+    }>): Promise<boolean>;
+    touchProgressWatchesForAlias(alias: string): Promise<number>;
+    settleProgressWatch(input: Readonly<{
+        conversationId: string;
+        outcome: ProgressWatchOutcome;
+        ownerAlias?: string;
+    }>): Promise<boolean>;
+    /** Advance every due watch once under one durable store mutation. */
+    advanceDueProgressWatches(): Promise<ProgressWatchAction[]>;
+    nextProgressWatchActionAt(): Promise<string | undefined>;
+    deferProgressWatchNudge(conversationId: string, retryDelayMs?: number): Promise<boolean>;
+    hasPair(input: GatewayPairInput): Promise<boolean>;
+    inspectAffectedPairInFlightMessages(input: GatewayPairInput): Promise<AffectedInFlightMessageInspection[]>;
+    /**
+     * Remove exactly one consent edge and settle only work owned by that edge.
+     * Adjacent pairs, terminal token metadata, and unrelated messages survive.
+     */
+    unpairRoutes(input: UnpairRoutesInput): Promise<UnpairRoutesResult>;
+    /**
+     * Controller-internal inventory used to prepare an exact, evidence-aware
+     * terminal plan before a route mutation. Message bodies and route handles
+     * never cross this boundary. The route mutation validates the returned set
+     * again so a stale or incomplete plan cannot partially settle the ledger.
+     */
+    inspectAffectedInFlightMessages(aliases: readonly string[]): Promise<AffectedInFlightMessageInspection[]>;
+    enqueueMessage(input: EnqueueMessageInput): Promise<EnqueueMessageResult>;
+    /**
+     * Accept one message from a caller-attested native Claude peer without
+     * registering or persisting that peer as a route. The exact private binding
+     * is used only to prove a live same-host connector generation for this call.
+     */
+    enqueueNativeIngress(input: EnqueueNativeIngressInput): Promise<EnqueueMessageResult>;
+    /**
+     * Queue a correlated Codex reply for a caller-attested transient Claude
+     * peer. The service owns conversation correlation and the live dispatch
+     * capability; the store retains only bounded public-alias metadata.
+     */
+    enqueueNativeReply(input: EnqueueNativeReplyInput): Promise<EnqueueMessageResult>;
+    dequeueMessage(targetAlias?: string, mode?: "any" | "steer_only"): Promise<TransientQueuedMessage | undefined>;
+    /**
+     * Atomically terminalizes every message whose delivery deadline is due.
+     * Returned settlements are emitted only by the mutation that removed the
+     * message, so callers can release service-owned capabilities exactly once.
+     *
+     * @deprecated GatewayService must arbitrate deadlines through the delivery
+     * reducer because only the service owns transport-write evidence. Retained
+     * temporarily as a store-level recovery/test primitive; production service
+     * code must not call it.
+     */
+    expireDueMessages(now?: Date): Promise<TerminalMessageSettlement[]>;
+    settleMessage(input: SettleMessageInput): Promise<SettleMessageResult>;
+    requeueInFlightMessage(messageId: string, body: string): Promise<RequeueInFlightMessageResult>;
+    markMessageProgress(messageId: string, progress: InFlightMessageProgressState): Promise<void>;
+    /**
+     * Atomically terminalize one queued message and return the authoritative
+     * settlement produced by the winning mutation. A later contender observes
+     * `not_queued` and must not infer or publish another terminal outcome. At
+     * or beyond the delivery deadline, expiry is authoritative regardless of
+     * the caller's requested terminal state.
+     */
+    settleQueuedMessage(input: SettleQueuedMessageInput): Promise<SettleQueuedMessageResult>;
+    /** @deprecated Prefer settleQueuedMessage so callers retain terminal proof. */
+    cancelQueuedMessage(messageId: string): Promise<boolean>;
+    publicSnapshot(): Promise<GatewayPublicSnapshot>;
+    private mutate;
+    private requireState;
+    private journal;
+    private requireExactSuccession;
+    private assertSuccessionLedgerEmpty;
+    private requireCodexRouteForIdentity;
+    private requireJournalRoute;
+    private requireAnyJournalRoute;
+    private assertNewSuccessionIdentityAvailable;
+    private replaceCodexRouteForSuccession;
+    private assertAllowedIdentity;
+    private requireCompatibleObservedEndpoint;
+    private validateRouteInput;
+    private requireOwnedRoute;
+    private requireAvailableRoute;
+    private requirePairRoutes;
+    private requireExactPair;
+    private validateTransientNativeClaudePeer;
+    private enqueueResolvedMessage;
+    private consumeRateLimit;
+    private recordRejection;
+    private appendEvent;
+    /** Commit watch activity only after every message-admission check succeeds. */
+    private applyProgressWatchMessageActivity;
+    private progressWatchDueTransition;
+    private commitProgressWatchNudge;
+    private appendProgressWatchEvent;
+    private settleProgressWatchesForAliases;
+    private settleProgressWatchesForPair;
+    private finishMetadata;
+    private validateAffectedInFlightSettlements;
+    private validateAffectedPairInFlightSettlements;
+    private terminateAffectedMessages;
+    private terminateAffectedPairMessages;
+    private prune;
+    private recoverAfterRestart;
+    private recoverCodexSuccessionAfterRestart;
+    private aggregateHealth;
+    private prepareOwnedDirectory;
+    private assertOwnedPrivate;
+    private readPrivateFile;
+    private acquireLock;
+    releaseControllerLock(): Promise<void>;
+    private loadStateFile;
+    private persist;
+}
+export {};