agent-embassy 1.0.0

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

@@ -0,0 +1,514 @@
+import type { ProgressWatchJournalEvent, ProgressWatchMachine } from "./progress-watch-machine.js";
+import type { CompatibilityAttestation } from "./compatibility.js";
+export declare const gatewayProviders: readonly ["codex", "claude"];
+export type GatewayProvider = (typeof gatewayProviders)[number];
+export declare const gatewayInboundModes: readonly ["paired", "open"];
+export type GatewayInboundMode = (typeof gatewayInboundModes)[number];
+export declare const connectorHealthStates: readonly ["offline", "connecting", "healthy", "degraded", "incompatible"];
+export type ConnectorHealth = (typeof connectorHealthStates)[number];
+export declare const compatibilityStates: readonly ["unknown", "compatible", "incompatible", "expired"];
+export type CompatibilityState = (typeof compatibilityStates)[number];
+export declare const routeStates: readonly ["stale", "idle", "busy", "awaiting_approval", "offline", "incompatible", "disabled"];
+export type RouteState = (typeof routeStates)[number];
+export declare const routeRegistrationModes: readonly ["explicit_opt_in", "selected_live_peer"];
+export type RouteRegistrationMode = (typeof routeRegistrationModes)[number];
+export declare const messageDirections: readonly ["codex_to_claude", "claude_to_codex"];
+export type MessageDirection = (typeof messageDirections)[number];
+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 declare const terminalDeliveryStates: Set<"expired" | "queued" | "duplicate" | "dispatching" | "transport_written" | "held" | "delivered" | "unconfirmed" | "failed" | "ambiguous" | "cancelled" | "abandoned" | "rejected">;
+export declare const alertSeverities: readonly ["info", "warning", "error"];
+export type AlertSeverity = (typeof alertSeverities)[number];
+export type BusyPolicy = "queue";
+/** Canonical closed-array bounds shared by store projections and control/UI. */
+export declare const gatewayPublicSnapshotLimits: Readonly<{
+    readonly connectors: 64;
+    readonly compatibilityChecks: 2;
+    readonly availablePeers: 256;
+    readonly routes: 256;
+    readonly pairs: 256;
+    readonly progressWatches: 64;
+    readonly progressWatchEvents: 256;
+    readonly activityEvents: 256;
+    readonly messages: 1024;
+    readonly alerts: 256;
+}>;
+/** Leaves headroom for the private control protocol response envelope. */
+export declare const GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET: number;
+/**
+ * Private connector identity. Values in this structure are permitted only in
+ * controller-owned state and connector calls. They must never be copied into
+ * public snapshots, normalized events, logs, or error messages.
+ */
+export type PrivateEndpointIdentity = {
+    provider: GatewayProvider;
+    hostId: string;
+    endpointGeneration: string;
+};
+/**
+ * Private, immutable target binding. routeHandle may be a native provider
+ * thread/session identifier; ownerLease proves which registration owns it.
+ */
+export type PrivateRouteBinding = PrivateEndpointIdentity & {
+    routeHandle: string;
+    ownerLease: 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: PrivateRouteBinding;
+    registrationMode: RouteRegistrationMode;
+    enabled: boolean;
+    state: RouteState;
+    compatibility: CompatibilityState;
+    busyPolicy: BusyPolicy;
+    registeredAt: string;
+    updatedAt: string;
+    lastSeenAt?: string;
+    queueDepth: number;
+    counters: RouteCounters;
+    safeErrorCode?: string;
+};
+/**
+ * Durable bidirectional consent between two exact route owners. Aliases are
+ * display coordinates; the private leases prevent an alias from silently
+ * retargeting an existing permission edge.
+ */
+export type GatewayPairRecord = {
+    claudeAlias: string;
+    codexAlias: string;
+    claudeOwnerLease: string;
+    codexOwnerLease: string;
+    createdAt: 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: PrivateRouteBinding;
+    registrationMode: RouteRegistrationMode;
+    enabled: boolean;
+    state: RouteState;
+    compatibility: CompatibilityState;
+    safeErrorCode?: string;
+};
+export type ConnectorRecord = {
+    provider: GatewayProvider;
+    hostId: string;
+    endpointGeneration: string;
+    health: ConnectorHealth;
+    compatibility: CompatibilityState;
+    protocol: string;
+    protocolVersion: string;
+    updatedAt: string;
+    lastSeenAt?: string;
+    safeErrorCode?: string;
+};
+/** Metadata persisted for a queued message. Message bodies are never here. */
+export type QueuedMessageMetadata = {
+    messageId: string;
+    messageIdSuffix: string;
+    /** Bounded public correlation only; the full conversation capability stays private. */
+    conversationIdSuffix?: string;
+    direction: MessageDirection;
+    sourceAlias: string;
+    targetAlias: string;
+    enqueuedAt: string;
+    deadlineAt: string;
+    bytes: number;
+    hopCount: number;
+    /** This message was admitted by the exact durable consent edge. */
+    pair?: true;
+    /** Exact Claude-to-Codex `STEER:` classification; absence means ordinary. */
+    steer?: true;
+};
+/** A transient dispatch value. Its body must remain in process memory. */
+export type TransientQueuedMessage = QueuedMessageMetadata & {
+    body: string;
+};
+export type InFlightMessageMetadata = QueuedMessageMetadata & {
+    dispatchedAt: string;
+};
+export type DedupeRecord = {
+    fingerprint: string;
+    messageIdSuffix: string;
+    conversationIdSuffix?: string;
+    sourceAlias: string;
+    targetAlias: string;
+    direction: MessageDirection;
+    pair?: true;
+    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;
+    hopCount: number;
+    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 GatewayPersistedState = {
+    schemaVersion: 1;
+    createdAt: string;
+    updatedAt: string;
+    eventSequence: number;
+    routes: GatewayRouteRecord[];
+    pairs: GatewayPairRecord[];
+    connectors: ConnectorRecord[];
+    queue: QueuedMessageMetadata[];
+    inFlight: InFlightMessageMetadata[];
+    events: NormalizedMessageEvent[];
+    dedupe: DedupeRecord[];
+    rateBuckets: RateBucket[];
+    accounting: GatewayAccounting;
+    watchSequence: number;
+    progressWatches: ProgressWatchMachine[];
+    progressWatchEvents: ProgressWatchJournalEvent[];
+    /** Bounded, body-free probe evidence keyed by provider surface and version. */
+    compatibilityAttestations: CompatibilityAttestation[];
+    /** Strictly validated internal restart journal; never publicly projected. */
+    codexSuccession?: unknown;
+};
+export type PublicRouteSnapshot = {
+    alias: string;
+    provider: GatewayProvider;
+    host: string;
+    enabled: boolean;
+    state: RouteState;
+    compatibility: CompatibilityState;
+    busyPolicy: BusyPolicy;
+    lastSeenAt?: string;
+    queueDepth: number;
+    /** Earliest enqueue time for this route's current queue, if non-empty. */
+    oldestQueuedAt?: string;
+    counters: RouteCounters;
+    safeErrorCode?: string;
+};
+/** Metadata-only public consent edge. Private route authority is omitted. */
+export type PublicPairSnapshot = {
+    claudeAlias: string;
+    codexAlias: string;
+    host: string;
+    counters: RouteCounters;
+};
+export type PublicConnectorSnapshot = {
+    provider: GatewayProvider;
+    host: string;
+    health: ConnectorHealth;
+    compatibility: CompatibilityState;
+    protocol: string;
+    protocolVersion: string;
+    lastSeenAt?: string;
+    safeErrorCode?: string;
+};
+export declare const publicAvailablePeerStates: readonly ["idle", "busy", "awaiting_approval", "offline", "incompatible"];
+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.
+ */
+export type PublicAvailablePeerSnapshot = {
+    alias: string;
+    provider: GatewayProvider;
+    host: string;
+    state: PublicAvailablePeerState;
+    compatibility: CompatibilityState;
+    /** True only when this row passed the provider's strict selectable-peer checks. */
+    validated: boolean;
+    selected: boolean;
+    lastSeenAt?: string;
+    safeErrorCode?: string;
+};
+export declare const gatewayActivityKinds: readonly ["discovery", "selection", "registration", "pairing", "watch"];
+export type GatewayActivityKind = (typeof gatewayActivityKinds)[number];
+export declare const gatewayActivityActions: readonly ["discovery_refreshed", "claude_selected", "claude_unselected", "codex_registered", "codex_succeeded", "codex_unregistered", "routes_paired", "routes_unpaired", "watch_ended"];
+export type GatewayActivityAction = (typeof gatewayActivityActions)[number];
+/** Bounded, body-free operator activity retained for this broker process. */
+export type PublicGatewayActivityEvent = {
+    sequence: number;
+    timestamp: string;
+    kind: GatewayActivityKind;
+    action: GatewayActivityAction;
+    outcome: "accepted" | "rejected";
+    aliases: string[];
+    operatorAction: true;
+    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;
+};
+/** Counts are computed only from the bounded retained delivery ledger. */
+export type DeadlinePressureSnapshot = {
+    configuredDeadlineMs: number;
+    retainedSince?: string;
+    terminalEvents: number;
+    expiredEvents: number;
+    buckets: DeadlinePressureBucket[];
+};
+/** Strict closed-schema guard for runtime-supplied transient inventory rows. */
+export declare function isPublicAvailablePeerSnapshot(value: unknown): value is PublicAvailablePeerSnapshot;
+export declare function arePublicAvailablePeerSnapshots(value: unknown, maximumRows?: number): value is PublicAvailablePeerSnapshot[];
+export type SafeGatewayAlert = {
+    code: string;
+    severity: AlertSeverity;
+    timestamp: string;
+    provider?: GatewayProvider;
+    host?: string;
+    alias?: string;
+};
+export type PublicProgressWatchSnapshot = {
+    conversationIdSuffix: string;
+    ownerAlias: string;
+    workerAlias: string;
+    phase: "quiet" | "episode";
+    capability: "conversation" | "route";
+    lastActivityAt: string;
+    nextActionAt: string;
+    idleMs: number;
+    nudgeCount: 0 | 1 | 2;
+    workerReportedComplete: boolean;
+};
+export type PublicProgressWatchEventSnapshot = {
+    sequence: number;
+    timestamp: string;
+    conversationIdSuffix: string;
+    ownerAlias: string;
+    workerAlias: string;
+    kind: "opened" | "nudge" | "worker_reported_complete" | "capability_degraded" | "done" | "unresponsive" | "endpoint_retired" | "disabled";
+    nudgeNumber?: 1 | 2;
+};
+export type GatewayPublicSnapshot = {
+    schemaVersion: 1;
+    generatedAt: string;
+    /** Launch-time Claude-to-Codex consent policy; paired is the safe default. */
+    inboundMode: GatewayInboundMode;
+    health: ConnectorHealth;
+    connectors: PublicConnectorSnapshot[];
+    compatibilityChecks?: CompatibilityAttestation[];
+    availablePeers: PublicAvailablePeerSnapshot[];
+    routes: PublicRouteSnapshot[];
+    pairs: PublicPairSnapshot[];
+    progressWatches?: PublicProgressWatchSnapshot[];
+    progressWatchEvents?: PublicProgressWatchEventSnapshot[];
+    activityEvents?: PublicGatewayActivityEvent[];
+    deadlinePressure?: DeadlinePressureSnapshot;
+    messages: NormalizedMessageEvent[];
+    accounting: GatewayAccounting;
+    alerts: SafeGatewayAlert[];
+    truncation: GatewaySnapshotTruncation;
+};
+export type GatewaySnapshotTruncation = {
+    connectors: number;
+    compatibilityChecks?: number;
+    availablePeers: number;
+    routes: number;
+    pairs: number;
+    progressWatches?: number;
+    progressWatchEvents?: 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. Connector/selected-route inventory is the
+ * last category removed.
+ */
+export declare function projectGatewayPublicSnapshot(snapshot: GatewayPublicSnapshot, maximumBytes?: number): GatewayPublicSnapshot;
+export type RegisterRouteInput = {
+    alias: string;
+    binding: PrivateRouteBinding;
+    registrationMode: RouteRegistrationMode;
+    state?: "idle" | "busy" | "awaiting_approval";
+    compatibility?: "compatible";
+};
+export type ObserveConnectorInput = {
+    identity: PrivateEndpointIdentity;
+    health: Exclude<ConnectorHealth, "offline">;
+    compatibility: CompatibilityState;
+    protocol: string;
+    protocolVersion: string;
+    safeErrorCode?: string;
+};
+export type ObserveRouteInput = {
+    binding: PrivateRouteBinding;
+    state: "idle" | "busy" | "awaiting_approval";
+    compatibility: "compatible";
+    safeErrorCode?: string;
+} | {
+    binding: PrivateRouteBinding;
+    state: "stale";
+    compatibility: "expired";
+    safeErrorCode: string;
+};
+export type RebindStaleRouteInput = {
+    /** The currently persisted alias. */
+    alias: string;
+    /** The provider's latest live display name for the same logical route. */
+    newAlias?: string;
+    currentOwnerLease: string;
+    newBinding: PrivateRouteBinding;
+    reason: "endpoint_reobserved" | "peer_explicitly_reselected" | "peer_identity_reobserved";
+    state?: "idle" | "busy" | "awaiting_approval";
+};
+export type EnqueueMessageInput = {
+    sourceAlias: string;
+    targetAlias: string;
+    body: string;
+    dedupeKey: string;
+    /** Last eight opaque characters of the controller-owned conversation ID. */
+    conversationIdSuffix?: string;
+    deadlineAt?: string;
+    hopCount?: number;
+    steer?: true;
+    /**
+     * Controller-derived watch intent committed in the same mutation as the
+     * accepted message. Bodies and command flags are never persisted here.
+     */
+    progressWatch?: {
+        conversationId: string;
+        actorAlias: string;
+        openIdleMs?: number;
+        completionSignal?: true;
+    };
+    /** Controller-authored nudge committed atomically with its queued body. */
+    progressWatchNudge?: {
+        conversationId: string;
+        nudgeNumber: 1 | 2;
+    };
+};
+/**
+ * Controller-internal proof of one currently observed native Claude peer.
+ * The binding may contain a native session identifier and must remain an
+ * in-memory call argument. Store metadata retains only the public alias.
+ */
+export type TransientNativeClaudePeer = {
+    alias: string;
+    binding: PrivateRouteBinding;
+};
+export type EnqueueNativeIngressInput = Omit<EnqueueMessageInput, "sourceAlias" | "targetAlias"> & {
+    source: TransientNativeClaudePeer;
+    targetAlias: string;
+    /** Pre-deadline reply evidence retained across exact pair teardown. */
+    authorizedPairTeardownReply?: true;
+};
+export type EnqueueNativeReplyInput = Omit<EnqueueMessageInput, "sourceAlias" | "targetAlias"> & {
+    sourceAlias: string;
+    target: TransientNativeClaudePeer;
+    /** Retain the original paired admission authority, when one existed. */
+    pair?: true;
+};
+export type EnqueueMessageResult = {
+    accepted: boolean;
+    duplicate: boolean;
+    messageId?: string;
+    messageIdSuffix: string;
+    /** The accepted message is owned by one exact consent edge. */
+    pair?: true;
+    /** Exact older queued steer displaced by the per-edge cap, if any. */
+    supersededSettlement?: TerminalMessageSettlement;
+};
+export type InFlightMessageProgressState = Extract<DeliveryState, "transport_written" | "held">;
+export type SettleMessageInput = {
+    messageId: string;
+    state: Extract<DeliveryState, "delivered" | "unconfirmed" | "failed" | "ambiguous" | "expired" | "cancelled">;
+    safeErrorCode?: string;
+};
+/**
+ * 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: Extract<DeliveryState, "delivered" | "unconfirmed" | "failed" | "ambiguous" | "expired" | "cancelled" | "abandoned">;
+    safeErrorCode?: string;
+};
+export type SettleMessageResult = {
+    status: "settled";
+    settlement: TerminalMessageSettlement;
+} | {
+    status: "not_in_flight";
+};
+export type RequeueInFlightMessageResult = {
+    status: "requeued";
+} | {
+    status: "settled";
+    settlement: TerminalMessageSettlement;
+} | {
+    status: "not_in_flight";
+};
+export type GatewayStoreLimits = {
+    maxRoutes: number;
+    maxPairs: number;
+    /** Omitted injected-test configs use the production default of 32. */
+    maxWatches?: number;
+    eventCapacity: number;
+    eventTtlMs: number;
+    dedupeCapacity: number;
+    dedupeTtlMs: number;
+    maxQueueMessages: number;
+    maxQueueMessagesPerRoute: number;
+    maxInFlightMessages: number;
+    maxQueueBytes: number;
+    maxMessageBytes: number;
+    messageDeadlineMs: number;
+    maxHopCount: number;
+    rateLimitPerRoute: number;
+    rateWindowMs: number;
+};
+export type GatewayStoreDependencies = {
+    now?: () => Date;
+    randomId?: () => string;
+    /** Deterministic durability-fault seam; production callers leave this unset. */
+    afterStateFileRename?: () => void | Promise<void>;
+};