agent-embassy 2.0.1 → 3.1.0

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

@@ -1,12 +1,17 @@
 import type { GatewayConfig } from "./config.js";
 import { type PeerCatalogResult, type PeerHandoffParams } from "./peer-protocol.js";
-import type { AcceptMessageInput, AcceptMessageResult, AuthorizeMessageInput, AuthorizeMessageResult, EnqueueMessageInput, EnqueueMessageResult, EnqueueNativeIngressInput, EnqueueNativeReplyInput, GatewayConsentEdgeRecord, GatewayMessageRecord, GatewayPersistedState, GatewayPrivateRouteInspection, GatewayPublicSnapshot, GatewayStoreDependencies, LogicalRouteBinding, PublicGatewayActivityEvent, RegisterRouteInput, RemoveRouteAtomicResult, ReplaceCodexRegistrationAtomicInput, ReplaceCodexRegistrationAtomicResult, ReserveMessageResult, ResolvePrewriteAttemptInput, ResolvePrewriteAttemptResult, SettleAttemptInput, SettleAttemptForShutdownInput, SettleAttemptForShutdownResult, SettleAttemptResult, SettleQueuedMessageForShutdownInput, SettleQueuedMessageForShutdownResult, TerminalMessageSettlement } from "./types.js";
+import type { AcceptMessageInput, AcceptMessageResult, AuthorizeMessageInput, AuthorizeMessageResult, EnqueueMessageInput, EnqueueMessageResult, EnqueueNativeIngressInput, GatewayMessageRecord, GatewayPersistedState, GatewayPrivateRouteInspection, GatewayPublicSnapshot, GatewayStoreDependencies, InstallClaudeRouteResult, LogicalRouteBinding, MessageDirection, PublicGatewayActivityEvent, RegisterRouteInput, RemoveRouteAtomicResult, ReplaceCodexRegistrationAtomicInput, ReplaceCodexRegistrationAtomicResult, ReserveMessageResult, ResolvePrewriteAttemptInput, ResolvePrewriteAttemptResult, SettleAttemptInput, SettleAttemptForShutdownInput, SettleAttemptForShutdownResult, SettleAttemptResult, SettleQueuedMessageForShutdownInput, SettleQueuedMessageForShutdownResult, TerminalMessageSettlement } from "./types.js";
+/** The controller lock's file name; the CLI reads the same file for a pid. */
+export declare const GATEWAY_CONTROLLER_LOCK_FILE = ".gateway-controller.lock";
 export declare const GATEWAY_MAX_STATE_FILE_BYTES: number;
-export declare function isGatewayPersistedStateV4(value: unknown): value is GatewayPersistedState;
-type ConsentEdgeInput = Readonly<{
-    aliases: readonly [string, string];
-    expectedRegistrationIds: readonly [string, string];
-}>;
+/**
+ * `configuredHost` is the broker's own host identity, known at construction and
+ * always supplied on the shipped path. Deriving the local host from the routes
+ * alone is not sufficient: a federation node whose only routes are mirrors has
+ * no local route to derive from, and a state file it just wrote would fail its
+ * own validator on the next persist.
+ */
+export declare function isGatewayPersistedStateV5(value: unknown, configuredHost?: string): value is GatewayPersistedState;
 export declare class GatewayStore {
     readonly config: GatewayConfig;
     rootDir: string;
@@ -18,7 +23,20 @@ export declare class GatewayStore {
     private state;
     private lockHandle;
     private lockToken;
+    private readonly isProcessAlive;
+    private readonly hostname;
     private persistenceDeferred;
+    /**
+     * Registration ids that must never reach the durable state document. They
+     * are ordinary rows in the in-memory state — admission, dispatch, queueing
+     * and settlement all see them — and are projected out at the one place that
+     * serializes, together with every row that names one. When such a
+     * registration is removed, the same rows leave the live state in the same
+     * mutate, before the id leaves this set; a rolled-back mutate restores the
+     * set with the state. Nothing here is written down, so a restart reclaims
+     * them by construction.
+     */
+    private readonly ephemeralRegistrations;
     constructor(config: GatewayConfig, dependencies?: GatewayStoreDependencies);
     get stateFilePath(): string;
     initialize(options?: Readonly<{
@@ -28,7 +46,6 @@ export declare class GatewayStore {
     close(): Promise<void>;
     inspectPrivateRoutes(): Promise<GatewayPrivateRouteInspection[]>;
     listLogicalRoutes(): Promise<GatewayPrivateRouteInspection[]>;
-    inspectPrivateConsentEdges(): Promise<GatewayConsentEdgeRecord[]>;
     inspectPrivateRoute(alias: string): Promise<GatewayPrivateRouteInspection | undefined>;
     reconcilePeerCatalog(peerHost: string, catalog: PeerCatalogResult): Promise<Readonly<{
         settlements: readonly TerminalMessageSettlement[];
@@ -36,26 +53,77 @@ export declare class GatewayStore {
     }>>;
     enqueuePeerHandoff(peerHost: string, handoff: PeerHandoffParams): Promise<EnqueueMessageResult>;
     registerRoute(input: RegisterRouteInput): Promise<void>;
+    /** Whether this registration is memory-only; false for every durable route. */
+    isEphemeralRegistration(registrationId: string): boolean;
+    /**
+     * Everything an ephemeral registration owns, taken out of `state`: the route
+     * itself, every message that names it as source or target, the dedupe
+     * fingerprints and rate bucket keyed by its alias, the journal rows —
+     * message activity and runtime activity — that name the alias, and the
+     * queued-bytes total those messages contributed. Pure: the caller decides
+     * whether this becomes the written projection or the live state.
+     */
+    private ephemeralRowsRemoved;
+    /**
+     * The document actually written. While an ephemeral registration lives, its
+     * rows are projected out here, so the written state stays internally
+     * consistent under the strict loader — which refuses a state whose active
+     * message points at a route it cannot find, or whose queued total disagrees
+     * with its queued rows. Both refusals are exactly right, and neither must
+     * ever be reachable by a document we wrote. When the registration is
+     * removed, `removeRegistrationMetadata` takes the same rows out of the live
+     * state in the same mutate. Attributable rows and bodies are removed;
+     * aggregate counters may remain advanced.
+     */
+    private persistedProjection;
     removeOwnedRouteAtomic(input: Readonly<{
         alias: string;
         binding: LogicalRouteBinding;
         activity?: Readonly<{
             operatorAction: boolean;
+            action?: "route_retired";
         }>;
     }>): Promise<RemoveRouteAtomicResult>;
     replaceCodexRegistrationAtomic(input: ReplaceCodexRegistrationAtomicInput): Promise<ReplaceCodexRegistrationAtomicResult>;
-    replaceClaudeSelection(replacement: RegisterRouteInput): Promise<Readonly<{
-        settlements: readonly TerminalMessageSettlement[];
-    }>>;
-    hasConsentEdge(input: ConsentEdgeInput): Promise<boolean>;
-    addConsentEdge(input: ConsentEdgeInput): Promise<void>;
-    removeConsentEdge(input: ConsentEdgeInput): Promise<Readonly<{
-        settlements: readonly TerminalMessageSettlement[];
-        unreferencedAliases: readonly string[];
-    }>>;
+    /**
+     * Installs the route of a discovered Claude session on its first send, or
+     * brings an existing route up to date with discovery. The (host, session
+     * UUID) pair is the identity: a session already bound keeps its
+     * registration (and its in-flight conversations) and is renamed if its
+     * current name changed; a route whose alias now names a different session
+     * is displaced, its work settled `cancelled/ENDPOINT_RETIRED`. Both
+     * outcomes are journaled so `embassy status` can show them. Installation
+     * never creates a permission: same-UID, same-host addressing already is
+     * the permission, and the service's alias-collision fence has already run.
+     */
+    installClaudeRoute(replacement: RegisterRouteInput): Promise<InstallClaudeRouteResult>;
+    /**
+     * The refusal half of admission, without the write. A send to a Claude
+     * session that has no route yet would otherwise install one — displacing
+     * another session and settling its queued work — on its way to being
+     * refused for its own reasons: too large, past the deadline window, rate
+     * limited, or into a full queue. Callers that are about to materialize a
+     * route run this first and materialize only if it returns.
+     *
+     * The refusal is still journaled, because a rejection is a fact about a real
+     * attempt; nothing else is written, and the authoritative checks still run
+     * inside `enqueueMessage` itself. `dedupeKey` is optional: a first send's key
+     * is broker-generated and cannot collide, and omitting it keeps this from
+     * inventing one to test against.
+     */
+    assertEnqueueAdmissible(input: Readonly<{
+        sourceAlias: string;
+        targetAlias: string;
+        direction: MessageDirection;
+        sourceRegistrationId: string;
+        body: string;
+        dedupeKey?: string;
+        conversationIdSuffix?: string;
+        deadlineAt?: string;
+        steer?: true;
+    }>): Promise<void>;
     enqueueMessage(input: EnqueueMessageInput): Promise<EnqueueMessageResult>;
     enqueueNativeIngress(input: EnqueueNativeIngressInput): Promise<EnqueueMessageResult>;
-    enqueueNativeReply(input: EnqueueNativeReplyInput): Promise<EnqueueMessageResult>;
     inspectDispatchableTargets(): Promise<string[]>;
     nextDeadlineAt(): Promise<string | undefined>;
     deliveryStatus(token: string): Promise<GatewayMessageRecord | undefined>;
@@ -72,12 +140,10 @@ export declare class GatewayStore {
     private projectMessageEvent;
     private validateRouteInput;
     private requireRoute;
-    private resolvePair;
-    private requireConsent;
     private enqueueResolved;
-    private terminalizeConsentEdge;
     private allocateDeliveryToken;
     private consumeRate;
+    private rejectEnqueue;
     private recordRejection;
     private finishMessage;
     private touchMessage;
@@ -93,11 +159,30 @@ export declare class GatewayStore {
     private mutate;
     private requireState;
     private prepareOwnedDirectory;
+    /**
+     * Boot-time litter sweep (emb-106): the static `gateway-dashboard*.html`
+     * files 2.x published, any `.tmp` file its temp-file+rename publish could
+     * have left behind mid-crash, and controller locks this store recovered as
+     * stale more than seven days ago, are unlinked best-effort. Only a
+     * regular file owned by this uid is removed (lstat, no symlink following);
+     * nothing else in the state directory is touched, and a removal failure
+     * never blocks startup. Runs only after the controller lock is held and
+     * the state this boot will run on has passed both its schema check and
+     * assertConfiguredBounds, so a refused boot leaves the directory exactly
+     * as found.
+     */
+    private removeStateDirectoryLitter;
     private assertOwnedPrivate;
     private readPrivateFile;
+    /**
+     * Move a lock nobody owns aside instead of deleting it: a crash stays
+     * diagnosable for a week (the boot sweep ages these out), and the caller
+     * is told, because a silent recovery of another process's lock would be
+     * the one event an operator most needs to see.
+     */
+    private recoverStaleLock;
     private acquireLock;
     releaseControllerLock(): Promise<void>;
     private loadStateFile;
     private persist;
 }
-export {};