agent-embassy 3.1.0 → 4.0.0

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

@@ -1,541 +0,0 @@
-export declare const gatewayProviders: readonly ["claude", "codex", "peer"];
-export type GatewayProvider = (typeof gatewayProviders)[number];
-export declare const gatewayRegistrationIngressPrefixes: Readonly<{
-    claude: undefined;
-    codex: string;
-    peer: string;
-}>;
-export declare const connectorHealthStates: readonly ["offline", "connecting", "healthy", "degraded"];
-export type ConnectorHealth = (typeof connectorHealthStates)[number];
-export declare const routeStates: readonly ["stale", "idle", "busy", "awaiting_approval", "offline", "disabled"];
-export type RouteState = (typeof routeStates)[number];
-export declare const routeRegistrationModes: readonly ["explicit_opt_in", "selected_live_peer", "federated_peer"];
-export type RouteRegistrationMode = (typeof routeRegistrationModes)[number];
-export type MessageDirection = `${GatewayProvider}_to_${GatewayProvider}`;
-export type ParsedMessageDirection = Readonly<{
-    sourceProvider: GatewayProvider;
-    targetProvider: GatewayProvider;
-}>;
-export declare const isGatewayProvider: (value: unknown) => value is GatewayProvider;
-export declare function directionId(sourceProvider: GatewayProvider, targetProvider: GatewayProvider): MessageDirection;
-export declare function parseDirection(value: unknown): ParsedMessageDirection | undefined;
-export declare const isMessageDirection: (value: unknown) => value is MessageDirection;
-export declare const deliveryStates: readonly ["queued", "duplicate", "dispatching", "transport_written", "held", "delivered", "unconfirmed", "failed", "ambiguous", "expired", "cancelled", "abandoned", "rejected"];
-export type DeliveryState = (typeof deliveryStates)[number];
-export type TerminalDeliveryOutcome = Extract<DeliveryState, "delivered" | "unconfirmed" | "failed" | "ambiguous" | "expired" | "cancelled" | "abandoned">;
-export declare const alertSeverities: readonly ["info", "warning", "error"];
-export type AlertSeverity = (typeof alertSeverities)[number];
-export type BusyPolicy = "queue";
-export declare const gatewayPublicSnapshotLimits: Readonly<{
-    readonly connectors: 64;
-    readonly registryRejectionCodes: 32;
-    readonly availablePeers: 256;
-    readonly routes: 256;
-    readonly activityEvents: 256;
-    readonly messages: 1024;
-    readonly alerts: 256;
-}>;
-export declare const GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET: number;
-/**
- * Durable logical registration. Provider endpoint generations are deliberately
- * absent: they are operation-local evidence and never routing authority.
- */
-export type LogicalRouteBinding = {
-    provider: GatewayProvider;
-    hostId: string;
-    routeHandle: string;
-    registrationId: string;
-};
-export type RouteCounters = {
-    accepted: number;
-    delivered: number;
-    unconfirmed: number;
-    failed: number;
-    ambiguous: number;
-    expired: number;
-    cancelled: number;
-    abandoned: number;
-    rejected: number;
-    bytesAccepted: number;
-};
-export type GatewayRouteRecord = {
-    alias: string;
-    binding: LogicalRouteBinding;
-    registrationMode: RouteRegistrationMode;
-    enabled: boolean;
-    busyPolicy: BusyPolicy;
-    registeredAt: string;
-    updatedAt: string;
-    counters: RouteCounters;
-};
-/**
- * Controller-internal route view used to prove ownership across a restart.
- * This type must never cross the control protocol or enter a public snapshot.
- */
-export type GatewayPrivateRouteInspection = {
-    alias: string;
-    binding: LogicalRouteBinding;
-    registrationMode: RouteRegistrationMode;
-    enabled: boolean;
-};
-export type QueuedMessageMetadata = {
-    messageId: string;
-    messageIdSuffix: string;
-    conversationIdSuffix?: string;
-    direction: MessageDirection;
-    sourceAlias: string;
-    targetAlias: string;
-    enqueuedAt: string;
-    deadlineAt: string;
-    bytes: number;
-    body?: string;
-    steer?: true;
-};
-export type DedupeRecord = {
-    fingerprint: string;
-    messageIdSuffix: string;
-    conversationIdSuffix?: string;
-    sourceAlias: string;
-    targetAlias: string;
-    direction: MessageDirection;
-    firstSeenAt: string;
-    expiresAt: string;
-};
-export type RateBucket = {
-    sourceAlias: string;
-    windowStartedAt: string;
-    count: number;
-};
-export type NormalizedMessageEvent = {
-    sequence: number;
-    timestamp: string;
-    messageIdSuffix: string;
-    conversationIdSuffix?: string;
-    direction: MessageDirection;
-    sourceAlias: string;
-    targetAlias: string;
-    state: DeliveryState;
-    bytes: number;
-    body?: string;
-    steer?: true;
-    latencyMs?: number;
-    safeErrorCode?: string;
-};
-export type GatewayAccounting = {
-    accepted: number;
-    duplicates: number;
-    delivered: number;
-    unconfirmed: number;
-    failed: number;
-    ambiguous: number;
-    expired: number;
-    cancelled: number;
-    abandoned: number;
-    rejected: number;
-    bytesAccepted: number;
-    queuedBytes: number;
-};
-export type GatewayPreparedWriteEvidence = {
-    kind: "claude_mailbox" | "codex_turn_start" | "codex_turn_steer" | "peer_mailbox" | "peer_handoff";
-    bodyBytes: number;
-    bodySha256: string;
-    frameBytes: number;
-    sha256: string;
-};
-export type GatewayMessageAttemptAuthority = {
-    attemptId: string;
-    attemptCount: number;
-    targetRegistrationId: string;
-    sourceRegistrationId: string;
-};
-export type GatewayMessageState = {
-    phase: "queued";
-    attemptCount: number;
-} | (GatewayMessageAttemptAuthority & {
-    phase: "reserved";
-    reservedAt: string;
-}) | (GatewayMessageAttemptAuthority & {
-    phase: "armed";
-    armedAt: string;
-    prepared: GatewayPreparedWriteEvidence;
-}) | (GatewayMessageAttemptAuthority & {
-    phase: "accepted";
-    acceptedAt: string;
-    prepared: GatewayPreparedWriteEvidence;
-    lossOutcome: "unconfirmed" | "ambiguous";
-}) | {
-    phase: "terminal";
-    outcome: TerminalDeliveryOutcome;
-    terminalAt: string;
-    safeErrorCode?: string;
-    latencyMs: number;
-};
-export type GatewayMessageRecord = QueuedMessageMetadata & {
-    sequence: number;
-    deliveryToken?: string;
-    sourceRegistrationId: string;
-    targetRegistrationId: string | null;
-    state: GatewayMessageState;
-};
-export type GatewayMessageActivity = {
-    type: "message_activity";
-    event: NormalizedMessageEvent;
-};
-export type GatewayRuntimeActivity = {
-    type: "activity";
-    event: PublicGatewayActivityEvent;
-};
-export type GatewayStateActivity = GatewayMessageActivity | GatewayRuntimeActivity;
-export type GatewayPersistedState = {
-    schemaVersion: 5;
-    commit: {
-        sequence: number;
-        id: string;
-    };
-    createdAt: string;
-    updatedAt: string;
-    eventSequence: number;
-    routes: GatewayRouteRecord[];
-    messages: GatewayMessageRecord[];
-    dedupe: DedupeRecord[];
-    rateBuckets: RateBucket[];
-    activity: GatewayStateActivity[];
-    accounting: GatewayAccounting;
-};
-export type PublicRouteSnapshot = {
-    alias: string;
-    provider: GatewayProvider;
-    host: string;
-    enabled: boolean;
-    state: RouteState;
-    busyPolicy: BusyPolicy;
-    lastSeenAt?: string;
-    queueDepth: number;
-    oldestQueuedAt?: string;
-    counters: RouteCounters;
-    safeErrorCode?: string;
-    mutable?: boolean;
-};
-export type PublicConnectorSnapshot = {
-    provider: GatewayProvider;
-    host: string;
-    health: ConnectorHealth;
-    protocol: string;
-    protocolVersion: string;
-    lastSeenAt?: string;
-    observationAgeMs?: number;
-    safeErrorCode?: string;
-    registry?: PublicRegistryObservationSnapshot;
-};
-export declare const CONNECTOR_OBSERVATION_STALE_AFTER_MS = 35000;
-/** The words a connector is allowed to say. Never a sentence, never a number. */
-export type StatusWord = "ok" | "stale" | "degraded" | "offline";
-/**
- * Connector words. A connector reporting `CONNECTOR_OBSERVATION_STALE` has
- * nothing wrong with it: no route of that provider was observed inside the
- * broker's window. That is `stale`, not `degraded`, and the difference is the
- * point — an idle Mac with no registered Codex task must not read as broken.
- */
-export declare function connectorWord(connector: PublicConnectorSnapshot): StatusWord;
-/**
- * The overall word is informational and derived from the two connectors a
- * message actually travels through. A shell peer never contributes: its
- * mailbox is pull-only, so "nobody is awaiting it" is a fact about the
- * operator's other terminal, not about the broker.
- */
-export declare function gatewayHealthWord(connectors: readonly PublicConnectorSnapshot[]): StatusWord;
-/**
- * Bounded, native-ID-free evidence attached to one Claude connector. Counts
- * describe only the latest pass; the monotonic flag distinguishes an ordinary
- * empty registry from one that has never yielded parseable required fields
- * this boot.
- */
-export type PublicRegistryObservationSnapshot = {
-    entriesScanned: number;
-    parseableRecords: number;
-    parseableRecordSeenSinceBoot: boolean;
-    rejected: {
-        safeErrorCode: string;
-        count: number;
-    }[];
-    rejectedCodesOmitted: number;
-};
-export declare const publicAvailablePeerStates: readonly ["idle", "busy", "awaiting_approval", "offline"];
-export type PublicAvailablePeerState = (typeof publicAvailablePeerStates)[number];
-/**
- * A transient, metadata-only discovery row. Native provider IDs, process
- * identifiers, registry/socket paths, and generations are deliberately absent.
- * Version 1 uses this for genuine Claude peers; Codex inventory remains the
- * explicit PublicRouteSnapshot list. `routed` means the session currently has
- * an installed logical route — it is a fact about the route table, never a
- * permission: any discovered session is addressable, and its route installs on
- * first use.
- */
-export type PublicAvailablePeerSnapshot = {
-    alias: string;
-    provider: GatewayProvider;
-    host: string;
-    state: PublicAvailablePeerState;
-    validated: boolean;
-    routed: boolean;
-    lastSeenAt?: string;
-    safeErrorCode?: string;
-};
-export declare const gatewayActivityKinds: readonly ["discovery", "registration"];
-export type GatewayActivityKind = (typeof gatewayActivityKinds)[number];
-/**
- * `claude_route_installed` and `claude_route_retired` are journaled by the
- * store when a send installs, renames, or displaces a discovered Claude
- * session's route; there is no explicit Claude registration command.
- */
-export declare const gatewayActivityActions: readonly ["discovery_refreshed", "codex_registered", "codex_succeeded", "codex_unregistered", "claude_route_installed", "claude_route_retired", "route_retired"];
-export type GatewayActivityAction = (typeof gatewayActivityActions)[number];
-export type PublicGatewayActivityEvent = {
-    sequence: number;
-    timestamp: string;
-    kind: GatewayActivityKind;
-    action: GatewayActivityAction;
-    outcome: "accepted" | "rejected";
-    aliases: string[];
-    operatorAction: boolean;
-    safeErrorCode?: string;
-};
-export declare const deadlinePressureBucketNames: readonly ["under_1m", "1m_to_5m", "5m_to_15m", "15m_to_60m", "over_60m"];
-export type DeadlinePressureBucketName = (typeof deadlinePressureBucketNames)[number];
-export type DeadlinePressureBucket = {
-    bucket: DeadlinePressureBucketName;
-    settled: number;
-    expired: number;
-};
-export type DeadlinePressureSnapshot = {
-    configuredDeadlineMs: number;
-    retainedSince?: string;
-    terminalEvents: number;
-    expiredEvents: number;
-    buckets: DeadlinePressureBucket[];
-};
-export declare function isPublicRegistryObservationSnapshot(value: unknown): value is PublicRegistryObservationSnapshot;
-export type SafeGatewayAlert = {
-    code: string;
-    severity: AlertSeverity;
-    timestamp: string;
-    provider?: GatewayProvider;
-    host?: string;
-    alias?: string;
-};
-export type GatewayPublicSnapshot = {
-    schemaVersion: 2;
-    generatedAt: string;
-    health: ConnectorHealth;
-    connectors: PublicConnectorSnapshot[];
-    availablePeers: PublicAvailablePeerSnapshot[];
-    routes: PublicRouteSnapshot[];
-    activityEvents?: PublicGatewayActivityEvent[];
-    deadlinePressure?: DeadlinePressureSnapshot;
-    messages: NormalizedMessageEvent[];
-    accounting: GatewayAccounting;
-    alerts: SafeGatewayAlert[];
-    truncation: GatewaySnapshotTruncation;
-};
-export type GatewaySnapshotTruncation = {
-    connectors: number;
-    availablePeers: number;
-    routes: number;
-    activityEvents?: number;
-    messages: number;
-    alerts: number;
-};
-/**
- * Deterministically projects a canonical snapshot under the local control
- * byte budget. Content is never shortened: complete metadata rows are either
- * retained or counted as omitted. Registry rejection-code detail is shed
- * before routes; connector inventory remains last.
- */
-export declare function projectGatewayPublicSnapshot(snapshot: GatewayPublicSnapshot, maximumBytes?: number): GatewayPublicSnapshot;
-export type RegisterRouteInput = {
-    alias: string;
-    binding: LogicalRouteBinding;
-    registrationMode: RouteRegistrationMode;
-    /**
-     * An ephemeral registration is real in memory — it routes, queues, and
-     * settles exactly like any other — but it is projected out of the durable
-     * state document along with every row that names it, so it cannot survive
-     * a restart and cannot be published to a federation peer; and when it is
-     * removed, by `unregister-peer` or by its own expiry, those rows leave the
-     * live state with it, so nothing of it is written afterwards either.
-     * `embassy check` uses one so a self-test leaves nothing behind.
-     */
-    ephemeral?: true;
-};
-export type GatewayReservedAttempt = Readonly<{
-    messageId: string;
-    attemptId: string;
-    attemptCount: number;
-    body: string;
-    deadlineAt: string;
-    direction: MessageDirection;
-    sourceAlias: string;
-    targetAlias: string;
-    conversationIdSuffix?: string;
-    sourceRegistrationId: string;
-    targetRegistrationId: string;
-    bytes: number;
-    steer?: true;
-}>;
-export type ReserveMessageResult = Readonly<{
-    status: "empty";
-}> | Readonly<{
-    status: "terminal";
-    settlement: TerminalMessageSettlement;
-}> | Readonly<{
-    status: "reserved";
-    attempt: GatewayReservedAttempt;
-}>;
-type AttemptInput = Readonly<{
-    messageId: string;
-    attemptId: string;
-}>;
-type StaleAttemptResult = Readonly<{
-    status: "stale";
-}>;
-type SettledAttemptResult = Readonly<{
-    status: "settled";
-    settlement: TerminalMessageSettlement;
-}>;
-export type AuthorizeMessageInput = AttemptInput & Readonly<{
-    sourceRegistrationId: string;
-    targetRegistrationId: string;
-    prepared: GatewayPreparedWriteEvidence;
-}>;
-export type AuthorizeMessageResult = Readonly<{
-    status: "authorized";
-}> | Readonly<{
-    status: "stale";
-    reason: "not_reserved" | "attempt_mismatch" | "registration_changed";
-}> | Readonly<{
-    status: "terminal";
-    reason: "expired" | "fenced";
-    settlement: TerminalMessageSettlement;
-}>;
-export type AcceptMessageInput = AttemptInput & Readonly<{
-    lossOutcome: "unconfirmed" | "ambiguous";
-}>;
-export type AcceptMessageResult = Readonly<{
-    status: "accepted";
-}> | StaleAttemptResult;
-export type ResolvePrewriteAttemptInput = AttemptInput & Readonly<{
-    outcome: "requeue" | "failed";
-    safeErrorCode?: string;
-}>;
-export type ResolvePrewriteAttemptResult = Readonly<{
-    status: "requeued";
-}> | SettledAttemptResult | StaleAttemptResult;
-export type SettleAttemptInput = AttemptInput & Readonly<{
-    state: Exclude<TerminalDeliveryOutcome, "abandoned">;
-    safeErrorCode?: string;
-}>;
-export type SettleAttemptResult = SettledAttemptResult | StaleAttemptResult;
-export type SettleAttemptForShutdownInput = AttemptInput;
-export type SettleAttemptForShutdownResult = Readonly<{
-    status: "requeued";
-}> | SettledAttemptResult | StaleAttemptResult;
-export type SettleQueuedMessageForShutdownInput = Readonly<{
-    messageId: string;
-}>;
-export type SettleQueuedMessageForShutdownResult = SettledAttemptResult | StaleAttemptResult;
-export type RemoveRouteAtomicResult = Readonly<{
-    removed: boolean;
-    settlements: readonly TerminalMessageSettlement[];
-}>;
-export type GatewayAtomicActivityInput = Readonly<{
-    operatorAction: boolean;
-}>;
-export type ReplaceCodexRegistrationAtomicInput = Readonly<{
-    oldAlias: string;
-    expectedOldRegistrationId: string;
-    replacement: RegisterRouteInput;
-    activity: GatewayAtomicActivityInput;
-}>;
-export type ReplaceCodexRegistrationAtomicResult = Readonly<{
-    replaced: boolean;
-    idempotent: boolean;
-    settlements: readonly TerminalMessageSettlement[];
-}>;
-/**
- * Result of installing a discovered Claude session's route on first send.
- * `settlements` carries the work of any route the install displaced.
- */
-export type InstallClaudeRouteResult = Readonly<{
-    installed: boolean;
-    settlements: readonly TerminalMessageSettlement[];
-}>;
-export type EnqueueMessageInput = {
-    sourceAlias: string;
-    targetAlias: string;
-    expectedSourceRegistrationId?: string;
-    expectedTargetRegistrationId?: string;
-    body: string;
-    dedupeKey: string;
-    conversationIdSuffix?: string;
-    deadlineAt?: string;
-    steer?: true;
-};
-/**
- * The native Claude sender of one inbound message: its installed route's
- * alias and exact binding. The binding carries a native session identifier
- * and must remain an in-memory call argument.
- */
-export type NativeClaudeSender = {
-    alias: string;
-    binding: LogicalRouteBinding;
-};
-export type EnqueueNativeIngressInput = Omit<EnqueueMessageInput, "sourceAlias" | "targetAlias" | "expectedSourceRegistrationId" | "expectedTargetRegistrationId"> & {
-    source: NativeClaudeSender;
-    targetAlias: string;
-    expectedTargetRegistrationId: string;
-};
-export type EnqueueMessageResult = {
-    accepted: boolean;
-    duplicate: boolean;
-    messageId?: string;
-    messageIdSuffix: string;
-    deliveryToken?: string;
-    supersededSettlement?: TerminalMessageSettlement;
-};
-/**
- * Controller-internal proof that one message won its terminal-state race.
- * Full message IDs are required only for in-memory service correlation; this
- * structure must never enter a public snapshot or persisted event.
- */
-export type TerminalMessageSettlement = {
-    messageId: string;
-    state: TerminalDeliveryOutcome;
-    safeErrorCode?: string;
-};
-export type GatewayStoreLimits = {
-    maxRoutes: number;
-    eventCapacity: number;
-    eventTtlMs: number;
-    dedupeCapacity: number;
-    dedupeTtlMs: number;
-    maxQueueMessages: number;
-    maxQueueMessagesPerRoute: number;
-    maxInFlightMessages: number;
-    maxQueueBytes: number;
-    maxMessageBytes: number;
-    maxRetainedBodyBytes?: number;
-    messageDeadlineMs: number;
-    rateLimitPerRoute: number;
-    rateWindowMs: number;
-};
-export type GatewayStoreDependencies = {
-    now?: () => Date;
-    randomId?: () => string;
-    renameStateFile?: (source: string, target: string) => Promise<void>;
-    afterStateFileRename?: () => void | Promise<void>;
-    /** Controller-lock liveness probe; the default is `process.kill(pid, 0)`. */
-    isProcessAlive?: (pid: number) => boolean;
-    /** This machine's name as the controller lock records it; the default is `os.hostname()`. */
-    hostname?: () => string;
-};
-export {};