agent-embassy 1.7.0 → 1.8.0

package/dist/src/gateway/codex-stateless-transport.d.ts

@@ -0,0 +1,114 @@
+import { type LocalCodexTransportDependencies, type LocalCodexTransportErrorCode, type LocalCodexTransportFactory, type LocalCodexTransportFactoryOptions } from "./codex-local-transport.js";
+type TurnOutcome = "completed" | "failed" | "interrupted";
+type ReplyCode = "REPLY_TOO_LARGE" | "REPLY_UNAVAILABLE" | null;
+export type StatelessCodexRoute = Readonly<{
+    alias: string;
+    hostId: string;
+    registrationId: string;
+    threadId: string;
+}>;
+export type StatelessCodexWriteEvidence = Readonly<{
+    attemptId: string;
+    kind: "codex_turn_start" | "codex_turn_steer";
+    bodyBytes: number;
+    frameBytes: number;
+    sha256: string;
+}>;
+type StatelessCodexOperationCommon = Readonly<{
+    attemptId: string;
+    deadlineAt: string;
+    route: StatelessCodexRoute;
+    authorizeWrite: (evidence: StatelessCodexWriteEvidence) => Promise<boolean>;
+    /** Already provenance-framed by the broker; never emitted as evidence. */
+    text: string;
+}>;
+export type StatelessCodexActiveSteerInput = Readonly<{
+    attemptId: string;
+    deadlineAt: string;
+    text: string;
+    authorizeWrite: (evidence: StatelessCodexWriteEvidence) => Promise<boolean>;
+}>;
+type ActiveSteerResultCommon = Readonly<{
+    attemptId: string;
+}>;
+export type StatelessCodexActiveSteerResult = (ActiveSteerResultCommon & Readonly<{
+    phase: "clean";
+    state: "deferred" | "failed";
+    safeErrorCode: StatelessCodexSafeErrorCode;
+}>) | (ActiveSteerResultCommon & Readonly<{
+    phase: "armed";
+    state: "ambiguous";
+    safeErrorCode: StatelessCodexSafeErrorCode;
+}>) | (ActiveSteerResultCommon & Readonly<{
+    phase: "terminal";
+    state: "terminal";
+    outcome: "delivered";
+    replyCode: "REPLY_UNAVAILABLE";
+    replyText: null;
+}>);
+export type StatelessCodexAcceptedOperation = Readonly<{
+    attemptId: string;
+    /** Ephemeral exact App Server evidence. Never persist or log this ID. */
+    turnId: string;
+    steer: (input: StatelessCodexActiveSteerInput) => Promise<StatelessCodexActiveSteerResult>;
+}>;
+export type StatelessCodexOperationInput = StatelessCodexOperationCommon & Readonly<{
+    kind: "start";
+    onAccepted: (accepted: StatelessCodexAcceptedOperation) => Promise<void>;
+    /** Exact-operation lifecycle only; never sends an App Server interrupt. */
+    signal?: AbortSignal;
+}>;
+export type StatelessCodexSafeErrorCode = LocalCodexTransportErrorCode | "ACCEPTANCE_UNCONFIRMED" | "APPROVAL_REQUIRED" | "INPUT_INVALID" | "MESSAGE_EXPIRED" | "PROTOCOL_ERROR" | "REQUEST_TIMEOUT" | "RESULT_SCHEMA_MISMATCH" | "ROUTE_BUSY" | "RPC_REJECTED" | "THREAD_NOT_OBSERVED" | "TRANSPORT_CLOSED" | "TRANSPORT_WRITE_FAILED" | "WRITE_AUTHORIZATION_DENIED" | "WRITE_AUTHORIZATION_UNCERTAIN";
+type ResultCommon = Readonly<{
+    attemptId: string;
+    cleanupConfirmed: boolean;
+}>;
+export type StatelessCodexOperationResult = (ResultCommon & Readonly<{
+    phase: "clean";
+    state: "deferred" | "failed";
+    safeErrorCode: StatelessCodexSafeErrorCode;
+}>) | (ResultCommon & Readonly<{
+    phase: "armed";
+    state: "ambiguous";
+    safeErrorCode: StatelessCodexSafeErrorCode;
+}>) | (ResultCommon & Readonly<{
+    phase: "accepted";
+    state: "unconfirmed";
+    safeErrorCode: StatelessCodexSafeErrorCode;
+}>) | (ResultCommon & Readonly<{
+    phase: "terminal";
+    state: "terminal";
+    outcome: "delivered" | TurnOutcome;
+    replyCode: ReplyCode;
+    replyText: string | null;
+}>);
+export type StatelessCodexObservation = Readonly<{
+    state: "idle" | "busy" | "awaiting_approval" | "unobserved";
+    safeErrorCode?: "CODEX_OBSERVER_PROTOCOL_ERROR" | "CODEX_OBSERVER_UNAVAILABLE" | "THREAD_NOT_OBSERVED";
+}>;
+export type StatelessCodexOperationTransport = Readonly<{
+    execute: (input: StatelessCodexOperationInput) => Promise<StatelessCodexOperationResult>;
+    /** Independent display evidence. It never prepares or performs a semantic write. */
+    observe: (route: StatelessCodexRoute, signal?: AbortSignal) => Promise<StatelessCodexObservation>;
+}>;
+export type StatelessCodexOperationTransportOptions = Readonly<{
+    local?: Omit<LocalCodexTransportFactoryOptions, "hostId">;
+    maxDeadlineMs?: number;
+    maxFrameBytes?: number;
+    maxInputBytes?: number;
+    maxReplyBytes?: number;
+    now?: () => Date;
+    requestTimeoutMs?: number;
+    turnTimeoutMs?: number;
+}>;
+export type StatelessCodexOperationTransportDependencies = Readonly<{
+    createFactory?: (options: LocalCodexTransportFactoryOptions) => Promise<LocalCodexTransportFactory>;
+    localDependencies?: LocalCodexTransportDependencies;
+}>;
+/**
+ * Construct an inert stateless Codex operation runner. Construction performs
+ * no provider I/O. Every execute independently re-attests the current managed
+ * installation, owns one proxy/connection, and closes it before returning.
+ */
+export declare function createStatelessCodexOperationTransport(options?: StatelessCodexOperationTransportOptions, dependencies?: StatelessCodexOperationTransportDependencies): StatelessCodexOperationTransport;
+export {};