agent-embassy 1.0.0

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

@@ -0,0 +1,308 @@
+import { type CompatibilityCertificationReport, type CompatibilityCheckReport } from "./compatibility.js";
+import type { GatewayPublicSnapshot } from "./types.js";
+export declare const GATEWAY_CONTROL_PROTOCOL_VERSION: 1;
+export declare const GATEWAY_CONTROL_MAX_FRAME_BYTES: number;
+export declare const GATEWAY_CONTROL_MAX_RESPONSE_BYTES: number;
+export declare const GATEWAY_CONTROL_MAX_MESSAGE_BYTES: number;
+export declare const GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS = 3000;
+export declare const GATEWAY_CONTROL_MAX_CONNECTIONS = 32;
+export declare const gatewayControlMethods: readonly ["health", "register_codex", "unregister_codex", "select_claude", "unselect_claude", "pair", "unpair", "list_snapshot", "observe_snapshot", "compat_check", "compat_certify", "delivery_status", "untrack", "send_to_claude", "send_to_codex", "reply", "refresh_dashboard"];
+export type GatewayControlMethod = (typeof gatewayControlMethods)[number];
+export type GatewayBusyPolicy = "queue";
+export type RegisterCodexParams = {
+    alias: string;
+    threadId: string;
+    hostId?: string;
+    busyPolicy?: GatewayBusyPolicy;
+    succeedsAlias?: string;
+};
+export type ValidatedRegisterCodexParams = {
+    alias: string;
+    threadId: string;
+    hostId: string;
+    busyPolicy: GatewayBusyPolicy;
+    succeedsAlias?: string;
+};
+export type UnregisterCodexParams = {
+    alias: string;
+    threadId: string;
+};
+export type SelectClaudeParams = {
+    /** Latest name@host or native Claude session UUID. */
+    alias: string;
+    /** Optional inherited Codex task identity used for fail-closed inference. */
+    codexThreadId?: string;
+};
+export type PairParams = {
+    claudeAlias: string;
+    codexAlias: string;
+    /** Optional task attestation: when supplied it must match the alias's live registered thread exactly; when omitted, pairing binds to the alias's live registered endpoint without thread attestation. */
+    codexThreadId?: string;
+};
+export type SendToClaudeParams = {
+    fromAlias: string;
+    threadId: string;
+    /** Latest name@host or native Claude session UUID. */
+    toAlias: string;
+    text: string;
+    expectsReply?: boolean;
+    trackIdleMinutes?: number;
+};
+export type ValidatedSendToClaudeParams = {
+    fromAlias: string;
+    threadId: string;
+    toAlias: string;
+    text: string;
+    expectsReply: boolean;
+    trackIdleMinutes?: number;
+};
+export type SendToCodexParams = {
+    fromAlias: string;
+    toAlias: string;
+    text: string;
+    replyAddress?: string;
+    expectsReply?: boolean;
+    trackIdleMinutes?: number;
+};
+export type ValidatedSendToCodexParams = {
+    fromAlias: string;
+    toAlias: string;
+    text: string;
+    replyAddress?: string;
+    expectsReply: boolean;
+    trackIdleMinutes?: number;
+};
+export type GatewayReplyCaller = {
+    kind: "codex";
+    alias: string;
+    threadId: string;
+} | {
+    kind: "claude";
+    alias: string;
+    replyAddress?: string;
+};
+export type ValidatedGatewayReplyCaller = GatewayReplyCaller;
+export type ReplyParams = {
+    conversationId: string;
+    text: string;
+    caller: GatewayReplyCaller;
+    trackIdleMinutes?: number;
+};
+export type UntrackParams = {
+    conversationId: string;
+};
+export type DeliveryStatusParams = {
+    token: string;
+};
+export type GatewayControlRequest = {
+    protocolVersion: 1;
+    method: "health";
+    params: Record<string, never>;
+} | {
+    protocolVersion: 1;
+    method: "register_codex";
+    params: RegisterCodexParams;
+} | {
+    protocolVersion: 1;
+    method: "unregister_codex";
+    params: UnregisterCodexParams;
+} | {
+    protocolVersion: 1;
+    method: "select_claude";
+    params: SelectClaudeParams;
+} | {
+    protocolVersion: 1;
+    method: "unselect_claude";
+    params: SelectClaudeParams;
+} | {
+    protocolVersion: 1;
+    method: "pair";
+    params: PairParams;
+} | {
+    protocolVersion: 1;
+    method: "unpair";
+    params: PairParams;
+} | {
+    protocolVersion: 1;
+    method: "list_snapshot";
+    params: Record<string, never>;
+} | {
+    protocolVersion: 1;
+    method: "observe_snapshot";
+    params: Record<string, never>;
+} | {
+    protocolVersion: 1;
+    method: "compat_check";
+    params: Record<string, never>;
+} | {
+    protocolVersion: 1;
+    method: "compat_certify";
+    params: {
+        codexAlias?: string;
+        withTurn: boolean;
+    };
+} | {
+    protocolVersion: 1;
+    method: "delivery_status";
+    params: DeliveryStatusParams;
+} | {
+    protocolVersion: 1;
+    method: "untrack";
+    params: UntrackParams;
+} | {
+    protocolVersion: 1;
+    method: "send_to_claude";
+    params: SendToClaudeParams;
+} | {
+    protocolVersion: 1;
+    method: "send_to_codex";
+    params: SendToCodexParams;
+} | {
+    protocolVersion: 1;
+    method: "reply";
+    params: ReplyParams;
+} | {
+    protocolVersion: 1;
+    method: "refresh_dashboard";
+    params: Record<string, never>;
+};
+export type GatewayDecisionCode = "ok" | "not_found" | "conflict" | "route_mismatch" | "busy" | "unavailable" | "rejected";
+export type GatewayDecision = {
+    accepted: true;
+    code: "ok";
+} | {
+    accepted: false;
+    code: Exclude<GatewayDecisionCode, "ok">;
+};
+export type GatewaySendResult = {
+    accepted: true;
+    code: "ok";
+    conversationId: string;
+    deliveryToken: string;
+} | {
+    accepted: false;
+    code: Exclude<GatewayDecisionCode, "ok">;
+};
+export type GatewayHealthResult = {
+    status: "ok" | "degraded";
+    /** Coarse controller activity clock; not a semantic snapshot revision. */
+    revision: number;
+};
+export type GatewayRefreshResult = GatewayDecision & {
+    revision: number;
+};
+export type GatewayDeliveryStatusState = "queued" | "stalled" | "delivered" | "unconfirmed" | "expired" | "failed" | "ambiguous" | "cancelled";
+export type GatewayDeliveryStatusResult = {
+    found: false;
+} | {
+    found: true;
+    state: GatewayDeliveryStatusState;
+    terminal: boolean;
+    updatedAt: string;
+    deadlineAt: string;
+    pendingForMs?: number;
+    safeErrorCode?: string;
+};
+export type GatewaySnapshot = GatewayPublicSnapshot;
+/**
+ * One atomic, read-only public observation. `snapshotRevision` is distinct
+ * from the coarse controller revision returned by `health`: it resets with
+ * the gateway process and changes only when public snapshot semantics change.
+ */
+export type GatewaySnapshotObservation = {
+    snapshotRevision: number;
+    snapshot: GatewaySnapshot;
+};
+type ResultByMethod = {
+    health: GatewayHealthResult;
+    register_codex: GatewayDecision;
+    unregister_codex: GatewayDecision;
+    select_claude: GatewayDecision;
+    unselect_claude: GatewayDecision;
+    pair: GatewayDecision;
+    unpair: GatewayDecision;
+    list_snapshot: GatewaySnapshot;
+    observe_snapshot: GatewaySnapshotObservation;
+    compat_check: CompatibilityCheckReport;
+    compat_certify: CompatibilityCertificationReport;
+    delivery_status: GatewayDeliveryStatusResult;
+    untrack: GatewayDecision;
+    send_to_claude: GatewaySendResult;
+    send_to_codex: GatewaySendResult;
+    reply: GatewaySendResult;
+    refresh_dashboard: GatewayRefreshResult;
+};
+type MaybePromise<T> = T | Promise<T>;
+export type GatewayControlHandlers = {
+    health: () => MaybePromise<GatewayHealthResult>;
+    registerCodex: (params: Readonly<ValidatedRegisterCodexParams>) => MaybePromise<GatewayDecision>;
+    unregisterCodex: (params: Readonly<UnregisterCodexParams>) => MaybePromise<GatewayDecision>;
+    selectClaude: (params: Readonly<SelectClaudeParams>) => MaybePromise<GatewayDecision>;
+    unselectClaude: (params: Readonly<SelectClaudeParams>) => MaybePromise<GatewayDecision>;
+    pair: (params: Readonly<PairParams>) => MaybePromise<GatewayDecision>;
+    unpair: (params: Readonly<PairParams>) => MaybePromise<GatewayDecision>;
+    listSnapshot: () => MaybePromise<GatewaySnapshot>;
+    observeSnapshot: () => MaybePromise<GatewaySnapshotObservation>;
+    compatibilityCheck: () => MaybePromise<CompatibilityCheckReport>;
+    compatibilityCertify: (params: Readonly<{
+        codexAlias?: string;
+        withTurn: boolean;
+    }>) => MaybePromise<CompatibilityCertificationReport>;
+    deliveryStatus: (params: Readonly<DeliveryStatusParams>) => MaybePromise<GatewayDeliveryStatusResult>;
+    untrack: (params: Readonly<UntrackParams>) => MaybePromise<GatewayDecision>;
+    sendToClaude: (params: Readonly<ValidatedSendToClaudeParams>) => MaybePromise<GatewaySendResult>;
+    sendToCodex: (params: Readonly<ValidatedSendToCodexParams>) => MaybePromise<GatewaySendResult>;
+    reply: (params: Readonly<ReplyParams>) => MaybePromise<GatewaySendResult>;
+    refreshDashboard: () => MaybePromise<GatewayRefreshResult>;
+};
+export type GatewayWireErrorCode = "INVALID_JSON" | "FRAME_TOO_LARGE" | "INVALID_REQUEST" | "UNSUPPORTED_VERSION" | "UNKNOWN_METHOD" | "MULTIPLE_FRAMES" | "SERVER_BUSY" | "REQUEST_TIMEOUT" | "HANDLER_FAILURE" | "INVALID_HANDLER_RESPONSE" | "RESPONSE_TOO_LARGE";
+export type GatewayControlErrorResponse = {
+    protocolVersion: 1;
+    ok: false;
+    error: {
+        code: GatewayWireErrorCode;
+        message: string;
+    };
+};
+export type GatewayControlSuccessResponse<M extends GatewayControlMethod = GatewayControlMethod> = {
+    protocolVersion: 1;
+    ok: true;
+    result: ResultByMethod[M];
+};
+export type GatewayControlResponse<M extends GatewayControlMethod = GatewayControlMethod> = GatewayControlSuccessResponse<M> | GatewayControlErrorResponse;
+export declare class GatewayControlTransportError extends Error {
+    readonly code: string;
+    readonly ambiguous: boolean;
+    readonly recoverable: boolean;
+    constructor(code: string, message: string, ambiguous?: boolean);
+}
+export type GatewayControlServer = {
+    readonly socketPath: string;
+    readonly closed: boolean;
+    close: () => Promise<void>;
+};
+export type StartGatewayControlServerOptions = {
+    stateDir: string;
+    socketPath: string;
+    handlers: GatewayControlHandlers;
+    requestTimeoutMs?: number;
+};
+export declare function createGatewayConversationId(): string;
+export declare function isGatewayAlias(value: string): boolean;
+export declare function isClaudeSessionSelector(value: string): boolean;
+export declare function isGatewayHostId(value: string): boolean;
+export declare function isGatewayConversationId(value: string): boolean;
+export declare function isGatewayDeliveryToken(value: string): boolean;
+export declare function isGatewayReplyAddress(value: string): boolean;
+export declare function isGatewaySnapshot(value: unknown): value is GatewaySnapshot;
+export declare function startGatewayControlServer(options: StartGatewayControlServerOptions): Promise<GatewayControlServer>;
+export type SendGatewayControlRequestOptions<M extends GatewayControlMethod> = {
+    socketPath: string;
+    request: Extract<GatewayControlRequest, {
+        method: M;
+    }>;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+};
+export declare function sendGatewayControlRequest<M extends GatewayControlMethod>(options: SendGatewayControlRequestOptions<M>): Promise<GatewayControlResponse<M>>;
+export {};