agent-embassy 3.0.0 → 4.0.0

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

@@ -1,373 +0,0 @@
-import type { GatewayConfig } from "./config.js";
-import { type GatewayControlHandlers, type GatewaySnapshotObservation } from "./control.js";
-import { spawnPeerClient } from "./peer-client.js";
-import { GatewayStore } from "./store.js";
-import { type GatewayPreparedWriteEvidence, type GatewayProvider, type GatewayPublicSnapshot, type LogicalRouteBinding } from "./types.js";
-export type GatewayAdapterRouteState = "idle" | "busy" | "awaiting_approval";
-export type GatewayAdapterRouteObservationState = GatewayAdapterRouteState | "unobserved";
-export type GatewayAdapterDiscovery = Readonly<{
-    alias: string;
-    routeHandle: string;
-    kind: "interactive" | "bg";
-    state: GatewayAdapterRouteState;
-}>;
-export type GatewayAdapterRegistryObservation = Readonly<{
-    entriesScanned: number;
-    parseableRecords: number;
-    rejected: readonly Readonly<{
-        safeErrorCode: string;
-        count: number;
-    }>[];
-}>;
-export type GatewayAdapterDiscoverySnapshot = Readonly<{
-    peers: readonly GatewayAdapterDiscovery[];
-    complete: boolean;
-    registry?: GatewayAdapterRegistryObservation;
-}>;
-export type GatewayAdapterRouteObservation = Readonly<{
-    route: LogicalRouteBinding;
-    state: GatewayAdapterRouteObservationState;
-    observedAt: string;
-    safeErrorCode?: string;
-}>;
-export type GatewayAdapterNativeEndpoint = Readonly<{
-    provider: GatewayProvider;
-    hostId: string;
-    routeHandle: string;
-}>;
-export type GatewayAdapterCallbacks = Readonly<{
-    onRouteState: (event: GatewayAdapterRouteObservation) => void;
-    onClaudeReply: (event: Readonly<{
-        endpoint: GatewayAdapterNativeEndpoint;
-        text: string;
-    }>) => void;
-    onClaudeMessage?: (event: Readonly<{
-        endpoint: GatewayAdapterNativeEndpoint;
-        sourceAlias: string;
-        targetAlias: string;
-        text: string;
-        receiptHandle?: string;
-    }>) => void;
-    onProtocolNotice?: (event: Readonly<{
-        code: string;
-    }>) => void;
-}>;
-export type GatewayAdapterStart = Readonly<{
-    health: "healthy" | "degraded";
-    safeErrorCode?: string;
-    ownedRoute?: Readonly<{
-        alias: string;
-        routeHandle: string;
-        state: GatewayAdapterRouteState;
-    }>;
-}>;
-export type GatewayAdapterDispatchResult = Readonly<{
-    state: "deferred";
-    safeErrorCode?: string;
-}> | Readonly<{
-    state: "delivered" | "unconfirmed" | "failed" | "ambiguous" | "expired" | "cancelled";
-    safeErrorCode?: string;
-    replyText?: string;
-}>;
-export type GatewayAdapterDispatchInput = Readonly<{
-    attemptId: string;
-    sourceAlias: string;
-    sourceProvider: GatewayProvider;
-    targetAlias: string;
-    conversationId: string;
-    binding: LogicalRouteBinding;
-    authorization: "selected_route";
-    messageId: string;
-    text: string;
-    expectsReply: boolean;
-    deadlineAt: string;
-    steer?: true;
-    queuedAhead?: number;
-    authorizeWrite: (evidence: GatewayPreparedWriteEvidence & Readonly<{
-        attemptId: string;
-    }>) => Promise<boolean>;
-    onAccepted: (evidence: Readonly<{
-        attemptId: string;
-    }>) => Promise<void>;
-}>;
-export interface GatewayProviderAdapter {
-    readonly identity: Readonly<{
-        provider: GatewayProvider;
-        hostId: string;
-    }>;
-    readonly protocol: string;
-    readonly protocolVersion: string;
-    latestRegistryObservation?(): GatewayAdapterRegistryObservation | undefined;
-    initialize(callbacks: GatewayAdapterCallbacks): Promise<GatewayAdapterStart>;
-    observeLogicalRoute?(input: Readonly<{
-        alias: string;
-        routeHandle: string;
-        registrationId: string;
-    }>): void;
-    forgetLogicalRoute?(registrationId: string): void;
-    discoverClaudePeers?(): Promise<GatewayAdapterDiscoverySnapshot>;
-    selectRoute?(input: Readonly<{
-        alias: string;
-        routeHandle: string;
-    }>): Promise<{
-        routeHandle: string;
-        state: GatewayAdapterRouteState;
-    }>;
-    assertWorkspaceDisjoint?(routeHandle: string, stateRoot: string): Promise<void>;
-    resolveReplyAddress?(address: string): Promise<{
-        routeHandle: string;
-    }>;
-    advertiseNativeSourcePeer?(input: Readonly<{
-        alias: string;
-        sourceProvider: GatewayProvider;
-        cwd: string;
-    }>): Promise<void>;
-    unadvertiseNativeSourcePeer?(alias: string): Promise<void>;
-    updateNativeSourcePeerStatus?(alias: string, status: "idle" | "busy" | "waiting"): Promise<void>;
-    updateNativeInboundStatus?(receiptHandle: string, status: "held" | "delivered" | "denied" | "expired", diagnosticCode?: string): Promise<void>;
-    notifyNativeInboundProgress?(receiptHandle: string, progress: Readonly<{
-        kind: "stall";
-        reason: "ROUTE_BUSY" | "ROUTE_UNAVAILABLE" | "AWAITING_EXTERNAL_APPROVAL";
-        queuedForMs: number;
-    }>): Promise<void>;
-    releaseNativeInboundReceipt?(receiptHandle: string): Promise<boolean>;
-    dispatch(input: GatewayAdapterDispatchInput): Promise<GatewayAdapterDispatchResult>;
-    releaseRoute?(routeHandle: string): Promise<void>;
-    close(): Promise<void>;
-}
-type GatewayServiceTimer = ReturnType<typeof setTimeout>;
-type GatewayServiceTimers = Readonly<{
-    setTimeout: (callback: () => void, delayMs: number) => GatewayServiceTimer;
-    clearTimeout: (timer: GatewayServiceTimer) => void;
-}>;
-export type GatewayServiceOptions = Readonly<{
-    config: GatewayConfig;
-    adapters?: readonly GatewayProviderAdapter[];
-    store?: GatewayStore;
-    now?: () => Date;
-    nativePeerCwd?: string;
-    timers?: GatewayServiceTimers;
-    /** True when a process outside Embassy holds the managed Codex control socket while the managed layout is missing. */
-    managedCodexSocketHeld?: () => Promise<boolean>;
-    spawnPeer?: typeof spawnPeerClient;
-}>;
-export declare class GatewayService {
-    readonly config: GatewayConfig;
-    readonly store: GatewayStore;
-    private readonly adapters;
-    private readonly now;
-    private readonly timers;
-    private readonly nativePeerCwd;
-    private readonly managedCodexSocketHeld;
-    private readonly spawnPeer;
-    private readonly peerClients;
-    private readonly peerCatalogs;
-    private readonly peerCleanupAliases;
-    /** View-only freshness; never consulted by routing or write authorization. */
-    private readonly peerRouteViews;
-    private readonly connectors;
-    private readonly routeObservations;
-    private readonly candidates;
-    private readonly collidingClaudeAliases;
-    private readonly conversations;
-    private readonly messageContexts;
-    private readonly activeAttempts;
-    private readonly reserveOperations;
-    private readonly inboundOperations;
-    private readonly peerRefreshOperations;
-    private readonly pendingClaudeReplies;
-    private readonly nativeReceipts;
-    private readonly dispatchRunners;
-    private readonly steerRunners;
-    private readonly startingTargets;
-    private readonly runtimeAlerts;
-    /**
-     * Ephemeral peer registrations and the wall-clock instant each one dies.
-     * Nothing durable records them, so this map is the whole lifetime: it is
-     * swept on the ordinary maintenance tick, and a restart simply never sees
-     * the routes at all.
-     */
-    private readonly ephemeralPeerExpiries;
-    /** Consecutive failed retirements per ephemeral alias; cleared on success or removal. */
-    private readonly ephemeralExpiryFailures;
-    private control;
-    private wakeTimer;
-    private nextDiscoveryAt;
-    private nextManagedCodexCheckAt;
-    private nextPeerRefreshAt;
-    private managedCodexSocketHeldOutside;
-    private revision;
-    private snapshotRevision;
-    private snapshotFingerprint;
-    private running;
-    private closing;
-    private closeInFlight;
-    constructor(options: GatewayServiceOptions);
-    start(signal?: AbortSignal): Promise<void>;
-    close(): Promise<void>;
-    private closeOnce;
-    handlers(): GatewayControlHandlers;
-    private buildPeerCatalog;
-    private receivePeerHandoff;
-    snapshot(): Promise<GatewayPublicSnapshot>;
-    observeSnapshot(): Promise<GatewaySnapshotObservation>;
-    private health;
-    private installOwnedRoute;
-    private observeLoadedRoutes;
-    private observeRoute;
-    private forgetRoute;
-    private adapterFor;
-    private claudeAdapter;
-    private advertise;
-    private unadvertise;
-    private reconcileAdvertisement;
-    private reconcileUnadvertisement;
-    private removeOwnedRoute;
-    private recordActivity;
-    private registerCodex;
-    private registerPeer;
-    private assertPeer;
-    private unregisterPeer;
-    /**
-     * Retires every ephemeral peer registration whose lifetime has run out. It
-     * is the same removal an explicit `unregister-peer` performs — queued work
-     * is settled, not abandoned — minus the token check, because the authority
-     * here is the clock the broker set itself.
-     *
-     * The clock is keyed by alias, and an alias can be re-registered durably
-     * after its ephemeral holder left, so nothing is retired unless the route
-     * behind the alias is still an ephemeral one. A retirement that throws
-     * keeps its entry and is retried `EPHEMERAL_EXPIRY_RETRY_MS` later, with an
-     * alert each time; after `EPHEMERAL_EXPIRY_MAX_ATTEMPTS` consecutive
-     * failures the entry is dropped and the registration is left to the next
-     * restart, which clears it by construction.
-     */
-    private expireEphemeralPeers;
-    private awaitPeer;
-    private peerReceipt;
-    private unregisterCodex;
-    /**
-     * The name this session may take. A name belongs to one route at a time, so
-     * when another Claude route already holds it and THAT route's session is
-     * still live, this session takes a disambiguated name rather than displacing
-     * a working session and cancelling its queued work. Twins that share a
-     * display name therefore both keep routes and both stay reachable by UUID;
-     * only a route whose session is actually gone is displaced.
-     */
-    private claimableAlias;
-    /**
-     * Installs (or brings up to date) the route of one discovered Claude
-     * session. The adapter pins the session's route handle, the workspace
-     * check keeps deliberately broad workspaces out, and the store reuses the
-     * registration of a session already bound under the same (host, UUID) so a
-     * re-anchored or renamed session keeps its identity and in-flight
-     * conversations. Any Claude route the install displaced is forgotten and
-     * released at the adapter; its work was settled `ENDPOINT_RETIRED` by the
-     * store — and only a route whose own session is gone is ever displaced.
-     */
-    private installClaudeRoute;
-    /**
-     * Two first sends to the same never-installed session race: both read no
-     * route and both mint a registration, and the loser's write is refused
-     * because the identity is now bound. That is a race, not a conflict — the
-     * session is exactly the one the loser resolved — so re-read once and adopt
-     * the registration that won instead of failing an honest send.
-     */
-    private installWithConcurrentFirstSend;
-    /**
-     * Looks a Claude selector up without writing anything. Callers that may
-     * still refuse — a `--from` alias that must match the sending session, a
-     * native sender whose adapter-reported name must match discovery — resolve
-     * here first, refuse on the read, and only then materialize.
-     *
-     * THE ALIAS-COLLISION FENCE lives here (emb-94, moved into the send path by
-     * emb-104). Invariant: discovery is refreshed inside every send that
-     * addresses a Claude session, never only on the timer; a NAME currently
-     * shared by more than one live session is refused with a hard,
-     * non-retryable `PEER_ALIAS_COLLISION` naming that alias, so the broker
-     * never picks first and never installs a route under an ambiguous name;
-     * collisions stay sticky while a scan is incomplete
-     * (`collidingClaudeAliases` retention in refreshClaudeDiscovery); and
-     * `availablePeers` keeps filtering colliders so `status` never lists an
-     * unaddressable name.
-     *
-     * The fence is a fence on NAMES, not on sessions. A session UUID is
-     * unambiguous by construction, so a UUID selector — an explicit
-     * `send --to <uuid>`, an identity-pinned route addressed by its own handle,
-     * or a sender resolved from its inherited socket — passes the fence even
-     * while its display name collides. That is the emb-94 escape hatch: the
-     * operator can always reach an ambiguously named session, and a collision on
-     * a *sender's* name never silences that sender, whose identity was attested
-     * rather than typed. In-flight conversations are likewise unaffected:
-     * `reply` resolves by exact binding.
-     */
-    private lookUpClaudeRoute;
-    /**
-     * The name discovery currently shows for a looked-up session, which a caller
-     * compares against the alias it claimed before anything is written.
-     */
-    private claimedAlias;
-    /** Installs the looked-up session's route if it is not already current. */
-    private materializeClaudeRoute;
-    private resolveClaudeRoute;
-    private assertThread;
-    /**
-     * Direction follows the inherited principal, not the route table: a Claude
-     * session or its target may have no route yet, because routes install on
-     * first send. A Codex task sends to Claude sessions and shell peers; a
-     * Claude session sends to Codex tasks and shell peers (Claude-to-Claude is
-     * native); a shell peer sends to either.
-     */
-    private send;
-    private sendToClaude;
-    private sendToCodex;
-    /**
-     * A send addressed by conversation token: the caller must own one end, the
-     * other end is the binding the conversation recorded, and the caller's
-     * principal is the same attested one every send carries.
-     */
-    private replyToConversation;
-    private assertReplyCaller;
-    private enqueueConversation;
-    /**
-     * A renamed Claude session is the same principal under a new display name,
-     * so its open conversations follow it: the registration, not the alias, is
-     * the identity, and a reply under the current name must still resolve.
-     */
-    private renameConversationCoordinates;
-    private rememberConversation;
-    private conversationIsActive;
-    private deliveryStatus;
-    private messageUpdatedAt;
-    private kick;
-    private kickExact;
-    private kickSteer;
-    private startRunner;
-    private runTarget;
-    private settleAttemptForShutdown;
-    private resolvePrewrite;
-    private applyDispatchResult;
-    private callbacksFor;
-    private onRouteState;
-    private onClaudeMessage;
-    private onClaudeReply;
-    private enqueueCorrelatedReply;
-    private installPendingClaudeReply;
-    private pruneExpiredPendingClaudeReplies;
-    private retirePendingClaudeReply;
-    private activatePendingClaudeReply;
-    private deliverPendingClaudeReply;
-    private finishSettlements;
-    private finishSettlement;
-    private scheduleTargetRetry;
-    private scheduleWake;
-    private onWake;
-    private refreshPeers;
-    private refreshClaudeDiscovery;
-    private refreshManagedCodexSocket;
-    private assertWritable;
-    private routeObservationStillCurrent;
-    private alert;
-    private recordPeerFailure;
-}
-export {};